irontide_engine/

torrent.rs

// M175: TorrentActor handles piece arithmetic (bounded by num_pieces: u32),
// peer counters (bounded by max_peers_per_torrent), time deltas vs Instants
// captured during the actor's lifetime, and qBt DTO conversions where the
// wire format dictates narrower integer types. Per-site rationale carried
// forward from M175 plan; review at a single grep target via
// `grep "M175" crates/irontide-session/src/torrent.rs`.
#![allow(
    clippy::cast_possible_truncation,
    clippy::cast_precision_loss,
    clippy::cast_possible_wrap,
    clippy::cast_sign_loss,
    clippy::unchecked_time_subtraction,
    reason = "M175: piece/peer arithmetic bounded by num_pieces/max_peers (u32); time deltas use post-init Instants; qBt DTOs follow wire-format integer widths"
)]

//! `TorrentActor` (single-owner event loop) and `TorrentHandle` (cloneable public API).
//!
//! The actor owns all per-torrent state (chunk tracking, piece selection, choking,
//! peer management) and communicates with spawned `PeerTasks` via channels.
//! The handle is a thin wrapper around an mpsc sender.

use std::collections::{BTreeSet, HashMap, HashSet};
use std::net::SocketAddr;

use rustc_hash::FxHashMap;
use std::sync::Arc;
use std::sync::atomic::AtomicU32;
use std::time::{Duration, Instant};

use bytes::Bytes;
use tokio::sync::{broadcast, mpsc, oneshot};
use tracing::{Instrument, debug, info, trace, warn};

use crate::alert::{Alert, AlertKind, post_alert};
use crate::disk::{DiskHandle, DiskJobFlags, DiskManagerHandle};
use crate::piece_reservation::{
    AtomicPieceStates, BlockMaps, PieceOrderMap, PieceTracker, StealCandidates,
};

use irontide_core::{
    DEFAULT_CHUNK_SIZE, FilePriority, Id20, Lengths, Magnet, PeerId, TorrentMetaV1,
    torrent_from_bytes,
};
// M173 Lane B (B6): DhtHandle is no longer imported here — TorrentActor
// uses irontide_dht::DhtReceiver via the DhtBroadcast pattern instead.
// `current_dht()`/`current_dht_v6()` helpers return Option<DhtHandle>
// from the receiver and use the fully-qualified path.
use irontide_storage::{Bitfield, ChunkTracker, MemoryStorage, TorrentStorage};

use crate::choker::{Choker, PeerInfo as ChokerPeerInfo};
use crate::end_game::EndGame;
use crate::metadata::MetadataDownloader;
use crate::peer_adder::{self, ConnectPeer};
use crate::peer_state::{PeerSource, PeerState};
use crate::tracker_manager::TrackerManager;
use crate::types::{
    PartialPieceInfo, PeerCommand, PeerEvent, PeerInfo, TorrentCommand, TorrentConfig,
    TorrentState, TorrentStats,
};

/// Shared global rate limiter bucket.
pub(crate) type SharedBucket = Arc<parking_lot::Mutex<crate::rate_limiter::TokenBucket>>;

/// Tribool result for piece hash verification in hybrid torrents.
///
/// Mirrors libtorrent-rasterbar's `boost::tribool` approach for dual-hash
/// verification. `NotApplicable` covers cases where verification cannot run
/// (e.g. missing hash picker, disk error before any block is checked).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum HashResult {
    /// All hashes matched.
    Passed,
    /// At least one hash did not match.
    Failed,
    /// Verification could not be performed (missing state / deferred).
    NotApplicable,
}

/// Relocate torrent files from `src_base` to `dst_base`.
///
/// For each file, tries `rename` first (fast, same-filesystem), then falls
/// back to copy + delete (cross-filesystem). Creates parent directories as
/// needed. Returns error on the first failure.
pub(crate) fn relocate_files(
    src_base: &std::path::Path,
    dst_base: &std::path::Path,
    file_paths: &[std::path::PathBuf],
) -> std::io::Result<()> {
    for rel_path in file_paths {
        let src = src_base.join(rel_path);
        let dst = dst_base.join(rel_path);

        if !src.exists() {
            // File may not exist yet (e.g., not downloaded)
            continue;
        }

        if let Some(parent) = dst.parent() {
            std::fs::create_dir_all(parent)?;
        }

        // Try rename first (O(1) on same filesystem)
        if std::fs::rename(&src, &dst).is_err() {
            // Cross-filesystem: copy + delete
            std::fs::copy(&src, &dst)?;
            std::fs::remove_file(&src)?;
        }
    }

    // Try to remove empty parent directories from source
    // (best-effort, ignore errors)
    for rel_path in file_paths {
        let mut dir = src_base.join(rel_path);
        dir.pop(); // get parent dir
        while dir != *src_base {
            if std::fs::remove_dir(&dir).is_err() {
                break; // not empty or other error
            }
            dir.pop();
        }
    }

    Ok(())
}

/// M224: Initial regular-unchoke slot count for a fresh `Choker`. Returns
/// the cap from `Settings.max_uploads_per_torrent` when `n >= 1`, or the
/// historical default of 4 when `n == -1` ("unlimited").
pub(crate) fn initial_unchoke_slots(max_uploads_per_torrent: i32) -> usize {
    if max_uploads_per_torrent >= 1 {
        max_uploads_per_torrent as usize
    } else {
        4
    }
}

/// Current time as POSIX seconds (0 on clock error).
pub(crate) fn now_unix() -> i64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map_or(0, |d| d.as_secs() as i64)
}

/// M112: Cooldown period between holepunch attempts to the same address.
pub(crate) const HOLEPUNCH_COOLDOWN: Duration = Duration::from_mins(2);

/// M112: Maximum number of tracked holepunch cooldown entries to prevent unbounded growth.
pub(crate) const HOLEPUNCH_MAX_TRACKED: usize = 256;

/// M190: Maximum rendezvous requests per peer within the relay rate window.
pub(crate) const HOLEPUNCH_RELAY_MAX_PER_WINDOW: u32 = 5;

/// M190: Duration of the relay rate-limit window.
pub(crate) const HOLEPUNCH_RELAY_WINDOW: Duration = Duration::from_secs(30);

/// Returns true if the disconnect reason suggests the peer is behind NAT
/// and a holepunch attempt might succeed.
pub(crate) fn should_attempt_holepunch(reason: &str) -> bool {
    // Don't re-attempt holepunch for failures from a previous holepunch attempt
    if reason.contains("holepunch") {
        return false;
    }
    reason.contains("refused")
        || reason.contains("timed out")
        || reason.contains("Connection reset")
        || reason.contains("connection reset")
}

/// Cloneable handle for interacting with a running torrent.
#[derive(Clone)]
pub struct TorrentHandle {
    pub cmd_tx: mpsc::Sender<TorrentCommand>,
}

impl TorrentHandle {
    /// Create a torrent session from parsed .torrent metadata.
    ///
    /// Spawns the actor event loop and returns a handle for sending commands.
    ///
    /// M173 Lane B (B6): the `dht_rx`/`dht_v6_rx` parameters are receivers
    /// from the session-level [`irontide_dht::DhtBroadcast`]. They observe
    /// runtime DHT restarts (B11) so the torrent never holds a stale
    /// `DhtHandle` clone whose backing actor has shut down.
    ///
    /// # Errors
    /// Returns an error if disk registration fails or the torrent actor cannot be started.
    #[allow(clippy::too_many_arguments)]
    pub async fn from_torrent(
        meta: TorrentMetaV1,
        version: irontide_core::TorrentVersion,
        meta_v2: Option<irontide_core::TorrentMetaV2>,
        disk: DiskHandle,
        disk_manager: DiskManagerHandle,
        config: TorrentConfig,
        dht_rx: irontide_dht::DhtReceiver,
        dht_v6_rx: irontide_dht::DhtReceiver,
        global_upload_bucket: Option<SharedBucket>,
        global_download_bucket: Option<SharedBucket>,
        slot_tuner: crate::slot_tuner::SlotTuner,
        alert_tx: broadcast::Sender<Alert>,
        alert_mask: Arc<AtomicU32>,
        utp_socket: Option<irontide_utp::UtpSocket>,
        utp_socket_v6: Option<irontide_utp::UtpSocket>,
        ban_manager: irontide_session_types::SharedBanManager,
        ip_filter: irontide_session_types::SharedIpFilter,
        plugins: Arc<Vec<Box<dyn crate::extension::ExtensionPlugin>>>,
        sam_session: Option<Arc<crate::i2p::SamSession>>,
        ssl_manager: Option<Arc<crate::ssl_manager::SslManager>>,
        factory: Arc<crate::transport::NetworkFactory>,
        hash_pool: Option<std::sync::Arc<crate::hash_pool::HashPool>>,
        counters: Arc<crate::stats::SessionCounters>,
    ) -> crate::Result<Self> {
        let mut config = config;
        // BEP 27: private torrents disable DHT, PEX, and LSD
        if meta.info.private == Some(1) {
            config.enable_dht = false;
            config.enable_pex = false;
            config.enable_lsd = false;
        }

        let info_hashes = match (&version, &meta_v2) {
            (irontide_core::TorrentVersion::Hybrid, Some(v2_meta)) => {
                if let Some(v2_hash) = v2_meta.info_hashes.v2 {
                    irontide_core::InfoHashes::hybrid(meta.info_hash, v2_hash)
                } else {
                    irontide_core::InfoHashes::v1_only(meta.info_hash)
                }
            }
            (irontide_core::TorrentVersion::V2Only, Some(v2_meta)) => v2_meta.info_hashes.clone(),
            _ => irontide_core::InfoHashes::v1_only(meta.info_hash),
        };

        if meta.info.piece_length > config.max_piece_length {
            return Err(crate::Error::InvalidSettings(format!(
                "piece_length {} exceeds max_piece_length {}",
                meta.info.piece_length, config.max_piece_length
            )));
        }

        let num_pieces = meta.info.num_pieces() as u32;
        let lengths = Lengths::new(
            meta.info.total_length(),
            meta.info.piece_length,
            DEFAULT_CHUNK_SIZE,
        );
        let mut chunk_tracker = ChunkTracker::new(lengths.clone());

        // Initialize HashPicker for v2/hybrid torrents and enable v2 block tracking
        let hash_picker = if version.has_v2() {
            if let Some(ref v2_meta) = meta_v2 {
                chunk_tracker.enable_v2_tracking();

                let block_size = 16384u64;
                let blocks_per_piece = (meta.info.piece_length / block_size) as u32;

                // Build FileHashInfo from v2 file tree
                let v2_files = v2_meta.info.files();
                let file_infos: Vec<irontide_core::FileHashInfo> = v2_files
                    .iter()
                    .filter_map(|f| {
                        let root = f.attr.pieces_root?;
                        let num_blocks = f.attr.length.div_ceil(block_size) as u32;
                        let num_pieces = f.attr.length.div_ceil(meta.info.piece_length) as u32;
                        Some(irontide_core::FileHashInfo {
                            root,
                            num_blocks,
                            num_pieces,
                        })
                    })
                    .collect();

                if file_infos.is_empty() {
                    None
                } else {
                    let mut picker = irontide_core::HashPicker::new(&file_infos, blocks_per_piece);

                    // Pre-load piece-layer hashes from the .torrent file
                    let _verified = picker.load_piece_layers(&v2_meta.piece_layers);

                    Some(picker)
                }
            } else {
                None
            }
        } else {
            None
        };

        let file_lengths: Vec<u64> = meta.info.files().iter().map(|f| f.length).collect();
        let file_priorities = vec![FilePriority::Normal; file_lengths.len()];
        let wanted_pieces =
            crate::piece_selector::build_wanted_pieces(&file_priorities, &file_lengths, &lengths);

        let (cmd_tx, cmd_rx) = mpsc::channel(256);
        let (event_tx, event_rx) = mpsc::channel(2048);
        let (write_error_tx, write_error_rx) = mpsc::channel(64);
        let (verify_result_tx, verify_result_rx) = mpsc::channel(1024);
        let (hash_result_tx, hash_result_rx) = mpsc::channel(64); // M96
        let our_peer_id = if config.anonymous_mode {
            PeerId::generate_anonymous().0
        } else {
            PeerId::generate().0
        };

        // Bind listener for incoming connections
        // Try dual-stack [::]:port first, fall back to IPv4-only
        let listener: Option<Box<dyn crate::transport::TransportListener>> = match factory
            .bind_tcp(SocketAddr::from((
                std::net::Ipv6Addr::UNSPECIFIED,
                config.listen_port,
            )))
            .await
        {
            Ok(l) => Some(l),
            Err(_) => factory
                .bind_tcp(SocketAddr::from(([0, 0, 0, 0], config.listen_port)))
                .await
                .ok(),
        };
        // Note: DSCP on listener is skipped for transport-abstracted sockets (no raw fd)

        let mut tracker_manager = TrackerManager::from_torrent_filtered(
            &meta,
            our_peer_id,
            config.listen_port,
            config.url_security,
            config.peer_dscp,
            config.anonymous_mode,
        );
        tracker_manager.set_info_hashes(info_hashes.clone());

        // BEP 7: include our I2P destination in tracker announces
        if let Some(ref sam) = sam_session {
            tracker_manager.set_i2p_destination(Some(sam.destination().to_base64()));
        }

        let enable_dht = config.enable_dht;

        // M173 Lane B (B6): snapshot the broadcast at construction time
        // to seed the initial peer-discovery channels. Future DHT
        // restarts (B11) deliver peer batches via the watch
        // subscription, not the initial snapshot.
        let dht_initial = dht_rx.current();
        let dht_v6_initial = dht_v6_rx.current();

        // Start DHT peer discovery if enabled and available
        let dht_peers_rx = if enable_dht {
            if let Some(ref dht) = dht_initial {
                match dht.get_peers(meta.info_hash).await {
                    Ok(rx) => Some(rx),
                    Err(e) => {
                        warn!("failed to start DHT v4 get_peers: {e}");
                        None
                    }
                }
            } else {
                None
            }
        } else {
            None
        };

        let dht_v6_peers_rx = if enable_dht {
            if let Some(ref dht6) = dht_v6_initial {
                match dht6.get_peers(meta.info_hash).await {
                    Ok(rx) => Some(rx),
                    Err(e) => {
                        debug!("failed to start DHT v6 get_peers: {e}");
                        None
                    }
                }
            } else {
                None
            }
        } else {
            None
        };

        // Dual-swarm: also search for v2 hash peers if hybrid
        let v2_as_v1 = if info_hashes.is_hybrid() {
            info_hashes
                .v2
                .map(|v2| Id20(v2.0[..20].try_into().unwrap()))
        } else {
            None
        };
        let (dht_v2_peers_rx, dht_v6_v2_peers_rx) =
            if let (true, Some(v2_id)) = (enable_dht, v2_as_v1) {
                let rx4 = if let Some(ref dht) = dht_initial {
                    dht.get_peers(v2_id).await.ok()
                } else {
                    None
                };
                let rx6 = if let Some(ref dht6) = dht_v6_initial {
                    dht6.get_peers(v2_id).await.ok()
                } else {
                    None
                };
                (rx4, rx6)
            } else {
                (None, None)
            };

        let upload_bucket = crate::rate_limiter::TokenBucket::new(config.upload_rate_limit);
        let download_bucket = Arc::new(parking_lot::Mutex::new(
            crate::rate_limiter::TokenBucket::new(config.download_rate_limit),
        ));
        let rate_limiter_set = crate::rate_limiter::RateLimiterSet::new(
            0,
            0,
            0,
            0,
            config.upload_rate_limit,
            config.download_rate_limit,
        );

        let super_seed = if config.super_seeding {
            Some(crate::super_seed::SuperSeedState::new())
        } else {
            None
        };
        // M118: broadcast channel for Have distribution — capacity scales with torrent size
        let (have_broadcast_tx, _) =
            tokio::sync::broadcast::channel(std::cmp::max(128, num_pieces as usize / 4));
        let is_share_mode = config.share_mode;

        let (piece_ready_tx, _) = broadcast::channel(64);
        let initial_have = chunk_tracker.bitfield().clone();
        let (have_watch_tx, have_watch_rx) = tokio::sync::watch::channel(initial_have);
        let stream_read_semaphore =
            crate::streaming::stream_read_semaphore(config.max_concurrent_stream_reads);

        let choker = Choker::with_algorithms(
            initial_unchoke_slots(config.max_uploads_per_torrent),
            config.seed_choking_algorithm,
            config.choking_algorithm,
            config.upload_rate_limit,
            2,
            20,
        );

        // M96: Wire hash pool into disk handle for V1-only torrents
        let mut disk = disk;
        if matches!(version, irontide_core::TorrentVersion::V1Only)
            && let Some(pool) = &hash_pool
        {
            disk.set_hash_pool(pool.clone());
            disk.set_hash_result_tx(hash_result_tx.clone());
        }

        // M116: Pre-compute file->piece mapping for zero-alloc completion checks.
        let cached_files = Some(build_cached_file_info(&meta, &lengths));

        // v0.173.4 (prong 1): seed the snapshot watch with an empty initial
        let (order_map_tx, _order_map_rx_seed) =
            tokio::sync::watch::channel(Arc::new(PieceOrderMap::empty()));

        let actor = TorrentActor {
            lock_timing: crate::timed_lock::LockTimingSettings::from_ms(
                config.lock_warn_threshold_ms,
            ),
            config,
            info_hash: meta.info_hash,
            our_peer_id,
            state: TorrentState::Downloading,
            disk: Some(disk),
            disk_manager,
            chunk_tracker: Some(chunk_tracker),
            lengths: Some(lengths),
            num_pieces,
            streaming_pieces: BTreeSet::new(),
            time_critical_pieces: BTreeSet::new(),
            streaming_cursors: Vec::new(),
            piece_ready_tx,
            have_watch_tx,
            have_watch_rx,
            stream_read_semaphore,
            file_priorities,
            wanted_pieces,
            end_game: EndGame::new(),
            peers: HashMap::new(),
            unchoke_durations: HashMap::new(),
            cached_peer_rates: FxHashMap::default(),
            refill_notify: Arc::new(tokio::sync::Notify::new()),
            atomic_states: None,
            block_maps: None,
            steal_candidates: None,
            last_steal_populate: Instant::now(),
            piece_write_guards: None,
            soft_reap_buf: Vec::new(),
            eviction_history: std::collections::VecDeque::new(),
            force_immediate_choker_tick: false,
            piece_tracker: None,
            order_map_dirty: false,
            next_order_map_gen: 0,
            order_map_tx,
            piece_owner: Vec::new(),
            peer_slab: crate::piece_reservation::PeerSlab::new(),
            priority_pieces: BTreeSet::new(),
            max_in_flight: 512,
            reservation_notify: None,
            last_tick_dispatch_state: None,
            choker,
            user_seed_mode: false,
            user_forced: false,
            max_connections: 0,
            peer_states: None,
            connect_semaphore: Arc::new(tokio::sync::Semaphore::new(0)),
            connect_permits: HashMap::new(),
            live_outgoing_peers: std::sync::Arc::new(parking_lot::RwLock::new(
                std::collections::HashMap::new(),
            )),
            connect_rx: None,
            metadata_downloader: None,
            downloaded: 0,
            uploaded: 0,
            checking_progress: 0.0,
            total_download: 0,
            total_upload: 0,
            total_failed_bytes: 0,
            total_redundant_bytes: 0,
            added_time: std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map_or(0, |d| d.as_secs() as i64),
            completed_time: 0,
            last_download: 0,
            last_upload: 0,
            last_seen_complete: 0,
            active_duration: 0,
            finished_duration: 0,
            seeding_duration: 0,
            active_since: Some(std::time::Instant::now()),
            state_duration_since: None,
            started_at: std::time::Instant::now(),
            moving_storage: false,
            has_incoming: false,
            need_save_resume: false,
            error: String::new(),
            error_file: -1,
            cmd_rx,
            event_tx,
            event_rx,
            write_error_rx,
            write_error_tx,
            verify_result_rx,
            verify_result_tx,
            pending_verify: HashSet::new(),
            piece_generations: vec![0u64; num_pieces as usize],
            hash_result_rx,
            hash_result_tx,
            meta: Some(meta),
            cached_files,
            listener,
            utp_socket,
            utp_socket_v6,
            tracker_manager,
            tracker_result_rx: None,
            dht_rx,
            dht_v6_rx,
            dht_enabled: enable_dht,
            dht_peers_rx,
            dht_v6_peers_rx,
            dht_v6_empty_count: 0,
            dht_v6_last_retry: None,
            alert_tx,
            alert_mask,
            upload_bucket,
            download_bucket,
            global_upload_bucket,
            global_download_bucket,
            slot_tuner,
            upload_bytes_interval: 0,
            peak_download_rate: 0,
            web_seeds: HashMap::new(),
            banned_web_seeds: HashSet::new(),
            web_seed_in_flight: HashMap::new(),
            web_seed_stats: HashMap::new(),
            pex_peer_count: 0,
            lsd_peer_count: 0,
            super_seed,
            have_broadcast_tx,
            suggested_to_peers: HashMap::new(),
            predictive_have_sent: HashSet::new(),

            ban_manager,
            ip_filter,
            piece_contributors: HashMap::new(),
            parole_pieces: HashMap::new(),
            external_ip: None,
            share_lru: std::collections::VecDeque::new(),
            share_max_pieces: if is_share_mode { 64 } else { 0 },
            plugins,
            hash_picker,
            version,
            meta_v2,
            info_hashes,
            dht_v2_peers_rx,
            dht_v6_v2_peers_rx,
            magnet_selected_files: None,
            sam_session,
            i2p_accept_rx: None,
            i2p_peer_counter: 0,
            i2p_destinations: HashMap::new(),
            ssl_manager,
            rate_limiter_set,
            auto_sequential_active: false,
            factory,
            hash_pool_ref: hash_pool,
            connect_attempts: 0,
            connect_failures: 0,
            choke_rotations: 0,
            inflight_started: Vec::new(),
            completed_piece_times: std::collections::VecDeque::new(),
            piece_steals: 0,
            holepunch_relayed: 0,
            holepunch_relay_rate: HashMap::new(),
            holepunch_cooldowns: HashMap::new(),
            holepunch_pending: Vec::new(),
            counters,
        };

        let spawn_info_hash = actor.info_hash;
        let join_handle = tokio::spawn(actor.run());
        // Monitor the actor task so panics/exits are logged instead of silently swallowed.
        tokio::spawn(async move {
            match join_handle.await {
                Ok(()) => {
                    tracing::warn!(%spawn_info_hash, "torrent actor exited cleanly");
                }
                Err(e) if e.is_panic() => {
                    let panic_payload = e.into_panic();
                    let msg = if let Some(s) = panic_payload.downcast_ref::<&str>() {
                        (*s).to_string()
                    } else if let Some(s) = panic_payload.downcast_ref::<String>() {
                        s.clone()
                    } else {
                        "unknown panic payload".to_string()
                    };
                    tracing::error!(%spawn_info_hash, "torrent actor PANICKED: {msg}");
                }
                Err(e) => {
                    tracing::error!(%spawn_info_hash, "torrent actor task error: {e}");
                }
            }
        });
        Ok(Self { cmd_tx })
    }

    /// Create a torrent session from a magnet link (metadata fetched via BEP 9).
    ///
    /// M173 Lane B (B6): the `dht_rx`/`dht_v6_rx` parameters are receivers
    /// from the session-level [`irontide_dht::DhtBroadcast`]; see
    /// [`Self::from_torrent`] for the rationale.
    ///
    /// # Errors
    /// Returns an error if disk registration fails or the torrent actor cannot be started.
    #[allow(clippy::too_many_arguments)]
    pub async fn from_magnet(
        magnet: Magnet,
        disk_manager: DiskManagerHandle,
        config: TorrentConfig,
        dht_rx: irontide_dht::DhtReceiver,
        dht_v6_rx: irontide_dht::DhtReceiver,
        global_upload_bucket: Option<SharedBucket>,
        global_download_bucket: Option<SharedBucket>,
        slot_tuner: crate::slot_tuner::SlotTuner,
        alert_tx: broadcast::Sender<Alert>,
        alert_mask: Arc<AtomicU32>,
        utp_socket: Option<irontide_utp::UtpSocket>,
        utp_socket_v6: Option<irontide_utp::UtpSocket>,
        ban_manager: irontide_session_types::SharedBanManager,
        ip_filter: irontide_session_types::SharedIpFilter,
        plugins: Arc<Vec<Box<dyn crate::extension::ExtensionPlugin>>>,
        sam_session: Option<Arc<crate::i2p::SamSession>>,
        ssl_manager: Option<Arc<crate::ssl_manager::SslManager>>,
        factory: Arc<crate::transport::NetworkFactory>,
        hash_pool: Option<std::sync::Arc<crate::hash_pool::HashPool>>,
        counters: Arc<crate::stats::SessionCounters>,
    ) -> crate::Result<Self> {
        let (cmd_tx, cmd_rx) = mpsc::channel(256);
        let (event_tx, event_rx) = mpsc::channel(2048);
        let (write_error_tx, write_error_rx) = mpsc::channel(64);
        let (verify_result_tx, verify_result_rx) = mpsc::channel(1024);
        // M96: Dummy channel — replaced when metadata arrives and num_pieces is known
        let (hash_result_tx, hash_result_rx) = mpsc::channel(1);
        let our_peer_id = if config.anonymous_mode {
            PeerId::generate_anonymous().0
        } else {
            PeerId::generate().0
        };

        // Try dual-stack [::]:port first, fall back to IPv4-only
        let listener: Option<Box<dyn crate::transport::TransportListener>> = match factory
            .bind_tcp(SocketAddr::from((
                std::net::Ipv6Addr::UNSPECIFIED,
                config.listen_port,
            )))
            .await
        {
            Ok(l) => Some(l),
            Err(_) => factory
                .bind_tcp(SocketAddr::from(([0, 0, 0, 0], config.listen_port)))
                .await
                .ok(),
        };
        // Note: DSCP on listener is skipped for transport-abstracted sockets (no raw fd)

        let mut tracker_manager = TrackerManager::empty(
            magnet.info_hash(),
            our_peer_id,
            config.listen_port,
            config.peer_dscp,
            config.anonymous_mode,
        );
        // Add tracker URLs from the magnet link (BEP 9 §3.1)
        for url in &magnet.trackers {
            tracker_manager.add_tracker_url(url);
        }

        // BEP 7: include our I2P destination in tracker announces
        if let Some(ref sam) = sam_session {
            tracker_manager.set_i2p_destination(Some(sam.destination().to_base64()));
        }

        let enable_dht = config.enable_dht;

        // M173 Lane B (B6): snapshot the broadcast at construction time
        // for the initial peer-discovery wiring; future DHT restarts
        // (B11) deliver new handles via the watch subscription.
        let dht_initial = dht_rx.current();
        let dht_v6_initial = dht_v6_rx.current();

        // Start DHT peer discovery if enabled and available
        let dht_peers_rx = if enable_dht {
            if let Some(ref dht) = dht_initial {
                match dht.get_peers(magnet.info_hash()).await {
                    Ok(rx) => Some(rx),
                    Err(e) => {
                        warn!("failed to start DHT v4 get_peers: {e}");
                        None
                    }
                }
            } else {
                None
            }
        } else {
            None
        };

        let dht_v6_peers_rx = if enable_dht {
            if let Some(ref dht6) = dht_v6_initial {
                match dht6.get_peers(magnet.info_hash()).await {
                    Ok(rx) => Some(rx),
                    Err(e) => {
                        debug!("failed to start DHT v6 get_peers: {e}");
                        None
                    }
                }
            } else {
                None
            }
        } else {
            None
        };

        let upload_bucket = crate::rate_limiter::TokenBucket::new(config.upload_rate_limit);
        let download_bucket = Arc::new(parking_lot::Mutex::new(
            crate::rate_limiter::TokenBucket::new(config.download_rate_limit),
        ));
        let rate_limiter_set = crate::rate_limiter::RateLimiterSet::new(
            0,
            0,
            0,
            0,
            config.upload_rate_limit,
            config.download_rate_limit,
        );

        let super_seed = if config.super_seeding {
            Some(crate::super_seed::SuperSeedState::new())
        } else {
            None
        };
        // M118: broadcast channel — start with min capacity for magnet (resized on metadata)
        let (have_broadcast_tx, _) = tokio::sync::broadcast::channel(128);
        let is_share_mode = config.share_mode;
        let magnet_selected_files = magnet.selected_files.clone();
        let info_hashes = magnet.info_hashes.clone();

        let (piece_ready_tx, _) = broadcast::channel(64);
        let (have_watch_tx, have_watch_rx) = tokio::sync::watch::channel(Bitfield::new(0));
        let stream_read_semaphore =
            crate::streaming::stream_read_semaphore(config.max_concurrent_stream_reads);

        let choker = Choker::with_algorithms(
            initial_unchoke_slots(config.max_uploads_per_torrent),
            config.seed_choking_algorithm,
            config.choking_algorithm,
            config.upload_rate_limit,
            2,
            20,
        );

        let (order_map_tx, _order_map_rx_seed) =
            tokio::sync::watch::channel(Arc::new(PieceOrderMap::empty()));

        let actor = TorrentActor {
            lock_timing: crate::timed_lock::LockTimingSettings::from_ms(
                config.lock_warn_threshold_ms,
            ),
            config,
            info_hash: magnet.info_hash(),
            our_peer_id,
            state: TorrentState::FetchingMetadata,
            disk: None,
            disk_manager,
            chunk_tracker: None,
            lengths: None,
            num_pieces: 0,
            streaming_pieces: BTreeSet::new(),
            time_critical_pieces: BTreeSet::new(),
            streaming_cursors: Vec::new(),
            piece_ready_tx,
            have_watch_tx,
            have_watch_rx,
            stream_read_semaphore,
            file_priorities: Vec::new(),
            wanted_pieces: Bitfield::new(0),
            end_game: EndGame::new(),
            peers: HashMap::new(),
            unchoke_durations: HashMap::new(),
            cached_peer_rates: FxHashMap::default(),
            refill_notify: Arc::new(tokio::sync::Notify::new()),
            atomic_states: None,
            block_maps: None,
            steal_candidates: None,
            last_steal_populate: Instant::now(),
            piece_write_guards: None,
            soft_reap_buf: Vec::new(),
            eviction_history: std::collections::VecDeque::new(),
            force_immediate_choker_tick: false,
            piece_tracker: None,
            order_map_dirty: false,
            next_order_map_gen: 0,
            order_map_tx,
            piece_owner: Vec::new(),
            peer_slab: crate::piece_reservation::PeerSlab::new(),
            priority_pieces: BTreeSet::new(),
            max_in_flight: 512,
            reservation_notify: None,
            last_tick_dispatch_state: None,
            choker,
            user_seed_mode: false,
            user_forced: false,
            max_connections: 0,
            peer_states: None,
            connect_semaphore: Arc::new(tokio::sync::Semaphore::new(0)),
            connect_permits: HashMap::new(),
            live_outgoing_peers: std::sync::Arc::new(parking_lot::RwLock::new(
                std::collections::HashMap::new(),
            )),
            connect_rx: None,
            metadata_downloader: Some(MetadataDownloader::new(magnet.info_hash())),
            downloaded: 0,
            uploaded: 0,
            checking_progress: 0.0,
            total_download: 0,
            total_upload: 0,
            total_failed_bytes: 0,
            total_redundant_bytes: 0,
            added_time: std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map_or(0, |d| d.as_secs() as i64),
            completed_time: 0,
            last_download: 0,
            last_upload: 0,
            last_seen_complete: 0,
            active_duration: 0,
            finished_duration: 0,
            seeding_duration: 0,
            active_since: Some(std::time::Instant::now()),
            state_duration_since: None,
            started_at: std::time::Instant::now(),
            moving_storage: false,
            has_incoming: false,
            need_save_resume: false,
            error: String::new(),
            error_file: -1,
            cmd_rx,
            event_tx,
            event_rx,
            write_error_rx,
            write_error_tx,
            verify_result_rx,
            verify_result_tx,
            pending_verify: HashSet::new(),
            piece_generations: Vec::new(),
            hash_result_rx,
            hash_result_tx,
            meta: None,
            cached_files: None,
            listener,
            utp_socket,
            utp_socket_v6,
            tracker_manager,
            tracker_result_rx: None,
            dht_rx,
            dht_v6_rx,
            dht_enabled: enable_dht,
            dht_peers_rx,
            dht_v6_peers_rx,
            dht_v6_empty_count: 0,
            dht_v6_last_retry: None,
            alert_tx,
            alert_mask,
            upload_bucket,
            download_bucket,
            global_upload_bucket,
            global_download_bucket,
            slot_tuner,
            upload_bytes_interval: 0,
            peak_download_rate: 0,
            web_seeds: HashMap::new(),
            banned_web_seeds: HashSet::new(),
            web_seed_in_flight: HashMap::new(),
            web_seed_stats: HashMap::new(),
            pex_peer_count: 0,
            lsd_peer_count: 0,
            super_seed,
            have_broadcast_tx,
            suggested_to_peers: HashMap::new(),
            predictive_have_sent: HashSet::new(),

            ban_manager,
            ip_filter,
            piece_contributors: HashMap::new(),
            parole_pieces: HashMap::new(),
            external_ip: None,
            share_lru: std::collections::VecDeque::new(),
            share_max_pieces: if is_share_mode { 64 } else { 0 },
            plugins,
            hash_picker: None,
            version: irontide_core::TorrentVersion::V1Only,
            meta_v2: None,
            info_hashes,
            dht_v2_peers_rx: None,
            dht_v6_v2_peers_rx: None,
            magnet_selected_files,
            sam_session,
            i2p_accept_rx: None,
            i2p_peer_counter: 0,
            i2p_destinations: HashMap::new(),
            ssl_manager,
            rate_limiter_set,
            auto_sequential_active: false,
            factory,
            hash_pool_ref: hash_pool,
            connect_attempts: 0,
            connect_failures: 0,
            choke_rotations: 0,
            inflight_started: Vec::new(),
            completed_piece_times: std::collections::VecDeque::new(),
            piece_steals: 0,
            holepunch_relayed: 0,
            holepunch_relay_rate: HashMap::new(),
            holepunch_cooldowns: HashMap::new(),
            holepunch_pending: Vec::new(),
            counters,
        };

        let spawn_info_hash = actor.info_hash;
        let join_handle = tokio::spawn(actor.run());
        tokio::spawn(async move {
            match join_handle.await {
                Ok(()) => {
                    tracing::warn!(%spawn_info_hash, "torrent actor exited cleanly");
                }
                Err(e) if e.is_panic() => {
                    let panic_payload = e.into_panic();
                    let msg = if let Some(s) = panic_payload.downcast_ref::<&str>() {
                        (*s).to_string()
                    } else if let Some(s) = panic_payload.downcast_ref::<String>() {
                        s.clone()
                    } else {
                        "unknown panic payload".to_string()
                    };
                    tracing::error!(%spawn_info_hash, "torrent actor PANICKED: {msg}");
                }
                Err(e) => {
                    tracing::error!(%spawn_info_hash, "torrent actor task error: {e}");
                }
            }
        });
        Ok(Self { cmd_tx })
    }

    /// Send an incoming peer (routed by the session) to this torrent.
    ///
    /// # Errors
    /// Returns an error if the torrent actor has shut down.
    pub async fn send_incoming_peer(
        &self,
        stream: crate::transport::BoxedStream,
        addr: SocketAddr,
    ) -> crate::Result<()> {
        self.cmd_tx
            .send(TorrentCommand::IncomingPeer { stream, addr })
            .await
            .map_err(|_| crate::Error::Shutdown)
    }

    /// Query current torrent statistics.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn stats(&self) -> crate::Result<TorrentStats> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::Stats { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// v0.173.1: fetch the torrent's current metadata from the `TorrentActor`.
    ///
    /// Returns `Ok(None)` if metadata has not yet been assembled (magnet
    /// pre-resolution), `Ok(Some(meta))` once the info dict is known. Returns
    /// `Err(Shutdown)` if the actor has already exited. Callers that need the
    /// meta to exist should fall back to `crate::Error::MetadataNotReady` on
    /// the `Ok(None)` branch.
    ///
    /// This replaces `SessionActor.TorrentEntry.meta` as the single source of
    /// truth: see `docs/plans/2026-04-22-irontide-v0.173.1-qbt-v2-bug-sweep.md`
    /// for the Class A archaeology.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn get_meta(&self) -> crate::Result<Option<TorrentMetaV1>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::GetMeta { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Add peer addresses to the available-peer pool.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn add_peers(&self, peers: Vec<SocketAddr>, source: PeerSource) -> crate::Result<()> {
        self.cmd_tx
            .send(TorrentCommand::AddPeers { peers, source })
            .await
            .map_err(|_| crate::Error::Shutdown)
    }

    /// Pause the torrent session (disconnect peers, announce Stopped).
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn pause(&self) -> crate::Result<()> {
        self.cmd_tx
            .send(TorrentCommand::Pause)
            .await
            .map_err(|_| crate::Error::Shutdown)
    }

    /// Queue a torrent via auto-manage (system-managed pause).
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn queue(&self) -> crate::Result<()> {
        self.cmd_tx
            .send(TorrentCommand::Queue)
            .await
            .map_err(|_| crate::Error::Shutdown)
    }

    /// M170: update the qBt-compat category label on this torrent.
    ///
    /// Pass `None` to clear the label. The change is visible via the
    /// next `stats()` call and persists across `save_resume_data`.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn set_category(&self, category: Option<String>) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::SetCategory {
                category,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// M171: replace this torrent's tag set wholesale (qBt-compat).
    ///
    /// Mirrors qBt's `addTags` / `removeTags` wire behaviour at the API
    /// layer — always a wholesale replacement at the engine layer. The
    /// change is visible via the next `stats()` call and persists
    /// across `save_resume_data`.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn set_tags(&self, tags: Vec<String>) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::SetTags { tags, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Resume a paused torrent session (reconnect, announce Started).
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn resume(&self) -> crate::Result<()> {
        self.cmd_tx
            .send(TorrentCommand::Resume)
            .await
            .map_err(|_| crate::Error::Shutdown)
    }

    /// Gracefully shut down the torrent session.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn shutdown(&self) -> crate::Result<()> {
        // Best-effort send with timeout — if the channel is full or closed,
        // the actor will exit when all senders are dropped anyway.
        let _ = tokio::time::timeout(
            std::time::Duration::from_secs(5),
            self.cmd_tx.send(TorrentCommand::Shutdown),
        )
        .await;
        Ok(())
    }

    /// Snapshot current torrent state into libtorrent-compatible resume data.
    ///
    /// # Errors
    ///
    /// Returns an error if the I/O operation fails.
    pub async fn save_resume_data(&self) -> crate::Result<irontide_core::FastResumeData> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::SaveResumeData { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Clear the `need_save_resume` dirty flag after a successful file save.
    ///
    /// # Errors
    /// Returns an error if the torrent actor has shut down.
    pub async fn clear_save_resume_flag(&self) -> crate::Result<()> {
        self.cmd_tx
            .send(TorrentCommand::ClearSaveResumeFlag)
            .await
            .map_err(|_| crate::Error::Shutdown)
    }

    /// M245 F1 — atomically take resume data IFF the torrent is dirty.
    ///
    /// Replaces the racy `stats()` → `save_resume_data()` → `clear_save_resume_flag()`
    /// three-step the session's periodic saver used to run per torrent. The
    /// actor reads `need_save_resume`, builds the resume data, and clears the
    /// flag in ONE indivisible command turn (no `.await` between read and
    /// clear), so a dirty mark set concurrently can never be lost to a clear
    /// that races the build.
    ///
    /// Returns `Ok(None)` when the torrent is clean (nothing to write),
    /// `Ok(Some(data))` when dirty data was taken and the flag cleared. On a
    /// build error the flag is left set so the torrent is retried next cycle.
    ///
    /// # Errors
    /// Returns an error if the torrent actor has shut down, or if building the
    /// resume data fails.
    pub async fn take_resume_if_dirty(
        &self,
    ) -> crate::Result<Option<irontide_core::FastResumeData>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::TakeResumeIfDirty { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// M245 F1 — re-arm `need_save_resume` after a failed resume WRITE.
    ///
    /// The session saver calls this when the disk write fails AFTER
    /// [`Self::take_resume_if_dirty`] already cleared the flag, so the torrent
    /// is re-marked dirty and retried on the next save cycle instead of being
    /// silently dropped. Fire-and-forget.
    ///
    /// # Errors
    /// Returns an error if the torrent actor has shut down.
    pub async fn mark_resume_dirty(&self) -> crate::Result<()> {
        self.cmd_tx
            .send(TorrentCommand::MarkResumeDirty)
            .await
            .map_err(|_| crate::Error::Shutdown)
    }

    /// Restore a piece bitmap from resume data (M161 Phase 4).
    ///
    /// Replaces the chunk tracker's bitfield with the provided raw piece bytes.
    /// Returns an error if the bitfield length does not match the torrent's
    /// piece count or if the chunk tracker is not yet initialized.
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Shutdown`] if the torrent actor has stopped.
    /// Returns [`crate::Error::InvalidSettings`] if the bitfield is invalid.
    pub async fn restore_resume_bitmap(&self, pieces: Vec<u8>) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::RestoreResumeBitmap { pieces, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// M178: Restore per-URL web-seed stats from resume data.
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Shutdown`] if the torrent actor has stopped.
    pub async fn restore_web_seed_stats(
        &self,
        stats: HashMap<String, irontide_core::WebSeedStats>,
    ) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::RestoreWebSeedStats { stats, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// M178 Lane B3: cumulative `(pex_peer_count, lsd_peer_count)` for
    /// this torrent. Both counters track UNIQUE peers — duplicate
    /// announcements from the same peer count once.
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Shutdown`] if the torrent actor has stopped.
    pub async fn peer_source_counts(&self) -> crate::Result<(usize, usize)> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::GetPeerSourceCounts { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Snapshot the per-peer cumulative unchoke duration for this torrent.
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Shutdown`] if the torrent actor has stopped.
    pub async fn query_unchoke_durations(
        &self,
    ) -> crate::Result<HashMap<SocketAddr, std::time::Duration>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::QueryUnchokeDurations { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// M178 Lane C: snapshot per-URL `WebSeedStats` for this torrent.
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Shutdown`] if the actor has stopped.
    pub async fn get_web_seed_stats(&self) -> crate::Result<Vec<irontide_core::WebSeedStats>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::GetWebSeedStats { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Set the download priority for a specific file.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn set_file_priority(
        &self,
        index: usize,
        priority: irontide_core::FilePriority,
    ) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::SetFilePriority {
                index,
                priority,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Get the current per-file priorities.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn file_priorities(&self) -> crate::Result<Vec<irontide_core::FilePriority>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::FilePriorities { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Get the list of all configured trackers with their status.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn tracker_list(&self) -> crate::Result<Vec<crate::tracker_manager::TrackerInfo>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::TrackerList { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// M171 Lane B: snapshot the web seed URLs (BEP 19 + BEP 17 merged).
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn get_web_seeds(&self) -> crate::Result<Vec<String>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::GetWebSeeds { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// M171 Lane B: snapshot the per-piece qBt state codes.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn get_piece_states(&self) -> crate::Result<Vec<u8>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::GetPieceStates { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// M171 Lane B: paginated piece hash list.
    ///
    /// `offset` and `limit` are clamped to the real hash count inside
    /// the actor — callers can pass arbitrary values without overflow
    /// concerns.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn get_piece_hashes(&self, offset: u32, limit: u32) -> crate::Result<Vec<String>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::GetPieceHashes {
                offset,
                limit,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        // M245 L3: the actor returns the raw windowed hash bytes; hex-encode
        // here, OFF the recv loop. Output stays byte-identical to the pre-M245
        // `Vec<String>` (40-char SHA-1 / 64-char SHA-256 hex).
        let raw = rx.await.map_err(|_| crate::Error::Shutdown)?;
        Ok(raw.iter().map(hex::encode).collect())
    }

    /// Force all trackers to re-announce immediately.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn force_reannounce(&self) -> crate::Result<()> {
        self.cmd_tx
            .send(TorrentCommand::ForceReannounce)
            .await
            .map_err(|_| crate::Error::Shutdown)
    }

    /// Scrape trackers for seeder/leecher counts.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn scrape(&self) -> crate::Result<Option<(String, irontide_tracker::ScrapeInfo)>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::Scrape { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Open a streaming reader for a file within the torrent.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn open_file(
        &self,
        file_index: usize,
    ) -> crate::Result<crate::streaming::FileStream> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::OpenFile {
                file_index,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        let handle = rx.await.map_err(|_| crate::Error::Shutdown)??;
        Ok(crate::streaming::FileStream::from_handle(handle))
    }

    /// Update the external IP for BEP 40 peer priority sorting.
    ///
    /// # Errors
    /// Returns an error if the torrent actor has shut down.
    pub async fn update_external_ip(&self, ip: std::net::IpAddr) -> crate::Result<()> {
        self.cmd_tx
            .send(TorrentCommand::UpdateExternalIp { ip })
            .await
            .map_err(|_| crate::Error::Shutdown)
    }

    /// Move torrent data files to a new download directory.
    ///
    /// Relocates existing files (rename or copy+delete), re-registers storage
    /// with the disk manager, and fires a `StorageMoved` alert on success.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn move_storage(&self, new_path: std::path::PathBuf) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::MoveStorage {
                new_path,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Set the per-torrent download rate limit in bytes/sec (0 = unlimited).
    ///
    /// # Errors
    ///
    /// Returns an error if the data cannot be parsed or I/O fails.
    pub async fn set_download_limit(&self, bytes_per_sec: u64) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::SetDownloadLimit {
                bytes_per_sec,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Set the per-torrent upload rate limit in bytes/sec (0 = unlimited).
    ///
    /// # Errors
    ///
    /// Returns an error if the data cannot be parsed or I/O fails.
    pub async fn set_upload_limit(&self, bytes_per_sec: u64) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::SetUploadLimit {
                bytes_per_sec,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Get the current per-torrent download rate limit in bytes/sec (0 = unlimited).
    ///
    /// # Errors
    ///
    /// Returns an error if the data cannot be parsed or I/O fails.
    pub async fn download_limit(&self) -> crate::Result<u64> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::DownloadLimit { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Get the current per-torrent upload rate limit in bytes/sec (0 = unlimited).
    ///
    /// # Errors
    ///
    /// Returns an error if the data cannot be parsed or I/O fails.
    pub async fn upload_limit(&self) -> crate::Result<u64> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::UploadLimit { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Enable or disable sequential (in-order) piece downloading.
    ///
    /// # Errors
    ///
    /// Returns an error if the data cannot be parsed or I/O fails.
    pub async fn set_sequential_download(&self, enabled: bool) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::SetSequentialDownload { enabled, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Query whether sequential downloading is enabled.
    ///
    /// # Errors
    ///
    /// Returns an error if the data cannot be parsed or I/O fails.
    pub async fn is_sequential_download(&self) -> crate::Result<bool> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::IsSequentialDownload { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Enable or disable BEP 16 super seeding mode.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn set_super_seeding(&self, enabled: bool) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::SetSuperSeeding { enabled, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Query whether BEP 16 super seeding mode is enabled.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn is_super_seeding(&self) -> crate::Result<bool> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::IsSuperSeeding { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Enable or disable user-requested seed-only mode (M159).
    ///
    /// When `enabled` is `true`, the actor stops scheduling new block requests
    /// and cancels all in-flight requests, but keeps existing peers connected
    /// and continues serving uploads. Toggling back to `false` restores normal
    /// piece scheduling.
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Shutdown`] if the torrent actor has terminated.
    pub async fn set_seed_mode(&self, enabled: bool) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::SetSeedMode { enabled, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Add a new tracker URL to this torrent (fire-and-forget).
    ///
    /// The URL is validated and deduplicated by the tracker manager.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn add_tracker(&self, url: String) -> crate::Result<()> {
        self.cmd_tx
            .send(TorrentCommand::AddTracker { url })
            .await
            .map_err(|_| crate::Error::Shutdown)
    }

    /// Replace all tracker URLs for this torrent.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn replace_trackers(&self, urls: Vec<String>) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::ReplaceTrackers { urls, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Trigger a full piece verification (force recheck).
    ///
    /// Transitions the torrent through `Checking` state, clears all piece
    /// completion data, re-verifies every piece against its hash, then
    /// transitions to `Seeding` (all valid) or `Downloading` (some missing).
    /// Returns after the check is complete.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn force_recheck(&self) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::ForceRecheck { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Rename a file within the torrent on disk.
    ///
    /// Changes the filename of the specified file (by index) to `new_name`.
    /// The file stays in the same directory; only the filename component changes.
    /// Fires a `FileRenamed` alert on success.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn rename_file(&self, file_index: usize, new_name: String) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::RenameFile {
                file_index,
                new_name,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Route an incoming SSL peer (TLS already completed) to this torrent (M42).
    ///
    /// # Errors
    /// Returns an error if the torrent actor has shut down.
    pub async fn spawn_ssl_peer(
        &self,
        addr: SocketAddr,
        stream: impl tokio::io::AsyncRead + tokio::io::AsyncWrite + Unpin + Send + 'static,
    ) -> crate::Result<()> {
        self.cmd_tx
            .send(TorrentCommand::SpawnSslPeer {
                addr,
                stream: crate::types::BoxedAsyncStream(Box::new(stream)),
            })
            .await
            .map_err(|_| crate::Error::Shutdown)
    }

    /// Set the per-torrent maximum number of connections (0 = use global default).
    ///
    /// # Errors
    ///
    /// Returns an error if the connection or binding fails.
    pub async fn set_max_connections(&self, limit: usize) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::SetMaxConnections { limit, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Get the current per-torrent maximum connection limit (0 = use global default).
    ///
    /// # Errors
    ///
    /// Returns an error if the connection or binding fails.
    pub async fn max_connections(&self) -> crate::Result<usize> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::MaxConnections { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Set the per-torrent maximum number of upload slots (unchoke slots).
    ///
    /// # Errors
    ///
    /// Returns an error if the data cannot be parsed or I/O fails.
    pub async fn set_max_uploads(&self, limit: usize) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::SetMaxUploads { limit, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Get the current per-torrent maximum upload slots (unchoke slots).
    ///
    /// # Errors
    ///
    /// Returns an error if the data cannot be parsed or I/O fails.
    pub async fn max_uploads(&self) -> crate::Result<usize> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::MaxUploads { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Get per-peer details for all connected peers.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn get_peer_info(&self) -> crate::Result<Vec<PeerInfo>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::GetPeerInfo { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Get in-flight piece download status (the download queue).
    ///
    /// # Errors
    ///
    /// Returns an error if the data cannot be parsed or I/O fails.
    pub async fn get_download_queue(&self) -> crate::Result<Vec<PartialPieceInfo>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::GetDownloadQueue { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Check whether a specific piece has been downloaded.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn have_piece(&self, index: u32) -> crate::Result<bool> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::HavePiece { index, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Get per-piece availability counts from connected peers.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn piece_availability(&self) -> crate::Result<Vec<u32>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::PieceAvailability { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Get per-file bytes-downloaded progress.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn file_progress(&self) -> crate::Result<Vec<u64>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::FileProgress { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Get the torrent's identity hashes (v1 and/or v2).
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn info_hashes(&self) -> crate::Result<irontide_core::InfoHashes> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::InfoHashes { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Get the full v1 metainfo, if available.
    ///
    /// Returns `None` for magnet links before metadata has been received.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn torrent_file(&self) -> crate::Result<Option<TorrentMetaV1>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::TorrentFile { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Get the full v2 metainfo, if available.
    ///
    /// Returns `None` if the torrent is not a v2/hybrid torrent, or for magnet
    /// links before metadata has been received.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn torrent_file_v2(&self) -> crate::Result<Option<irontide_core::TorrentMetaV2>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::TorrentFileV2 { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Force an immediate DHT announce for this torrent.
    ///
    /// Fire-and-forget at the torrent level — the DHT announce is best-effort.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn force_dht_announce(&self) -> crate::Result<()> {
        self.cmd_tx
            .send(TorrentCommand::ForceDhtAnnounce)
            .await
            .map_err(|_| crate::Error::Shutdown)
    }

    /// Read all data for a specific piece from disk.
    ///
    /// Returns the complete piece data as `Bytes`. The piece must have been
    /// downloaded already; use [`have_piece`](Self::have_piece) to check first.
    ///
    /// # Errors
    ///
    /// Returns an error if the data cannot be parsed or I/O fails.
    pub async fn read_piece(&self, index: u32) -> crate::Result<Bytes> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::ReadPiece { index, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Flush the disk write cache, ensuring all buffered writes are persisted.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn flush_cache(&self) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::FlushCache { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Check whether this handle refers to a live torrent.
    ///
    /// Returns `false` after the torrent has been removed or shut down.
    /// This is a synchronous check on the channel state — no command dispatch.
    #[must_use]
    pub fn is_valid(&self) -> bool {
        !self.cmd_tx.is_closed()
    }

    /// Clear any error state on the torrent and resume if it was paused due to error.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn clear_error(&self) -> crate::Result<()> {
        self.cmd_tx
            .send(TorrentCommand::ClearError)
            .await
            .map_err(|_| crate::Error::Shutdown)
    }

    /// Get per-file open/mode status based on the current torrent state.
    ///
    /// Returns one [`crate::types::FileStatus`] entry per file in the torrent.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn file_status(&self) -> crate::Result<Vec<crate::types::FileStatus>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::FileStatus { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Read the current torrent state as a [`TorrentFlags`] bitflag set.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn flags(&self) -> crate::Result<crate::types::TorrentFlags> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::Flags { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Set (enable) the specified torrent flags.
    ///
    /// Delegates to the underlying operations (pause/resume, sequential download, etc.).
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn set_flags(&self, flags: crate::types::TorrentFlags) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::SetFlags { flags, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Unset (disable) the specified torrent flags.
    ///
    /// Delegates to the underlying operations (pause/resume, sequential download, etc.).
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn unset_flags(&self, flags: crate::types::TorrentFlags) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::UnsetFlags { flags, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Immediately initiate a peer connection to the given address.
    ///
    /// Bypasses the normal peer selection queue — the connection attempt starts
    /// right away. Fire-and-forget: no reply is sent.
    ///
    /// # Errors
    ///
    /// Returns an error if the connection or binding fails.
    pub async fn connect_peer(&self, addr: SocketAddr) -> crate::Result<()> {
        self.cmd_tx
            .send(TorrentCommand::ConnectPeer { addr })
            .await
            .map_err(|_| crate::Error::Shutdown)
    }

    /// M147: Send pre-resolved metadata from the background resolver.
    ///
    /// Fire-and-forget: uses `try_send` to avoid blocking the resolver task.
    /// If the channel is full or closed, the pre-resolved metadata is silently
    /// discarded (the `TorrentActor`'s own `FetchingMetadata` phase will handle it).
    pub fn send_pre_resolved_metadata(&self, info_bytes: Vec<u8>, peers: Vec<SocketAddr>) {
        let _ = self
            .cmd_tx
            .try_send(TorrentCommand::PreResolvedMetadata { info_bytes, peers });
    }

    /// **TEST-ONLY (v0.173.2).** Synchronous counterpart to
    /// [`Self::send_pre_resolved_metadata`] that waits for the actor to
    /// finish processing before returning.
    ///
    /// Uses backpressured `cmd_tx.send().await` plus a oneshot completion
    /// ack, so `test_inject_metadata(...).await` resolves only after the
    /// metadata has been processed by the `TorrentActor`. See
    /// `TorrentCommand::TestInjectMetadata` for the rationale.
    ///
    /// # Errors
    /// - [`crate::Error::Shutdown`] if the torrent command channel is closed.
    ///
    /// # Visibility
    /// `pub` (not `pub(crate)`) because the sole caller is `SessionActor::run`
    /// in `irontide-session` — a *different* crate since the M244 split moved
    /// `torrent.rs` here. Still gated behind `test-util`, so it only exists in
    /// test builds; `irontide-session/test-util` forwards to
    /// `irontide-engine/test-util` to keep the call site and definition in sync.
    #[cfg(feature = "test-util")]
    pub async fn test_inject_metadata(&self, info_bytes: Vec<u8>) -> crate::Result<()> {
        let (tx, rx) = tokio::sync::oneshot::channel();
        self.cmd_tx
            .send(TorrentCommand::TestInjectMetadata {
                info_bytes,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?;
        Ok(())
    }
}

// ---------------------------------------------------------------------------
// M116: Cached file metadata for zero-allocation piece completion checks
// ---------------------------------------------------------------------------

/// Pre-computed file metadata for zero-allocation piece completion checks.
#[derive(Debug, Clone)]
pub(crate) struct CachedFileEntry {
    pub(crate) index: usize,
    #[allow(dead_code)] // Used in tests; retained for future diagnostics
    pub(crate) length: u64,
    pub(crate) first_piece: u32,
    pub(crate) last_piece: u32,
}

/// Cached file-to-piece mapping, computed once at torrent registration.
#[derive(Debug, Clone)]
pub(crate) struct CachedFileInfo {
    pub(crate) entries: Vec<CachedFileEntry>,
}

pub(crate) fn build_cached_file_info(meta: &TorrentMetaV1, lengths: &Lengths) -> CachedFileInfo {
    let piece_length = lengths.piece_length();
    let files = meta.info.files();
    let mut entries = Vec::with_capacity(files.len());
    let mut offset = 0u64;
    for (index, file) in files.iter().enumerate() {
        let first_piece = (offset / piece_length) as u32;
        let last_piece = if file.length == 0 {
            first_piece
        } else {
            ((offset + file.length - 1) / piece_length) as u32
        };
        entries.push(CachedFileEntry {
            index,
            length: file.length,
            first_piece,
            last_piece,
        });
        offset += file.length;
    }
    CachedFileInfo { entries }
}

// ---------------------------------------------------------------------------
// TorrentActor — internal single-owner event loop
// ---------------------------------------------------------------------------

pub(crate) struct TorrentActor {
    pub(crate) config: TorrentConfig,
    /// M120: Lock timing settings for hot-path diagnostics.
    pub(crate) lock_timing: crate::timed_lock::LockTimingSettings,
    pub(crate) info_hash: Id20,
    pub(crate) our_peer_id: Id20,
    pub(crate) state: TorrentState,

    // Disk I/O (None in magnet mode until metadata arrives)
    pub(crate) disk: Option<DiskHandle>,
    pub(crate) disk_manager: DiskManagerHandle,
    pub(crate) chunk_tracker: Option<ChunkTracker>,
    pub(crate) lengths: Option<Lengths>,
    pub(crate) num_pieces: u32,

    // Piece management
    pub(crate) file_priorities: Vec<FilePriority>,
    pub(crate) wanted_pieces: Bitfield,
    pub(crate) end_game: EndGame,

    // Streaming (M28)
    pub(crate) streaming_pieces: BTreeSet<u32>,
    pub(crate) time_critical_pieces: BTreeSet<u32>,
    pub(crate) streaming_cursors: Vec<crate::streaming::StreamingCursor>,
    pub(crate) piece_ready_tx: broadcast::Sender<u32>,
    pub(crate) have_watch_tx: tokio::sync::watch::Sender<Bitfield>,
    pub(crate) have_watch_rx: tokio::sync::watch::Receiver<Bitfield>,
    pub(crate) stream_read_semaphore: Arc<tokio::sync::Semaphore>,

    // Peer management
    pub(crate) peers: HashMap<SocketAddr, PeerState>,
    /// Per-(SocketAddr × torrent) cumulative time we had each peer
    /// unchoked. Survives reconnects: when a `PeerState` is dropped on
    /// disconnect, its `unchoke_duration_total` is flushed into this map
    /// keyed by the peer's `SocketAddr`. Reads via
    /// `SessionHandle::peer_unchoke_durations` sum the persistent value
    /// here with each currently-live `PeerState`'s in-flight accumulator.
    /// Used by the libtorrent-mirror `optimistic_unchoke_fairness` perf
    /// scenario to assert the choker rotates upload slots fairly.
    pub(crate) unchoke_durations: HashMap<SocketAddr, Duration>,
    /// Cached peer download rates for piece stealing decisions.
    /// Refreshed on each periodic tick (~1s) instead of rebuilding per block.
    pub(crate) cached_peer_rates: FxHashMap<SocketAddr, f64>,
    /// Notify handle for reactive queue refill (legacy, unused in M73).
    #[allow(dead_code)]
    pub(crate) refill_notify: Arc<tokio::sync::Notify>,
    /// M93: Lock-free piece states (shared with peers via Arc).
    pub(crate) atomic_states: Option<Arc<crate::piece_reservation::AtomicPieceStates>>,
    /// M103: Shared block-level request/received bitmaps.
    pub(crate) block_maps: Option<Arc<BlockMaps>>,
    /// M103: Shared queue of stealable pieces.
    pub(crate) steal_candidates: Option<Arc<StealCandidates>>,
    /// M132: Last time we populated the steal queue with in-flight pieces.
    pub(crate) last_steal_populate: Instant,
    /// M120: Per-piece write guards to prevent steal/write races.
    pub(crate) piece_write_guards: Option<Arc<crate::piece_reservation::PieceWriteGuards>>,
    /// v0.173.3: Reusable buffer for `soft_reap_candidates` output.
    /// Reaped every `soft_reap_interval` tick (~1/s) with typical size
    /// 0-16 entries; held here so the allocation is reused across ticks.
    pub(crate) soft_reap_buf: Vec<std::net::SocketAddr>,
    /// v0.187.3 / 3A: sliding-window of recent proactive eviction timestamps.
    /// Entries older than 60s are pruned on each tick; the actor refuses to
    /// evict when the post-prune length is >= `proactive_evictions_per_minute_limit`.
    /// Prevents the 130 → 20-50 churn observed in the dogfood report.
    pub(crate) eviction_history: std::collections::VecDeque<std::time::Instant>,
    /// v0.187.3 / Bug 8a: when set, the main loop runs the choker on the
    /// next iteration regardless of `unchoke_interval`. Set on transition
    /// INTO `Seeding` so interested peers see Unchoke promptly. Cleared
    /// after the next `run_choker().await`.
    pub(crate) force_immediate_choker_tick: bool,
    /// M187: Actor-owned piece dispatch tracker (direct-acquire model).
    pub(crate) piece_tracker: Option<PieceTracker>,
    /// M187: Watch sender that broadcasts `PieceOrderMap` to peer tasks.
    pub(crate) order_map_tx: tokio::sync::watch::Sender<Arc<PieceOrderMap>>,

    /// M246: set by the `SetFilePriority` arm to request a coalesced order-map
    /// rebuild on the next 1 s pipeline tick — a batch of M priority changes
    /// sets it M times but triggers ONE rebuild. Cleared by
    /// `rebuild_order_map_now`.
    pub(crate) order_map_dirty: bool,

    /// M246: actor-owned monotone generation counter for the published
    /// `PieceOrderMap`. Every rebuild assigns `next_order_map_gen += 1`; the
    /// generation is NEVER derived from the published `watch` value — under any
    /// async publish that would let two back-to-back batch rebuilds read the
    /// same generation and drop one (the rejected-Candidate-H bug class).
    pub(crate) next_order_map_gen: u64,
    /// M93: Maps piece index -> peer slab slot that owns it.
    pub(crate) piece_owner: Vec<Option<u16>>,
    /// M93: Arena-allocated peer tracking: slot <-> `SocketAddr`.
    pub(crate) peer_slab: crate::piece_reservation::PeerSlab,
    #[allow(dead_code)]
    pub(crate) priority_pieces: BTreeSet<u32>,
    /// M93: Maximum in-flight pieces.
    pub(crate) max_in_flight: usize,
    /// Piece notify handle (for driver spawning).
    pub(crate) reservation_notify: Option<Arc<tokio::sync::Notify>>,
    /// Dispatch state snapshot at the previous pipeline tick:
    /// `(queue_pieces.count_ones(), inflight.len())`. The tick uses this to
    /// gate its `notify_waiters()` safety-net call — if neither value has
    /// changed, no peer needs waking, and waking all of them would just
    /// trigger spurious acquire calls (the 93% `NoneAvailable` rate measured
    /// on 2026-05-11 was largely driven by unconditional 1 Hz wake spam).
    /// `None` until the first tick records a baseline.
    pub(crate) last_tick_dispatch_state: Option<(u32, usize)>,
    pub(crate) choker: Choker,
    /// M159: User-requested seed-only mode flag.
    ///
    /// When `true`, the actor stops issuing new block requests (gating the
    /// `StartRequesting` dispatch sent to peer tasks) and cancels any
    /// in-flight requests. Uploads continue unaffected. Distinct from the
    /// naturally-complete seeding state tracked by `state == Seeding`.
    pub(crate) user_seed_mode: bool,
    /// Whether the user force-started this torrent (bypassing queue limits).
    pub(crate) user_forced: bool,
    /// Per-torrent connection limit override (0 = use `config.max_peers`).
    pub(crate) max_connections: usize,
    /// M137: Unified peer lifecycle tracker (replaces `peers_connected` + `connect_backoff` + `peer_tx` + `unique_peers_attempted`).
    pub(crate) peer_states: Option<Arc<crate::peer_states::PeerStates>>,
    /// M147: `ConnectPool` semaphore — gates connection attempts only.
    /// Permits are released on `HandshakeComplete` (not held for peer lifetime).
    pub(crate) connect_semaphore: Arc<tokio::sync::Semaphore>,
    /// M147: Maps peer address → permit holder. Permits are taken on `HandshakeComplete`
    /// to free `ConnectPool` slots. RAII cleanup on task exit handles failure cases.
    pub(crate) connect_permits:
        HashMap<SocketAddr, Arc<parking_lot::Mutex<Option<tokio::sync::OwnedSemaphorePermit>>>>,
    /// M107: Receiver for connect requests from the adder task.
    pub(crate) connect_rx: Option<mpsc::Receiver<ConnectPeer>>,

    // Metadata (for magnet links)
    pub(crate) metadata_downloader: Option<MetadataDownloader>,

    // Parsed torrent meta (for piece hash verification)
    pub(crate) meta: Option<TorrentMetaV1>,

    /// M116: Pre-computed file->piece mapping for zero-alloc completion checks.
    pub(crate) cached_files: Option<CachedFileInfo>,

    // Stats
    pub(crate) downloaded: u64,
    pub(crate) uploaded: u64,
    pub(crate) checking_progress: f32,
    pub(crate) total_download: u64,
    pub(crate) total_upload: u64,
    pub(crate) total_failed_bytes: u64,
    pub(crate) total_redundant_bytes: u64,
    pub(crate) added_time: i64,
    pub(crate) completed_time: i64,
    pub(crate) last_download: i64,
    pub(crate) last_upload: i64,
    pub(crate) last_seen_complete: i64,
    pub(crate) active_duration: i64,
    pub(crate) finished_duration: i64,
    pub(crate) seeding_duration: i64,
    pub(crate) active_since: Option<std::time::Instant>,
    pub(crate) state_duration_since: Option<std::time::Instant>,
    #[allow(dead_code)] // M104: ConnectPhase removed; kept for future diagnostics
    pub(crate) started_at: std::time::Instant,
    pub(crate) moving_storage: bool,
    pub(crate) has_incoming: bool,
    pub(crate) need_save_resume: bool,
    pub(crate) error: String,
    pub(crate) error_file: i32,

    // Channels
    pub(crate) cmd_rx: mpsc::Receiver<TorrentCommand>,
    pub(crate) event_tx: mpsc::Sender<PeerEvent>,
    pub(crate) event_rx: mpsc::Receiver<PeerEvent>,

    // Async disk pipeline channels
    pub(crate) write_error_rx: mpsc::Receiver<crate::disk::DiskWriteError>,
    pub(crate) write_error_tx: mpsc::Sender<crate::disk::DiskWriteError>,
    pub(crate) verify_result_rx: mpsc::Receiver<crate::disk::VerifyResult>,
    pub(crate) verify_result_tx: mpsc::Sender<crate::disk::VerifyResult>,
    /// Pieces currently awaiting async verification — prevents duplicate
    /// verify tasks when end game or slow peers deliver duplicate blocks.
    pub(crate) pending_verify: HashSet<u32>,
    /// Generation counter per piece — increments on release/re-reserve.
    /// Used to detect stale hash results from the `HashPool` (M96).
    pub(crate) piece_generations: Vec<u64>,
    /// Receiver for hash pool results (M96).
    pub(crate) hash_result_rx: tokio::sync::mpsc::Receiver<crate::hash_pool::HashResult>,
    /// Sender for hash pool results — cloned into `DiskHandle` (M96).
    pub(crate) hash_result_tx: tokio::sync::mpsc::Sender<crate::hash_pool::HashResult>,

    // TCP listener for incoming peer connections
    pub(crate) listener: Option<Box<dyn crate::transport::TransportListener>>,

    // uTP socket for outbound connections (shared with session, cloned)
    pub(crate) utp_socket: Option<irontide_utp::UtpSocket>,
    // IPv6 uTP socket for outbound connections to IPv6 peers
    pub(crate) utp_socket_v6: Option<irontide_utp::UtpSocket>,

    // Tracker management
    pub(crate) tracker_manager: TrackerManager,
    /// M143: Receiver for streaming tracker announce results.
    /// `Some` while a background announce is in-flight, `None` when idle.
    pub(crate) tracker_result_rx: Option<mpsc::Receiver<crate::tracker_manager::TrackerPeerBatch>>,

    // DHT handles (shared, optional). M173 Lane B (B6): subscribe to
    // the session-level DhtBroadcast so a runtime DHT restart is
    // observed on the next call without holding a stale clone. The
    // `dht_enabled` flag gates BEP 27 private torrents (which must
    // not announce to DHT regardless of session-level enable) plus
    // any per-torrent opt-out.
    pub(crate) dht_rx: irontide_dht::DhtReceiver,
    pub(crate) dht_v6_rx: irontide_dht::DhtReceiver,
    pub(crate) dht_enabled: bool,
    pub(crate) dht_peers_rx: Option<mpsc::UnboundedReceiver<Vec<SocketAddr>>>,
    pub(crate) dht_v6_peers_rx: Option<mpsc::UnboundedReceiver<Vec<SocketAddr>>>,
    /// Consecutive times the V6 DHT returned an empty table.
    /// After 30 failures (~3s at 100ms), stop retrying to avoid log spam.
    pub(crate) dht_v6_empty_count: u32,
    /// Timestamp of last V6 DHT retry attempt (M97).
    pub(crate) dht_v6_last_retry: Option<std::time::Instant>,

    // Alert system (M15)
    pub(crate) alert_tx: broadcast::Sender<Alert>,
    pub(crate) alert_mask: Arc<AtomicU32>,

    // Rate limiting (M14)
    pub(crate) upload_bucket: crate::rate_limiter::TokenBucket,
    pub(crate) download_bucket: SharedBucket,
    pub(crate) global_upload_bucket: Option<SharedBucket>,
    #[allow(dead_code)] // M73: rate limiting deferred to M74
    pub(crate) global_download_bucket: Option<SharedBucket>,
    pub(crate) slot_tuner: crate::slot_tuner::SlotTuner,
    pub(crate) upload_bytes_interval: u64,

    /// Peak aggregate download rate observed (bytes/sec), for peer turnover cutoff.
    pub(crate) peak_download_rate: u64,

    // Web seeding (M22)
    pub(crate) web_seeds: HashMap<String, mpsc::Sender<crate::web_seed::WebSeedCommand>>,
    pub(crate) banned_web_seeds: HashSet<String>,
    pub(crate) web_seed_in_flight: HashMap<u32, String>,
    /// M178: Per-URL stats accumulated from `PeerEvent::WebSeedProgress`
    /// events emitted by `WebSeedTask`. Persisted to fast-resume so stats
    /// survive app restart (see `resume_file.rs`).
    pub(crate) web_seed_stats: HashMap<String, irontide_core::WebSeedStats>,
    /// M178 (Lane B3 / TODO-2): cumulative count of UNIQUE peers received
    /// via PEX (BEP 11) since this actor started. Surfaced through
    /// `SessionHandle::pex_peer_count` for the qBt v2 trackers endpoint
    /// and the GUI Trackers tab pseudo-tracker rows. Reset on torrent
    /// removal (actor lifecycle).
    pub(crate) pex_peer_count: usize,
    /// M178 (Lane B3 / TODO-2): cumulative count of UNIQUE peers received
    /// via LSD (BEP 14) multicast. Self-cookie filtering happens upstream
    /// in M174's session-level LSD path.
    pub(crate) lsd_peer_count: usize,

    // BEP 16 super seeding (M23)
    pub(crate) super_seed: Option<crate::super_seed::SuperSeedState>,
    // M118: Broadcast channel for Have distribution (replaces HaveBuffer)
    pub(crate) have_broadcast_tx: tokio::sync::broadcast::Sender<u32>,

    /// M44: pieces we've suggested to each peer (avoid re-suggesting)
    pub(crate) suggested_to_peers: HashMap<SocketAddr, HashSet<u32>>,

    /// M44: pieces for which we've already sent predictive Have
    pub(crate) predictive_have_sent: HashSet<u32>,

    // Smart banning (M25)
    pub(crate) ban_manager: irontide_session_types::SharedBanManager,
    pub(crate) piece_contributors: HashMap<u32, HashSet<std::net::IpAddr>>,
    pub(crate) parole_pieces: HashMap<u32, crate::ban::ParoleState>,

    // IP filtering (M29)
    pub(crate) ip_filter: irontide_session_types::SharedIpFilter,

    // BEP 40 peer priority (M32b)
    pub(crate) external_ip: Option<std::net::IpAddr>,

    // Share mode (M32c): LRU tracker for in-memory piece relay.
    // Tracks which pieces are currently "live" (servable) in share mode.
    // Oldest pieces are evicted when capacity is reached.
    pub(crate) share_lru: std::collections::VecDeque<u32>,
    /// Max pieces to keep live in share mode (0 = share mode disabled).
    pub(crate) share_max_pieces: usize,

    // Extension plugins (M32d)
    pub(crate) plugins: Arc<Vec<Box<dyn crate::extension::ExtensionPlugin>>>,

    // BEP 52 v2/hybrid support (M34-M35)
    pub(crate) hash_picker: Option<irontide_core::HashPicker>,
    pub(crate) version: irontide_core::TorrentVersion,
    #[allow(dead_code)] // stored for hybrid torrent re-serialization (M35 Task 5)
    pub(crate) meta_v2: Option<irontide_core::TorrentMetaV2>,

    /// Full info hashes for dual-swarm support (v1 + v2 for hybrid).
    pub(crate) info_hashes: irontide_core::InfoHashes,

    /// Dual-swarm DHT peer receivers (v2 hash in hybrid torrents).
    pub(crate) dht_v2_peers_rx: Option<mpsc::UnboundedReceiver<Vec<SocketAddr>>>,
    pub(crate) dht_v6_v2_peers_rx: Option<mpsc::UnboundedReceiver<Vec<SocketAddr>>>,

    /// BEP 53: deferred file selection from magnet `so=` parameter.
    /// Applied after metadata is received to set file priorities.
    pub(crate) magnet_selected_files: Option<Vec<irontide_core::FileSelection>>,

    /// I2P SAM session for anonymous peer connections (M41).
    pub(crate) sam_session: Option<Arc<crate::i2p::SamSession>>,

    /// Receiver for incoming I2P peer connections (M41).
    pub(crate) i2p_accept_rx: Option<mpsc::Receiver<crate::i2p::SamStream>>,

    /// Counter for generating synthetic `SocketAddr` values for I2P peers (M41).
    pub(crate) i2p_peer_counter: u32,

    /// Maps synthetic `SocketAddr` → `I2pDestination` for outbound I2P connects.
    pub(crate) i2p_destinations: HashMap<SocketAddr, crate::i2p::I2pDestination>,

    /// SSL manager for SSL torrent certificate handling (M42).
    pub(crate) ssl_manager: Option<Arc<crate::ssl_manager::SslManager>>,

    /// Per-class rate limiting with mixed-mode (M45).
    pub(crate) rate_limiter_set: crate::rate_limiter::RateLimiterSet,
    /// Whether auto-sequential mode is currently active (hysteresis state).
    pub(crate) auto_sequential_active: bool,
    /// Network transport factory for TCP operations (M51).
    pub(crate) factory: Arc<crate::transport::NetworkFactory>,
    /// Shared hash pool for parallel piece verification (M96).
    pub(crate) hash_pool_ref: Option<std::sync::Arc<crate::hash_pool::HashPool>>,
    /// M108: Shared snapshot of connected peer addresses for PEX send tasks.
    pub(crate) live_outgoing_peers:
        std::sync::Arc<parking_lot::RwLock<std::collections::HashMap<SocketAddr, u8>>>,
    /// M108: Total outbound connection attempts dispatched to peer adder.
    pub(crate) connect_attempts: u64,
    /// M108: Total connection failures (peers that disconnected).
    pub(crate) connect_failures: u64,
    /// M138: Total number of peers evicted by proactive choke rotation.
    pub(crate) choke_rotations: u64,
    /// M149: When each in-flight piece started downloading. Indexed by piece index.
    /// Set when `piece_owner` assigns a piece, cleared on verify/hash-fail.
    pub(crate) inflight_started: Vec<Option<Instant>>,
    /// M149: Rolling window of recent piece completion times for steal threshold.
    pub(crate) completed_piece_times: std::collections::VecDeque<Duration>,
    /// M149: Total number of piece-level steals performed.
    pub(crate) piece_steals: u64,
    /// M190: Total holepunch rendezvous requests we relayed.
    pub(crate) holepunch_relayed: u64,
    /// M190: Per-peer rate limit for holepunch rendezvous requests.
    pub(crate) holepunch_relay_rate: HashMap<SocketAddr, (Instant, u32)>,
    /// M112: Tracks recent holepunch attempts to prevent retry storms.
    pub(crate) holepunch_cooldowns: HashMap<SocketAddr, Instant>,
    /// M112: Buffer for holepunch attempts (`disconnect_peer` is sync, `try_holepunch` is async).
    pub(crate) holepunch_pending: Vec<SocketAddr>,
    /// Sim-perf engine surface: shared session counters used by
    /// `rebuild_availability_snapshot` to track Allow / Defer rates,
    /// and by per-peer spawn sites to seed `PeerShared::counters`.
    pub(crate) counters: Arc<crate::stats::SessionCounters>,
}

/// Maximum number of in-flight end-game requests per peer.
/// libtorrent continues full pipelining in end-game; we use a moderate
/// depth so that round-trip latency doesn't bottleneck throughput.
/// End-game pipeline depth: match normal mode (128 slots per peer).
/// Safe because the reactive per-block cascade was replaced with a 200ms
/// batch refill tick — raising depth no longer amplifies picker invocations.
pub(crate) const END_GAME_DEPTH: usize = 128;

/// Minimum free pipeline slots before invoking the full piece picker in
/// `handle_piece_data()`.  Avoids running the 5-layer picker on every single
impl TorrentActor {
    /// Returns the current IPv4 `DhtHandle`, or `None` if DHT is disabled
    /// for this torrent (BEP 27 private, per-torrent opt-out, or
    /// session-level disable). M173 Lane B (B6): reads from the
    /// session-level [`irontide_dht::DhtBroadcast`] receiver, so a
    /// runtime DHT restart (B11) is observed transparently here.
    pub(crate) fn current_dht(&self) -> Option<irontide_dht::DhtHandle> {
        if self.dht_enabled {
            self.dht_rx.current()
        } else {
            None
        }
    }

    /// Returns the current IPv6 `DhtHandle`, or `None` if DHT is disabled.
    /// See [`Self::current_dht`].
    pub(crate) fn current_dht_v6(&self) -> Option<irontide_dht::DhtHandle> {
        if self.dht_enabled {
            self.dht_v6_rx.current()
        } else {
            None
        }
    }

    /// Hold-window helper: wait up to `hold` for the IPv4 DHT broadcast
    /// to deliver a non-`None` handle. Returns `None` if the wait
    /// times out OR if DHT is disabled for this torrent.
    ///
    /// Used by call sites that issue requests during a DHT restart
    /// window and prefer to hold a brief moment rather than fail
    /// immediately. The hold is bounded — callers must not loop on
    /// `None`, since a permanently-disabled DHT will hit the timeout
    /// every iteration.
    ///
    /// # Errors
    ///
    /// Returns `None` on timeout, on disabled DHT, or if the
    /// broadcast sender has been dropped (session shutting down).
    #[allow(dead_code)] // wired by future per-call-site refactors as needed
    pub(crate) async fn current_dht_or_wait(
        &mut self,
        hold: std::time::Duration,
    ) -> Option<irontide_dht::DhtHandle> {
        if !self.dht_enabled {
            return None;
        }
        if let Some(handle) = self.dht_rx.current() {
            return Some(handle);
        }
        // Wait for the broadcast to fire `replace(Some(_))`.
        match tokio::time::timeout(hold, self.dht_rx.changed()).await {
            Ok(Ok(())) => self.dht_rx.current(),
            Ok(Err(_)) | Err(_) => None,
        }
    }

    /// Main event loop.
    async fn run(mut self) {
        // Verify existing pieces on startup (resume support)
        self.verify_existing_pieces().await;

        // M93: Initialize lock-free piece states after verification
        // so we_have reflects already-verified pieces.
        if let Some(ct) = &self.chunk_tracker {
            let atomic_states = Arc::new(AtomicPieceStates::new(
                self.num_pieces,
                ct.bitfield(),
                &self.wanted_pieces,
            ));
            self.atomic_states = Some(Arc::clone(&atomic_states));
            self.piece_owner = vec![None; self.num_pieces as usize];
            // M149: Initialize inflight tracking
            self.inflight_started = vec![None; self.num_pieces as usize];
            self.max_in_flight = self.config.max_in_flight_pieces;

            // M103: Initialize block stealing infrastructure
            if self.config.use_block_stealing {
                if let Some(ref lengths) = self.lengths {
                    self.block_maps = Some(Arc::new(BlockMaps::new(self.num_pieces, lengths)));
                }
                self.steal_candidates = Some(Arc::new(StealCandidates::new()));
            }
            // M120: Per-piece write guards
            self.piece_write_guards = Some(Arc::new(
                crate::piece_reservation::PieceWriteGuards::new(self.num_pieces),
            ));

            // M187: Init direct-acquire dispatch state.
            self.piece_tracker = Some(PieceTracker::new(
                self.num_pieces,
                ct.bitfield(),
                &self.wanted_pieces,
            ));
            if let Some(ref cached) = self.cached_files {
                let file_piece_ranges: Vec<(u32, u32)> = cached
                    .entries
                    .iter()
                    .map(|e| (e.first_piece, e.last_piece))
                    .collect();
                let om = Arc::new(PieceOrderMap::build(
                    &self.file_priorities,
                    &file_piece_ranges,
                    self.num_pieces,
                    0,
                ));
                self.order_map_tx.send_replace(om);
            }

            let notify = Arc::new(tokio::sync::Notify::new());
            self.reservation_notify = Some(notify);
        }

        // Spawn web seeds if not already seeding
        if self.state != TorrentState::Seeding {
            self.spawn_web_seeds();
            self.assign_pieces_to_web_seeds();
        }

        // M147: Set up ConnectPool — semaphore gates connection attempts only.
        // Permits are released on HandshakeComplete, not held for peer lifetime.
        let connect_semaphore = Arc::new(tokio::sync::Semaphore::new(
            self.effective_max_connections(),
        ));
        self.connect_semaphore = Arc::clone(&connect_semaphore);
        self.connect_permits.clear();
        // M137: Create PeerStates with the adder's input channel.
        // v0.187.3: pull eviction-ban cap + duration from session settings so
        // user changes via apply_settings take effect on the next spawn.
        let (queue_tx, queue_rx) = mpsc::unbounded_channel();
        let peer_states = Arc::new(crate::peer_states::PeerStates::new_with_config(
            queue_tx,
            self.config.eviction_ban_set_cap,
            std::time::Duration::from_secs(self.config.eviction_ban_duration_secs),
        ));
        self.peer_states = Some(Arc::clone(&peer_states));
        let (adder_connect_tx, adder_connect_rx) = mpsc::channel(64);
        self.connect_rx = Some(adder_connect_rx);
        // M147: ConnectPool semaphore gates connection attempts (released on handshake)
        tokio::spawn(peer_adder::peer_adder_task(
            queue_rx,
            Arc::clone(&connect_semaphore),
            Arc::clone(&peer_states),
            Arc::clone(&self.ban_manager),
            Arc::clone(&self.ip_filter),
            adder_connect_tx,
        ));

        let mut unchoke_interval = tokio::time::interval(Duration::from_secs(10));
        let mut rate_interval = tokio::time::interval(Duration::from_secs(2));
        rate_interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
        let mut optimistic_interval = tokio::time::interval(Duration::from_secs(30));
        let mut refill_interval = tokio::time::interval(Duration::from_millis(100));
        let mut dht_requery_sleep = Box::pin(tokio::time::sleep(Duration::ZERO));
        let mut suggest_interval = if self.config.suggest_mode {
            Some(tokio::time::interval(Duration::from_secs(30)))
        } else {
            None
        };
        // M136: 1s steal-queue maintenance tick.
        let mut turnover_interval = tokio::time::interval(Duration::from_secs(1));
        let mut pipeline_tick_interval = tokio::time::interval(Duration::from_secs(1));
        // M77: Skip missed ticks — safety-net notify should fire at most once/second
        pipeline_tick_interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
        let mut end_game_tick_interval = tokio::time::interval(Duration::from_millis(200));
        end_game_tick_interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
        let mut diag_interval = tokio::time::interval(Duration::from_secs(5));
        // M108: 30s connection success rate summary for variance diagnosis.
        let mut conn_stats_interval = tokio::time::interval(Duration::from_secs(30));
        // M107: 5s metadata piece timeout — only meaningful in FetchingMetadata state
        let mut metadata_timeout_interval = tokio::time::interval(Duration::from_secs(5));
        // M103: 50ms debounce for reactive snapshot (was 500ms fixed interval)
        // M147: 1s soft reap interval — disconnects connecting peers without TCP SYN-ACK
        let mut soft_reap_interval = tokio::time::interval(Duration::from_secs(1));
        // M148: 2s proactive eviction — breaks the catch-22 where LivePool fills with
        // deadweight and no HandshakeComplete events arrive to trigger eviction.
        let mut eviction_interval = tokio::time::interval(Duration::from_secs(2));
        eviction_interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);

        // Don't fire immediately for the first tick
        unchoke_interval.tick().await;
        optimistic_interval.tick().await;
        refill_interval.tick().await;
        // Note: dht_requery_sleep uses Sleep (not Interval), no initial tick skip needed
        if let Some(ref mut si) = suggest_interval {
            si.tick().await; // skip initial tick
        }
        turnover_interval.tick().await;
        pipeline_tick_interval.tick().await;
        end_game_tick_interval.tick().await;
        diag_interval.tick().await;
        conn_stats_interval.tick().await;
        metadata_timeout_interval.tick().await;
        soft_reap_interval.tick().await;
        eviction_interval.tick().await;

        // Initial tracker announce (Started event) — non-blocking, fires via select! arm
        // DHT announce (v4 + v6) — dual-swarm for hybrid torrents
        if self.state == TorrentState::Downloading && self.config.enable_dht {
            // Primary hash (v1 or best_v1)
            if let Some(dht) = self.current_dht()
                && let Err(e) = dht.announce(self.info_hash, self.config.listen_port).await
            {
                warn!("DHT v4 announce failed: {e}");
            }
            if let Some(dht6) = self.current_dht_v6()
                && let Err(e) = dht6.announce(self.info_hash, self.config.listen_port).await
            {
                debug!("DHT v6 announce failed: {e}");
            }
            // Dual-swarm: also announce v2 hash (truncated) for hybrid torrents
            if self.info_hashes.is_hybrid()
                && let Some(v2) = self.info_hashes.v2
            {
                let v2_as_v1 = Id20(v2.0[..20].try_into().unwrap());
                if v2_as_v1 != self.info_hash {
                    if let Some(dht) = self.current_dht()
                        && let Err(e) = dht.announce(v2_as_v1, self.config.listen_port).await
                    {
                        debug!("DHT v4 dual-swarm announce failed: {e}");
                    }
                    if let Some(dht6) = self.current_dht_v6()
                        && let Err(e) = dht6.announce(v2_as_v1, self.config.listen_port).await
                    {
                        debug!("DHT v6 dual-swarm announce failed: {e}");
                    }
                }
            }
        }

        // I2P accept loop: spawn a background task that feeds incoming I2P
        // connections back via a channel, so the select! arm can handle them.
        if self.config.enable_i2p
            && let Some(ref sam) = self.sam_session
        {
            let (tx, rx) = mpsc::channel(16);
            let sam = Arc::clone(sam);
            tokio::spawn(async move {
                loop {
                    match sam.accept().await {
                        Ok(stream) => {
                            if tx.send(stream).await.is_err() {
                                break; // torrent actor dropped
                            }
                        }
                        Err(e) => {
                            warn!("I2P accept error: {e}");
                            tokio::time::sleep(Duration::from_secs(5)).await;
                        }
                    }
                }
            });
            self.i2p_accept_rx = Some(rx);
        }

        loop {
            tokio::select! {
                biased;
                // Events from peers — batch-drain to reduce select! overhead.
                // At 100 MB/s we get ~6K events/sec; processing one-by-one
                // means 6K select! iterations with waker re-registration.
                // biased; ensures this high-throughput arm is checked first.
                event = self.event_rx.recv() => {
                    if let Some(event) = event {
                        // M182: ping the per-peer event_drain Notify so
                        // the reader's BackpressureQueue retries any
                        // spilled events. Looked up from peers by
                        // event.peer_addr (most variants carry one);
                        // events without a peer (PexPeers,
                        // TrackersReceived, WebSeed*) skip the ping —
                        // they don't fill the per-peer event channel.
                        Self::ping_event_drain(&self.peers, &event);
                        self.handle_peer_event(event)
                            .instrument(tracing::debug_span!("handle_peer_event"))
                            .await;
                        // Drain up to 512 more ready events without re-entering select!
                        for _ in 0..512 {
                            match self.event_rx.try_recv() {
                                Ok(event) => {
                                    Self::ping_event_drain(&self.peers, &event);
                                    self.handle_peer_event(event).await;
                                }
                                Err(_) => break,
                            }
                        }
                    }
                }
                // Async piece verification results
                Some(result) = self.verify_result_rx.recv() => {
                    self.pending_verify.remove(&result.piece);
                    // Guard: ignore stale/duplicate results for already-verified pieces
                    let dominated = self.chunk_tracker.as_ref()
                        .is_some_and(|ct| ct.bitfield().get(result.piece));
                    if !dominated {
                        if result.passed {
                            self.on_piece_verified(result.piece).await;
                        } else {
                            self.on_piece_hash_failed(result.piece).await;
                            // M73: Drivers pick up released pieces automatically via shared state
                        }
                    }
                }
                // M96: Hash pool verification results
                Some(result) = self.hash_result_rx.recv() => {
                    self.handle_hash_result(result).await;
                }
                // Commands from handle
                cmd = self.cmd_rx.recv() => {
                    match cmd {
                        Some(TorrentCommand::AddPeers { peers, source }) => {
                            self.handle_add_peers(peers, source);
                        }
                        Some(TorrentCommand::Stats { reply }) => {
                            let _ = reply.send(self.make_stats());
                        }
                        Some(TorrentCommand::Pause) => {
                            self.handle_pause().await;
                        }
                        Some(TorrentCommand::Queue) => {
                            self.handle_queue();
                        }
                        Some(TorrentCommand::Resume) => {
                            self.handle_resume().await;
                        }
                        Some(TorrentCommand::ForceResume) => {
                            self.user_forced = true;
                            self.handle_resume().await;
                        }
                        Some(TorrentCommand::SetCategory { category, reply }) => {
                            // M170: update the per-torrent category label.
                            // Marks resume as dirty so the next periodic
                            // save captures it.
                            self.config.category = category;
                            self.need_save_resume = true;
                            let _ = reply.send(());
                        }
                        Some(TorrentCommand::SetTags { tags, reply }) => {
                            // M171: replace the per-torrent tag set. Marks
                            // resume as dirty so the next periodic save
                            // captures it. `make_stats()` reads
                            // `self.config.tags` directly so the change is
                            // immediately visible to the next `stats()`
                            // call.
                            self.config.tags = tags;
                            self.need_save_resume = true;
                            let _ = reply.send(());
                        }
                        Some(TorrentCommand::GetWebSeeds { reply }) => {
                            // M171 Lane B: union of BEP 19 `url-list` and
                            // BEP 17 `httpseeds`. Order: BEP 19 first, then
                            // BEP 17 — matches the wire order. Returns an
                            // empty vec when metadata hasn't resolved yet
                            // (magnet still fetching info dict).
                            let urls = match &self.meta {
                                Some(meta) => {
                                    let mut v = Vec::with_capacity(
                                        meta.url_list.len() + meta.httpseeds.len(),
                                    );
                                    v.extend(meta.url_list.iter().cloned());
                                    v.extend(meta.httpseeds.iter().cloned());
                                    v
                                }
                                None => Vec::new(),
                            };
                            let _ = reply.send(urls);
                        }
                        Some(TorrentCommand::GetPieceStates { reply }) => {
                            // M171 Lane B: snapshot per-piece state as qBt
                            // codes. Returns an empty vec when metadata
                            // hasn't resolved (piece count unknown).
                            let states = match self.atomic_states.as_ref() {
                                Some(atomic) => atomic.snapshot(),
                                None => Vec::new(),
                            };
                            let _ = reply.send(states);
                        }
                        Some(TorrentCommand::GetPieceHashes { offset, limit, reply }) => {
                            // M171 Lane B: v1 piece hashes live in
                            // `meta.info.pieces` (20-byte SHA-1 concat);
                            // v2-only piece hashes live in
                            // `meta_v2.piece_layers` values (32-byte
                            // SHA-256 concat). Hybrid prefers v1 because
                            // the qBt client ecosystem treats v1 as the
                            // canonical hash surface.
                            //
                            // M245 L3: select the RAW bytes for the requested
                            // window ONLY (cheap chunk-slice clones of resident
                            // metadata) and hand them back unencoded. The old
                            // path hex-encoded EVERY hash on this recv loop and
                            // then threw all but the window away; the
                            // `hex::encode` now happens in the handle method off
                            // the loop. `skip(offset).take(limit)` reproduces the
                            // old `[offset, offset+limit)`-clamped-to-len window.
                            let offset = offset as usize;
                            let limit = limit as usize;
                            let raw: Vec<Vec<u8>> = match self.version {
                                irontide_core::TorrentVersion::V1Only
                                | irontide_core::TorrentVersion::Hybrid => self
                                    .meta
                                    .as_ref()
                                    .map(|meta| {
                                        meta.info
                                            .pieces
                                            .chunks_exact(20)
                                            .skip(offset)
                                            .take(limit)
                                            .map(<[u8]>::to_vec)
                                            .collect::<Vec<Vec<u8>>>()
                                    })
                                    .unwrap_or_default(),
                                irontide_core::TorrentVersion::V2Only => self
                                    .meta_v2
                                    .as_ref()
                                    .map(|m| {
                                        m.piece_layers
                                            .values()
                                            .flat_map(|v| v.chunks_exact(32))
                                            .skip(offset)
                                            .take(limit)
                                            .map(<[u8]>::to_vec)
                                            .collect::<Vec<Vec<u8>>>()
                                    })
                                    .unwrap_or_default(),
                            };
                            let _ = reply.send(raw);
                        }
                        Some(TorrentCommand::SaveResumeData { reply }) => {
                            let result = self.build_resume_data();
                            let _ = reply.send(result);
                        }
                        Some(TorrentCommand::TakeResumeIfDirty { reply }) => {
                            // M245 F1 — atomic take. ATOMICITY GUARD: there must
                            // be NO `.await` between reading `need_save_resume`
                            // and clearing it. The actor processes commands
                            // serially, so this whole arm is one indivisible
                            // turn — `build_resume_data()` is synchronous (no
                            // yield). Any `need_save_resume = true` set by
                            // another command lands strictly BEFORE this turn
                            // (captured here) or strictly AFTER (preserved for
                            // the next cycle); it can never be lost to a clear
                            // that races the build, the pre-M245 stats→save→
                            // clear three-step bug. The flag is cleared ONLY on
                            // a successful build, so a build error keeps the
                            // torrent dirty for retry.
                            let result = if self.need_save_resume {
                                let built = self.build_resume_data();
                                if built.is_ok() {
                                    self.need_save_resume = false;
                                }
                                built.map(Some)
                            } else {
                                Ok(None)
                            };
                            let _ = reply.send(result);
                        }
                        Some(TorrentCommand::SetFilePriority { index, priority, reply }) => {
                            // M246: range-scope the synchronous correctness-bearing passes
                            // (wanted_pieces / atomic_states / piece_tracker — they gate
                            // dispatch and must be coherent the instant the reply is sent)
                            // to the changed file's pieces, and DEFER the advisory global
                            // order-map rebuild to the coalescing 1 s pipeline tick by
                            // setting `order_map_dirty`, instead of running four
                            // O(num_pieces) passes on the recv loop. A GUI batch of M files
                            // (M back-to-back commands) now sets the flag M times but
                            // triggers a single rebuild.
                            match self.apply_file_priority_scoped(index, priority) {
                                Ok((first, last)) => {
                                    self.sync_piece_states_for_range(first, last);
                                    if let Some(ref mut pt) = self.piece_tracker {
                                        for piece in first..=last {
                                            if self.wanted_pieces.get(piece) {
                                                pt.mark_wanted(piece);
                                            } else {
                                                pt.mark_unwanted(piece);
                                            }
                                        }
                                    }
                                    self.order_map_dirty = true;
                                    let _ = reply.send(Ok(()));
                                }
                                Err(e) => {
                                    let _ = reply.send(Err(e));
                                }
                            }
                        }
                        Some(TorrentCommand::FilePriorities { reply }) => {
                            let _ = reply.send(self.file_priorities.clone());
                        }
                        Some(TorrentCommand::ForceReannounce) => {
                            self.tracker_manager.force_reannounce();
                        }
                        Some(TorrentCommand::TrackerList { reply }) => {
                            let _ = reply.send(self.tracker_manager.tracker_list());
                        }
                        Some(TorrentCommand::Scrape { reply }) => {
                            let result = self.tracker_manager.scrape().await;
                            if let Some((ref url, ref info)) = result {
                                post_alert(&self.alert_tx, &self.alert_mask, AlertKind::ScrapeReply {
                                    info_hash: self.info_hash,
                                    url: url.clone(),
                                    complete: info.complete,
                                    incomplete: info.incomplete,
                                    downloaded: info.downloaded,
                                });
                            }
                            let _ = reply.send(result);
                        }
                        Some(TorrentCommand::OpenFile { file_index, reply }) => {
                            let result = self.handle_open_file(file_index);
                            let _ = reply.send(result);
                        }
                        Some(TorrentCommand::IncomingPeer { stream, addr }) => {
                            self.spawn_peer_from_stream_with_mode(
                                addr,
                                stream,
                                Some(irontide_wire::mse::EncryptionMode::Disabled),
                            );
                        }
                        Some(TorrentCommand::UpdateExternalIp { ip }) => {
                            self.external_ip = Some(ip);
                            post_alert(
                                &self.alert_tx,
                                &self.alert_mask,
                                AlertKind::ExternalIpDetected { ip },
                            );
                        }
                        Some(TorrentCommand::MoveStorage { new_path, reply }) => {
                            let result = self.handle_move_storage(new_path).await;
                            let _ = reply.send(result);
                        }
                        Some(TorrentCommand::SpawnSslPeer { addr, stream }) => {
                            // TLS is already completed; encryption is handled by TLS layer
                            self.spawn_peer_from_stream_with_mode(
                                addr,
                                stream.0,
                                Some(irontide_wire::mse::EncryptionMode::Disabled),
                            );
                        }
                        Some(TorrentCommand::SetDownloadLimit { bytes_per_sec, reply }) => {
                            self.download_bucket.lock().set_rate(bytes_per_sec);
                            let _ = reply.send(());
                        }
                        Some(TorrentCommand::SetUploadLimit { bytes_per_sec, reply }) => {
                            self.upload_bucket.set_rate(bytes_per_sec);
                            let _ = reply.send(());
                        }
                        Some(TorrentCommand::DownloadLimit { reply }) => {
                            let _ = reply.send(self.download_bucket.lock().rate());
                        }
                        Some(TorrentCommand::UploadLimit { reply }) => {
                            let _ = reply.send(self.upload_bucket.rate());
                        }
                        Some(TorrentCommand::SetSequentialDownload { enabled, reply }) => {
                            self.config.sequential_download = enabled;
                            let _ = reply.send(());
                        }
                        Some(TorrentCommand::IsSequentialDownload { reply }) => {
                            let _ = reply.send(self.config.sequential_download);
                        }
                        Some(TorrentCommand::SetSuperSeeding { enabled, reply }) => {
                            self.config.super_seeding = enabled;
                            self.super_seed = if enabled {
                                Some(crate::super_seed::SuperSeedState::new())
                            } else {
                                None
                            };
                            let _ = reply.send(());
                        }
                        Some(TorrentCommand::IsSuperSeeding { reply }) => {
                            let _ = reply.send(self.config.super_seeding);
                        }
                        Some(TorrentCommand::SetSeedMode { enabled, reply }) => {
                            self.handle_set_seed_mode(enabled);
                            let _ = reply.send(());
                        }
                        Some(TorrentCommand::SetSeedRatioLimit { limit, reply }) => {
                            self.config.seed_ratio_limit = limit;
                            self.need_save_resume = true;
                            let _ = reply.send(());
                        }
                        Some(TorrentCommand::AddTracker { url }) => {
                            self.tracker_manager.add_tracker_url(&url);
                        }
                        Some(TorrentCommand::ReplaceTrackers { urls, reply }) => {
                            self.tracker_manager.replace_all(&urls);
                            let _ = reply.send(());
                        }
                        Some(TorrentCommand::ForceRecheck { reply }) => {
                            self.handle_force_recheck(reply).await;
                        }
                        Some(TorrentCommand::RenameFile { file_index, new_name, reply }) => {
                            let result = self.handle_rename_file(file_index, new_name).await;
                            let _ = reply.send(result);
                        }
                        Some(TorrentCommand::SetMaxConnections { limit, reply }) => {
                            self.max_connections = limit;
                            let _ = reply.send(());
                        }
                        Some(TorrentCommand::MaxConnections { reply }) => {
                            let _ = reply.send(self.max_connections);
                        }
                        Some(TorrentCommand::SetMaxUploads { limit, reply }) => {
                            self.choker.set_unchoke_slots(limit);
                            let _ = reply.send(());
                        }
                        Some(TorrentCommand::MaxUploads { reply }) => {
                            let _ = reply.send(self.choker.unchoke_slots());
                        }
                        Some(TorrentCommand::GetPeerInfo { reply }) => {
                            let _ = reply.send(self.build_peer_info());
                        }
                        Some(TorrentCommand::GetDownloadQueue { reply }) => {
                            let _ = reply.send(self.build_download_queue());
                        }
                        Some(TorrentCommand::HavePiece { index, reply }) => {
                            let has = self.chunk_tracker.as_ref()
                                .is_some_and(|ct| ct.has_piece(index));
                            let _ = reply.send(has);
                        }
                        Some(TorrentCommand::PieceAvailability { reply }) => {
                            // M246 (D5): this O(num_peers * num_pieces) scan is the
                            // only super-linear residual handler, but it is a RARE
                            // on-demand read query — its sole caller is the public
                            // `piece_availability()` accessor, driven by the client's
                            // GUI/WebUI piece-availability bar, never per-tick or
                            // per-message. Incremental maintenance (hooking every
                            // connect / disconnect / HAVE to keep a running counter)
                            // is deliberately out of the L4 recv-loop-hardening scope:
                            // it would add steady-state cost to the hot path to speed
                            // up a query a human triggers a few times a minute.
                            let mut avail = vec![0u32; self.num_pieces as usize];
                            for peer in self.peers.values() {
                                for i in 0..self.num_pieces {
                                    if peer.bitfield.get(i) {
                                        avail[i as usize] += 1;
                                    }
                                }
                            }
                            let _ = reply.send(avail);
                        }
                        Some(TorrentCommand::FileProgress { reply }) => {
                            let _ = reply.send(self.compute_file_progress());
                        }
                        Some(TorrentCommand::InfoHashes { reply }) => {
                            let _ = reply.send(self.info_hashes.clone());
                        }
                        Some(TorrentCommand::TorrentFile { reply }) => {
                            let _ = reply.send(self.meta.clone());
                        }
                        Some(TorrentCommand::TorrentFileV2 { reply }) => {
                            let _ = reply.send(self.meta_v2.clone());
                        }
                        Some(TorrentCommand::ForceDhtAnnounce) => {
                            self.handle_force_dht_announce().await;
                        }
                        Some(TorrentCommand::ReadPiece { index, reply }) => {
                            let result = self.handle_read_piece(index).await;
                            let _ = reply.send(result);
                        }
                        Some(TorrentCommand::FlushCache { reply }) => {
                            let result = self.handle_flush_cache().await;
                            let _ = reply.send(result);
                        }
                        Some(TorrentCommand::ClearError) => {
                            self.handle_clear_error().await;
                        }
                        Some(TorrentCommand::ClearSaveResumeFlag) => {
                            self.need_save_resume = false;
                        }
                        Some(TorrentCommand::MarkResumeDirty) => {
                            // M245 F1 — re-arm after a failed resume WRITE so the
                            // torrent is retried next save cycle (see
                            // `TakeResumeIfDirty`).
                            self.need_save_resume = true;
                        }
                        Some(TorrentCommand::RestoreResumeBitmap { pieces, reply }) => {
                            let result = self.handle_restore_resume_bitmap(pieces);
                            let _ = reply.send(result);
                        }
                        Some(TorrentCommand::RestoreWebSeedStats { stats, reply }) => {
                            self.web_seed_stats = stats;
                            let _ = reply.send(Ok(()));
                        }
                        Some(TorrentCommand::GetPeerSourceCounts { reply }) => {
                            let _ = reply.send((self.pex_peer_count, self.lsd_peer_count));
                        }
                        Some(TorrentCommand::QueryUnchokeDurations { reply }) => {
                            let mut out = self.unchoke_durations.clone();
                            // Merge in each currently-live peer's transient
                            // accumulator + any in-flight unchoke window.
                            let now = Instant::now();
                            for peer in self.peers.values() {
                                let mut delta = peer.unchoke_duration_total;
                                if let Some(start) = peer.am_unchoke_started_at {
                                    delta += now.duration_since(start);
                                }
                                if !delta.is_zero() {
                                    *out.entry(peer.addr).or_default() += delta;
                                }
                            }
                            let _ = reply.send(out);
                        }
                        Some(TorrentCommand::GetWebSeedStats { reply }) => {
                            let snapshot: Vec<_> = self.web_seed_stats.values().cloned().collect();
                            let _ = reply.send(snapshot);
                        }
                        Some(TorrentCommand::FileStatus { reply }) => {
                            let _ = reply.send(self.build_file_status());
                        }
                        Some(TorrentCommand::Flags { reply }) => {
                            let _ = reply.send(self.build_flags());
                        }
                        Some(TorrentCommand::SetFlags { flags, reply }) => {
                            self.apply_set_flags(flags).await;
                            let _ = reply.send(());
                        }
                        Some(TorrentCommand::UnsetFlags { flags, reply }) => {
                            self.apply_unset_flags(flags).await;
                            let _ = reply.send(());
                        }
                        Some(TorrentCommand::ConnectPeer { addr }) => {
                            self.handle_connect_peer(addr);
                        }
                        Some(TorrentCommand::PreResolvedMetadata { info_bytes, peers }) => {
                            self.handle_pre_resolved_metadata(info_bytes, peers).await;
                        }
                        #[cfg(feature = "test-util")]
                        Some(TorrentCommand::TestInjectMetadata { info_bytes, reply }) => {
                            // Reuses the existing handle_pre_resolved_metadata at torrent.rs:3665.
                            // Synchronous because the test caller depends on completion before
                            // proceeding (unlike the production resolver which is fire-and-forget).
                            self.handle_pre_resolved_metadata(info_bytes, vec![]).await;
                            let _ = reply.send(());
                        }
                        Some(TorrentCommand::GetMeta { reply }) => {
                            // v0.173.1: single source of truth for torrent
                            // metadata — replaces `SessionActor.TorrentEntry.meta`
                            // so magnet-added torrents no longer lose the info
                            // dict between the TorrentActor and the session.
                            let _ = reply.send(self.meta.clone());
                        }
                        Some(TorrentCommand::UpdateSettings(delta)) => {
                            self.handle_update_settings(&delta);
                        }
                        Some(TorrentCommand::Shutdown) => {
                            info!("torrent actor: received Shutdown command, exiting");
                            self.shutdown_web_seeds().await;
                            self.shutdown_peers().await;
                            return;
                        }
                        None => {
                            warn!("torrent actor: cmd_rx channel closed (all senders dropped), exiting");
                            self.shutdown_web_seeds().await;
                            self.shutdown_peers().await;
                            return;
                        }
                    }
                }
                // Async disk write errors
                Some(err) = self.write_error_rx.recv() => {
                    warn!(piece = err.piece, begin = err.begin, "async disk write failed: {}", err.error);
                }
                // Accept incoming peers
                result = accept_incoming(&mut self.listener) => {
                    if let Ok((stream, addr)) = result {
                        self.spawn_peer_from_stream(addr, stream);
                    }
                }
                // Accept incoming I2P peers (M41)
                stream = accept_i2p(&mut self.i2p_accept_rx) => {
                    if let Some(stream) = stream {
                        self.handle_i2p_incoming(stream);
                    }
                }
                // Rate update timer (2s) — decoupled from the 10s unchoke
                // interval so the GUI sees responsive DL/UL numbers.
                _ = rate_interval.tick() => {
                    self.update_peer_rates();
                }
                // Unchoke timer
                _ = unchoke_interval.tick() => {
                    // M144 deviation from BEP 3 §3 (10s choking algorithm):
                    // We skip the choker during download — intentional rqbit-parity
                    // decision. BEP 3 specifies a 10s choking interval to manage
                    // upload slots via tit-for-tat. But IronTide unchokes all peers
                    // unconditionally on connect (M107); running the choker every
                    // 10s re-chokes most peers, breaking the reciprocity that drove
                    // the original unchoke. Only run during seeding/sharing where
                    // upload-slot management matters. Reviewed M174.
                    if self.state == TorrentState::Seeding
                        || self.state == TorrentState::Sharing
                    {
                        self.slot_tuner.observe(self.upload_bytes_interval);
                        self.choker.observe_throughput(self.upload_bytes_interval);
                        self.upload_bytes_interval = 0;
                        self.choker.set_unchoke_slots(self.slot_tuner.current_slots());
                        self.run_choker().await;
                        // v0.187.3: a normal tick satisfies the immediate-tick
                        // request, so clear the flag.
                        self.force_immediate_choker_tick = false;
                    } else {
                        self.upload_bytes_interval = 0;
                    }
                    // Update streaming cursors and piece priorities
                    self.update_streaming_cursors();
                    // Update auto-sequential hysteresis (M45)
                    if self.config.auto_sequential {
                        self.auto_sequential_active = crate::piece_selector::evaluate_auto_sequential(
                            self.piece_owner.iter().filter(|o| o.is_some()).count(),
                            self.peers.len(),
                            self.auto_sequential_active,
                        );
                    }
                    // Periodic web seed piece reassignment (moved from dht_recheck timer)
                    self.assign_pieces_to_web_seeds();
                }
                // Optimistic unchoke timer
                _ = optimistic_interval.tick() => {
                    self.rotate_optimistic();
                }
                // M107: Receive connect requests from the peer adder task
                Some(connect_peer) = async {
                    match self.connect_rx.as_mut() {
                        Some(rx) => rx.recv().await,
                        None => std::future::pending().await,
                    }
                } => {
                    self.handle_adder_connect(connect_peer);
                }
                () = &mut dht_requery_sleep, if self.state != TorrentState::Complete
                    && self.state != TorrentState::Paused
                    && self.state != TorrentState::Queued
                    && self.state != TorrentState::Seeding
                    && self.state != TorrentState::Stopped => {
                    self.run_dht_requery().await;
                    dht_requery_sleep = Box::pin(tokio::time::sleep(Duration::from_mins(1)));
                }
                // M143: Tracker re-announce timer — starts a background announce,
                // never blocks. Only fires when no announce is in-flight.
                // Also fires during FetchingMetadata so magnets with &tr= URLs
                // can discover peers before metadata arrives.
                () = async {
                    match self.tracker_manager.next_announce_in() {
                        Some(dur) => tokio::time::sleep(dur).await,
                        None => std::future::pending().await,
                    }
                }, if self.tracker_result_rx.is_none() => {
                    let left = self.calculate_left();
                    self.tracker_result_rx = Some(self.tracker_manager.start_announce(
                        irontide_tracker::AnnounceEvent::None,
                        self.uploaded,
                        self.downloaded,
                        left,
                    ));
                }
                // M143: Streaming tracker results — process each tracker
                // response as it arrives, without blocking the actor loop.
                result = async {
                    match self.tracker_result_rx.as_mut() {
                        Some(rx) => rx.recv().await,
                        None => std::future::pending().await,
                    }
                } => {
                    match result {
                        Some(batch) => {
                            let (peers, outcome) = self.tracker_manager.process_tracker_result(batch);
                            self.fire_tracker_alerts(&[outcome]);
                            if !peers.is_empty() {
                                debug!(count = peers.len(), "tracker returned peers (streaming)");
                                self.handle_add_peers(peers, PeerSource::Tracker);
                            }
                        }
                        None => {
                            // All trackers responded — clear in-flight state so
                            // the timer arm can re-fire for the next announce cycle.
                            self.tracker_result_rx = None;
                        }
                    }
                }
                // DHT v4 peer discovery
                result = async {
                    match &mut self.dht_peers_rx {
                        Some(rx) => rx.recv().await,
                        None => std::future::pending().await,
                    }
                } => {
                    if let Some(peers) = result {
                        debug!(count = peers.len(), "DHT v4 returned peers");
                        self.handle_add_peers(peers, PeerSource::Dht);
                    } else {
                        debug!("DHT v4 peer search exhausted");
                        self.dht_peers_rx = None;
                    }
                }
                // DHT v6 peer discovery
                result = async {
                    match &mut self.dht_v6_peers_rx {
                        Some(rx) => rx.recv().await,
                        None => std::future::pending().await,
                    }
                } => {
                    if let Some(peers) = result {
                        debug!(count = peers.len(), "DHT v6 returned peers");
                        self.dht_v6_empty_count = 0; // V6 is working, reset
                        self.handle_add_peers(peers, PeerSource::Dht);
                    } else {
                        self.dht_v6_peers_rx = None;
                        self.dht_v6_empty_count += 1;
                        if self.dht_v6_empty_count == 30 {
                            debug!("DHT v6 routing table persistently empty, giving up");
                        } else if self.dht_v6_empty_count < 30 {
                            debug!("DHT v6 peer search exhausted");
                        }
                    }
                }
                // Dual-swarm: DHT v4 v2-hash peer discovery (hybrid)
                result = async {
                    match &mut self.dht_v2_peers_rx {
                        Some(rx) => rx.recv().await,
                        None => std::future::pending().await,
                    }
                } => {
                    if let Some(peers) = result {
                        debug!(count = peers.len(), "DHT v4 v2-swarm returned peers");
                        self.handle_add_peers(peers, PeerSource::Dht);
                    } else {
                        debug!("DHT v4 v2-swarm peer search exhausted");
                        self.dht_v2_peers_rx = None;
                    }
                }
                // Dual-swarm: DHT v6 v2-hash peer discovery (hybrid)
                result = async {
                    match &mut self.dht_v6_v2_peers_rx {
                        Some(rx) => rx.recv().await,
                        None => std::future::pending().await,
                    }
                } => {
                    if let Some(peers) = result {
                        debug!(count = peers.len(), "DHT v6 v2-swarm returned peers");
                        self.handle_add_peers(peers, PeerSource::Dht);
                    } else {
                        debug!("DHT v6 v2-swarm peer search exhausted");
                        self.dht_v6_v2_peers_rx = None;
                    }
                }
                // M44: Suggest cached pieces timer
                _ = async {
                    match suggest_interval {
                        Some(ref mut interval) => interval.tick().await,
                        None => std::future::pending().await,
                    }
                } => {
                    self.suggest_cached_pieces().await;
                }
                _ = turnover_interval.tick() => {
                    self.run_steal_queue_maintenance();
                }
                // Pipeline tick (1s) — update EWMA, snub detection, peer scoring
                _ = pipeline_tick_interval.tick() => {
                    let snub_timeout = Duration::from_secs(u64::from(self.config.snub_timeout_secs));

                    for (_addr, peer) in &mut self.peers {
                        peer.pipeline.tick();

                        // Snub detection: no data for snub_timeout_secs while unchoked
                        if !peer.peer_choking && !peer.snubbed {
                            let idle = peer.last_data_received
                                .is_some_and(|t| t.elapsed() > snub_timeout);
                            if idle {
                                peer.snubbed = true;
                                // M106: Count pending requests as timed-out blocks
                                peer.blocks_timed_out = peer.blocks_timed_out
                                    .saturating_add(peer.pending_requests.len() as u64);
                                debug!(%_addr, "peer snubbed (no data for {}s)", self.config.snub_timeout_secs);
                            }
                        }
                    }

                    // Refresh cached peer rates for steal decisions (avoids
                    // rebuilding a FxHashMap from all peers on every block arrival).
                    self.refresh_peer_rates();

                    // M73: Periodic endgame activation check (was in batch_fill_all_peers)
                    if !self.end_game.is_active() {
                        self.check_end_game_activation();
                    }

                    self.tick_dispatch_safety_wake();

                    // M138: Proactive choke rotation — every tick, evict up to N choked peers
                    if self.config.choke_rotation_max_evictions > 0
                        && self.state == TorrentState::Downloading
                    {
                        self.run_choke_rotation();
                    }

                    // M246: coalesced order-map rebuild. The SetFilePriority arm sets
                    // `order_map_dirty` instead of building inline; a batch of priority
                    // changes collapses to ONE rebuild here (at most ~1 s later — the
                    // order map is an advisory dispatch walk-order hint, and the
                    // piece_tracker already gates wanted/reserved synchronously).
                    if self.order_map_dirty {
                        self.rebuild_order_map_now();
                    }
                }
                // (M75: peer tasks handle dispatch via integrated select! arm)
                // End-game refill tick (200ms) — replace reactive per-block cascade
                // with periodic batch refill. All peers with available pipeline slots
                // get new end-game blocks, preventing idle stalls between ticks.
                _ = end_game_tick_interval.tick(), if self.end_game.is_active() => {
                    let addrs: Vec<SocketAddr> = self.peers.iter()
                        .filter(|(_, p)| !p.peer_choking && p.pending_requests.len() < END_GAME_DEPTH)
                        .map(|(addr, _)| *addr)
                        .collect();
                    for addr in addrs {
                        self.request_end_game_block(addr).await;
                    }
                }
                // M107: Metadata piece timeout — re-request timed-out pieces from
                // all non-rejected peers that support ut_metadata.
                _ = metadata_timeout_interval.tick(), if self.state == TorrentState::FetchingMetadata => {
                    // Collect timed-out pieces (immutable borrow, then release).
                    let timed_out: Vec<u32> = self
                        .metadata_downloader
                        .as_ref()
                        .map(MetadataDownloader::timed_out_pieces)
                        .unwrap_or_default();

                    if !timed_out.is_empty() {
                        debug!(count = timed_out.len(), "metadata pieces timed out, re-requesting");

                        // Collect eligible peers (non-rejected, support ut_metadata).
                        // Clone cmd_tx to avoid holding borrows across the send loop.
                        let eligible_senders: Vec<mpsc::Sender<PeerCommand>> = self
                            .peers
                            .iter()
                            .filter(|(addr, peer)| {
                                self.metadata_downloader
                                    .as_ref()
                                    .is_some_and(|dl| !dl.is_rejected(addr))
                                    && peer
                                        .ext_handshake
                                        .as_ref()
                                        .is_some_and(|h| h.metadata_size.is_some())
                            })
                            .map(|(_, peer)| peer.cmd_tx.clone())
                            .collect();

                        // Send requests (uses cloned senders, no borrow conflict).
                        for cmd_tx in &eligible_senders {
                            for &piece in &timed_out {
                                let _ = cmd_tx.try_send(PeerCommand::RequestMetadata { piece });
                            }
                        }

                        // Update request times in the downloader.
                        if let Some(ref mut dl) = self.metadata_downloader {
                            for piece in timed_out {
                                dl.reset_request_time(piece);
                            }
                        }
                    }
                }
                // Periodic download status report (5s)
                _ = diag_interval.tick() => {
                    // Heartbeat: log state regardless of download state
                    {
                        let have = self.chunk_tracker.as_ref().map_or(0, |ct| ct.bitfield().count_ones());
                        let eg = self.end_game.is_active();
                        let eg_blocks = self.end_game.block_count();
                        info!(state = ?self.state, have, total = self.num_pieces, end_game = eg, eg_blocks, "heartbeat");
                    }
                    if self.state == TorrentState::Downloading {
                        let have = self.chunk_tracker.as_ref().map_or(0, |ct| ct.bitfield().count_ones());
                        let in_flight = self.atomic_states.as_ref().map_or(0, |s| s.in_flight_count() as usize);
                        let unchoked = self.peers.values().filter(|p| !p.peer_choking).count();
                        info!(have, in_flight, total = self.num_pieces,
                              downloaded_mb = self.downloaded / (1024 * 1024),
                              peers = self.peers.len(), unchoked,
                              "download progress");
                        for (addr, p) in &self.peers {
                            let last_data = p.last_data_received.map_or(9999, |t| t.elapsed().as_secs());
                            trace!(%addr,
                                   choking = p.peer_choking,
                                   pending = p.pending_requests.len(),
                                   ewma_rate = p.pipeline.ewma_rate() as u64,
                                   last_data_secs = last_data,
                                   bf_ones = p.bitfield.count_ones(),
                                   "peer state");
                        }
                    }
                }
                // M108: 30s connection success rate summary for variance diagnosis
                _ = conn_stats_interval.tick() => {
                    if self.connect_attempts > 0 {
                        let succeeded = self.connect_attempts.saturating_sub(self.connect_failures);
                        let success_pct = (succeeded as f64 / self.connect_attempts as f64 * 100.0) as u32;
                        info!(
                            connected = self.peers.len(),
                            attempted = self.connect_attempts,
                            failed = self.connect_failures,
                            success_rate = %format!("{success_pct}%"),
                            "connection stats"
                        );
                    }
                }
                // M147: Soft reap — disconnect connecting peers without TCP SYN-ACK.
                // v0.173.3: uses the buffer-fill variant + index iteration to reuse
                // soft_reap_buf across ticks without ever moving its heap allocation.
                // SocketAddr is Copy, so indexing into self.soft_reap_buf yields a
                // value copy and does not borrow self.soft_reap_buf for the loop body.
                _ = soft_reap_interval.tick() => {
                    let soft_timeout = self.config.connect_soft_timeout;
                    if soft_timeout > 0 {
                        if let Some(ref ps) = self.peer_states {
                            ps.soft_reap_candidates_into(
                                Duration::from_secs(soft_timeout),
                                &mut self.soft_reap_buf,
                            );
                        } else {
                            self.soft_reap_buf.clear();
                        }
                        for i in 0..self.soft_reap_buf.len() {
                            let peer_addr = self.soft_reap_buf[i];
                            debug!(%peer_addr, soft_timeout, "soft reap: no TCP SYN-ACK");
                            // Remove from connect_permits so RAII drops the permit
                            self.connect_permits.remove(&peer_addr);
                            self.disconnect_peer(peer_addr, "soft reap: no TCP SYN-ACK");
                            if let Some(ref ps) = self.peer_states
                                && let Some(backoff) = ps.mark_dead(peer_addr)
                            {
                                let ps_clone = Arc::clone(ps);
                                tokio::spawn(async move {
                                    tokio::time::sleep(backoff).await;
                                    ps_clone.mark_queued_for_retry(peer_addr);
                                });
                            }
                        }
                        self.soft_reap_buf.clear();
                    }
                }
                // M148 + v0.187.3: Proactive eviction with churn guard.
                //
                //                  PROACTIVE EVICTION POLICY (M148 → v0.187.3)
                //                  ============================================
                //
                //   Tick every 2s
                //   ├─ state == Seeding?                          ──── no-op
                //   ├─ live < (effective_max * 0.95)?             ──── no-op
                //   └─ eviction_history (in last 60s) < limit?    ──── no-op
                //       │
                //       ▼
                //   for up to 5 candidates:
                //     find_eviction_candidate() →
                //       Pass 0  ZeroThroughput     [skipped if state==Seeding]
                //               [skipped if peer.live_since < pass0_grace_secs]
                //               ban 10min, push to banned_set (FIFO cap 1024)
                //       Pass 1  Choked > 10s       no ban
                //       Pass 2  LowThroughput      no ban
                //       Pass 3  Bep40 priority     [only on HandshakeComplete]
                //               no ban
                //
                //     on evict: eviction_history.push_back(now)
                _ = eviction_interval.tick() => {
                    // v0.187.3 / Bug 8a: opportunistically service a pending
                    // immediate-tick request from a recent state transition
                    // (typically Downloading → Seeding). Caps the worst-case
                    // first-unchoke latency at the 2s eviction interval
                    // instead of the 10s unchoke interval.
                    if self.force_immediate_choker_tick
                        && (self.state == TorrentState::Seeding
                            || self.state == TorrentState::Sharing)
                    {
                        self.slot_tuner.observe(self.upload_bytes_interval);
                        self.choker.observe_throughput(self.upload_bytes_interval);
                        self.upload_bytes_interval = 0;
                        self.choker.set_unchoke_slots(self.slot_tuner.current_slots());
                        self.run_choker().await;
                        self.force_immediate_choker_tick = false;
                    }
                    if self.state != TorrentState::Seeding {
                        // v0.187.3 / 3A: prune eviction_history of entries older
                        // than 60s, then gate on the configured limit.
                        let prune_cutoff = std::time::Duration::from_mins(1);
                        while self
                            .eviction_history
                            .front()
                            .copied()
                            .is_some_and(|t| t.elapsed() > prune_cutoff)
                        {
                            self.eviction_history.pop_front();
                        }
                        let limit = self.config.proactive_evictions_per_minute_limit as usize;
                        let window_ok = self.eviction_history.len() < limit;

                        // v0.187.3 / Pressure gate: 0.95 (was 0.75 in v0.187.2).
                        // Higher threshold gives slow-start peers room to ramp
                        // before the eviction loop fires.
                        let should_evict = window_ok
                            && self.peer_states.as_ref().is_some_and(|ps| {
                                let live = ps
                                    .stats
                                    .live
                                    .load(std::sync::atomic::Ordering::Relaxed);
                                #[allow(
                                    clippy::cast_possible_truncation,
                                    clippy::cast_sign_loss
                                )]
                                let threshold =
                                    (self.effective_max_connections() as f32 * 0.95) as u32;
                                debug_assert!(
                                    self.effective_max_connections()
                                        <= crate::torrent_peers::HARD_PEER_CEILING,
                                    "effective_max must be clamped to HARD_PEER_CEILING"
                                );
                                live >= threshold
                            });
                        if should_evict {
                            // Evict up to 5 deadweight per tick, but no more than
                            // (limit - history.len()) total per the sliding window.
                            let max_this_tick = 5.min(limit.saturating_sub(self.eviction_history.len()));
                            for _ in 0..max_this_tick {
                                match self.find_eviction_candidate() {
                                    Some((victim, pass)) => {
                                        debug!(%victim, ?pass, "v0.187.3 proactive eviction");
                                        self.disconnect_peer(victim, "proactive eviction");
                                        if matches!(pass, crate::torrent_peers::EvictionPass::ZeroThroughput)
                                            && let Some(ref ps) = self.peer_states
                                        {
                                            ps.add_eviction_ban(victim);
                                        }
                                        self.eviction_history.push_back(std::time::Instant::now());
                                    }
                                    None => break,
                                }
                            }
                        }

                        // M149: Piece stealing scan (piggybacks on same 2s interval)
                        self.run_piece_steal_scan();
                    }
                }
                // Rate limiter refill (100ms)
                _ = refill_interval.tick() => {
                    let elapsed = Duration::from_millis(100);
                    self.upload_bucket.refill(elapsed);
                    self.download_bucket.lock().refill(elapsed);
                    // Refill per-class buckets and apply mixed-mode (M45)
                    self.rate_limiter_set.refill(elapsed);
                    let (tcp_peers, utp_peers) = self.transport_peer_counts();
                    self.rate_limiter_set.apply_mixed_mode(
                        self.config.mixed_mode_algorithm,
                        tcp_peers,
                        utp_peers,
                        self.config.upload_rate_limit,
                    );
                }
            }

            // M112: drain holepunch attempts (bridging sync disconnect_peer → async try_holepunch)
            for target in std::mem::take(&mut self.holepunch_pending) {
                self.try_holepunch(target).await;
            }
        }
    }

    // ----- Command handlers -----

    /// Compute distributed copy availability across the swarm.
    ///
    /// Returns `(full_copies, fraction, copies_float)` where `fraction` is in thousandths.
    pub(crate) fn distributed_copies(&self) -> (u32, u32, f32) {
        if self.num_pieces == 0 || self.peers.is_empty() {
            return (0, 0, 0.0);
        }

        let num = self.num_pieces as usize;
        let mut availability = vec![0u32; num];

        for peer in self.peers.values() {
            for idx in 0..self.num_pieces {
                if peer.bitfield.get(idx) {
                    availability[idx as usize] += 1;
                }
            }
        }

        let min_avail = availability.iter().copied().min().unwrap_or(0);
        let rarest_count = availability.iter().filter(|&&c| c == min_avail).count() as u32;
        let fraction = ((self.num_pieces - rarest_count) * 1000) / self.num_pieces;
        let copies_float = min_avail as f32 + fraction as f32 / 1000.0;

        (min_avail, fraction, copies_float)
    }

    /// M246 (D5): rare on-demand `O(num_pieces)` read-model builder (the
    /// `GetDownloadQueue` query) — intentionally left on the recv loop; it has
    /// no per-tick / per-message caller, so off-loading would not help the hot path.
    fn build_download_queue(&self) -> Vec<PartialPieceInfo> {
        self.piece_owner
            .iter()
            .enumerate()
            .filter_map(|(piece_index, owner)| {
                owner.map(|_| {
                    let piece_index = piece_index as u32;
                    let blocks_in_piece = self
                        .lengths
                        .as_ref()
                        .map_or(0, |l| l.piece_size(piece_index).div_ceil(l.chunk_size()));
                    PartialPieceInfo {
                        piece_index,
                        blocks_in_piece,
                        blocks_assigned: 0,
                    }
                })
            })
            .collect()
    }

    /// Compute per-file downloaded bytes.
    ///
    /// M246 (D5): rare on-demand `O(num_pieces)` read-model builder (the
    /// `FileProgress` query) — intentionally left on the recv loop; it has
    /// no per-tick / per-message caller, so off-loading would not help the hot path.
    fn compute_file_progress(&self) -> Vec<u64> {
        let Some(meta) = self.meta.as_ref() else {
            return Vec::new();
        };
        let Some(lengths) = self.lengths.as_ref() else {
            return Vec::new();
        };
        let Some(chunk_tracker) = self.chunk_tracker.as_ref() else {
            return Vec::new();
        };

        let files = meta.info.files();
        if files.is_empty() {
            return Vec::new();
        }

        let piece_length = lengths.piece_length();
        let mut result = Vec::with_capacity(files.len());
        let mut file_offset = 0u64;

        for file_entry in &files {
            let file_len = file_entry.length;
            if file_len == 0 {
                result.push(0);
                file_offset += file_len;
                continue;
            }

            let file_end = file_offset + file_len;
            let first_piece = (file_offset / piece_length) as u32;
            let last_piece = ((file_end - 1) / piece_length) as u32;

            let mut downloaded = 0u64;

            for p in first_piece..=last_piece {
                if !chunk_tracker.has_piece(p) {
                    continue;
                }

                let piece_start = lengths.piece_offset(p);
                let piece_end = piece_start + u64::from(lengths.piece_size(p));

                // Clamp to file boundaries
                let overlap_start = piece_start.max(file_offset);
                let overlap_end = piece_end.min(file_end);

                if overlap_start < overlap_end {
                    downloaded += overlap_end - overlap_start;
                }
            }

            result.push(downloaded);
            file_offset = file_end;
        }

        result
    }

    /// Exponential backoff delay for V6 DHT retries (M97).
    /// 100ms, 200ms, 400ms, 800ms, 1600ms, 3200ms, 5000ms (cap).
    fn v6_retry_delay(&self) -> std::time::Duration {
        let base_ms: u64 = 100;
        let max_ms: u64 = 5000;
        let delay_ms = base_ms
            .saturating_mul(
                1u64.checked_shl(self.dht_v6_empty_count)
                    .unwrap_or(u64::MAX),
            )
            .min(max_ms);
        std::time::Duration::from_millis(delay_ms)
    }

    /// Check if enough time has elapsed for the next V6 DHT retry (M97).
    fn should_retry_v6(&self) -> bool {
        let Some(last) = self.dht_v6_last_retry else {
            return true; // First attempt
        };
        last.elapsed() >= self.v6_retry_delay()
    }

    /// Force an immediate DHT announce on all available DHT handles (v4 + v6).
    async fn handle_force_dht_announce(&self) {
        if let Some(dht) = self.current_dht()
            && let Err(e) = dht.announce(self.info_hash, self.config.listen_port).await
        {
            warn!("Force DHT v4 announce failed: {e}");
        }
        if let Some(dht6) = self.current_dht_v6()
            && let Err(e) = dht6.announce(self.info_hash, self.config.listen_port).await
        {
            debug!("Force DHT v6 announce failed: {e}");
        }
        // Dual-swarm: also announce v2 hash for hybrid torrents
        if self.info_hashes.is_hybrid()
            && let Some(v2) = self.info_hashes.v2
        {
            let v2_as_v1 = Id20(v2.0[..20].try_into().unwrap());
            if v2_as_v1 != self.info_hash {
                if let Some(dht) = self.current_dht()
                    && let Err(e) = dht.announce(v2_as_v1, self.config.listen_port).await
                {
                    debug!("Force DHT v4 dual-swarm announce failed: {e}");
                }
                if let Some(dht6) = self.current_dht_v6()
                    && let Err(e) = dht6.announce(v2_as_v1, self.config.listen_port).await
                {
                    debug!("Force DHT v6 dual-swarm announce failed: {e}");
                }
            }
        }
    }

    /// M107: Periodic DHT re-query — discovers new peers during download.
    ///
    /// Replaces the old fixed 30s `dht_recheck_interval`. Clears the adder's
    /// seen set so previously-known peers can be re-evaluated, then issues
    /// fresh `get_peers` on all active DHT handles (v4, v6, v2-swarm).
    async fn run_dht_requery(&mut self) {
        if !self.config.enable_dht {
            return;
        }

        // Guard: don't re-query if we already have plenty of known peers.
        // M133: Scale with config instead of hardcoded 500 — with max_peers=128
        // this becomes 512, close to the old value but adapts to custom limits.
        if self.peers.len() > self.config.max_peers.saturating_mul(4) {
            return;
        }

        // M134: DhtLookup is now persistent — it re-injects routing table roots
        // every 15s internally. Only issue a fresh get_peers if the previous
        // lookup's channel has closed (lookup exhausted or aborted). Issuing a
        // new get_peers while one is active would abort the existing DhtLookup,
        // destroying its accumulated 256-node state.

        // v4 DHT — only start if no active lookup
        if self.dht_peers_rx.is_none()
            && let Some(dht) = self.current_dht()
        {
            match dht.get_peers(self.info_hash).await {
                Ok(rx) => self.dht_peers_rx = Some(rx),
                Err(e) => warn!("DHT v4 re-query failed: {e}"),
            }
        }

        // v6 DHT — only start if no active lookup
        if self.dht_v6_peers_rx.is_none()
            && self.dht_v6_empty_count < 30
            && self.should_retry_v6()
            && let Some(dht6) = self.current_dht_v6()
        {
            self.dht_v6_last_retry = Some(std::time::Instant::now());
            match dht6.get_peers(self.info_hash).await {
                Ok(rx) => self.dht_v6_peers_rx = Some(rx),
                Err(e) => debug!("DHT v6 re-query failed: {e}"),
            }
        }

        // v2 swarm re-query for hybrid torrents — only start if no active lookup
        if self.info_hashes.is_hybrid()
            && let Some(v2) = self.info_hashes.v2
        {
            let v2_bytes: [u8; 20] = v2.0[..20]
                .try_into()
                .expect("Id32 is 32 bytes; first 20 always fit");
            let v2_as_v1 = Id20(v2_bytes);

            if self.dht_v2_peers_rx.is_none()
                && let Some(dht) = self.current_dht()
            {
                match dht.get_peers(v2_as_v1).await {
                    Ok(rx) => self.dht_v2_peers_rx = Some(rx),
                    Err(e) => debug!("DHT v4 v2-swarm re-query failed: {e}"),
                }
            }
            if self.dht_v6_v2_peers_rx.is_none()
                && self.dht_v6_empty_count < 30
                && self.should_retry_v6()
                && let Some(dht6) = self.current_dht_v6()
            {
                self.dht_v6_last_retry = Some(std::time::Instant::now());
                match dht6.get_peers(v2_as_v1).await {
                    Ok(rx) => self.dht_v6_v2_peers_rx = Some(rx),
                    Err(e) => debug!("DHT v6 v2-swarm re-query failed: {e}"),
                }
            }
        }

        debug!(peers = self.peers.len(), "DHT re-query triggered");
    }

    /// Read a complete piece from disk by reading all chunks and concatenating.
    async fn handle_read_piece(&self, index: u32) -> crate::Result<Bytes> {
        let disk = self
            .disk
            .as_ref()
            .ok_or(crate::Error::MetadataNotReady(self.info_hash))?;
        let lengths = self
            .lengths
            .as_ref()
            .ok_or(crate::Error::MetadataNotReady(self.info_hash))?;

        let piece_size = lengths.piece_size(index);
        if piece_size == 0 {
            return Err(crate::Error::InvalidPieceIndex {
                index,
                num_pieces: lengths.num_pieces(),
            });
        }

        let chunk_size = lengths.chunk_size();
        let num_chunks = lengths.chunks_in_piece(index);
        let mut buf = bytes::BytesMut::with_capacity(piece_size as usize);

        for chunk_idx in 0..num_chunks {
            let begin = chunk_idx * chunk_size;
            let len = if chunk_idx == num_chunks - 1 {
                piece_size - begin
            } else {
                chunk_size
            };
            let data = disk
                .read_chunk(index, begin, len, DiskJobFlags::empty())
                .await
                .map_err(crate::Error::Storage)?;
            buf.extend_from_slice(&data);
        }

        Ok(buf.freeze())
    }

    /// Flush the disk write cache.
    async fn handle_flush_cache(&self) -> crate::Result<()> {
        let disk = self
            .disk
            .as_ref()
            .ok_or(crate::Error::MetadataNotReady(self.info_hash))?;
        disk.flush_cache().await.map_err(crate::Error::Storage)
    }

    /// Immediately initiate a connection to the given peer address.
    fn handle_connect_peer(&mut self, addr: SocketAddr) {
        // Skip if already connected
        if self.peers.contains_key(&addr) {
            return;
        }
        // M137: Track via unified PeerStates lifecycle
        if let Some(ref ps) = self.peer_states {
            ps.add_if_not_seen(addr, PeerSource::Incoming);
        }
    }

    /// Fire `TrackerReply` / `TrackerError` alerts from announce outcomes.
    pub(crate) fn fire_tracker_alerts(&self, outcomes: &[crate::tracker_manager::TrackerOutcome]) {
        for outcome in outcomes {
            match &outcome.result {
                Ok(num_peers) => {
                    post_alert(
                        &self.alert_tx,
                        &self.alert_mask,
                        AlertKind::TrackerReply {
                            info_hash: self.info_hash,
                            url: outcome.url.clone(),
                            num_peers: *num_peers,
                        },
                    );
                }
                Err(msg) => {
                    post_alert(
                        &self.alert_tx,
                        &self.alert_mask,
                        AlertKind::TrackerError {
                            info_hash: self.info_hash,
                            url: outcome.url.clone(),
                            message: msg.clone(),
                        },
                    );
                }
            }
        }
    }

    /// Calculate bytes remaining for tracker announce.
    pub(crate) fn calculate_left(&self) -> u64 {
        match (&self.meta, &self.chunk_tracker) {
            (Some(meta), Some(ct)) => {
                let total = meta.info.total_length();
                let have = u64::from(ct.bitfield().count_ones());
                let pieces_total = u64::from(self.num_pieces);
                let per_piece = total.checked_div(pieces_total).unwrap_or(0);
                total.saturating_sub(have * per_piece)
            }
            _ => 0,
        }
    }

    pub(crate) async fn shutdown_peers(&mut self) {
        // Best-effort announce Stopped to trackers (with timeout to prevent hang)
        let left = self.calculate_left();
        let _ = tokio::time::timeout(
            std::time::Duration::from_secs(3),
            self.tracker_manager
                .announce_stopped(self.uploaded, self.downloaded, left),
        )
        .await;

        // Non-blocking peer shutdown — peers may already be dead or channels full
        for peer in self.peers.values() {
            let _ = peer.cmd_tx.try_send(PeerCommand::Shutdown);
        }
    }

    // ----- Event handlers -----

    pub(crate) async fn handle_piece_data(
        &mut self,
        peer_addr: SocketAddr,
        index: u32,
        begin: u32,
        data: Bytes,
    ) {
        // Skip duplicate blocks — in end-game mode or after timeout re-requests,
        // the same block may arrive from multiple peers. Writing it to the store
        // buffer would overwrite valid data that's pending verification.
        if let Some(ref ct) = self.chunk_tracker
            && ct.has_chunk(index, begin)
        {
            self.total_download += data.len() as u64 + 13;
            // Remove from pending_requests to free pipeline slots. Without this,
            // the peer accumulates phantom entries from already-verified pieces
            // and eventually has zero available pipeline slots — permanent stall.
            if let Some(peer) = self.peers.get_mut(&peer_addr) {
                peer.pending_requests.remove(index, begin);
            }
            // Remove from end-game tracker so pick_block won't return this
            // block again. The normal path calls block_received which does
            // this, but we skip that path for duplicates.
            if self.end_game.is_active() {
                self.end_game.block_received(index, begin, peer_addr);
            }
            // M75: Permit already returned by peer task on Piece receipt
            return;
        }

        let data_len = data.len();

        // M100: Deferred write via per-torrent writer task.
        if let Some(ref disk) = self.disk {
            disk.write_block_deferred(index, begin, data);
        }

        self.downloaded += data_len as u64;
        self.total_download += data_len as u64 + 13; // payload + message header
        self.last_download = now_unix();
        self.need_save_resume = true;

        // M93: Track piece ownership (actor learns about peer's CAS reservation via chunk arrival)
        if let Some(slab_idx) = self.peer_slab.slot_of(&peer_addr)
            && self.piece_owner.get(index as usize) == Some(&None)
        {
            self.piece_owner[index as usize] = Some(slab_idx);
            // M149: Track when piece started downloading
            if self.inflight_started.get(index as usize) == Some(&None) {
                self.inflight_started[index as usize] = Some(Instant::now());
            }
            // M103: Add to steal queue if piece has unrequested blocks
            if let (Some(sc), Some(bm)) = (&self.steal_candidates, &self.block_maps)
                && let Some(lengths) = &self.lengths
            {
                let total_blocks = lengths.chunks_in_piece(index);
                if bm.next_unrequested(index, total_blocks).is_some() {
                    sc.push(index);
                }
            }
        }

        // Smart banning: track which peers contribute to each piece
        self.piece_contributors
            .entry(index)
            .or_default()
            .insert(peer_addr.ip());

        let now = std::time::Instant::now();
        if let Some(peer) = self.peers.get_mut(&peer_addr) {
            peer.pending_requests.remove(index, begin);
            peer.download_bytes_window += data_len as u64;
            peer.download_bytes_total += data_len as u64;
            peer.pipeline
                .block_received(index, begin, data_len as u32, now);
            peer.last_data_received = Some(now);
            // Clear snub if snubbed
            if peer.snubbed {
                peer.snubbed = false;
            }
        }
        // M137: Backoff is now automatically reset by mark_live() in PeerStates.

        // End-game: cancel this block on all other peers. The 200ms end-game
        // refill tick will re-stock freed peers — no reactive cascade needed.
        if self.end_game.is_active() {
            let cancels = self.end_game.block_received(index, begin, peer_addr);
            for (cancel_addr, ci, cb, cl) in cancels {
                if let Some(cancel_peer) = self.peers.get_mut(&cancel_addr) {
                    let _ = cancel_peer.cmd_tx.try_send(PeerCommand::Cancel {
                        index: ci,
                        begin: cb,
                        length: cl,
                    });
                    cancel_peer.pending_requests.remove(ci, cb);
                }
            }
        }

        // Track chunk completion
        let piece_complete = if let Some(ref mut ct) = self.chunk_tracker {
            ct.chunk_received(index, begin)
        } else {
            false
        };

        if piece_complete && !self.pending_verify.contains(&index) {
            // M44/M118: Predictive piece announce — broadcast Have before verification
            if self.config.predictive_piece_announce_ms > 0
                && !self.predictive_have_sent.contains(&index)
            {
                self.predictive_have_sent.insert(index);
                let _ = self.have_broadcast_tx.send(index);
            }

            // M100: Flush deferred writes before verification — ensures all
            // blocks are on disk so read_piece() sees complete data.
            if let Some(ref disk) = self.disk {
                disk.flush_piece_writes(index).await;
            }

            match self.version {
                irontide_core::TorrentVersion::V1Only => {
                    // Async: fire-and-forget, result via verify_result_rx
                    if let Some(ref disk) = self.disk
                        && let Some(expected) = self
                            .meta
                            .as_ref()
                            .and_then(|m| m.info.piece_hash(index as usize))
                    {
                        self.pending_verify.insert(index);
                        let generation = self
                            .piece_generations
                            .get(index as usize)
                            .copied()
                            .unwrap_or(0);
                        disk.enqueue_verify(index, expected, generation, &self.verify_result_tx);
                    }
                }
                irontide_core::TorrentVersion::V2Only => {
                    // Blocking: needs mutable hash_picker for Merkle tree
                    self.verify_and_mark_piece_v2(index).await;
                }
                irontide_core::TorrentVersion::Hybrid => {
                    // Blocking: needs both v1+v2 decision matrix
                    self.verify_and_mark_piece_hybrid(index).await;
                }
            }
        }

        // M75: Permit already returned by peer task on Piece receipt.
        // End-game dispatch still happens here.
        if self.end_game.is_active() {
            self.request_end_game_block(peer_addr).await;
        }
    }

    /// M92: Process a batch of block completions from a single peer.
    /// Iterates blocks, calling `process_block_completion()` for each.
    /// Piece verifications are triggered inline as pieces complete
    /// (same as the former per-block path).
    pub(crate) async fn handle_piece_blocks_batch(
        &mut self,
        peer_addr: SocketAddr,
        blocks: Vec<crate::types::BlockEntry>,
    ) {
        for block in &blocks {
            self.process_block_completion(peer_addr, block.index, block.begin, block.length)
                .await;
        }
    }

    fn handle_open_file(
        &mut self,
        file_index: usize,
    ) -> crate::Result<crate::streaming::FileStreamHandle> {
        let meta = self
            .meta
            .as_ref()
            .ok_or(crate::Error::MetadataNotReady(self.info_hash))?;
        let files = meta.info.files();
        if file_index >= files.len() {
            return Err(crate::Error::InvalidFileIndex {
                index: file_index,
                count: files.len(),
            });
        }
        if self.file_priorities.get(file_index).copied() == Some(FilePriority::Skip) {
            return Err(crate::Error::FileSkipped { index: file_index });
        }

        let lengths = self
            .lengths
            .as_ref()
            .ok_or(crate::Error::MetadataNotReady(self.info_hash))?;
        let disk = self
            .disk
            .as_ref()
            .ok_or(crate::Error::MetadataNotReady(self.info_hash))?;

        // Compute file offset within torrent data
        let mut file_offset = 0u64;
        for f in &files[..file_index] {
            file_offset += f.length;
        }
        let file_length = files[file_index].length;

        let (cursor_tx, cursor_rx) = tokio::sync::watch::channel(0u64);

        let permit = self
            .stream_read_semaphore
            .clone()
            .try_acquire_owned()
            .map_err(|_| crate::Error::Connection("too many concurrent stream readers".into()))?;

        // Add streaming cursor for the actor to track
        self.streaming_cursors
            .push(crate::streaming::StreamingCursor {
                file_index,
                file_offset,
                cursor_piece: (file_offset / lengths.piece_length()) as u32,
                readahead_pieces: self.config.readahead_pieces,
                cursor_rx,
            });

        Ok(crate::streaming::FileStreamHandle {
            disk: disk.clone(),
            lengths: lengths.clone(),
            file_index,
            file_offset,
            file_length,
            cursor_tx,
            piece_ready_rx: self.piece_ready_tx.subscribe(),
            have: self.have_watch_rx.clone(),
            read_permit: permit,
        })
    }

    /// M44: Suggest cached pieces to connected peers (BEP 6).
    async fn suggest_cached_pieces(&mut self) {
        if !self.config.suggest_mode {
            return;
        }
        let disk = match self.disk {
            Some(ref d) => d.clone(),
            None => return,
        };
        let cached = disk.cached_pieces().await;
        if cached.is_empty() {
            return;
        }
        let max_suggest = self.config.max_suggest_pieces;
        let peer_addrs: Vec<SocketAddr> = self.peers.keys().copied().collect();
        for peer_addr in peer_addrs {
            let already_suggested = self.suggested_to_peers.entry(peer_addr).or_default();
            let peer_has_piece = |piece: u32| -> bool {
                self.peers
                    .get(&peer_addr)
                    .is_some_and(|p| p.bitfield.get(piece))
            };
            let mut sent = 0;
            for &piece in &cached {
                if sent >= max_suggest {
                    break;
                }
                if peer_has_piece(piece) {
                    continue;
                }
                if already_suggested.contains(&piece) {
                    continue;
                }
                if let Some(peer) = self.peers.get(&peer_addr) {
                    let _ = peer.cmd_tx.try_send(PeerCommand::SuggestPiece(piece));
                    already_suggested.insert(piece);
                    sent += 1;
                }
            }
        }
    }

    /// M147: Handle pre-resolved metadata from the background resolver.
    ///
    /// If the `TorrentActor` is still in `FetchingMetadata` state, feed the
    /// info bytes through `MetadataDownloader` and call `try_assemble_metadata()`.
    /// If already past that state (actor resolved first), silently ignore.
    async fn handle_pre_resolved_metadata(&mut self, info_bytes: Vec<u8>, peers: Vec<SocketAddr>) {
        // Only act if still fetching metadata — actor may have resolved first.
        if self.state != TorrentState::FetchingMetadata {
            debug!(
                info_hash = %self.info_hash,
                state = ?self.state,
                "ignoring pre-resolved metadata: already past FetchingMetadata"
            );
            return;
        }

        debug!(
            info_hash = %self.info_hash,
            info_bytes_len = info_bytes.len(),
            num_peers = peers.len(),
            "received pre-resolved metadata from background resolver"
        );

        // Feed the complete info bytes to the MetadataDownloader.
        if let Some(ref mut dl) = self.metadata_downloader {
            // Set total size so the downloader knows the expected piece count.
            dl.set_total_size(info_bytes.len() as u64);

            // Feed as a single piece (piece 0) containing the full info dict.
            // For metadata smaller than 16 KiB this is a single piece.
            // For larger metadata, feed each 16 KiB chunk as a separate piece.
            let piece_size: usize = 16384;
            let num_pieces = info_bytes.len().div_ceil(piece_size);
            for i in 0..num_pieces {
                let start = i * piece_size;
                let end = (start + piece_size).min(info_bytes.len());
                let data = bytes::Bytes::copy_from_slice(&info_bytes[start..end]);
                dl.piece_received(i as u32, data);
            }
        }

        // Attempt assembly — this will transition to Downloading if
        // the info_hash validates.
        self.try_assemble_metadata().await;

        // Pre-seed discovered peers into the pipeline.
        if !peers.is_empty() {
            self.handle_add_peers(peers, crate::peer_state::PeerSource::Dht);
        }
    }

    pub(crate) async fn try_assemble_metadata(&mut self) {
        let assembled = if let Some(ref dl) = self.metadata_downloader {
            dl.assemble_and_verify()
        } else {
            return;
        };

        match assembled {
            Ok(info_bytes) => {
                // Build torrent bytes wrapping the raw info dict into a minimal torrent
                // We need to parse it as a full torrent. The info_bytes is the raw bencoded
                // info dict. We'll build a minimal torrent around it.
                // Actually, torrent_from_bytes expects a full torrent dict.
                // Let's build one:
                let mut torrent_bytes = b"d4:info".to_vec();
                torrent_bytes.extend_from_slice(&info_bytes);
                torrent_bytes.push(b'e');

                match torrent_from_bytes(&torrent_bytes) {
                    Ok(meta) => {
                        let num_pieces = meta.info.num_pieces() as u32;
                        let lengths = Lengths::new(
                            meta.info.total_length(),
                            meta.info.piece_length,
                            DEFAULT_CHUNK_SIZE,
                        );

                        // Create filesystem storage now that we know the file layout
                        let files = meta.info.files();
                        let file_paths: Vec<std::path::PathBuf> = files
                            .iter()
                            .map(|f| f.path.iter().collect::<std::path::PathBuf>())
                            .collect();
                        let file_lengths_vec: Vec<u64> = files.iter().map(|f| f.length).collect();
                        let prealloc_mode = self.config.preallocate_mode.unwrap_or_else(|| {
                            irontide_storage::PreallocateMode::from(
                                self.config.storage_mode == irontide_core::StorageMode::Full,
                            )
                        });
                        let storage: Arc<dyn TorrentStorage> =
                            match irontide_storage::FilesystemStorage::new(
                                &self.config.download_dir,
                                file_paths,
                                file_lengths_vec,
                                lengths.clone(),
                                None,
                                prealloc_mode,
                                self.config.filesystem_direct_io,
                            ) {
                                Ok(s) => Arc::new(s),
                                Err(e) => {
                                    warn!(
                                        "failed to create filesystem storage: {e}, falling back to memory"
                                    );
                                    Arc::new(MemoryStorage::new(lengths.clone()))
                                }
                            };
                        let mut disk_handle = self
                            .disk_manager
                            .register_torrent(self.info_hash, storage)
                            .await;

                        self.chunk_tracker = Some(ChunkTracker::new(lengths.clone()));
                        self.lengths = Some(lengths);
                        self.num_pieces = num_pieces;
                        // M96: Initialize real generation counters + hash result channel
                        self.piece_generations = vec![0u64; num_pieces as usize];
                        let (hash_tx, hash_rx) = tokio::sync::mpsc::channel(64);
                        self.hash_result_tx = hash_tx;
                        self.hash_result_rx = hash_rx;
                        // M96: Wire hash pool into disk handle (version check deferred
                        // until after metadata detection below sets self.version)
                        if let Some(ref pool) = self.hash_pool_ref {
                            disk_handle.set_hash_pool(pool.clone());
                            disk_handle.set_hash_result_tx(self.hash_result_tx.clone());
                        }
                        self.disk = Some(disk_handle);
                        // Update all connected peer tasks so they can validate
                        // incoming Bitfield messages with the correct piece count.
                        for peer in self.peers.values() {
                            let _ = peer
                                .cmd_tx
                                .try_send(PeerCommand::UpdateNumPieces(num_pieces));
                        }
                        let file_lengths: Vec<u64> =
                            meta.info.files().iter().map(|f| f.length).collect();
                        let mut meta = meta;
                        meta.info_bytes = Some(Bytes::from(info_bytes));
                        self.meta = Some(meta);

                        // M116: Populate cached file info for zero-alloc completion checks.
                        if let (Some(meta), Some(lengths)) = (&self.meta, &self.lengths) {
                            self.cached_files = Some(build_cached_file_info(meta, lengths));
                        }

                        self.file_priorities = vec![FilePriority::Normal; file_lengths.len()];

                        // BEP 53: apply magnet so= file selection
                        if let Some(ref selections) = self.magnet_selected_files {
                            self.file_priorities = irontide_core::FileSelection::to_priorities(
                                selections,
                                file_lengths.len(),
                            );
                            self.magnet_selected_files = None;
                        }

                        self.wanted_pieces = crate::piece_selector::build_wanted_pieces(
                            &self.file_priorities,
                            &file_lengths,
                            self.lengths.as_ref().unwrap(),
                        );
                        if self.config.share_mode {
                            self.transition_state(TorrentState::Sharing);
                        } else {
                            self.transition_state(TorrentState::Downloading);
                        }
                        self.metadata_downloader = None;

                        // Populate tracker manager with newly parsed metadata
                        if let Some(ref meta) = self.meta {
                            self.tracker_manager
                                .set_metadata_filtered(meta, self.config.url_security);
                        }

                        // Detect hybrid/v2 from metadata and update dual-swarm state
                        // (Gap 1 & 2: propagate info_hashes to tracker + DHT after magnet resolves)
                        if let Ok(detected) = irontide_core::torrent_from_bytes_any(&torrent_bytes)
                        {
                            let new_version = detected.version();
                            if new_version != irontide_core::TorrentVersion::V1Only {
                                let new_hashes = detected.info_hashes();
                                self.version = new_version;
                                self.info_hashes = new_hashes.clone();
                                self.tracker_manager.set_info_hashes(new_hashes.clone());
                                if let Some(v2_meta) = detected.as_v2() {
                                    self.meta_v2 = Some(v2_meta.clone());
                                }
                                // Start v2 DHT lookups for hybrid torrents
                                if new_hashes.is_hybrid()
                                    && let Some(v2) = new_hashes.v2
                                {
                                    let v2_as_v1 = Id20(v2.0[..20].try_into().unwrap());
                                    if v2_as_v1 != self.info_hash {
                                        if self.dht_v2_peers_rx.is_none()
                                            && let Some(dht) = self.current_dht()
                                            && let Ok(rx) = dht.get_peers(v2_as_v1).await
                                        {
                                            self.dht_v2_peers_rx = Some(rx);
                                        }
                                        if self.dht_v6_v2_peers_rx.is_none()
                                            && self.dht_v6_empty_count < 30
                                            && self.should_retry_v6()
                                            && let Some(dht6) = self.current_dht_v6()
                                            && let Ok(rx) = dht6.get_peers(v2_as_v1).await
                                        {
                                            self.dht_v6_last_retry =
                                                Some(std::time::Instant::now());
                                            self.dht_v6_v2_peers_rx = Some(rx);
                                        }
                                    }
                                }
                            }
                        }

                        let name = self
                            .meta
                            .as_ref()
                            .map(|m| m.info.name.clone())
                            .unwrap_or_default();
                        post_alert(
                            &self.alert_tx,
                            &self.alert_mask,
                            AlertKind::MetadataReceived {
                                info_hash: self.info_hash,
                                name,
                            },
                        );
                        info!("metadata assembled, switching to Downloading");

                        // M93: Initialize lock-free piece states after metadata
                        if let Some(ct) = &self.chunk_tracker {
                            let atomic_states = Arc::new(AtomicPieceStates::new(
                                self.num_pieces,
                                ct.bitfield(),
                                &self.wanted_pieces,
                            ));
                            self.atomic_states = Some(Arc::clone(&atomic_states));
                            self.piece_owner = vec![None; self.num_pieces as usize];
                            // M149: Initialize inflight tracking
                            self.inflight_started = vec![None; self.num_pieces as usize];
                            self.max_in_flight = self.config.max_in_flight_pieces;

                            // M103: Initialize block stealing infrastructure
                            if self.config.use_block_stealing {
                                if let Some(ref lengths) = self.lengths {
                                    self.block_maps =
                                        Some(Arc::new(BlockMaps::new(self.num_pieces, lengths)));
                                }
                                self.steal_candidates = Some(Arc::new(StealCandidates::new()));
                            }
                            // M120: Per-piece write guards
                            self.piece_write_guards = Some(Arc::new(
                                crate::piece_reservation::PieceWriteGuards::new(self.num_pieces),
                            ));

                            // M187: Init direct-acquire dispatch state.
                            self.piece_tracker = Some(PieceTracker::new(
                                self.num_pieces,
                                ct.bitfield(),
                                &self.wanted_pieces,
                            ));
                            if let Some(ref cached) = self.cached_files {
                                let file_piece_ranges: Vec<(u32, u32)> = cached
                                    .entries
                                    .iter()
                                    .map(|e| (e.first_piece, e.last_piece))
                                    .collect();
                                let om = Arc::new(PieceOrderMap::build(
                                    &self.file_priorities,
                                    &file_piece_ranges,
                                    self.num_pieces,
                                    0,
                                ));
                                self.order_map_tx.send_replace(om);
                            }

                            let notify = Arc::new(tokio::sync::Notify::new());
                            self.reservation_notify = Some(notify);
                        }

                        // Start web seeds now that we have metadata
                        self.spawn_web_seeds();
                        self.assign_pieces_to_web_seeds();

                        // Kick-start piece requesting for all peers that connected during
                        // metadata phase. Send StartRequesting to all connected peers.
                        let peer_addrs: Vec<SocketAddr> = self.peers.keys().copied().collect();
                        info!(
                            connected_peers = peer_addrs.len(),
                            "kick-starting piece requests for pre-connected peers"
                        );
                        for addr in peer_addrs {
                            let has_bitfield =
                                self.peers.get(&addr).map_or(0, |p| p.bitfield.count_ones());
                            let is_choking = self.peers.get(&addr).is_none_or(|p| p.peer_choking);
                            debug!(%addr, has_bitfield, is_choking, "post-metadata peer state");
                            self.maybe_express_interest(addr).await;
                            if let Some(peer) = self.peers.get(&addr)
                                && peer.bitfield.count_ones() > 0
                            {
                                let _slot = self.peer_slab.insert(addr);
                            }
                        }
                        self.recalc_max_in_flight();
                        // M93: Inform all connected peers about lock-free dispatch state.
                        // M159: Skip while user seed mode is active — we are currently
                        // not scheduling any new block requests.
                        if !self.user_seed_mode
                            && let Some(notify) = &self.reservation_notify
                            && let Some(ref lengths) = self.lengths
                        {
                            for peer in self.peers.values() {
                                let _ = peer.cmd_tx.try_send(PeerCommand::StartRequesting {
                                    piece_notify: Arc::clone(notify),
                                    disk_handle: self.disk.clone(),
                                    write_error_tx: self.write_error_tx.clone(),
                                    lengths: lengths.clone(),
                                });
                            }
                        }
                    }
                    Err(e) => {
                        warn!("failed to parse assembled metadata: {e}");
                        post_alert(
                            &self.alert_tx,
                            &self.alert_mask,
                            AlertKind::MetadataFailed {
                                info_hash: self.info_hash,
                            },
                        );
                    }
                }
            }
            Err(e) => {
                warn!("metadata assembly failed: {e}");
                post_alert(
                    &self.alert_tx,
                    &self.alert_mask,
                    AlertKind::MetadataFailed {
                        info_hash: self.info_hash,
                    },
                );
            }
        }
    }

    // ----- Web seeding (M22) -----

    fn spawn_web_seeds(&mut self) {
        if !self.config.enable_web_seed {
            return;
        }
        let Some(meta) = &self.meta else { return };
        let lengths = match &self.lengths {
            Some(l) => l.clone(),
            None => return,
        };

        let file_lengths: Vec<u64> = meta.info.files().iter().map(|f| f.length).collect();
        let file_map = irontide_storage::FileMap::new(file_lengths, lengths.clone());

        // BEP 19 (GetRight) web seeds
        for url in &meta.url_list {
            if self.banned_web_seeds.contains(url) || self.web_seeds.contains_key(url) {
                continue;
            }
            if self.web_seeds.len() >= self.config.max_web_seeds {
                break;
            }

            // Security validation
            if let Err(e) = crate::url_guard::validate_web_seed_url(url, self.config.url_security) {
                warn!(%url, %e, "web seed URL rejected by security policy");
                continue;
            }

            let url_builder = if meta.info.length.is_some() {
                crate::web_seed::WebSeedUrlBuilder::single(url.clone(), meta.info.name.clone())
            } else {
                let file_paths: Vec<String> = meta
                    .info
                    .files()
                    .iter()
                    .map(|f| f.path[1..].join("/")) // skip torrent name prefix
                    .collect();
                crate::web_seed::WebSeedUrlBuilder::multi(
                    url.clone(),
                    meta.info.name.clone(),
                    file_paths,
                )
            };

            let (cmd_tx, cmd_rx) = mpsc::channel(16);
            let initial_downloaded = self
                .web_seed_stats
                .get(url)
                .map_or(0, |s| s.downloaded_bytes);
            let task = crate::web_seed::WebSeedTask::new(
                url.clone(),
                crate::web_seed::WebSeedMode::GetRight,
                url_builder,
                lengths.clone(),
                file_map.clone(),
                self.info_hash,
                cmd_rx,
                self.event_tx.clone(),
                self.config.url_security,
                self.config.web_seed_progress_throttle_ms,
                initial_downloaded,
                self.config.web_seed_retry_base_secs,
                self.config.web_seed_retry_factor,
                self.config.web_seed_retry_cap_secs,
                self.config.web_seed_max_failures,
            );
            tokio::spawn(task.run());
            self.web_seeds.insert(url.clone(), cmd_tx);
            debug!(url, "spawned BEP 19 web seed");
        }

        // BEP 17 (Hoffman) HTTP seeds
        for url in &meta.httpseeds {
            if self.banned_web_seeds.contains(url) || self.web_seeds.contains_key(url) {
                continue;
            }
            if self.web_seeds.len() >= self.config.max_web_seeds {
                break;
            }

            // Security validation
            if let Err(e) = crate::url_guard::validate_web_seed_url(url, self.config.url_security) {
                warn!(%url, %e, "web seed URL rejected by security policy");
                continue;
            }

            // BEP 17 doesn't use URL builder for per-file paths; it sends parameterized URLs
            let url_builder =
                crate::web_seed::WebSeedUrlBuilder::single(url.clone(), meta.info.name.clone());

            let (cmd_tx, cmd_rx) = mpsc::channel(16);
            let initial_downloaded = self
                .web_seed_stats
                .get(url)
                .map_or(0, |s| s.downloaded_bytes);
            let task = crate::web_seed::WebSeedTask::new(
                url.clone(),
                crate::web_seed::WebSeedMode::Hoffman,
                url_builder,
                lengths.clone(),
                file_map.clone(),
                self.info_hash,
                cmd_rx,
                self.event_tx.clone(),
                self.config.url_security,
                self.config.web_seed_progress_throttle_ms,
                initial_downloaded,
                self.config.web_seed_retry_base_secs,
                self.config.web_seed_retry_factor,
                self.config.web_seed_retry_cap_secs,
                self.config.web_seed_max_failures,
            );
            tokio::spawn(task.run());
            self.web_seeds.insert(url.clone(), cmd_tx);
            debug!(url, "spawned BEP 17 web seed");
        }
    }

    pub(crate) fn assign_pieces_to_web_seeds(&mut self) {
        if self.state != TorrentState::Downloading || self.end_game.is_active() {
            return;
        }

        // Collect idle web seed URLs (not currently downloading a piece)
        let active_urls: HashSet<&String> = self.web_seed_in_flight.values().collect();
        let idle_urls: Vec<String> = self
            .web_seeds
            .keys()
            .filter(|u| !active_urls.contains(u))
            .cloned()
            .collect();

        let Some(ct) = &self.chunk_tracker else {
            return;
        };

        for url in idle_urls {
            // Find lowest-index piece that is: not verified, not reserved by a peer,
            // not in web_seed_in_flight, and wanted.
            let piece = (0..self.num_pieces).find(|&i| {
                !ct.has_piece(i)
                    && !self
                        .piece_owner
                        .get(i as usize)
                        .is_some_and(std::option::Option::is_some)
                    && !self.web_seed_in_flight.contains_key(&i)
                    && self.wanted_pieces.get(i)
            });

            if let Some(piece) = piece
                && let Some(cmd_tx) = self.web_seeds.get(&url)
            {
                let _ = cmd_tx.try_send(crate::web_seed::WebSeedCommand::FetchPiece(piece));
                self.web_seed_in_flight.insert(piece, url);
            }
        }
    }

    pub(crate) async fn handle_web_seed_piece_data(
        &mut self,
        url: String,
        index: u32,
        data: Bytes,
    ) {
        self.web_seed_in_flight.remove(&index);

        // If peer already completed this piece, discard
        if let Some(ref ct) = self.chunk_tracker
            && ct.has_piece(index)
        {
            self.assign_pieces_to_web_seeds();
            return;
        }

        // Write entire piece to disk at offset 0
        if let Some(ref disk) = self.disk
            && let Err(e) = disk
                .write_chunk(index, 0, data.clone(), DiskJobFlags::FLUSH_PIECE)
                .await
        {
            warn!(index, "web seed: failed to write piece: {e}");
            self.assign_pieces_to_web_seeds();
            return;
        }

        // Mark all chunks as received
        if let Some(ref mut ct) = self.chunk_tracker
            && let Some(ref lengths) = self.lengths
        {
            let num_chunks = lengths.chunks_in_piece(index);
            for chunk_idx in 0..num_chunks {
                if let Some((begin, _len)) = lengths.chunk_info(index, chunk_idx) {
                    ct.chunk_received(index, begin);
                }
            }
        }

        self.downloaded += data.len() as u64;
        self.total_download += data.len() as u64 + 13; // payload + message header
        self.last_download = now_unix();
        self.need_save_resume = true;

        // Verify the piece hash
        self.verify_and_mark_piece(index).await;

        // If hash failed, ban this web seed (BEP 19 spec)
        if let Some(ref ct) = self.chunk_tracker
            && !ct.has_piece(index)
        {
            self.ban_web_seed(&url);
            return;
        }

        self.assign_pieces_to_web_seeds();
    }

    pub(crate) fn handle_web_seed_error(&mut self, url: &str, piece: u32, message: &str) {
        self.web_seed_in_flight.remove(&piece);
        warn!(%url, piece, %message, "web seed error");
        self.assign_pieces_to_web_seeds();
    }

    /// M178: Update per-URL `WebSeedStats` from a `WebSeedProgress` event.
    ///
    /// State machine: Idle → Active on first success; Active → Errored on
    /// failure; Errored → Active on recovery (`last_error` PERSISTS through
    /// recovery per Issue 2.2 / D-eng-8). `consecutive_failures` increments
    /// monotonically within a failure run and resets to zero on success.
    /// `last_attempt_unix_secs` updates on every event regardless of outcome.
    pub(crate) fn handle_web_seed_progress(
        &mut self,
        url: &str,
        bytes: u64,
        rate_bps: u64,
        error: Option<String>,
    ) {
        let now_unix = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map_or(0, |d| d.as_secs());
        let entry = self
            .web_seed_stats
            .entry(url.to_owned())
            .or_insert_with(|| irontide_core::WebSeedStats {
                url: url.to_owned(),
                ..Default::default()
            });
        entry.downloaded_bytes = bytes;
        entry.last_rate_bps = rate_bps;
        entry.last_attempt_unix_secs = now_unix;
        if let Some(msg) = error {
            entry.state = irontide_core::WebSeedState::Errored;
            entry.last_error = Some(msg);
            entry.consecutive_failures = entry.consecutive_failures.saturating_add(1);
            // M186: Populate next_retry_unix_secs during backoff
            let attempt = entry.consecutive_failures.saturating_sub(1);
            let secs = self
                .config
                .web_seed_retry_base_secs
                .saturating_mul(self.config.web_seed_retry_factor.saturating_pow(attempt))
                .min(self.config.web_seed_retry_cap_secs);
            entry.next_retry_unix_secs = Some(now_unix + secs);
        } else {
            entry.state = irontide_core::WebSeedState::Active;
            entry.consecutive_failures = 0;
            entry.next_retry_unix_secs = None;
        }
        self.need_save_resume = true;
    }

    pub(crate) fn ban_web_seed(&mut self, url: &str) {
        warn!(%url, "banning web seed due to hash failure");
        self.banned_web_seeds.insert(url.to_owned());

        // Send shutdown to the task
        if let Some(cmd_tx) = self.web_seeds.remove(url) {
            let _ = cmd_tx.try_send(crate::web_seed::WebSeedCommand::Shutdown);
        }

        // Remove all in-flight pieces for this URL
        self.web_seed_in_flight.retain(|_, v| v != url);

        post_alert(
            &self.alert_tx,
            &self.alert_mask,
            AlertKind::WebSeedBanned {
                info_hash: self.info_hash,
                url: url.to_owned(),
            },
        );
    }

    async fn shutdown_web_seeds(&mut self) {
        for (_, cmd_tx) in self.web_seeds.drain() {
            let _ = cmd_tx.send(crate::web_seed::WebSeedCommand::Shutdown).await;
        }
        self.web_seed_in_flight.clear();
    }

    /// Rebuild the cached peer rates map from current peer state.
    fn refresh_peer_rates(&mut self) {
        self.cached_peer_rates.clear();
        self.cached_peer_rates.reserve(self.peers.len());
        for (&addr, p) in &self.peers {
            self.cached_peer_rates.insert(addr, p.pipeline.ewma_rate());
        }
    }

    // ----- Choking -----

    fn update_peer_rates(&mut self) {
        for peer in self.peers.values_mut() {
            peer.download_rate = peer.download_bytes_window / 2;
            peer.upload_rate = peer.upload_bytes_window / 2;
            peer.download_bytes_window = 0;
            peer.upload_bytes_window = 0;
        }

        // Track peak download rate for peer turnover cutoff
        let aggregate_download: u64 = self.peers.values().map(|p| p.download_rate).sum();
        if aggregate_download > self.peak_download_rate {
            self.peak_download_rate = aggregate_download;
        }
    }

    async fn run_choker(&mut self) {
        let peer_infos: Vec<ChokerPeerInfo> = self
            .peers
            .values()
            .map(|p| ChokerPeerInfo {
                addr: p.addr,
                download_rate: p.download_rate,
                upload_rate: p.upload_rate,
                interested: p.peer_interested,
                upload_only: p.upload_only,
                is_seed: p.upload_only
                    || (self.num_pieces > 0 && p.bitfield.count_ones() == self.num_pieces),
            })
            .collect();

        let decision = self.choker.decide(&peer_infos);

        for addr in &decision.to_unchoke {
            if let Some(peer) = self.peers.get_mut(addr)
                && peer.am_choking
            {
                peer.am_choking = false;
                // Track unchoke window for fairness measurement.
                if peer.am_unchoke_started_at.is_none() {
                    peer.am_unchoke_started_at = Some(Instant::now());
                }
                let _ = peer.cmd_tx.try_send(PeerCommand::SetChoking(false));
            }
        }

        for addr in &decision.to_choke {
            if let Some(peer) = self.peers.get_mut(addr)
                && !peer.am_choking
            {
                if peer.supports_fast {
                    let pending: Vec<(u32, u32, u32)> = peer.incoming_requests.drain(..).collect();
                    for (index, begin, length) in pending {
                        let _ = peer.cmd_tx.try_send(PeerCommand::RejectRequest {
                            index,
                            begin,
                            length,
                        });
                    }
                }
                peer.am_choking = true;
                // Accumulate the unchoke window we just closed.
                if let Some(start) = peer.am_unchoke_started_at.take() {
                    peer.unchoke_duration_total += start.elapsed();
                }
                let _ = peer.cmd_tx.try_send(PeerCommand::SetChoking(true));
            }
        }

        // Serve any buffered requests from newly-unchoked peers
        self.serve_incoming_requests().await;

        // Zombie pruning: disconnect peers with empty bitfields after 30s.
        // These peers consume connection slots but contribute no pieces.
        // Only prune during downloading — when seeding, empty-bitfield peers
        // are leechers we want to upload to.
        if self.state == TorrentState::Downloading {
            let zombie_threshold = Duration::from_secs(30);
            let zombies: Vec<SocketAddr> = self
                .peers
                .values()
                .filter(|p| {
                    p.bitfield.count_ones() == 0 && p.connected_at.elapsed() > zombie_threshold
                })
                .map(|p| p.addr)
                .collect();

            for &addr in &zombies {
                debug!(%addr, "disconnecting zombie peer (empty bitfield after 30s)");
                self.disconnect_peer(addr, "zombie peer (empty bitfield)");
            }
            if !zombies.is_empty() {
                self.recalc_max_in_flight();
            }
        }
    }

    fn rotate_optimistic(&mut self) {
        let peer_infos: Vec<ChokerPeerInfo> = self
            .peers
            .values()
            .map(|p| ChokerPeerInfo {
                addr: p.addr,
                download_rate: p.download_rate,
                upload_rate: p.upload_rate,
                interested: p.peer_interested,
                upload_only: p.upload_only,
                is_seed: p.upload_only
                    || (self.num_pieces > 0 && p.bitfield.count_ones() == self.num_pieces),
            })
            .collect();

        self.choker.rotate_optimistic(&peer_infos);
    }

    /// Handle an incoming I2P peer connection (M41).
    ///
    /// Assigns a synthetic `SocketAddr` (from the reserved 240.0.0.0/4 range) since
    /// I2P peers don't have real IP addresses, then hands the underlying TCP stream
    /// to `spawn_peer_from_stream`.
    fn handle_i2p_incoming(&mut self, stream: crate::i2p::SamStream) {
        if self.peers.len() >= self.effective_max_connections() {
            return;
        }

        let synthetic_addr = self.next_i2p_synthetic_addr();

        let remote_dest = stream.remote_destination().clone();
        let dest_preview = {
            let b64 = remote_dest.to_base64();
            if b64.len() >= 8 {
                b64[..8].to_string()
            } else {
                b64
            }
        };
        self.i2p_destinations.insert(synthetic_addr, remote_dest);
        let tcp_stream = stream.into_inner();

        self.spawn_peer_from_stream(synthetic_addr, tcp_stream);

        debug!(dest = %dest_preview, addr = %synthetic_addr, "accepted I2P peer");
    }

    /// Add an I2P peer by destination, assigning a synthetic `SocketAddr`.
    #[allow(dead_code)] // Used by Task 2 (outbound I2P connects)
    fn add_i2p_peer(
        &mut self,
        dest: crate::i2p::I2pDestination,
        source: PeerSource,
    ) -> Option<SocketAddr> {
        // Dedup: check if we already track this destination
        if self.i2p_destinations.values().any(|d| d == &dest) {
            return None;
        }
        let addr = self.next_i2p_synthetic_addr();
        self.i2p_destinations.insert(addr, dest);
        // M137: Track via unified PeerStates lifecycle
        if let Some(ref ps) = self.peer_states {
            ps.add_if_not_seen(addr, source);
        }
        Some(addr)
    }

    /// Generate a unique synthetic `SocketAddr` for an I2P peer.
    ///
    /// Uses addresses from 240.0.0.0/4 (reserved, never routable) to avoid
    /// conflicts with real peers. The counter ensures uniqueness across the
    /// torrent's lifetime.
    fn next_i2p_synthetic_addr(&mut self) -> SocketAddr {
        self.i2p_peer_counter = self.i2p_peer_counter.wrapping_add(1);
        let a = ((self.i2p_peer_counter >> 16) & 0x0F) as u8 | 0xF0;
        let b = ((self.i2p_peer_counter >> 8) & 0xFF) as u8;
        let c = (self.i2p_peer_counter & 0xFF) as u8;
        SocketAddr::new(
            std::net::IpAddr::V4(std::net::Ipv4Addr::new(a, b, c, 1)),
            (self.i2p_peer_counter & 0xFFFF) as u16,
        )
    }
}

/// Check whether a `SocketAddr` uses a synthetic I2P address (240.0.0.0/4 range).
pub(crate) fn is_i2p_synthetic_addr(addr: &SocketAddr) -> bool {
    match addr {
        SocketAddr::V4(v4) => v4.ip().octets()[0] & 0xF0 == 0xF0,
        SocketAddr::V6(_) => false,
    }
}

/// Helper to accept a connection from an optional transport listener.
/// Returns `pending` if no listener is bound, so the `select!` branch is skipped.
async fn accept_incoming(
    listener: &mut Option<Box<dyn crate::transport::TransportListener>>,
) -> std::io::Result<(crate::transport::BoxedStream, SocketAddr)> {
    match listener {
        Some(l) => l.accept().await,
        None => std::future::pending().await,
    }
}

/// Helper to receive an incoming I2P connection from the accept loop channel.
/// Returns `pending` if I2P is not enabled, so the `select!` branch is skipped.
async fn accept_i2p(
    rx: &mut Option<mpsc::Receiver<crate::i2p::SamStream>>,
) -> Option<crate::i2p::SamStream> {
    match rx {
        Some(rx) => rx.recv().await,
        None => std::future::pending().await,
    }
}

// ============================================================================
// BEP 52 hash serving (M87)
// ============================================================================

/// Determine what to serve for a BEP 52 hash request.
///
/// Returns `Some(hashes)` to serve, or `None` to reject.
/// Only serves piece-layer hashes (the layer stored in `piece_layers`).
/// Block-layer or other layer requests are rejected since we don't store
/// the full Merkle tree.
pub(crate) fn serve_hashes(
    meta_v2: Option<&irontide_core::TorrentMetaV2>,
    version: irontide_core::TorrentVersion,
    lengths: Option<&Lengths>,
    request: &irontide_core::HashRequest,
) -> Option<Vec<irontide_core::Id32>> {
    // Reject if v1-only or no v2 metadata
    let meta_v2 = match meta_v2 {
        Some(m) if version != irontide_core::TorrentVersion::V1Only => m,
        _ => return None,
    };

    // Look up piece-layer hashes for the requested file root
    let piece_hashes = meta_v2.file_piece_hashes(&request.file_root)?;

    // We need lengths to validate the request geometry
    let lengths = lengths?;

    // Compute per-file block count from piece hashes and piece/chunk sizes.
    // Each piece hash covers `piece_length / chunk_size` blocks, except the
    // last piece which may cover fewer. For validation purposes we use the
    // padded count that `validate_hash_request` expects.
    let blocks_per_piece = (meta_v2.info.piece_length / u64::from(lengths.chunk_size())) as u32;
    let num_pieces = piece_hashes.len() as u32;
    let num_blocks = num_pieces.saturating_mul(blocks_per_piece);

    if !irontide_core::validate_hash_request(request, num_blocks, num_pieces) {
        return None;
    }

    // We only have piece-layer hashes. The piece layer is at
    // base = log2(blocks_per_piece). Reject requests for other layers.
    let piece_layer_base = blocks_per_piece.trailing_zeros();
    if request.base != piece_layer_base {
        return None;
    }

    // Extract requested hashes from the piece layer
    let start = request.index as usize;
    let end = (start + request.count as usize).min(piece_hashes.len());
    let mut hashes: Vec<irontide_core::Id32> = piece_hashes[start..end].to_vec();

    // Compute proof (uncle) hashes if requested.
    //
    // BEP 52 specifies a single subtree proof for the entire batch, not
    // per-leaf proofs. The receiver rebuilds the subtree root from the
    // base hashes itself, so we skip the first `log2(count)` levels of
    // the proof path (those are internal to the requested subtree) and
    // only send the uncle hashes above it.
    if request.proof_layers > 0 && !piece_hashes.is_empty() {
        let tree = irontide_core::MerkleTree::from_leaves(&piece_hashes);
        let full_proof = tree.proof_path(start);
        // Skip levels internal to the requested subtree
        let subtree_depth = if request.count > 1 {
            (request.count as usize)
                .next_power_of_two()
                .trailing_zeros() as usize
        } else {
            0
        };
        let available = full_proof.len().saturating_sub(subtree_depth);
        let proof_count = (request.proof_layers as usize).min(available);
        hashes.extend_from_slice(&full_proof[subtree_depth..subtree_depth + proof_count]);
    }

    Some(hashes)
}

// ============================================================================
// Test-only constructors
// ============================================================================

#[cfg(test)]
impl TorrentActor {
    /// v0.173.3 (A4): Build a minimal `TorrentActor` exercising only the
    /// fields touched by `rebuild_availability_snapshot`.
    ///
    /// Every other field is filled with the cheapest valid placeholder
    /// (empty channels, zero atomics, no-op handles). The actor is **not**
    /// spawned via `tokio::spawn` so it has no live `run()` loop — the
    /// returned struct is suitable for direct method-level testing only.
    ///
    /// `num_pieces` controls the size of the pre-allocated availability
    /// vector and atomic-states bitmap. `throttle_ms` plumbs the v0.173.3
    /// throttle config into the synthetic actor's `TorrentConfig`.
    ///
    /// Must run inside a tokio runtime because `DiskManagerHandle::new`
    /// internally spawns its background actor.
    pub(crate) fn for_throttle_test(num_pieces: u32, _throttle_ms: u64) -> Self {
        use irontide_storage::Bitfield;

        let config = TorrentConfig {
            ..TorrentConfig::default()
        };

        let info_hash = Id20([0u8; 20]);
        let our_peer_id = Id20([0u8; 20]);

        let (_cmd_tx, cmd_rx) = mpsc::channel(1);
        let (event_tx, event_rx) = mpsc::channel(1);
        let (write_error_tx, write_error_rx) = mpsc::channel(1);
        let (verify_result_tx, verify_result_rx) = mpsc::channel(1);
        let (hash_result_tx, hash_result_rx) = mpsc::channel(1);
        let (piece_ready_tx, _piece_ready_rx) = broadcast::channel(1);
        let (have_watch_tx, have_watch_rx) = tokio::sync::watch::channel(Bitfield::new(num_pieces));
        let (have_broadcast_tx, _) = tokio::sync::broadcast::channel(128);
        let (alert_tx, _alert_rx) = broadcast::channel(64);
        let (_disk_mgr_tx, _disk_mgr_rx) = mpsc::channel::<crate::disk::DiskJob>(1);

        let stream_read_semaphore = Arc::new(tokio::sync::Semaphore::new(8));
        let alert_mask = Arc::new(AtomicU32::new(crate::alert::AlertCategory::ALL.bits()));

        // DiskManagerHandle::new spawns an actor — requires runtime.
        let (disk_manager, _disk_join) =
            crate::disk::DiskManagerHandle::new(crate::disk::DiskConfig::default());

        let ban_manager = Arc::new(parking_lot::RwLock::new(crate::ban::BanManager::new(
            crate::ban::BanConfig::default(),
        )));
        let ip_filter = Arc::new(parking_lot::RwLock::new(crate::ip_filter::IpFilter::new()));

        let upload_bucket = crate::rate_limiter::TokenBucket::new(0);
        let download_bucket = Arc::new(parking_lot::Mutex::new(
            crate::rate_limiter::TokenBucket::new(0),
        ));
        let rate_limiter_set = crate::rate_limiter::RateLimiterSet::new(0, 0, 0, 0, 0, 0);

        let dht_rx = irontide_dht::DhtBroadcast::new(None).subscribe();
        let dht_v6_rx = irontide_dht::DhtBroadcast::new(None).subscribe();
        let factory = Arc::new(crate::transport::NetworkFactory::tokio());

        // Atomic states + availability sized for `num_pieces`. The
        // availability snapshot rebuild reads both; everything else
        // (chunk tracker, file priorities, peers) can stay empty.
        let we_have = Bitfield::new(num_pieces);
        let mut wanted = Bitfield::new(num_pieces);
        for i in 0..num_pieces {
            wanted.set(i);
        }
        let atomic_states = Arc::new(crate::piece_reservation::AtomicPieceStates::new(
            num_pieces, &we_have, &wanted,
        ));

        let (order_map_tx, _order_map_rx_seed) =
            tokio::sync::watch::channel(Arc::new(PieceOrderMap::empty()));

        Self {
            lock_timing: crate::timed_lock::LockTimingSettings::from_ms(0),
            config,
            info_hash,
            our_peer_id,
            state: TorrentState::Downloading,
            disk: None,
            disk_manager,
            chunk_tracker: None,
            lengths: None,
            num_pieces,
            file_priorities: Vec::new(),
            wanted_pieces: Bitfield::new(num_pieces),
            end_game: EndGame::new(),
            streaming_pieces: BTreeSet::new(),
            time_critical_pieces: BTreeSet::new(),
            streaming_cursors: Vec::new(),
            piece_ready_tx,
            have_watch_tx,
            have_watch_rx,
            stream_read_semaphore,
            peers: HashMap::new(),
            unchoke_durations: HashMap::new(),
            cached_peer_rates: FxHashMap::default(),
            refill_notify: Arc::new(tokio::sync::Notify::new()),
            atomic_states: Some(atomic_states),
            block_maps: None,
            steal_candidates: None,
            last_steal_populate: Instant::now(),
            piece_write_guards: None,
            soft_reap_buf: Vec::new(),
            eviction_history: std::collections::VecDeque::new(),
            force_immediate_choker_tick: false,
            piece_tracker: None,
            order_map_dirty: false,
            next_order_map_gen: 0,
            order_map_tx,
            piece_owner: vec![None; num_pieces as usize],
            peer_slab: crate::piece_reservation::PeerSlab::new(),
            priority_pieces: BTreeSet::new(),
            max_in_flight: 512,
            reservation_notify: None,
            last_tick_dispatch_state: None,
            choker: Choker::new(4),
            user_seed_mode: false,
            user_forced: false,
            max_connections: 0,
            peer_states: None,
            connect_semaphore: Arc::new(tokio::sync::Semaphore::new(0)),
            connect_permits: HashMap::new(),
            live_outgoing_peers: std::sync::Arc::new(parking_lot::RwLock::new(
                std::collections::HashMap::new(),
            )),
            connect_rx: None,
            metadata_downloader: None,
            meta: None,
            cached_files: None,
            downloaded: 0,
            uploaded: 0,
            checking_progress: 0.0,
            total_download: 0,
            total_upload: 0,
            total_failed_bytes: 0,
            total_redundant_bytes: 0,
            added_time: 0,
            completed_time: 0,
            last_download: 0,
            last_upload: 0,
            last_seen_complete: 0,
            active_duration: 0,
            finished_duration: 0,
            seeding_duration: 0,
            active_since: None,
            state_duration_since: None,
            started_at: Instant::now(),
            moving_storage: false,
            has_incoming: false,
            need_save_resume: false,
            error: String::new(),
            error_file: -1,
            cmd_rx,
            event_tx,
            event_rx,
            write_error_rx,
            write_error_tx,
            verify_result_rx,
            verify_result_tx,
            pending_verify: HashSet::new(),
            piece_generations: vec![0u64; num_pieces as usize],
            hash_result_rx,
            hash_result_tx,
            listener: None,
            utp_socket: None,
            utp_socket_v6: None,
            tracker_manager: TrackerManager::empty(info_hash, our_peer_id, 0, 0, false),
            tracker_result_rx: None,
            dht_rx,
            dht_v6_rx,
            dht_enabled: false,
            dht_peers_rx: None,
            dht_v6_peers_rx: None,
            dht_v6_empty_count: 0,
            dht_v6_last_retry: None,
            alert_tx,
            alert_mask,
            upload_bucket,
            download_bucket,
            global_upload_bucket: None,
            global_download_bucket: None,
            slot_tuner: crate::slot_tuner::SlotTuner::disabled(4),
            upload_bytes_interval: 0,
            peak_download_rate: 0,
            web_seeds: HashMap::new(),
            banned_web_seeds: HashSet::new(),
            web_seed_in_flight: HashMap::new(),
            web_seed_stats: HashMap::new(),
            pex_peer_count: 0,
            lsd_peer_count: 0,
            super_seed: None,
            have_broadcast_tx,
            suggested_to_peers: HashMap::new(),
            predictive_have_sent: HashSet::new(),
            ban_manager,
            piece_contributors: HashMap::new(),
            parole_pieces: HashMap::new(),
            ip_filter,
            external_ip: None,
            share_lru: std::collections::VecDeque::new(),
            share_max_pieces: 0,
            plugins: Arc::new(Vec::new()),
            hash_picker: None,
            version: irontide_core::TorrentVersion::V1Only,
            meta_v2: None,
            info_hashes: irontide_core::InfoHashes::v1_only(info_hash),
            dht_v2_peers_rx: None,
            dht_v6_v2_peers_rx: None,
            magnet_selected_files: None,
            sam_session: None,
            i2p_accept_rx: None,
            i2p_peer_counter: 0,
            i2p_destinations: HashMap::new(),
            ssl_manager: None,
            rate_limiter_set,
            auto_sequential_active: false,
            factory,
            hash_pool_ref: None,
            connect_attempts: 0,
            connect_failures: 0,
            choke_rotations: 0,
            inflight_started: Vec::new(),
            completed_piece_times: std::collections::VecDeque::new(),
            piece_steals: 0,
            holepunch_relayed: 0,
            holepunch_relay_rate: HashMap::new(),
            holepunch_cooldowns: HashMap::new(),
            holepunch_pending: Vec::new(),
            counters: Arc::new(crate::stats::SessionCounters::new()),
        }
    }
}

// ============================================================================
// Tests
// ============================================================================

#[cfg(test)]
mod tests {
    use super::*;
    use bytes::Bytes;
    use futures::{SinkExt, StreamExt};
    use irontide_wire::{ExtHandshake, Handshake, Message, MessageCodec};
    use std::time::Duration;
    use tokio::io::{AsyncReadExt, AsyncWriteExt};
    use tokio::net::TcpListener;
    use tokio_util::codec::{FramedRead, FramedWrite};

    // M224: initial unchoke slot derivation from Settings.max_uploads_per_torrent.

    #[test]
    fn initial_unchoke_slots_unlimited_returns_default_four() {
        assert_eq!(initial_unchoke_slots(-1), 4);
    }

    #[test]
    fn initial_unchoke_slots_capped_returns_value() {
        assert_eq!(initial_unchoke_slots(1), 1);
        assert_eq!(initial_unchoke_slots(4), 4);
        assert_eq!(initial_unchoke_slots(16), 16);
    }

    // -- Helpers --

    /// Build a valid `TorrentMetaV1` from raw data with given piece length.
    fn make_test_torrent(data: &[u8], piece_length: u64) -> TorrentMetaV1 {
        use serde::Serialize;

        #[derive(Serialize)]
        struct Info<'a> {
            length: u64,
            name: &'a str,
            #[serde(rename = "piece length")]
            piece_length: u64,
            #[serde(with = "serde_bytes")]
            pieces: &'a [u8],
        }

        #[derive(Serialize)]
        struct Torrent<'a> {
            info: Info<'a>,
        }

        let mut pieces = Vec::new();
        let mut offset = 0;
        while offset < data.len() {
            let end = (offset + piece_length as usize).min(data.len());
            let hash = irontide_core::sha1(&data[offset..end]);
            pieces.extend_from_slice(hash.as_bytes());
            offset = end;
        }

        let t = Torrent {
            info: Info {
                length: data.len() as u64,
                name: "test",
                piece_length,
                pieces: &pieces,
            },
        };

        let bytes = irontide_bencode::to_bytes(&t).unwrap();
        torrent_from_bytes(&bytes).unwrap()
    }

    fn test_config() -> TorrentConfig {
        TorrentConfig {
            listen_port: 0, // random port
            max_peers: 200,
            target_request_queue: 5,
            download_dir: std::path::PathBuf::from("/tmp"),
            enable_dht: false,
            enable_pex: false,
            enable_fast: false,
            seed_ratio_limit: None,
            seed_time_limit_secs: None,
            inactive_seed_time_limit_secs: None,
            strict_end_game: true,
            upload_rate_limit: 0,
            download_rate_limit: 0,
            max_uploads_per_torrent: -1,
            encryption_mode: irontide_wire::mse::EncryptionMode::Disabled,
            enable_utp: false,
            enable_web_seed: true,
            enable_holepunch: false,
            enable_bep40_eviction: true,
            max_web_seeds: 4,
            web_seed_retry_base_secs: 10,
            web_seed_retry_factor: 6,
            web_seed_retry_cap_secs: 3600,
            web_seed_max_failures: 10,
            super_seeding: false,
            upload_only_announce: true,
            hashing_threads: 2,
            sequential_download: false,
            initial_picker_threshold: 4,
            whole_pieces_threshold: 20,
            snub_timeout_secs: 15,
            readahead_pieces: 8,
            streaming_timeout_escalation: true,
            max_concurrent_stream_reads: 8,
            proxy: crate::proxy::ProxyConfig::default(),
            anonymous_mode: false,
            share_mode: false,
            enable_i2p: false,
            allow_i2p_mixed: false,
            ssl_listen_port: 0,
            seed_choking_algorithm: crate::choker::SeedChokingAlgorithm::FastestUpload,
            choking_algorithm: crate::choker::ChokingAlgorithm::FixedSlots,
            piece_extent_affinity: true,
            suggest_mode: false,
            max_suggest_pieces: 10,
            predictive_piece_announce_ms: 0,
            mixed_mode_algorithm: crate::rate_limiter::MixedModeAlgorithm::PeerProportional,
            auto_sequential: true,
            storage_mode: irontide_core::StorageMode::Auto,
            preallocate_mode: None,
            block_request_timeout_secs: 60,
            enable_lsd: false,
            force_proxy: false,
            steal_threshold_ratio: 10.0,
            steal_threshold_endgame: 3.0,
            peer_read_timeout_secs: 0,         // disabled in tests
            peer_write_timeout_secs: 0,        // disabled in tests
            data_contribution_timeout_secs: 0, // disabled in tests
            // v0.187.3 eviction tunables — defaults that match production.
            pass0_grace_secs: 60,
            proactive_evictions_per_minute_limit: 30,
            eviction_ban_duration_secs: 600,
            eviction_ban_set_cap: 1024,
            choke_rotation_max_evictions: 0, // disabled in tests
            max_concurrent_connects: 128,
            connect_soft_timeout: 3,
            dispatch_backlog_cap: 8,
            event_backlog_cap: 32,
            peer_writer_channel_cap: 1024,
            use_actor_dispatch: true,
            web_seed_progress_throttle_ms: 250,
            url_security: crate::url_guard::UrlSecurityConfig::default(),
            peer_connect_timeout: 2,
            peer_dscp: 0x08,
            initial_queue_depth: 128,
            max_request_queue_depth: 250,
            request_queue_time: 3.0,
            max_metadata_size: 4 * 1024 * 1024,
            max_message_size: 16 * 1024 * 1024,
            max_piece_length: 32 * 1024 * 1024,
            max_outstanding_requests: 500,
            max_in_flight_pieces: 20,
            use_block_stealing: true,
            steal_stale_piece_secs: 2,
            fixed_pipeline_depth: 128,
            lock_warn_threshold_ms: 0, // disabled in tests
            filesystem_direct_io: false,
            category: None,
            tags: Vec::new(),
        }
    }

    fn make_storage(data: &[u8], piece_length: u64) -> Arc<MemoryStorage> {
        let lengths = Lengths::new(data.len() as u64, piece_length, DEFAULT_CHUNK_SIZE);
        Arc::new(MemoryStorage::new(lengths))
    }

    fn make_seeded_storage(data: &[u8], piece_length: u64) -> Arc<MemoryStorage> {
        let lengths = Lengths::new(data.len() as u64, piece_length, DEFAULT_CHUNK_SIZE);
        let storage = Arc::new(MemoryStorage::new(lengths.clone()));
        // Write data piece by piece
        let num_pieces = lengths.num_pieces();
        for p in 0..num_pieces {
            let piece_size = lengths.piece_size(p) as usize;
            let offset = lengths.piece_offset(p) as usize;
            let end = offset + piece_size;
            storage.write_chunk(p, 0, &data[offset..end]).unwrap();
        }
        storage
    }

    fn test_alert_channel() -> (broadcast::Sender<Alert>, Arc<AtomicU32>) {
        let (tx, _) = broadcast::channel(64);
        let mask = Arc::new(AtomicU32::new(crate::alert::AlertCategory::ALL.bits()));
        (tx, mask)
    }

    fn test_ban_manager() -> irontide_session_types::SharedBanManager {
        Arc::new(parking_lot::RwLock::new(crate::ban::BanManager::new(
            crate::ban::BanConfig::default(),
        )))
    }

    fn test_ip_filter() -> irontide_session_types::SharedIpFilter {
        Arc::new(parking_lot::RwLock::new(crate::ip_filter::IpFilter::new()))
    }

    fn test_disk_manager() -> (DiskManagerHandle, tokio::task::JoinHandle<()>) {
        DiskManagerHandle::new(crate::disk::DiskConfig::default())
    }

    async fn test_register_disk(
        info_hash: Id20,
        storage: Arc<dyn TorrentStorage>,
    ) -> (DiskHandle, DiskManagerHandle, tokio::task::JoinHandle<()>) {
        let (dm, join) = test_disk_manager();
        let dh = dm.register_torrent(info_hash, storage).await;
        (dh, dm, join)
    }

    /// M173 Lane B (B6): build a `DhtReceiver` pre-populated with `None`
    /// — what the test fixtures previously passed as `dht: None`.
    fn test_dht_rx() -> irontide_dht::DhtReceiver {
        // `&'static` storage so each call returns a fresh subscriber
        // without leaking the underlying broadcast.
        let bx = irontide_dht::DhtBroadcast::new(None);
        bx.subscribe()
    }

    /// Handshake size constant.
    const HANDSHAKE_SIZE: usize = 68;

    // ---- Test 1: Create from torrent ----

    #[tokio::test]
    async fn create_from_torrent() {
        let data = vec![0xAB; 32768]; // 32 KiB
        let meta = make_test_torrent(&data, 16384); // 2 pieces
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::Downloading);
        assert_eq!(stats.pieces_total, 2);
        assert_eq!(stats.pieces_have, 0);
        assert_eq!(stats.peers_connected, 0);

        handle.shutdown().await.unwrap();
    }

    // ---- M245 F1: atomic TakeResumeIfDirty / MarkResumeDirty ----

    /// Build a started `TorrentHandle` over a 2-piece in-memory torrent.
    /// Returns the handle, the independently-derived expected piece-hash hex
    /// (v1 SHA-1, computed from `meta.info.pieces` BEFORE the meta is consumed —
    /// the parity oracle for L3), and the disk-manager join handle (kept alive
    /// by the caller — dropping it would abort the disk-manager task). Mirrors
    /// `create_from_torrent`'s construction so the tests drive a real actor.
    async fn started_test_handle() -> (TorrentHandle, Vec<String>, tokio::task::JoinHandle<()>) {
        let data = vec![0xAB; 32768]; // 32 KiB → 2 pieces at 16 KiB
        let meta = make_test_torrent(&data, 16384);
        let expected_hex: Vec<String> =
            meta.info.pieces.chunks_exact(20).map(hex::encode).collect();
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None,
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();
        (handle, expected_hex, dj)
    }

    /// F1 atomicity: a dirty torrent yields resume data exactly ONCE — the take
    /// clears `need_save_resume` in the same actor turn, so the immediate second
    /// take sees a clean torrent and returns `None`. This is the property the
    /// pre-M245 `stats()`→`save_resume_data()`→`clear_save_resume_flag()`
    /// three-step could not guarantee (a dirty mark landing between the separate
    /// check and clear was lost).
    #[tokio::test]
    async fn take_resume_if_dirty_is_atomic_capture_and_clear() {
        let (handle, _expected_hex, _dj) = started_test_handle().await;

        // SetTags is a synchronous, explicit `need_save_resume = true` with a
        // reply — a deterministic dirty trigger (no reliance on state-machine
        // side effects).
        handle.set_tags(vec!["m245".to_string()]).await.unwrap();

        let first = handle.take_resume_if_dirty().await.unwrap();
        assert!(first.is_some(), "dirty torrent must yield resume data");

        let second = handle.take_resume_if_dirty().await.unwrap();
        assert!(
            second.is_none(),
            "flag was cleared atomically in the same take — no second capture"
        );

        handle.shutdown().await.unwrap();
    }

    /// F1 retry guarantee (RATIFIED D3-A): after a take has already cleared the
    /// flag, a simulated off-actor write failure re-dirties via
    /// `mark_resume_dirty`, and the NEXT take re-captures — the resume update is
    /// not lost. Without the re-dirty the torrent would stay clean and skip its
    /// retry until it next mutated, risking a stale `.resume` on disk.
    #[tokio::test]
    async fn mark_resume_dirty_restores_capture_after_write_failure() {
        let (handle, _expected_hex, _dj) = started_test_handle().await;

        handle.set_tags(vec!["m245".to_string()]).await.unwrap();

        let captured = handle.take_resume_if_dirty().await.unwrap();
        assert!(captured.is_some(), "dirty torrent captured once");

        // Clean now — confirm the take cleared it before we re-dirty.
        let between = handle.take_resume_if_dirty().await.unwrap();
        assert!(between.is_none(), "take cleared the flag");

        // Simulate run_resume_save_jobs' write failure path re-arming the flag.
        handle.mark_resume_dirty().await.unwrap();

        let recaptured = handle.take_resume_if_dirty().await.unwrap();
        assert!(
            recaptured.is_some(),
            "re-dirtied torrent must re-capture — no lost resume update"
        );

        handle.shutdown().await.unwrap();
    }

    /// L3 (M245): `get_piece_hashes` returns correctly hex-encoded v1 SHA-1
    /// piece hashes. Behaviour-parity guard for moving the `hex::encode` OFF the
    /// recv loop (the actor now returns raw bytes for the window; the handle
    /// method encodes) — the public `Vec<String>` output must stay byte-identical
    /// to encoding `meta.info.pieces` directly. Also pins the windowing
    /// semantics: `[offset, offset+limit)` clamped to the hash count.
    #[tokio::test]
    async fn get_piece_hashes_hex_parity_and_windowing() {
        let (handle, expected_hex, _dj) = started_test_handle().await;
        assert_eq!(expected_hex.len(), 2, "2-piece test torrent");

        // Full range: output equals the independently-computed hex.
        let all = handle.get_piece_hashes(0, 1000).await.unwrap();
        assert_eq!(
            all, expected_hex,
            "hex output must match the raw piece hashes"
        );

        // Window: offset 1, limit 1 → only the second hash.
        let windowed = handle.get_piece_hashes(1, 1).await.unwrap();
        assert_eq!(windowed, vec![expected_hex[1].clone()]);

        // offset 0, limit 1 → only the first.
        let first = handle.get_piece_hashes(0, 1).await.unwrap();
        assert_eq!(first, vec![expected_hex[0].clone()]);

        // Offset past the end → empty (clamped, no panic).
        let past = handle.get_piece_hashes(99, 5).await.unwrap();
        assert!(past.is_empty(), "offset past end yields empty");

        // limit beyond end → clamped to what remains.
        let clamped = handle.get_piece_hashes(1, 1000).await.unwrap();
        assert_eq!(clamped, vec![expected_hex[1].clone()]);

        handle.shutdown().await.unwrap();
    }

    // ---- Test 2: Create from magnet ----

    #[tokio::test]
    async fn create_from_magnet() {
        let magnet = Magnet {
            info_hashes: irontide_core::InfoHashes::v1_only(
                Id20::from_hex("aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d").unwrap(),
            ),
            display_name: Some("test".into()),
            trackers: vec![],
            peers: vec![],
            selected_files: None,
        };
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dm, _dj) = test_disk_manager();
        let handle = TorrentHandle::from_magnet(
            magnet,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::FetchingMetadata);
        assert_eq!(stats.pieces_total, 0);

        handle.shutdown().await.unwrap();
    }

    // ---- Test 3: Add peers ----

    #[tokio::test]
    async fn add_peers_increases_available() {
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Bind listeners so the connect attempts succeed and peers stay in connected state
        let listener1 = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr1 = listener1.local_addr().unwrap();
        let listener2 = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr2 = listener2.local_addr().unwrap();

        handle
            .add_peers(vec![addr1, addr2], PeerSource::Tracker)
            .await
            .unwrap();

        // Small delay for the actor to process
        tokio::time::sleep(Duration::from_millis(100)).await;

        let stats = handle.stats().await.unwrap();
        // Peers may be available or already connecting (try_connect_peers fires immediately)
        assert!(
            stats.peers_available + stats.peers_connected >= 2,
            "expected at least 2 peers known, got available={}, connected={}",
            stats.peers_available,
            stats.peers_connected
        );

        handle.shutdown().await.unwrap();
    }

    // ---- Test 4: Stats reporting ----

    #[tokio::test]
    async fn stats_reporting() {
        let data = vec![0xAB; 65536]; // 64 KiB
        let meta = make_test_torrent(&data, 16384); // 4 pieces
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::Downloading);
        assert_eq!(stats.downloaded, 0);
        assert_eq!(stats.uploaded, 0);
        assert_eq!(stats.pieces_have, 0);
        assert_eq!(stats.pieces_total, 4);
        assert_eq!(stats.peers_connected, 0);
        assert_eq!(stats.peers_available, 0);

        handle.shutdown().await.unwrap();
    }

    // ---- Test 5: Private torrent disables DHT/PEX ----

    #[tokio::test]
    async fn private_torrent_disables_dht_pex() {
        // Build a private torrent by embedding private=1 in the info dict
        use serde::Serialize;

        #[derive(Serialize)]
        struct Info<'a> {
            length: u64,
            name: &'a str,
            #[serde(rename = "piece length")]
            piece_length: u64,
            #[serde(with = "serde_bytes")]
            pieces: &'a [u8],
            private: i64,
        }

        #[derive(Serialize)]
        struct Torrent<'a> {
            info: Info<'a>,
        }

        let data = vec![0xAB; 16384];
        let hash = irontide_core::sha1(&data);
        let mut pieces = Vec::new();
        pieces.extend_from_slice(hash.as_bytes());

        let t = Torrent {
            info: Info {
                length: data.len() as u64,
                name: "private_test",
                piece_length: 16384,
                pieces: &pieces,
                private: 1,
            },
        };

        let bytes = irontide_bencode::to_bytes(&t).unwrap();
        let meta = torrent_from_bytes(&bytes).unwrap();
        assert_eq!(meta.info.private, Some(1));

        let storage = make_storage(&data, 16384);
        let mut config = test_config();
        config.enable_dht = true;
        config.enable_pex = true;

        // The from_torrent constructor should disable DHT and PEX
        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // We can't directly inspect the actor's config, but we can verify
        // the torrent was created successfully. The real test is that PEX peers
        // would be ignored and DHT not used. For now verify the handle works.
        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::Downloading);

        handle.shutdown().await.unwrap();
    }

    // ---- Test 6: Shutdown cleanup ----

    #[tokio::test]
    async fn shutdown_cleanup() {
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        handle.shutdown().await.unwrap();

        // After shutdown, stats should fail (channel closed)
        tokio::time::sleep(Duration::from_millis(50)).await;
        let result = handle.stats().await;
        assert!(result.is_err());
    }

    // ---- Test 7: Duplicate add_peers ignored ----

    #[tokio::test]
    async fn duplicate_peers_ignored() {
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Bind a listener so the connection succeeds and the peer stays connected
        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        handle
            .add_peers(vec![addr, addr, addr], PeerSource::Tracker)
            .await
            .unwrap();

        tokio::time::sleep(Duration::from_millis(100)).await;
        let stats = handle.stats().await.unwrap();
        // Only one unique peer should be known (available or connecting)
        assert!(
            stats.peers_available + stats.peers_connected <= 1,
            "expected at most 1 unique peer, got available={}, connected={}",
            stats.peers_available,
            stats.peers_connected
        );

        handle.shutdown().await.unwrap();
    }

    // ---- Test 8: Multiple handles (Clone) share same actor ----

    #[tokio::test]
    async fn cloned_handle_shares_actor() {
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();
        let handle2 = handle.clone();

        // Bind a listener so the connection succeeds and the peer stays connected
        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let peer_addr = listener.local_addr().unwrap();

        // Add peers through one handle
        handle
            .add_peers(vec![peer_addr], PeerSource::Tracker)
            .await
            .unwrap();

        tokio::time::sleep(Duration::from_millis(100)).await;

        // Read stats through the other — peer may be available or connecting
        let stats = handle2.stats().await.unwrap();
        assert!(
            stats.peers_available + stats.peers_connected >= 1,
            "expected at least 1 peer known, got available={}, connected={}",
            stats.peers_available,
            stats.peers_connected
        );

        handle.shutdown().await.unwrap();
    }

    // ---- Test 9: Peer connection and disconnect via listener ----

    #[tokio::test]
    async fn peer_connect_and_disconnect_via_listener() {
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;
        let storage = make_storage(&data, 16384);

        // Bind a listener on a specific port so we can connect to it
        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let listen_addr = listener.local_addr().unwrap();

        let config = TorrentConfig {
            listen_port: listen_addr.port(),
            ..test_config()
        };

        // Drop the pre-bound listener before from_torrent binds
        drop(listener);

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Give the actor time to start
        tokio::time::sleep(Duration::from_millis(50)).await;

        // Connect a mock peer
        let mut stream = tokio::net::TcpStream::connect(listen_addr).await.unwrap();

        // Perform handshake
        let remote_id = Id20::from_hex("1111111111111111111111111111111111111111").unwrap();
        let remote_hs = Handshake::new(info_hash, remote_id);
        stream.write_all(&remote_hs.to_bytes()).await.unwrap();
        stream.flush().await.unwrap();

        let mut hs_buf = [0u8; HANDSHAKE_SIZE];
        stream.read_exact(&mut hs_buf).await.unwrap();
        let their_hs = Handshake::from_bytes(&hs_buf).unwrap();
        assert_eq!(their_hs.info_hash, info_hash);

        // Give time for peer to be registered
        tokio::time::sleep(Duration::from_millis(100)).await;

        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.peers_connected, 1);

        // Drop the connection
        drop(stream);

        // Wait for disconnect event
        tokio::time::sleep(Duration::from_millis(200)).await;

        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.peers_connected, 0);

        handle.shutdown().await.unwrap();
    }

    // ---- Test 10: Piece download and verification via injected events ----
    //
    // We test the full flow: connect a mock peer that sends bitfield, unchoke,
    // then responds to requests with correct piece data.

    #[tokio::test]
    async fn piece_download_and_verify() {
        // Create a 1-piece torrent with 16384 bytes (exactly one chunk)
        let data = vec![0xCDu8; 16384];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;
        let storage = make_storage(&data, 16384);

        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let listen_addr = listener.local_addr().unwrap();
        drop(listener);

        let config = TorrentConfig {
            listen_port: listen_addr.port(),
            ..test_config()
        };

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        tokio::time::sleep(Duration::from_millis(50)).await;

        // Connect mock peer
        let stream = tokio::net::TcpStream::connect(listen_addr).await.unwrap();
        let remote_id = Id20::from_hex("2222222222222222222222222222222222222222").unwrap();

        // Run mock seeder in a task
        let mock_data = data.clone();
        let mock_task = tokio::spawn(async move {
            let (reader, writer) = tokio::io::split(stream);
            let mut reader = reader;
            let mut writer = writer;

            // Handshake
            let hs = Handshake::new(info_hash, remote_id);
            writer.write_all(&hs.to_bytes()).await.unwrap();
            writer.flush().await.unwrap();

            let mut hs_buf = [0u8; HANDSHAKE_SIZE];
            reader.read_exact(&mut hs_buf).await.unwrap();

            // Switch to framed
            let mut framed_read = FramedRead::new(reader, MessageCodec::new());
            let mut framed_write = FramedWrite::new(writer, MessageCodec::new());

            // Read ext handshake from the torrent actor's peer
            let _msg = framed_read.next().await;

            // Send ext handshake back
            let ext_hs = ExtHandshake::new();
            let payload = ext_hs.to_bytes().unwrap();
            framed_write
                .send(Message::Extended { ext_id: 0, payload })
                .await
                .unwrap();

            // Send bitfield (all pieces = piece 0 set)
            let mut bf = Bitfield::new(1);
            bf.set(0);
            framed_write
                .send(Message::Bitfield(Bytes::copy_from_slice(bf.as_bytes())))
                .await
                .unwrap();

            // Send Unchoke
            framed_write.send(Message::Unchoke).await.unwrap();

            // Wait for requests and respond with piece data
            while let Some(Ok(msg)) = framed_read.next().await {
                if let Message::Request {
                    index,
                    begin,
                    length,
                } = msg
                {
                    let start = begin as usize;
                    let end = start + length as usize;
                    let piece_data = &mock_data[start..end];
                    framed_write
                        .send(Message::Piece {
                            index,
                            begin,
                            data_0: Bytes::copy_from_slice(piece_data),
                            data_1: Bytes::new(),
                        })
                        .await
                        .unwrap();
                }
            }
        });

        // Wait for the download to complete
        let deadline = tokio::time::Instant::now() + Duration::from_secs(5);
        loop {
            tokio::time::sleep(Duration::from_millis(100)).await;
            let stats = handle.stats().await.unwrap();
            if stats.state == TorrentState::Seeding {
                assert_eq!(stats.pieces_have, 1);
                assert_eq!(stats.pieces_total, 1);
                break;
            }
            if tokio::time::Instant::now() > deadline {
                let stats = handle.stats().await.unwrap();
                panic!(
                    "download did not complete within 5s, state={:?}, have={}/{}",
                    stats.state, stats.pieces_have, stats.pieces_total
                );
            }
        }

        handle.shutdown().await.unwrap();
        mock_task.abort();
    }

    // ---- Test 11: Failed piece verification re-requests ----

    #[tokio::test]
    async fn failed_piece_verification() {
        // Create a 1-piece torrent
        let data = vec![0xEEu8; 16384];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;
        let storage = make_storage(&data, 16384);

        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let listen_addr = listener.local_addr().unwrap();
        drop(listener);

        let config = TorrentConfig {
            listen_port: listen_addr.port(),
            ..test_config()
        };

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        tokio::time::sleep(Duration::from_millis(50)).await;

        // Connect mock peer that first sends bad data, then correct data
        let stream = tokio::net::TcpStream::connect(listen_addr).await.unwrap();
        let remote_id = Id20::from_hex("3333333333333333333333333333333333333333").unwrap();

        let correct_data = data.clone();
        let mock_task = tokio::spawn(async move {
            let (reader, writer) = tokio::io::split(stream);

            // Handshake
            let mut writer = writer;
            let mut reader = reader;
            let hs = Handshake::new(info_hash, remote_id);
            writer.write_all(&hs.to_bytes()).await.unwrap();
            writer.flush().await.unwrap();

            let mut hs_buf = [0u8; HANDSHAKE_SIZE];
            reader.read_exact(&mut hs_buf).await.unwrap();

            let mut framed_read = FramedRead::new(reader, MessageCodec::new());
            let mut framed_write = FramedWrite::new(writer, MessageCodec::new());

            // Read ext handshake
            let _msg = framed_read.next().await;

            // Send ext handshake
            let ext_hs = ExtHandshake::new();
            let payload = ext_hs.to_bytes().unwrap();
            framed_write
                .send(Message::Extended { ext_id: 0, payload })
                .await
                .unwrap();

            // Bitfield: have piece 0
            let mut bf = Bitfield::new(1);
            bf.set(0);
            framed_write
                .send(Message::Bitfield(Bytes::copy_from_slice(bf.as_bytes())))
                .await
                .unwrap();

            // Unchoke
            framed_write.send(Message::Unchoke).await.unwrap();

            let mut request_count = 0u32;
            while let Some(Ok(msg)) = framed_read.next().await {
                if let Message::Request {
                    index,
                    begin,
                    length,
                } = msg
                {
                    request_count += 1;
                    let piece_data = if request_count <= 1 {
                        // First request: send bad data
                        vec![0xFF; length as usize]
                    } else {
                        // Subsequent: send correct data
                        let start = begin as usize;
                        let end = start + length as usize;
                        correct_data[start..end].to_vec()
                    };
                    framed_write
                        .send(Message::Piece {
                            index,
                            begin,
                            data_0: Bytes::from(piece_data),
                            data_1: Bytes::new(),
                        })
                        .await
                        .unwrap();
                }
            }
        });

        // Wait for completion (should eventually succeed after retry)
        let deadline = tokio::time::Instant::now() + Duration::from_secs(5);
        loop {
            tokio::time::sleep(Duration::from_millis(100)).await;
            let stats = handle.stats().await.unwrap();
            if stats.state == TorrentState::Seeding {
                assert_eq!(stats.pieces_have, 1);
                break;
            }
            if tokio::time::Instant::now() > deadline {
                let stats = handle.stats().await.unwrap();
                panic!(
                    "download did not complete after retry within 5s, state={:?}, have={}",
                    stats.state, stats.pieces_have,
                );
            }
        }

        handle.shutdown().await.unwrap();
        mock_task.abort();
    }

    // ---- Test 12: Complete state transitions after all pieces ----

    #[tokio::test]
    async fn complete_transitions_state() {
        // 2-piece torrent, each 16384 bytes (one chunk each)
        let data = vec![0xBBu8; 32768];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;
        let storage = make_storage(&data, 16384);

        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let listen_addr = listener.local_addr().unwrap();
        drop(listener);

        let config = TorrentConfig {
            listen_port: listen_addr.port(),
            ..test_config()
        };

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        tokio::time::sleep(Duration::from_millis(50)).await;

        // Mock seeder with all 2 pieces
        let stream = tokio::net::TcpStream::connect(listen_addr).await.unwrap();
        let remote_id = Id20::from_hex("4444444444444444444444444444444444444444").unwrap();

        let mock_data = data.clone();
        let mock_task = tokio::spawn(async move {
            let (reader, writer) = tokio::io::split(stream);
            let mut writer = writer;
            let mut reader = reader;

            let hs = Handshake::new(info_hash, remote_id);
            writer.write_all(&hs.to_bytes()).await.unwrap();
            writer.flush().await.unwrap();

            let mut hs_buf = [0u8; HANDSHAKE_SIZE];
            reader.read_exact(&mut hs_buf).await.unwrap();

            let mut framed_read = FramedRead::new(reader, MessageCodec::new());
            let mut framed_write = FramedWrite::new(writer, MessageCodec::new());

            // Read ext handshake
            let _msg = framed_read.next().await;

            // Send ext handshake
            let ext_hs = ExtHandshake::new();
            let payload = ext_hs.to_bytes().unwrap();
            framed_write
                .send(Message::Extended { ext_id: 0, payload })
                .await
                .unwrap();

            // Bitfield: have both pieces
            let mut bf = Bitfield::new(2);
            bf.set(0);
            bf.set(1);
            framed_write
                .send(Message::Bitfield(Bytes::copy_from_slice(bf.as_bytes())))
                .await
                .unwrap();

            framed_write.send(Message::Unchoke).await.unwrap();

            while let Some(Ok(msg)) = framed_read.next().await {
                if let Message::Request {
                    index,
                    begin,
                    length,
                } = msg
                {
                    let abs_start = (index as usize * 16384) + begin as usize;
                    let abs_end = abs_start + length as usize;
                    let piece_data = &mock_data[abs_start..abs_end];
                    framed_write
                        .send(Message::Piece {
                            index,
                            begin,
                            data_0: Bytes::copy_from_slice(piece_data),
                            data_1: Bytes::new(),
                        })
                        .await
                        .unwrap();
                }
            }
        });

        let deadline = tokio::time::Instant::now() + Duration::from_secs(5);
        loop {
            tokio::time::sleep(Duration::from_millis(100)).await;
            let stats = handle.stats().await.unwrap();
            if stats.state == TorrentState::Seeding {
                assert_eq!(stats.pieces_have, 2);
                assert_eq!(stats.pieces_total, 2);
                break;
            }
            if tokio::time::Instant::now() > deadline {
                let stats = handle.stats().await.unwrap();
                panic!(
                    "expected Complete, got {:?}, have={}/{}",
                    stats.state, stats.pieces_have, stats.pieces_total
                );
            }
        }

        handle.shutdown().await.unwrap();
        mock_task.abort();
    }

    // ---- Test 13: Multiple pieces with multi-chunk pieces ----

    #[tokio::test]
    async fn multi_chunk_piece_download() {
        // 1 piece of 32768 bytes = 2 chunks of 16384 each
        let data = vec![0xAAu8; 32768];
        let meta = make_test_torrent(&data, 32768);
        let info_hash = meta.info_hash;
        let storage = make_storage(&data, 32768);

        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let listen_addr = listener.local_addr().unwrap();
        drop(listener);

        let config = TorrentConfig {
            listen_port: listen_addr.port(),
            ..test_config()
        };

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        tokio::time::sleep(Duration::from_millis(50)).await;

        let stream = tokio::net::TcpStream::connect(listen_addr).await.unwrap();
        let remote_id = Id20::from_hex("5555555555555555555555555555555555555555").unwrap();

        let mock_data = data.clone();
        let mock_task = tokio::spawn(async move {
            let (reader, writer) = tokio::io::split(stream);
            let mut writer = writer;
            let mut reader = reader;

            let hs = Handshake::new(info_hash, remote_id);
            writer.write_all(&hs.to_bytes()).await.unwrap();
            writer.flush().await.unwrap();

            let mut hs_buf = [0u8; HANDSHAKE_SIZE];
            reader.read_exact(&mut hs_buf).await.unwrap();

            let mut framed_read = FramedRead::new(reader, MessageCodec::new());
            let mut framed_write = FramedWrite::new(writer, MessageCodec::new());

            let _msg = framed_read.next().await;

            let ext_hs = ExtHandshake::new();
            let payload = ext_hs.to_bytes().unwrap();
            framed_write
                .send(Message::Extended { ext_id: 0, payload })
                .await
                .unwrap();

            let mut bf = Bitfield::new(1);
            bf.set(0);
            framed_write
                .send(Message::Bitfield(Bytes::copy_from_slice(bf.as_bytes())))
                .await
                .unwrap();

            framed_write.send(Message::Unchoke).await.unwrap();

            while let Some(Ok(msg)) = framed_read.next().await {
                if let Message::Request {
                    index: _,
                    begin,
                    length,
                } = msg
                {
                    let start = begin as usize;
                    let end = start + length as usize;
                    framed_write
                        .send(Message::Piece {
                            index: 0,
                            begin,
                            data_0: Bytes::copy_from_slice(&mock_data[start..end]),
                            data_1: Bytes::new(),
                        })
                        .await
                        .unwrap();
                }
            }
        });

        let deadline = tokio::time::Instant::now() + Duration::from_secs(5);
        loop {
            tokio::time::sleep(Duration::from_millis(100)).await;
            let stats = handle.stats().await.unwrap();
            if stats.state == TorrentState::Seeding {
                assert_eq!(stats.pieces_have, 1);
                break;
            }
            assert!(
                tokio::time::Instant::now() <= deadline,
                "multi-chunk download did not complete within 5s"
            );
        }

        handle.shutdown().await.unwrap();
        mock_task.abort();
    }

    // ---- Test 14: Seeder/Leecher integration with two actors ----

    #[tokio::test]
    async fn seeder_leecher_integration() {
        // Seeder has all data, leecher has none. Connect them via TCP.
        let data = vec![0xDDu8; 32768]; // 32 KiB, 2 pieces of 16384
        let piece_length = 16384u64;
        let meta = make_test_torrent(&data, piece_length);
        let info_hash = meta.info_hash;

        // Seeder: storage pre-filled
        let seeder_storage = make_seeded_storage(&data, piece_length);

        // For the seeder, we need a from_torrent variant that starts in Complete state
        // but still serves pieces. Since our actor starts in Downloading, the seeder
        // will just be a mock that accepts and serves.

        // Use a mock seeder approach instead (manual protocol handling):
        let seeder_listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let seeder_addr = seeder_listener.local_addr().unwrap();

        let seeder_task = tokio::spawn(async move {
            let (stream, _addr) = seeder_listener.accept().await.unwrap();
            let (reader, writer) = tokio::io::split(stream);
            let mut writer = writer;
            let mut reader = reader;

            // Handshake
            let mut hs_buf = [0u8; HANDSHAKE_SIZE];
            reader.read_exact(&mut hs_buf).await.unwrap();
            let their_hs = Handshake::from_bytes(&hs_buf).unwrap();
            assert_eq!(their_hs.info_hash, info_hash);

            let hs = Handshake::new(info_hash, PeerId::generate().0);
            writer.write_all(&hs.to_bytes()).await.unwrap();
            writer.flush().await.unwrap();

            let mut framed_read = FramedRead::new(reader, MessageCodec::new());
            let mut framed_write = FramedWrite::new(writer, MessageCodec::new());

            // Read ext handshake
            let _msg = framed_read.next().await;

            // Send ext handshake
            let ext_hs = ExtHandshake::new();
            let payload = ext_hs.to_bytes().unwrap();
            framed_write
                .send(Message::Extended { ext_id: 0, payload })
                .await
                .unwrap();

            // Send bitfield (all pieces)
            let mut bf = Bitfield::new(2);
            bf.set(0);
            bf.set(1);
            framed_write
                .send(Message::Bitfield(Bytes::copy_from_slice(bf.as_bytes())))
                .await
                .unwrap();

            // Unchoke
            framed_write.send(Message::Unchoke).await.unwrap();

            // Serve requests
            while let Some(Ok(msg)) = framed_read.next().await {
                if let Message::Request {
                    index,
                    begin,
                    length,
                } = msg
                {
                    let piece_data = seeder_storage.read_chunk(index, begin, length).unwrap();
                    framed_write
                        .send(Message::Piece {
                            index,
                            begin,
                            data_0: Bytes::from(piece_data),
                            data_1: Bytes::new(),
                        })
                        .await
                        .unwrap();
                }
            }
        });

        // Leecher: empty storage
        let leecher_storage = make_storage(&data, piece_length);
        let leecher_meta = make_test_torrent(&data, piece_length);

        let leecher_config = test_config();
        let (latx, lamask) = test_alert_channel();
        let (ldh, ldm, _ldj) = test_register_disk(leecher_meta.info_hash, leecher_storage).await;
        let leecher = TorrentHandle::from_torrent(
            leecher_meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            ldh,
            ldm,
            leecher_config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            latx,
            lamask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Add seeder as a peer
        leecher
            .add_peers(vec![seeder_addr], PeerSource::Tracker)
            .await
            .unwrap();

        // Give the connect interval time to fire (it ticks every 5s).
        // The actor's try_connect_peers runs on the timer, and also immediately
        // when peers are added via AddPeers command. Wait up to 10 seconds.
        let deadline = tokio::time::Instant::now() + Duration::from_secs(10);
        loop {
            tokio::time::sleep(Duration::from_millis(200)).await;
            let stats = leecher.stats().await.unwrap();
            if stats.state == TorrentState::Seeding {
                assert_eq!(stats.pieces_have, 2);
                assert_eq!(stats.pieces_total, 2);
                break;
            }
            if tokio::time::Instant::now() > deadline {
                let stats = leecher.stats().await.unwrap();
                panic!(
                    "seeder/leecher: leecher did not complete, state={:?}, have={}/{}, connected={}, available={}",
                    stats.state,
                    stats.pieces_have,
                    stats.pieces_total,
                    stats.peers_connected,
                    stats.peers_available,
                );
            }
        }

        leecher.shutdown().await.unwrap();
        seeder_task.abort();
    }

    // ---- Test 15: Magnet stats ----

    #[tokio::test]
    async fn magnet_initial_stats() {
        let magnet = Magnet {
            info_hashes: irontide_core::InfoHashes::v1_only(
                Id20::from_hex("bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb").unwrap(),
            ),
            display_name: Some("magnet test".into()),
            trackers: vec![],
            peers: vec![],
            selected_files: None,
        };

        let (atx, amask) = test_alert_channel();
        let (dm, _dj) = test_disk_manager();
        let handle = TorrentHandle::from_magnet(
            magnet,
            dm,
            test_config(),
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::FetchingMetadata);
        assert_eq!(stats.pieces_total, 0);
        assert_eq!(stats.pieces_have, 0);
        assert_eq!(stats.downloaded, 0);
        assert_eq!(stats.uploaded, 0);
        assert_eq!(stats.peers_connected, 0);
        assert_eq!(stats.peers_available, 0);

        handle.shutdown().await.unwrap();
    }

    // ---- Test 16: Tracker manager is populated from torrent metadata ----

    #[tokio::test]
    async fn tracker_populated_from_metadata() {
        use serde::Serialize;

        #[derive(Serialize)]
        struct Info<'a> {
            length: u64,
            name: &'a str,
            #[serde(rename = "piece length")]
            piece_length: u64,
            #[serde(with = "serde_bytes")]
            pieces: &'a [u8],
        }

        #[derive(Serialize)]
        struct Torrent<'a> {
            announce: &'a str,
            info: Info<'a>,
        }

        let data = vec![0xAB; 16384];
        let hash = irontide_core::sha1(&data);
        let mut pieces = Vec::new();
        pieces.extend_from_slice(hash.as_bytes());

        let t = Torrent {
            announce: "http://tracker.example.com:8080/announce",
            info: Info {
                length: data.len() as u64,
                name: "test",
                piece_length: 16384,
                pieces: &pieces,
            },
        };

        let bytes = irontide_bencode::to_bytes(&t).unwrap();
        let meta = torrent_from_bytes(&bytes).unwrap();
        assert!(meta.announce.is_some());

        let storage = make_storage(&data, 16384);
        let config = test_config();

        // The torrent should start and announce to tracker (which will fail since
        // the tracker doesn't exist, but that's fine — failures are non-fatal).
        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::Downloading);

        handle.shutdown().await.unwrap();
    }

    // ---- Test 17: Private torrent with DHT=None works ----

    #[tokio::test]
    async fn private_torrent_no_dht_field() {
        use serde::Serialize;

        #[derive(Serialize)]
        struct Info<'a> {
            length: u64,
            name: &'a str,
            #[serde(rename = "piece length")]
            piece_length: u64,
            #[serde(with = "serde_bytes")]
            pieces: &'a [u8],
            private: i64,
        }

        #[derive(Serialize)]
        struct Torrent<'a> {
            announce: &'a str,
            info: Info<'a>,
        }

        let data = vec![0xAB; 16384];
        let hash = irontide_core::sha1(&data);
        let mut pieces = Vec::new();
        pieces.extend_from_slice(hash.as_bytes());

        let t = Torrent {
            announce: "http://private-tracker.example.com/announce",
            info: Info {
                length: data.len() as u64,
                name: "private_test",
                piece_length: 16384,
                pieces: &pieces,
                private: 1,
            },
        };

        let bytes = irontide_bencode::to_bytes(&t).unwrap();
        let meta = torrent_from_bytes(&bytes).unwrap();
        assert_eq!(meta.info.private, Some(1));

        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::Downloading);

        handle.shutdown().await.unwrap();
    }

    // ---- Test 18: Magnet defers tracker announce ----

    #[tokio::test]
    async fn magnet_no_tracker_before_metadata() {
        let magnet = Magnet {
            info_hashes: irontide_core::InfoHashes::v1_only(
                Id20::from_hex("cccccccccccccccccccccccccccccccccccccccc").unwrap(),
            ),
            display_name: Some("magnet test".into()),
            trackers: vec![],
            peers: vec![],
            selected_files: None,
        };

        let (atx, amask) = test_alert_channel();
        let (dm, _dj) = test_disk_manager();
        let handle = TorrentHandle::from_magnet(
            magnet,
            dm,
            test_config(),
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::FetchingMetadata);

        // With no trackers configured, no announces happen regardless of state.
        // Note: tracker announces ARE now allowed during FetchingMetadata for
        // magnets with &tr= URLs (needed to discover peers before metadata).
        tokio::time::sleep(Duration::from_millis(50)).await;

        handle.shutdown().await.unwrap();
    }

    // ---- Test 19: Pause and resume ----

    #[tokio::test]
    async fn pause_and_resume() {
        let data = vec![0xEEu8; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();
        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::Downloading);

        handle.pause().await.unwrap();
        tokio::time::sleep(Duration::from_millis(50)).await;
        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::Paused);

        handle.resume().await.unwrap();
        tokio::time::sleep(Duration::from_millis(50)).await;
        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::Downloading);

        handle.shutdown().await.unwrap();
    }

    // ---- Test 20: Pause already paused is noop ----

    #[tokio::test]
    async fn pause_already_paused_is_noop() {
        let data = vec![0xEEu8; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();
        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        handle.pause().await.unwrap();
        tokio::time::sleep(Duration::from_millis(50)).await;
        handle.pause().await.unwrap(); // double pause is fine
        tokio::time::sleep(Duration::from_millis(50)).await;
        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::Paused);

        handle.shutdown().await.unwrap();
    }

    // ---- Test 21: Incoming request served from storage ----
    //
    // Phase 1: Mock seeder feeds piece 0 to the torrent so it becomes verified.
    // Phase 2: Mock leecher connects and requests piece 0, verifying upload pipeline.

    #[tokio::test]
    async fn incoming_request_served_from_storage() {
        let data = vec![0xABu8; 16384];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;
        let storage = make_storage(&data, 16384);

        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let listen_addr = listener.local_addr().unwrap();
        drop(listener);

        let config = TorrentConfig {
            listen_port: listen_addr.port(),
            ..test_config()
        };

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        tokio::time::sleep(Duration::from_millis(50)).await;

        // Phase 1: Seed the torrent with piece 0
        let seed_data = data.clone();
        let seed_stream = tokio::net::TcpStream::connect(listen_addr).await.unwrap();
        let seeder_task = tokio::spawn(async move {
            let (reader, writer) = tokio::io::split(seed_stream);
            let mut writer = writer;
            let mut reader = reader;

            let hs = Handshake::new(
                info_hash,
                Id20::from_hex("6666666666666666666666666666666666666666").unwrap(),
            );
            writer.write_all(&hs.to_bytes()).await.unwrap();
            writer.flush().await.unwrap();
            let mut hs_buf = [0u8; HANDSHAKE_SIZE];
            reader.read_exact(&mut hs_buf).await.unwrap();

            let mut framed_read = FramedRead::new(reader, MessageCodec::new());
            let mut framed_write = FramedWrite::new(writer, MessageCodec::new());

            let _msg = framed_read.next().await; // ext handshake
            let ext_hs = ExtHandshake::new();
            let payload = ext_hs.to_bytes().unwrap();
            framed_write
                .send(Message::Extended { ext_id: 0, payload })
                .await
                .unwrap();

            // Send bitfield + unchoke
            let mut bf = Bitfield::new(1);
            bf.set(0);
            framed_write
                .send(Message::Bitfield(Bytes::copy_from_slice(bf.as_bytes())))
                .await
                .unwrap();
            framed_write.send(Message::Unchoke).await.unwrap();

            // Respond to requests
            while let Some(Ok(msg)) = framed_read.next().await {
                if let Message::Request {
                    index,
                    begin,
                    length,
                } = msg
                {
                    let start = begin as usize;
                    let end = start + length as usize;
                    framed_write
                        .send(Message::Piece {
                            index,
                            begin,
                            data_0: Bytes::copy_from_slice(&seed_data[start..end]),
                            data_1: Bytes::new(),
                        })
                        .await
                        .unwrap();
                }
            }
        });

        // Wait for download to complete
        let deadline = tokio::time::Instant::now() + Duration::from_secs(5);
        loop {
            tokio::time::sleep(Duration::from_millis(100)).await;
            let stats = handle.stats().await.unwrap();
            if stats.pieces_have == 1 {
                break;
            }
            assert!(
                tokio::time::Instant::now() <= deadline,
                "piece download did not complete within 5s"
            );
        }

        // Phase 2: Connect a mock leecher to request piece 0 back
        let leech_stream = tokio::net::TcpStream::connect(listen_addr).await.unwrap();
        let expected_data = data.clone();
        let leecher_task = tokio::spawn(async move {
            let (reader, writer) = tokio::io::split(leech_stream);
            let mut writer = writer;
            let mut reader = reader;

            let hs = Handshake::new(
                info_hash,
                Id20::from_hex("7777777777777777777777777777777777777777").unwrap(),
            );
            writer.write_all(&hs.to_bytes()).await.unwrap();
            writer.flush().await.unwrap();
            let mut hs_buf = [0u8; HANDSHAKE_SIZE];
            reader.read_exact(&mut hs_buf).await.unwrap();

            let mut framed_read = FramedRead::new(reader, MessageCodec::new());
            let mut framed_write = FramedWrite::new(writer, MessageCodec::new());

            let _msg = framed_read.next().await; // ext handshake
            let ext_hs = ExtHandshake::new();
            let payload = ext_hs.to_bytes().unwrap();
            framed_write
                .send(Message::Extended { ext_id: 0, payload })
                .await
                .unwrap();

            // Send Interested and wait for Unchoke
            framed_write.send(Message::Interested).await.unwrap();

            let deadline = tokio::time::Instant::now() + Duration::from_secs(15);
            loop {
                tokio::select! {
                    msg = framed_read.next() => {
                        match msg {
                            Some(Ok(Message::Unchoke)) => { break; }
                            Some(Ok(_)) => {}
                            _ => panic!("connection closed before unchoke"),
                        }
                    }
                    () = tokio::time::sleep_until(deadline) => {
                        panic!("timed out waiting for unchoke");
                    }
                }
            }

            // Request piece 0
            framed_write
                .send(Message::Request {
                    index: 0,
                    begin: 0,
                    length: 16384,
                })
                .await
                .unwrap();

            // Read Piece response
            let deadline = tokio::time::Instant::now() + Duration::from_secs(5);
            loop {
                tokio::select! {
                    msg = framed_read.next() => {
                        match msg {
                            Some(Ok(Message::Piece { index, begin, data_0, data_1 })) => {
                                assert_eq!(index, 0);
                                assert_eq!(begin, 0);
                                let _ = &data_1; // empty after wire round-trip
                                assert_eq!(data_0.as_ref(), expected_data.as_slice());
                                return; // success
                            }
                            Some(Ok(_)) => {}
                            Some(Err(e)) => panic!("error reading: {e}"),
                            None => panic!("connection closed before piece"),
                        }
                    }
                    () = tokio::time::sleep_until(deadline) => {
                        panic!("timed out waiting for piece data");
                    }
                }
            }
        });

        // Wait for leecher to complete
        let result = tokio::time::timeout(Duration::from_secs(20), leecher_task).await;
        match result {
            Ok(Ok(())) => {}
            Ok(Err(e)) => panic!("leecher task panicked: {e}"),
            Err(elapsed) => panic!("test timed out after {elapsed}"),
        }

        // Verify uploaded bytes
        let stats = handle.stats().await.unwrap();
        assert!(
            stats.uploaded > 0,
            "expected uploaded > 0, got {}",
            stats.uploaded
        );

        handle.shutdown().await.unwrap();
        seeder_task.abort();
    }

    // ---- Test 22: Seed ratio limit stops torrent ----

    #[tokio::test]
    async fn seed_ratio_limit_stops_torrent() {
        // 1-piece torrent, ratio limit = 1.0
        // After downloading 16384 bytes and uploading 16384 bytes, ratio = 1.0 → stop
        let data = vec![0xCCu8; 16384];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;
        let storage = make_storage(&data, 16384);

        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let listen_addr = listener.local_addr().unwrap();
        drop(listener);

        let config = TorrentConfig {
            listen_port: listen_addr.port(),
            seed_ratio_limit: Some(1.0),
            ..test_config()
        };

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        tokio::time::sleep(Duration::from_millis(50)).await;

        // Phase 1: Seed the torrent with piece 0
        let seed_data = data.clone();
        let seed_stream = tokio::net::TcpStream::connect(listen_addr).await.unwrap();
        let seeder_task = tokio::spawn(async move {
            let (reader, writer) = tokio::io::split(seed_stream);
            let mut writer = writer;
            let mut reader = reader;

            let hs = Handshake::new(
                info_hash,
                Id20::from_hex("8888888888888888888888888888888888888888").unwrap(),
            );
            writer.write_all(&hs.to_bytes()).await.unwrap();
            writer.flush().await.unwrap();
            let mut hs_buf = [0u8; HANDSHAKE_SIZE];
            reader.read_exact(&mut hs_buf).await.unwrap();

            let mut framed_read = FramedRead::new(reader, MessageCodec::new());
            let mut framed_write = FramedWrite::new(writer, MessageCodec::new());

            let _msg = framed_read.next().await;
            let ext_hs = ExtHandshake::new();
            let payload = ext_hs.to_bytes().unwrap();
            framed_write
                .send(Message::Extended { ext_id: 0, payload })
                .await
                .unwrap();

            let mut bf = Bitfield::new(1);
            bf.set(0);
            framed_write
                .send(Message::Bitfield(Bytes::copy_from_slice(bf.as_bytes())))
                .await
                .unwrap();
            framed_write.send(Message::Unchoke).await.unwrap();

            while let Some(Ok(msg)) = framed_read.next().await {
                if let Message::Request {
                    index,
                    begin,
                    length,
                } = msg
                {
                    let start = begin as usize;
                    let end = start + length as usize;
                    framed_write
                        .send(Message::Piece {
                            index,
                            begin,
                            data_0: Bytes::copy_from_slice(&seed_data[start..end]),
                            data_1: Bytes::new(),
                        })
                        .await
                        .unwrap();
                }
            }
        });

        // Wait for download to complete (transitions to Seeding)
        let deadline = tokio::time::Instant::now() + Duration::from_secs(5);
        loop {
            tokio::time::sleep(Duration::from_millis(100)).await;
            let stats = handle.stats().await.unwrap();
            if stats.state == TorrentState::Seeding {
                break;
            }
            assert!(
                tokio::time::Instant::now() <= deadline,
                "download did not complete within 5s"
            );
        }

        // Phase 2: Connect leecher to request piece 0 — this should trigger ratio limit
        let leech_stream = tokio::net::TcpStream::connect(listen_addr).await.unwrap();
        let leecher_task = tokio::spawn(async move {
            let (reader, writer) = tokio::io::split(leech_stream);
            let mut writer = writer;
            let mut reader = reader;

            let hs = Handshake::new(
                info_hash,
                Id20::from_hex("9999999999999999999999999999999999999999").unwrap(),
            );
            writer.write_all(&hs.to_bytes()).await.unwrap();
            writer.flush().await.unwrap();
            let mut hs_buf = [0u8; HANDSHAKE_SIZE];
            reader.read_exact(&mut hs_buf).await.unwrap();

            let mut framed_read = FramedRead::new(reader, MessageCodec::new());
            let mut framed_write = FramedWrite::new(writer, MessageCodec::new());

            let _msg = framed_read.next().await;
            let ext_hs = ExtHandshake::new();
            let payload = ext_hs.to_bytes().unwrap();
            framed_write
                .send(Message::Extended { ext_id: 0, payload })
                .await
                .unwrap();

            framed_write.send(Message::Interested).await.unwrap();

            // Wait for unchoke
            let deadline = tokio::time::Instant::now() + Duration::from_secs(15);
            loop {
                tokio::select! {
                    msg = framed_read.next() => {
                        match msg {
                            Some(Ok(Message::Unchoke)) => break,
                            Some(Ok(_)) => {}
                            _ => return, // connection may close due to ratio shutdown
                        }
                    }
                    () = tokio::time::sleep_until(deadline) => return,
                }
            }

            // Request piece 0
            framed_write
                .send(Message::Request {
                    index: 0,
                    begin: 0,
                    length: 16384,
                })
                .await
                .unwrap();

            // Read until connection closes (the torrent may stop and disconnect us)
            while let Some(Ok(_msg)) = framed_read.next().await {}
        });

        // Wait for state to become Stopped
        let deadline = tokio::time::Instant::now() + Duration::from_secs(20);
        loop {
            tokio::time::sleep(Duration::from_millis(100)).await;
            let stats = handle.stats().await.unwrap();
            if stats.state == TorrentState::Stopped {
                assert!(
                    stats.uploaded >= 16384,
                    "expected uploaded >= 16384, got {}",
                    stats.uploaded
                );
                break;
            }
            if tokio::time::Instant::now() > deadline {
                let stats = handle.stats().await.unwrap();
                panic!(
                    "expected Stopped, got {:?}, uploaded={}, downloaded={}",
                    stats.state, stats.uploaded, stats.downloaded
                );
            }
        }

        handle.shutdown().await.unwrap();
        seeder_task.abort();
        leecher_task.abort();
    }

    // ---- Test 23: Resume with seeded storage starts as seeder ----

    #[tokio::test]
    async fn resume_with_seeded_storage() {
        let data = vec![0xDDu8; 32768]; // 2 pieces
        let meta = make_test_torrent(&data, 16384);
        let storage = make_seeded_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Give the actor time to verify existing pieces
        tokio::time::sleep(Duration::from_millis(100)).await;

        let stats = handle.stats().await.unwrap();
        assert_eq!(
            stats.state,
            TorrentState::Seeding,
            "should start as seeder with all pieces verified"
        );
        assert_eq!(stats.pieces_have, 2);
        assert_eq!(stats.pieces_total, 2);

        handle.shutdown().await.unwrap();
    }

    // ---- Test: save_resume_data captures state ----

    #[tokio::test]
    async fn save_resume_data_captures_state() {
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Give actor time to start
        tokio::time::sleep(Duration::from_millis(50)).await;

        let rd = handle.save_resume_data().await.unwrap();

        assert_eq!(rd.file_format, "libtorrent resume file");
        assert_eq!(rd.file_version, 1);
        assert_eq!(rd.info_hash, info_hash.as_bytes().to_vec());
        assert_eq!(rd.name, "test");
        assert_eq!(rd.save_path, "/tmp");
        assert_eq!(rd.paused, 0);
        // No pieces downloaded yet — bitfield should be all zeros
        assert!(!rd.pieces.is_empty());
        // Stats should be zero for a freshly started torrent with no peers
        assert_eq!(rd.total_uploaded, 0);
        assert_eq!(rd.total_downloaded, 0);

        handle.shutdown().await.unwrap();
    }

    // ---- Test: save_resume_data for seeder ----

    #[tokio::test]
    async fn save_resume_data_seeder() {
        let data = vec![0xCD; 32768];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;
        let storage = make_seeded_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Give actor time to verify pieces and switch to seeding
        tokio::time::sleep(Duration::from_millis(100)).await;

        let rd = handle.save_resume_data().await.unwrap();

        assert_eq!(rd.info_hash, info_hash.as_bytes().to_vec());
        assert_eq!(rd.name, "test");
        assert_eq!(rd.seed_mode, 1, "seeder should have seed_mode=1");
        assert_eq!(rd.paused, 0);
        // All pieces should be marked in the bitfield
        // 2 pieces -> 1 byte, top 2 bits set = 0b1100_0000 = 0xC0
        assert_eq!(rd.pieces.len(), 1);
        assert_eq!(
            rd.pieces[0] & 0xC0,
            0xC0,
            "both pieces should be marked complete"
        );

        handle.shutdown().await.unwrap();
    }

    // ---- Test: save_resume_data for paused torrent ----

    #[tokio::test]
    async fn save_resume_data_paused() {
        let data = vec![0xEF; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        tokio::time::sleep(Duration::from_millis(50)).await;
        handle.pause().await.unwrap();
        tokio::time::sleep(Duration::from_millis(50)).await;

        let rd = handle.save_resume_data().await.unwrap();
        assert_eq!(rd.paused, 1, "paused torrent should have paused=1");
        assert_eq!(rd.seed_mode, 0);

        handle.shutdown().await.unwrap();
    }

    // ---- Test: set_file_priority and read back ----

    #[tokio::test]
    async fn set_file_priority_and_read_back() {
        let info_bytes = b"d5:filesld6:lengthi100e4:pathl5:a.bineed6:lengthi100e4:pathl5:b.bineee4:name4:test12:piece lengthi100e6:pieces40:AAAAAAAAAAAAAAAAAAAABBBBBBBBBBBBBBBBBBBBe";
        let mut torrent_bytes = b"d4:info".to_vec();
        torrent_bytes.extend_from_slice(info_bytes);
        torrent_bytes.push(b'e');

        let meta = irontide_core::torrent_from_bytes(&torrent_bytes).unwrap();
        let lengths = Lengths::new(200, 100, DEFAULT_CHUNK_SIZE);
        let storage: Arc<dyn TorrentStorage> = Arc::new(MemoryStorage::new(lengths));
        let config = TorrentConfig {
            listen_port: 0,
            ..Default::default()
        };

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Default priorities should all be Normal
        let prios = handle.file_priorities().await.unwrap();
        assert_eq!(prios.len(), 2);
        assert!(prios.iter().all(|p| *p == FilePriority::Normal));

        // Set file 0 to Skip
        handle
            .set_file_priority(0, FilePriority::Skip)
            .await
            .unwrap();

        let prios = handle.file_priorities().await.unwrap();
        assert_eq!(prios[0], FilePriority::Skip);
        assert_eq!(prios[1], FilePriority::Normal);

        // Invalid index should error
        let result = handle.set_file_priority(99, FilePriority::High).await;
        assert!(result.is_err());

        handle.shutdown().await.unwrap();
        tokio::time::sleep(Duration::from_millis(50)).await;
    }

    /// Spawn a running multi-file torrent (3 files, 4 pieces, one shared
    /// boundary piece: file b at 150 B spans pieces 1-2, file c spans 2-3) for
    /// end-to-end `SetFilePriority` arm coverage.
    async fn spawn_test_torrent_multifile() -> TorrentHandle {
        let meta = make_multi_file_meta(&[(100, "a.bin"), (150, "b.bin"), (100, "c.bin")], 100);
        let lengths = Lengths::new(350, 100, DEFAULT_CHUNK_SIZE);
        let storage: Arc<dyn TorrentStorage> = Arc::new(MemoryStorage::new(lengths));
        let config = TorrentConfig {
            listen_port: 0,
            ..Default::default()
        };
        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None,
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap()
    }

    /// M246 characterization: the observable post-conditions of a file-priority
    /// change — `file_priorities()` round-trip and the invalid-index error — are
    /// synchronous and MUST survive the recv-loop hardening. Only the order-map
    /// *build* moves to the 1 s tick; the priority/wanted/atomic state that gates
    /// dispatch stays synchronous, so this surface is unchanged before and after.
    #[tokio::test]
    async fn set_file_priority_updates_wanted_and_priorities() {
        let handle = spawn_test_torrent_multifile().await;

        let prios = handle.file_priorities().await.unwrap();
        assert_eq!(prios.len(), 3);
        assert!(prios.iter().all(|p| *p == FilePriority::Normal));

        handle
            .set_file_priority(1, FilePriority::Skip)
            .await
            .unwrap();
        assert_eq!(
            handle.file_priorities().await.unwrap()[1],
            FilePriority::Skip
        );

        handle
            .set_file_priority(1, FilePriority::Normal)
            .await
            .unwrap();
        assert_eq!(
            handle.file_priorities().await.unwrap()[1],
            FilePriority::Normal
        );

        // Invalid index still errors synchronously.
        assert!(
            handle
                .set_file_priority(99, FilePriority::High)
                .await
                .is_err()
        );

        handle.shutdown().await.unwrap();
        tokio::time::sleep(Duration::from_millis(50)).await;
    }

    /// Build a synchronous (non-spawned) multi-file `TorrentActor` for direct
    /// method-level testing of the M246 range-scoped helpers. Populates
    /// `meta`, `lengths`, `cached_files`, `file_priorities` (all `Normal`),
    /// `atomic_states`, and `piece_tracker` sized to the layout, on top of
    /// `for_throttle_test`'s channel scaffolding. Must run inside a tokio runtime.
    fn priority_test_actor(files: &[(u64, &str)], piece_length: u64) -> TorrentActor {
        use irontide_storage::Bitfield;
        let meta = make_multi_file_meta(files, piece_length);
        let total: u64 = files.iter().map(|(l, _)| *l).sum();
        let lengths = Lengths::new(total, piece_length, DEFAULT_CHUNK_SIZE);
        let num_pieces = lengths.num_pieces();
        let file_lengths: Vec<u64> = files.iter().map(|(l, _)| *l).collect();

        let mut actor = TorrentActor::for_throttle_test(num_pieces, 0);
        actor.file_priorities = vec![FilePriority::Normal; files.len()];
        actor.wanted_pieces = crate::piece_selector::build_wanted_pieces(
            &actor.file_priorities,
            &file_lengths,
            &lengths,
        );
        actor.cached_files = Some(build_cached_file_info(&meta, &lengths));

        let we_have = Bitfield::new(num_pieces);
        actor.atomic_states = Some(Arc::new(crate::piece_reservation::AtomicPieceStates::new(
            num_pieces,
            &we_have,
            &actor.wanted_pieces,
        )));
        actor.piece_tracker = Some(crate::piece_reservation::PieceTracker::new(
            num_pieces,
            &we_have,
            &actor.wanted_pieces,
        ));
        actor.meta = Some(meta);
        actor.lengths = Some(lengths);
        actor
    }

    /// M246 D4: the scoped recompute must leave `wanted_pieces` byte-identical
    /// to a full `build_wanted_pieces` for every file, across a misaligned
    /// layout with multiple shared boundary pieces (b/c share piece 2; c/d
    /// share piece 3).
    #[tokio::test]
    async fn apply_file_priority_scoped_matches_full_rebuild() {
        let files: &[(u64, &str)] = &[(100, "a"), (150, "b"), (100, "c"), (250, "d")];
        let piece_length = 100;
        let file_lengths: Vec<u64> = files.iter().map(|(l, _)| *l).collect();
        for skip_idx in 0..files.len() {
            let mut actor = priority_test_actor(files, piece_length);
            actor
                .apply_file_priority_scoped(skip_idx, FilePriority::Skip)
                .unwrap();

            let mut ref_prios = vec![FilePriority::Normal; files.len()];
            ref_prios[skip_idx] = FilePriority::Skip;
            let reference = crate::piece_selector::build_wanted_pieces(
                &ref_prios,
                &file_lengths,
                actor.lengths.as_ref().unwrap(),
            );
            for p in 0..actor.num_pieces {
                assert_eq!(
                    actor.wanted_pieces.get(p),
                    reference.get(p),
                    "piece {p} mismatch after scoped skip of file {skip_idx}"
                );
            }
        }
    }

    /// M246 D4: sub-piece-sized files (a,b,c all inside piece 0). The shared
    /// piece stays wanted while ANY overlapping file is non-skip, and unwants
    /// only when all overlapping files are skipped.
    #[tokio::test]
    async fn apply_file_priority_scoped_handles_sub_piece_files() {
        let files: &[(u64, &str)] = &[(30, "a"), (30, "b"), (40, "c"), (100, "d")];
        let mut actor = priority_test_actor(files, 100);

        actor
            .apply_file_priority_scoped(0, FilePriority::Skip)
            .unwrap();
        assert!(
            actor.wanted_pieces.get(0),
            "piece 0 wanted: b,c still want it"
        );
        actor
            .apply_file_priority_scoped(1, FilePriority::Skip)
            .unwrap();
        actor
            .apply_file_priority_scoped(2, FilePriority::Skip)
            .unwrap();
        assert!(
            !actor.wanted_pieces.get(0),
            "piece 0 unwanted: a,b,c all skip"
        );
        assert!(
            actor.wanted_pieces.get(1),
            "piece 1 still wanted (d Normal)"
        );

        let file_lengths: Vec<u64> = files.iter().map(|(l, _)| *l).collect();
        let prios = vec![
            FilePriority::Skip,
            FilePriority::Skip,
            FilePriority::Skip,
            FilePriority::Normal,
        ];
        let reference = crate::piece_selector::build_wanted_pieces(
            &prios,
            &file_lengths,
            actor.lengths.as_ref().unwrap(),
        );
        for p in 0..actor.num_pieces {
            assert_eq!(
                actor.wanted_pieces.get(p),
                reference.get(p),
                "piece {p} mismatch"
            );
        }
    }

    /// M246 D4: a zero-length file (middle of the layout) yields an empty range
    /// and must not panic; the result still matches a full rebuild.
    #[tokio::test]
    async fn apply_file_priority_scoped_zero_length_file_no_panic() {
        let files: &[(u64, &str)] = &[(100, "a"), (0, "empty"), (100, "c")];
        let mut actor = priority_test_actor(files, 100);

        let r = actor
            .apply_file_priority_scoped(1, FilePriority::Skip)
            .unwrap();
        assert!(
            r.0 > r.1,
            "zero-length file yields an empty range, got {r:?}"
        );

        actor
            .apply_file_priority_scoped(0, FilePriority::Skip)
            .unwrap();

        let file_lengths: Vec<u64> = files.iter().map(|(l, _)| *l).collect();
        let prios = vec![FilePriority::Skip, FilePriority::Skip, FilePriority::Normal];
        let reference = crate::piece_selector::build_wanted_pieces(
            &prios,
            &file_lengths,
            actor.lengths.as_ref().unwrap(),
        );
        for p in 0..actor.num_pieces {
            assert_eq!(
                actor.wanted_pieces.get(p),
                reference.get(p),
                "piece {p} mismatch"
            );
        }
    }

    /// M246: `sync_piece_states_for_range` touches ONLY pieces inside the range;
    /// pieces outside stay at their prior atomic state.
    #[tokio::test]
    async fn sync_piece_states_for_range_only_touches_range() {
        let files: &[(u64, &str)] = &[(200, "a"), (200, "b"), (200, "c")];
        let mut actor = priority_test_actor(files, 100); // 6 pieces; file 1 = pieces 2,3
        let (first, last) = actor
            .apply_file_priority_scoped(1, FilePriority::Skip)
            .unwrap();
        assert_eq!((first, last), (2, 3));
        actor.sync_piece_states_for_range(first, last);

        let atomic = actor.atomic_states.as_ref().unwrap();
        assert_eq!(
            atomic.get(2),
            crate::piece_reservation::PieceState::Unwanted
        );
        assert_eq!(
            atomic.get(3),
            crate::piece_reservation::PieceState::Unwanted
        );
        for p in [0u32, 1, 4, 5] {
            assert_eq!(
                atomic.get(p),
                crate::piece_reservation::PieceState::Available,
                "piece {p} outside the range must be untouched"
            );
        }
    }

    /// M246 FINDING-1 regression: the order-map rebuild is DEFERRED (no rebuild
    /// before the tick), a batch coalesces to ONE rebuild, the generation comes
    /// from the actor-owned monotone counter (advances by exactly 1), and the
    /// SECOND of two back-to-back batch changes is NOT lost — the failure mode
    /// of the rejected Candidate H (read published gen, async publish → drop).
    #[tokio::test]
    async fn order_map_coalesces_and_gen_is_monotone() {
        // 3 files × 200 B, piece_length 100 → f0=[0,1], f1=[2,3], f2=[4,5].
        let mut actor = priority_test_actor(&[(200, "a"), (200, "b"), (200, "c")], 100);
        let gen0 = actor.order_map_tx.borrow().generation;

        // Two back-to-back scoped priority changes (the batch case). The arm sets
        // the dirty flag; we drive the helper + flag directly here.
        actor
            .apply_file_priority_scoped(0, FilePriority::Skip)
            .unwrap();
        actor.order_map_dirty = true;
        actor
            .apply_file_priority_scoped(2, FilePriority::Skip)
            .unwrap();
        actor.order_map_dirty = true;
        assert_eq!(
            actor.order_map_tx.borrow().generation,
            gen0,
            "no order-map rebuild before the tick"
        );

        // The tick rebuilds ONCE, capturing BOTH changes; gen advances by 1.
        actor.rebuild_order_map_now();
        assert_eq!(
            actor.order_map_tx.borrow().generation,
            gen0 + 1,
            "exactly one coalesced rebuild"
        );
        assert!(!actor.order_map_dirty, "dirty flag cleared after rebuild");

        // Both skipped files' pieces are absent; file 1's remain present — proof
        // the second change was not dropped.
        let map = actor.order_map_tx.borrow();
        for p in [0u32, 1, 4, 5] {
            assert!(
                !map.order.contains(&p),
                "skipped piece {p} must be absent from the order"
            );
        }
        for p in [2u32, 3] {
            assert!(
                map.order.contains(&p),
                "wanted piece {p} must be present in the order"
            );
        }
    }

    /// M246 Q6: the post-recheck reconfigure path delegates to
    /// `rebuild_order_map_now`, which clears a pending dirty flag so the next
    /// tick does not redundantly rebuild.
    #[tokio::test]
    async fn rebuild_order_map_now_clears_dirty_flag() {
        let mut actor = priority_test_actor(&[(200, "a"), (200, "b")], 100);
        actor.order_map_dirty = true;
        actor.rebuild_order_map_now();
        assert!(!actor.order_map_dirty);
    }

    #[tokio::test]
    async fn resume_data_preserves_file_priorities() {
        let info_bytes = b"d5:filesld6:lengthi100e4:pathl5:a.bineed6:lengthi100e4:pathl5:b.bineee4:name4:test12:piece lengthi100e6:pieces40:AAAAAAAAAAAAAAAAAAAABBBBBBBBBBBBBBBBBBBBe";
        let mut torrent_bytes = b"d4:info".to_vec();
        torrent_bytes.extend_from_slice(info_bytes);
        torrent_bytes.push(b'e');

        let meta = irontide_core::torrent_from_bytes(&torrent_bytes).unwrap();
        let lengths = Lengths::new(200, 100, DEFAULT_CHUNK_SIZE);
        let storage: Arc<dyn TorrentStorage> = Arc::new(MemoryStorage::new(lengths));
        let config = TorrentConfig {
            listen_port: 0,
            ..Default::default()
        };

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Set file priorities
        handle
            .set_file_priority(0, FilePriority::High)
            .await
            .unwrap();
        handle
            .set_file_priority(1, FilePriority::Skip)
            .await
            .unwrap();

        // Save resume data
        let rd = handle.save_resume_data().await.unwrap();
        assert_eq!(rd.file_priority, vec![7, 0]); // High=7, Skip=0

        // Verify bencode round-trip
        let encoded = irontide_bencode::to_bytes(&rd).unwrap();
        let decoded: irontide_core::FastResumeData =
            irontide_bencode::from_bytes(&encoded).unwrap();
        assert_eq!(decoded.file_priority, vec![7, 0]);

        handle.shutdown().await.unwrap();
        tokio::time::sleep(Duration::from_millis(50)).await;
    }

    // ---- Rate limiting integration tests (M14) ----

    #[tokio::test]
    async fn upload_rate_limiting_caps_throughput() {
        // Test that per-torrent upload rate limiting gates serve_incoming_requests.
        // We use a very low rate (1 KB/s) so the 16 KB piece requires ~16 seconds.
        // We verify: 1) piece does NOT arrive within 200ms (bucket too small),
        //            2) the torrent actor is alive and functional.
        let data = vec![0xAB; 16384]; // 1 piece
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;
        let storage = make_seeded_storage(&data, 16384);

        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let listen_addr = listener.local_addr().unwrap();

        let config = TorrentConfig {
            listen_port: listen_addr.port(),
            upload_rate_limit: 1024, // 1 KB/s — way too slow for 16 KB chunk
            ..test_config()
        };

        drop(listener);
        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        tokio::time::sleep(Duration::from_millis(50)).await;

        // Connect mock leecher (raw handshake + framed messages)
        let stream = tokio::net::TcpStream::connect(listen_addr).await.unwrap();
        let (reader, writer) = tokio::io::split(stream);
        let mut writer = writer;
        let mut reader = reader;

        let hs = Handshake::new(
            info_hash,
            Id20::from_hex("bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb").unwrap(),
        );
        writer.write_all(&hs.to_bytes()).await.unwrap();
        writer.flush().await.unwrap();
        let mut hs_buf = [0u8; HANDSHAKE_SIZE];
        reader.read_exact(&mut hs_buf).await.unwrap();

        let mut framed_read = FramedRead::new(reader, MessageCodec::new());
        let mut framed_write = FramedWrite::new(writer, MessageCodec::new());

        // Read ext handshake + bitfield
        let _msg = framed_read.next().await;
        let ext_hs = ExtHandshake::new();
        let payload = ext_hs.to_bytes().unwrap();
        framed_write
            .send(Message::Extended { ext_id: 0, payload })
            .await
            .unwrap();

        // Read the bitfield
        let _bf_msg = framed_read.next().await;

        // Express interest
        framed_write.send(Message::Interested).await.unwrap();

        // Wait for unchoke
        let deadline = tokio::time::Instant::now() + Duration::from_secs(15);
        loop {
            tokio::select! {
                msg = framed_read.next() => {
                    match msg {
                        Some(Ok(Message::Unchoke)) => break,
                        Some(Ok(_)) => {}
                        _ => panic!("connection closed before unchoke"),
                    }
                }
                () = tokio::time::sleep_until(deadline) => {
                    panic!("timed out waiting for unchoke");
                }
            }
        }

        // Request piece 0
        framed_write
            .send(Message::Request {
                index: 0,
                begin: 0,
                length: 16384,
            })
            .await
            .unwrap();

        // At 1 KB/s, the bucket accumulates ~100 bytes per 100ms tick (max burst = 1024).
        // A 16 KB chunk needs 16384 tokens, so it should NOT be served quickly.
        // We wait 2 seconds — at 1 KB/s we'd have at most 2 KB, still < 16 KB.
        let mut got_piece = false;
        if let Ok(true) = tokio::time::timeout(Duration::from_secs(2), async {
            loop {
                match framed_read.next().await {
                    Some(Ok(Message::Piece { .. })) => return true,
                    Some(Ok(_)) => {}
                    _ => return false,
                }
            }
        })
        .await
        {
            got_piece = true;
        }

        // Piece should NOT have arrived in 2 seconds (would need 16s at 1 KB/s)
        assert!(
            !got_piece,
            "piece should be delayed by rate limiter (1 KB/s for 16 KB chunk)"
        );

        // Verify actor is still alive
        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.uploaded, 0); // nothing served yet

        handle.shutdown().await.unwrap();
    }

    #[tokio::test]
    async fn unlimited_rate_has_no_effect() {
        // Default config (rate = 0) should behave identically to pre-M14
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        // Rate limits are 0 (unlimited) by default
        assert_eq!(config.upload_rate_limit, 0);
        assert_eq!(config.download_rate_limit, 0);

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::Downloading);
        assert_eq!(stats.pieces_total, 2);

        handle.shutdown().await.unwrap();
    }

    #[tokio::test]
    async fn download_rate_limiting_throttles_requests() {
        // Test that download_rate_limit prevents sending requests when budget exhausted.
        // With 1 KB/s limit and 16 KB chunks, budget is exhausted almost immediately.
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;
        let storage = make_storage(&data, 16384);

        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let listen_addr = listener.local_addr().unwrap();

        let config = TorrentConfig {
            listen_port: listen_addr.port(),
            download_rate_limit: 1024, // Very low: 1 KB/s
            ..test_config()
        };

        drop(listener);
        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        tokio::time::sleep(Duration::from_millis(50)).await;

        // Connect mock seeder
        let stream = tokio::net::TcpStream::connect(listen_addr).await.unwrap();
        let (reader, writer) = tokio::io::split(stream);
        let mut writer = writer;
        let mut reader = reader;

        let hs = Handshake::new(
            info_hash,
            Id20::from_hex("cccccccccccccccccccccccccccccccccccccccc").unwrap(),
        );
        writer.write_all(&hs.to_bytes()).await.unwrap();
        writer.flush().await.unwrap();
        let mut hs_buf = [0u8; HANDSHAKE_SIZE];
        reader.read_exact(&mut hs_buf).await.unwrap();

        let mut framed_read = FramedRead::new(reader, MessageCodec::new());
        let mut framed_write = FramedWrite::new(writer, MessageCodec::new());

        // Read ext handshake
        let _msg = framed_read.next().await;
        let ext_hs = ExtHandshake::new();
        let payload = ext_hs.to_bytes().unwrap();
        framed_write
            .send(Message::Extended { ext_id: 0, payload })
            .await
            .unwrap();

        // Send bitfield saying we have all pieces (act as seeder)
        let mut bf = Bitfield::new(2);
        bf.set(0);
        bf.set(1);
        framed_write
            .send(Message::Bitfield(Bytes::copy_from_slice(bf.as_bytes())))
            .await
            .unwrap();

        // Unchoke the torrent
        framed_write.send(Message::Unchoke).await.unwrap();

        // Count Request messages received within 500ms.
        // With 1 KB/s download limit, the bucket only accumulates ~50 bytes
        // per 100ms tick, far less than 16 KB needed for a full chunk request.
        let mut requests_received = 0u32;
        let deadline = tokio::time::Instant::now() + Duration::from_millis(500);
        loop {
            match tokio::time::timeout(
                deadline.saturating_duration_since(tokio::time::Instant::now()),
                framed_read.next(),
            )
            .await
            {
                Ok(Some(Ok(Message::Request { .. }))) => {
                    requests_received += 1;
                }
                Ok(Some(Ok(_))) => {}
                _ => break,
            }
        }

        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::Downloading);

        // With 1 KB/s download limit and 16 KB chunks, we should see very few
        // or no requests within 500ms (budget insufficient for even one chunk)
        assert!(
            requests_received <= 2,
            "with 1 KB/s limit, should get very few requests, got {requests_received}"
        );

        handle.shutdown().await.unwrap();
    }

    // ── Smart banning tests (M25) ────────────────────────────────────

    #[test]
    fn piece_contributor_tracking() {
        use std::net::IpAddr;
        let mut contributors: HashMap<u32, HashSet<IpAddr>> = HashMap::new();
        let ip1: IpAddr = "10.0.0.1".parse().unwrap();
        let ip2: IpAddr = "10.0.0.2".parse().unwrap();

        contributors.entry(0).or_default().insert(ip1);
        contributors.entry(0).or_default().insert(ip2);
        assert_eq!(contributors[&0].len(), 2);
        assert!(contributors[&0].contains(&ip1));
        assert!(contributors[&0].contains(&ip2));

        // Clear on verify
        contributors.remove(&0);
        assert!(!contributors.contains_key(&0));
    }

    #[test]
    fn parole_enter_on_hash_failure() {
        use crate::ban::ParoleState;
        use std::net::IpAddr;

        let ip1: IpAddr = "10.0.0.1".parse().unwrap();
        let ip2: IpAddr = "10.0.0.2".parse().unwrap();
        let contributors = vec![ip1, ip2];

        // Simulate entering parole
        let parole = ParoleState {
            original_contributors: contributors.into_iter().collect(),
            parole_peer: None,
        };

        assert_eq!(parole.original_contributors.len(), 2);
        assert!(parole.original_contributors.contains(&ip1));
        assert!(parole.original_contributors.contains(&ip2));
        assert!(parole.parole_peer.is_none());
    }

    #[test]
    fn parole_success_strikes_originals() {
        use crate::ban::{BanConfig, BanManager, ParoleState};
        use std::net::IpAddr;

        let ip1: IpAddr = "10.0.0.1".parse().unwrap();
        let ip2: IpAddr = "10.0.0.2".parse().unwrap();
        let parole_ip: IpAddr = "10.0.0.3".parse().unwrap();

        let mut mgr = BanManager::new(BanConfig {
            max_failures: 2,
            use_parole: true,
        });

        let parole = ParoleState {
            original_contributors: [ip1, ip2].into_iter().collect(),
            parole_peer: Some(parole_ip),
        };

        // Simulate parole success: strike all originals
        for ip in &parole.original_contributors {
            mgr.record_strike(*ip);
        }

        assert_eq!(*mgr.strikes_map().get(&ip1).unwrap(), 1);
        assert_eq!(*mgr.strikes_map().get(&ip2).unwrap(), 1);
        // Parole peer should not be struck
        assert!(!mgr.strikes_map().contains_key(&parole_ip));

        // Second strike bans them
        for ip in &parole.original_contributors {
            mgr.record_strike(*ip);
        }
        assert!(mgr.is_banned(&ip1));
        assert!(mgr.is_banned(&ip2));
    }

    #[test]
    fn parole_failure_strikes_parole_peer() {
        use crate::ban::{BanConfig, BanManager, ParoleState};
        use std::net::IpAddr;

        let ip1: IpAddr = "10.0.0.1".parse().unwrap();
        let parole_ip: IpAddr = "10.0.0.3".parse().unwrap();

        let mut mgr = BanManager::new(BanConfig {
            max_failures: 2,
            use_parole: true,
        });

        let parole = ParoleState {
            original_contributors: [ip1].into_iter().collect(),
            parole_peer: Some(parole_ip),
        };

        // Parole failure: strike the parole peer, not originals
        if let Some(pp) = parole.parole_peer {
            mgr.record_strike(pp);
        }

        assert_eq!(*mgr.strikes_map().get(&parole_ip).unwrap(), 1);
        assert!(!mgr.strikes_map().contains_key(&ip1));
    }

    #[tokio::test]
    async fn banned_peer_rejected_on_connect() {
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();
        let ban_mgr = test_ban_manager();

        // Pre-ban an IP
        let banned_ip: std::net::IpAddr = "192.168.1.100".parse().unwrap();
        ban_mgr.write().ban(banned_ip);

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            Arc::clone(&ban_mgr),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Add the banned peer — it should be filtered out
        handle
            .add_peers(
                vec![
                    SocketAddr::new(banned_ip, 6881),
                    "10.0.0.1:6881".parse().unwrap(),
                ],
                PeerSource::Tracker,
            )
            .await
            .unwrap();

        tokio::time::sleep(std::time::Duration::from_millis(100)).await;
        let stats = handle.stats().await.unwrap();
        // Only the non-banned peer should be in available pool (and may have connected)
        // The banned one should never appear
        assert!(
            stats.peers_available + stats.peers_connected <= 1,
            "banned peer should not be added: available={}, connected={}",
            stats.peers_available,
            stats.peers_connected
        );

        handle.shutdown().await.unwrap();
    }

    #[test]
    fn banned_peer_filtered_from_available() {
        use crate::ban::{BanConfig, BanManager};
        use std::net::IpAddr;

        let banned_ip: IpAddr = "192.168.1.200".parse().unwrap();
        let ok_ip: IpAddr = "10.0.0.1".parse().unwrap();

        let mgr = BanManager::new(BanConfig::default());
        // Not banned yet — both should pass
        assert!(!mgr.is_banned(&banned_ip));
        assert!(!mgr.is_banned(&ok_ip));

        let mut mgr = BanManager::new(BanConfig::default());
        mgr.ban(banned_ip);

        // Now banned_ip is filtered, ok_ip is not
        assert!(mgr.is_banned(&banned_ip));
        assert!(!mgr.is_banned(&ok_ip));
    }

    // ---- M27: Parallel hashing tests ----

    #[test]
    fn hashing_threads_config_default() {
        let s = irontide_settings::Settings::default();
        let expected = {
            let cores = std::thread::available_parallelism().map_or(4, std::num::NonZero::get);
            (cores / 4).clamp(2, 8)
        };
        assert_eq!(s.hashing_threads, expected);
        let tc = TorrentConfig::default();
        assert_eq!(tc.hashing_threads, expected);
    }

    #[tokio::test]
    async fn checking_state_and_progress_alerts() {
        use crate::alert::AlertKind;

        let data = vec![0xEEu8; 65536]; // 4 pieces of 16384
        let meta = make_test_torrent(&data, 16384);
        let storage = make_seeded_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let mut rx = atx.subscribe();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Collect alerts for up to 2 seconds
        let mut saw_checking = false;
        let mut progress_values: Vec<f32> = Vec::new();
        let mut saw_checked = false;
        let mut checked_have = 0u32;
        let mut checked_total = 0u32;

        let deadline = tokio::time::Instant::now() + Duration::from_secs(2);
        while tokio::time::Instant::now() < deadline {
            match tokio::time::timeout(Duration::from_millis(200), rx.recv()).await {
                Ok(Ok(alert)) => match alert.kind {
                    AlertKind::StateChanged {
                        new_state: TorrentState::Checking,
                        ..
                    } => {
                        saw_checking = true;
                    }
                    AlertKind::CheckingProgress { progress, .. } => {
                        progress_values.push(progress);
                    }
                    AlertKind::TorrentChecked {
                        pieces_have,
                        pieces_total,
                        ..
                    } => {
                        saw_checked = true;
                        checked_have = pieces_have;
                        checked_total = pieces_total;
                        break;
                    }
                    _ => {}
                },
                _ => break,
            }
        }

        assert!(saw_checking, "should have seen StateChanged → Checking");
        assert!(
            !progress_values.is_empty(),
            "should have seen CheckingProgress alerts"
        );
        // Progress should be monotonically increasing
        for w in progress_values.windows(2) {
            assert!(
                w[1] >= w[0],
                "progress should be monotonically increasing: {} < {}",
                w[0],
                w[1]
            );
        }
        assert!(saw_checked, "should have seen TorrentChecked");
        assert_eq!(checked_have, 4);
        assert_eq!(checked_total, 4);

        // Final state should be Seeding (all pieces valid)
        tokio::time::sleep(Duration::from_millis(50)).await;
        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::Seeding);

        handle.shutdown().await.unwrap();
    }

    #[tokio::test]
    #[allow(clippy::float_cmp, reason = "exact sentinel value comparison (0.0)")]
    async fn checking_progress_in_stats() {
        // When not in Checking state, checking_progress should be 0.0
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Give actor time to finish checking (no valid pieces → Downloading)
        tokio::time::sleep(Duration::from_millis(100)).await;

        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::Downloading);
        assert_eq!(
            stats.checking_progress, 0.0,
            "checking_progress should be 0.0 when not checking"
        );

        handle.shutdown().await.unwrap();
    }

    #[tokio::test]
    async fn verify_pieces_partial_data() {
        use crate::alert::AlertKind;

        // 4 pieces, only first 2 have valid data
        let data = vec![0xCCu8; 65536]; // 4 pieces × 16384
        let meta = make_test_torrent(&data, 16384);

        // Create storage and only write valid data for pieces 0 and 1
        let lengths = Lengths::new(data.len() as u64, 16384, DEFAULT_CHUNK_SIZE);
        let storage = Arc::new(MemoryStorage::new(lengths.clone()));
        for p in 0..2u32 {
            let offset = lengths.piece_offset(p) as usize;
            let size = lengths.piece_size(p) as usize;
            storage
                .write_chunk(p, 0, &data[offset..offset + size])
                .unwrap();
        }
        // Pieces 2 and 3 have no data (zeros) — won't match hash

        let config = test_config();
        let (atx, amask) = test_alert_channel();
        let mut rx = atx.subscribe();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Wait for TorrentChecked alert
        let mut checked_have = 0u32;
        let mut checked_total = 0u32;
        let deadline = tokio::time::Instant::now() + Duration::from_secs(2);
        while tokio::time::Instant::now() < deadline {
            match tokio::time::timeout(Duration::from_millis(200), rx.recv()).await {
                Ok(Ok(alert)) => {
                    if let AlertKind::TorrentChecked {
                        pieces_have,
                        pieces_total,
                        ..
                    } = alert.kind
                    {
                        checked_have = pieces_have;
                        checked_total = pieces_total;
                        break;
                    }
                }
                _ => break,
            }
        }

        assert_eq!(checked_have, 2, "only 2 pieces should be valid");
        assert_eq!(checked_total, 4);

        // Final state should be Downloading (partial)
        tokio::time::sleep(Duration::from_millis(50)).await;
        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::Downloading);
        assert_eq!(stats.pieces_have, 2);
        assert_eq!(stats.pieces_total, 4);

        handle.shutdown().await.unwrap();
    }

    // ---- M29: IP filter integration tests ----

    #[tokio::test]
    async fn ip_filter_blocks_peers_in_handle_add_peers() {
        let data = vec![0xCD; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        // Create an IP filter that blocks 203.0.113.0/24 (TEST-NET-3, public range)
        let ip_filter = {
            let mut f = crate::ip_filter::IpFilter::new();
            f.add_rule(
                "203.0.113.0".parse().unwrap(),
                "203.0.113.255".parse().unwrap(),
                1,
            );
            Arc::new(parking_lot::RwLock::new(f))
        };

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            Arc::clone(&ip_filter),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Add peers: one blocked (public IP in TEST-NET-3), one allowed (different public IP)
        let blocked_addr: SocketAddr = "203.0.113.42:6881".parse().unwrap();
        let allowed_addr: SocketAddr = "198.51.100.1:6881".parse().unwrap();
        handle
            .add_peers(vec![blocked_addr, allowed_addr], PeerSource::Tracker)
            .await
            .unwrap();

        tokio::time::sleep(std::time::Duration::from_millis(100)).await;
        let stats = handle.stats().await.unwrap();
        // Only the allowed peer should be in the pool
        assert!(
            stats.peers_available + stats.peers_connected <= 1,
            "blocked peer should not be added: available={}, connected={}",
            stats.peers_available,
            stats.peers_connected
        );

        handle.shutdown().await.unwrap();
    }

    #[tokio::test]
    async fn set_ip_filter_replaces_filter_and_blocks_new_ip() {
        // Test that updating the shared IP filter takes effect for new peer additions.
        // Use public IPs (TEST-NET ranges) since local networks are always exempt.
        let data = vec![0xCD; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        // Start with empty filter (everything allowed)
        let ip_filter: irontide_session_types::SharedIpFilter =
            Arc::new(parking_lot::RwLock::new(crate::ip_filter::IpFilter::new()));

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            Arc::clone(&ip_filter),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Initially, peers are allowed by the IP filter.
        // Use a local listener so the connection succeeds and the peer stays known.
        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let local_addr = listener.local_addr().unwrap();
        handle
            .add_peers(vec![local_addr], PeerSource::Tracker)
            .await
            .unwrap();
        tokio::time::sleep(std::time::Duration::from_millis(100)).await;
        let stats = handle.stats().await.unwrap();
        assert!(
            stats.peers_available + stats.peers_connected >= 1,
            "peer should be allowed initially"
        );
        handle.shutdown().await.unwrap();

        // Now update the shared filter to block that IP range
        {
            let mut f = ip_filter.write();
            f.add_rule(
                "198.51.100.0".parse().unwrap(),
                "198.51.100.255".parse().unwrap(),
                1,
            );
        }

        // Verify the filter is updated (public IP, so is_blocked applies)
        assert!(ip_filter.read().is_blocked("198.51.100.1".parse().unwrap()));
        // Verify a different public IP is still allowed
        assert!(!ip_filter.read().is_blocked("203.0.113.1".parse().unwrap()));
    }

    #[test]
    fn relocate_files_moves_and_cleans_up() {
        let tmp = std::env::temp_dir().join(format!("torrent_relocate_{}", std::process::id()));
        let src = tmp.join("src");
        let dst = tmp.join("dst");

        // Create source files mimicking multi-file torrent layout:
        // TorrentName/subdir/file1.txt
        // TorrentName/file2.txt
        let subdir = src.join("TorrentName").join("subdir");
        std::fs::create_dir_all(&subdir).unwrap();
        std::fs::write(subdir.join("file1.txt"), b"hello").unwrap();
        std::fs::write(src.join("TorrentName").join("file2.txt"), b"world").unwrap();

        let file_paths = vec![
            std::path::PathBuf::from("TorrentName/subdir/file1.txt"),
            std::path::PathBuf::from("TorrentName/file2.txt"),
        ];

        relocate_files(&src, &dst, &file_paths).unwrap();

        // Destination should have both files
        assert_eq!(
            std::fs::read_to_string(dst.join("TorrentName/subdir/file1.txt")).unwrap(),
            "hello"
        );
        assert_eq!(
            std::fs::read_to_string(dst.join("TorrentName/file2.txt")).unwrap(),
            "world"
        );

        // Source directory should be cleaned up (empty dirs removed)
        assert!(!src.join("TorrentName").join("subdir").exists());
        assert!(!src.join("TorrentName").exists());

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

    #[test]
    fn relocate_files_skips_missing() {
        let tmp =
            std::env::temp_dir().join(format!("torrent_relocate_skip_{}", std::process::id()));
        let src = tmp.join("src");
        let dst = tmp.join("dst");
        std::fs::create_dir_all(&src).unwrap();

        // File doesn't exist — should be skipped without error
        let file_paths = vec![std::path::PathBuf::from("nonexistent.txt")];
        relocate_files(&src, &dst, &file_paths).unwrap();

        assert!(!dst.join("nonexistent.txt").exists());

        let _ = std::fs::remove_dir_all(&tmp);
    }

    // ---- Test: force_recheck transitions through Checking state ----

    #[tokio::test]
    async fn force_recheck_transitions_to_checking() {
        let data = vec![0xDDu8; 32768]; // 2 pieces
        let meta = make_test_torrent(&data, 16384);
        let storage = make_seeded_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let mut arx = atx.subscribe();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Wait for initial verification to complete (should become Seeding)
        tokio::time::sleep(Duration::from_millis(100)).await;
        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::Seeding, "should start as seeder");

        // Drain any existing alerts
        while arx.try_recv().is_ok() {}

        // Force recheck
        handle.force_recheck().await.unwrap();

        // After force_recheck returns, look for a StateChanged alert that
        // went through Checking (the transition_state fires it)
        let mut saw_checking = false;
        while let Ok(alert) = arx.try_recv() {
            if let crate::alert::AlertKind::StateChanged { new_state, .. } = alert.kind
                && new_state == TorrentState::Checking
            {
                saw_checking = true;
            }
        }
        assert!(
            saw_checking,
            "should have transitioned through Checking state"
        );

        handle.shutdown().await.unwrap();
    }

    // ---- Test: force_recheck completes with correct state ----

    #[tokio::test]
    async fn force_recheck_completes() {
        let data = vec![0xEEu8; 32768]; // 2 pieces
        let meta = make_test_torrent(&data, 16384);
        let storage = make_seeded_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Wait for initial verification
        tokio::time::sleep(Duration::from_millis(100)).await;
        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::Seeding);
        assert_eq!(stats.pieces_have, 2);

        // Force recheck — should re-verify all pieces and return to Seeding
        handle.force_recheck().await.unwrap();

        let stats = handle.stats().await.unwrap();
        assert_eq!(
            stats.state,
            TorrentState::Seeding,
            "should return to Seeding after recheck"
        );
        assert_eq!(stats.pieces_have, 2, "all pieces should still be verified");

        handle.shutdown().await.unwrap();
    }

    // ---- Test: rename_file succeeds with valid index ----

    #[tokio::test]
    async fn rename_file_succeeds() {
        // Create a real file on disk that we can rename
        let tmp = std::env::temp_dir().join(format!("torrent_rename_{}", std::process::id()));
        std::fs::create_dir_all(&tmp).unwrap();

        let data = vec![0xFFu8; 16384]; // 1 piece
        let meta = make_test_torrent(&data, 16384);
        let storage = make_seeded_storage(&data, 16384);

        // The single-file torrent has name "test", so file path is "test"
        // Create the actual file on disk at download_dir/test
        std::fs::write(tmp.join("test"), &data).unwrap();

        let mut config = test_config();
        config.download_dir = tmp.clone();

        let (atx, amask) = test_alert_channel();
        let mut arx = atx.subscribe();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Wait for initial verification
        tokio::time::sleep(Duration::from_millis(100)).await;

        // Drain existing alerts
        while arx.try_recv().is_ok() {}

        // Rename file 0 to "test_renamed"
        handle.rename_file(0, "test_renamed".into()).await.unwrap();

        // Check that the old file is gone and new file exists
        assert!(!tmp.join("test").exists(), "old file should be removed");
        assert!(tmp.join("test_renamed").exists(), "new file should exist");

        // Check that FileRenamed alert was fired
        let mut saw_renamed = false;
        while let Ok(alert) = arx.try_recv() {
            if let AlertKind::FileRenamed { index, .. } = alert.kind {
                assert_eq!(index, 0);
                saw_renamed = true;
            }
        }
        assert!(saw_renamed, "should have received FileRenamed alert");

        handle.shutdown().await.unwrap();
        let _ = std::fs::remove_dir_all(&tmp);
    }

    // ---- Test: rename_file with invalid index returns error ----

    #[tokio::test]
    async fn rename_file_invalid_index_errors() {
        let data = vec![0xCCu8; 16384]; // 1 piece, single-file torrent
        let meta = make_test_torrent(&data, 16384);
        let storage = make_seeded_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Wait for initial verification
        tokio::time::sleep(Duration::from_millis(100)).await;

        // Try to rename file index 99 (out of range)
        let result = handle.rename_file(99, "bad".into()).await;
        assert!(result.is_err(), "should fail for out-of-range file index");

        handle.shutdown().await.unwrap();
    }

    // ---- Test: FileCompleted alert fires when all pieces of a file are verified ----

    #[tokio::test]
    async fn file_completed_alert_fires() {
        let data = vec![0xBBu8; 32768]; // 2 pieces
        let meta = make_test_torrent(&data, 16384);
        let storage = make_seeded_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let mut arx = atx.subscribe();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Wait for initial verification (seeded storage => all pieces verify)
        tokio::time::sleep(Duration::from_millis(200)).await;

        // Should have received FileCompleted alert for the single file
        let mut saw_file_completed = false;
        while let Ok(alert) = arx.try_recv() {
            if let AlertKind::FileCompleted { file_index, .. } = alert.kind {
                assert_eq!(file_index, 0, "should be file index 0");
                saw_file_completed = true;
            }
        }
        assert!(
            saw_file_completed,
            "should have received FileCompleted alert"
        );

        handle.shutdown().await.unwrap();
    }

    // ---- Test: MetadataFailed alert fires (unit test on AlertKind) ----

    #[test]
    fn metadata_failed_alert_fires() {
        // Test that MetadataFailed alert has the correct category
        let info_hash = Id20::from([0u8; 20]);
        let alert = crate::alert::Alert::new(AlertKind::MetadataFailed { info_hash });
        assert!(
            alert
                .category()
                .contains(crate::alert::AlertCategory::STATUS),
            "MetadataFailed should have STATUS category"
        );
        assert!(
            alert
                .category()
                .contains(crate::alert::AlertCategory::ERROR),
            "MetadataFailed should have ERROR category"
        );

        // Verify it can be posted through the alert system
        let (tx, mut rx) = broadcast::channel(16);
        let mask = Arc::new(AtomicU32::new(crate::alert::AlertCategory::ALL.bits()));
        post_alert(&tx, &mask, AlertKind::MetadataFailed { info_hash });
        let received = rx.try_recv().expect("should receive MetadataFailed alert");
        assert!(matches!(received.kind, AlertKind::MetadataFailed { .. }));
    }

    // ---- Test: set_max_connections persists ----

    #[tokio::test]
    async fn set_max_connections_persists() {
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Set max_connections to 10
        handle.set_max_connections(10).await.unwrap();
        let val = handle.max_connections().await.unwrap();
        assert_eq!(val, 10);

        // Update to a different value
        handle.set_max_connections(25).await.unwrap();
        let val = handle.max_connections().await.unwrap();
        assert_eq!(val, 25);

        // Verify stats reflect the override
        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.connections_limit, 25);

        handle.shutdown().await.unwrap();
    }

    // ---- Test: max_connections default is 0 (use config.max_peers) ----

    #[tokio::test]
    async fn max_connections_default() {
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();
        let expected_default = config.max_peers;

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Default max_connections should be 0
        let val = handle.max_connections().await.unwrap();
        assert_eq!(val, 0);

        // Stats should show config.max_peers as the effective limit
        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.connections_limit, expected_default);

        handle.shutdown().await.unwrap();
    }

    // ---- Test: set_max_uploads round trip ----

    #[tokio::test]
    async fn set_max_uploads_round_trip() {
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Set max_uploads to 8
        handle.set_max_uploads(8).await.unwrap();
        let val = handle.max_uploads().await.unwrap();
        assert_eq!(val, 8);

        // Verify stats uploads_limit reflects the new value
        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.uploads_limit, 8);

        handle.shutdown().await.unwrap();
    }

    // ---- Test: ExternalIpDetected alert fires ----

    #[tokio::test]
    async fn external_ip_detected_alert() {
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let mut arx = atx.subscribe();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Drain any initial alerts
        while arx.try_recv().is_ok() {}

        // Send UpdateExternalIp command
        let test_ip: std::net::IpAddr = "203.0.113.42".parse().unwrap();
        handle
            .cmd_tx
            .send(TorrentCommand::UpdateExternalIp { ip: test_ip })
            .await
            .unwrap();

        // Wait for the actor to process
        tokio::time::sleep(Duration::from_millis(50)).await;

        // Check for ExternalIpDetected alert
        let mut saw_alert = false;
        while let Ok(alert) = arx.try_recv() {
            if let AlertKind::ExternalIpDetected { ip } = alert.kind {
                assert_eq!(ip, test_ip);
                saw_alert = true;
            }
        }
        assert!(saw_alert, "should have received ExternalIpDetected alert");

        handle.shutdown().await.unwrap();
    }

    // ---- Test: get_peer_info returns connected peers ----

    #[tokio::test]
    async fn get_peer_info_returns_connected_peers() {
        let data = vec![0xAB; 65536]; // 64 KiB
        let meta = make_test_torrent(&data, 16384); // 4 pieces
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta.clone(),
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Set up a fake peer via TCP handshake
        let stats = handle.stats().await.unwrap();
        let listen_port = stats.peers_connected; // Initially 0

        // Add a peer to the available pool and let the actor connect
        let peer_listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let peer_addr = peer_listener.local_addr().unwrap();

        handle
            .add_peers(vec![peer_addr], PeerSource::Tracker)
            .await
            .unwrap();

        // Accept the connection and complete the handshake
        let accept_timeout =
            tokio::time::timeout(Duration::from_secs(2), peer_listener.accept()).await;
        if let Ok(Ok((mut stream, _))) = accept_timeout {
            // Read handshake
            let mut hs_buf = [0u8; HANDSHAKE_SIZE];
            if tokio::time::timeout(Duration::from_millis(500), stream.read_exact(&mut hs_buf))
                .await
                .is_ok()
            {
                // Send back handshake
                let hs = Handshake::new(meta.info_hash, Id20::from([0xBB; 20]));
                let hs_bytes = hs.to_bytes();
                let _ = stream.write_all(&hs_bytes).await;

                // Give the actor time to register the peer
                tokio::time::sleep(Duration::from_millis(200)).await;

                // Now query peer info
                let peer_info = handle.get_peer_info().await.unwrap();
                // We should have at least one peer (the one we just handshaked)
                if !peer_info.is_empty() {
                    let p = &peer_info[0];
                    // Verify default choking/interested state
                    assert!(p.peer_choking, "peer should be choking us initially");
                    // M107: we unconditionally unchoke on connect, so am_choking starts false
                    assert!(
                        !p.am_choking,
                        "we should not be choking peer after connect (M107 unconditional unchoke)"
                    );
                    assert!(
                        !p.peer_interested,
                        "peer should not be interested initially"
                    );
                    assert_eq!(p.num_pieces, 0);
                    assert_eq!(p.source, PeerSource::Tracker);
                }
            }
        }
        // Even if handshake timing fails, at least verify the API works
        let _ = handle.get_peer_info().await.unwrap();
        assert_eq!(listen_port, 0); // sanity: initially had no peers

        handle.shutdown().await.unwrap();
    }

    // ---- Test: get_peer_info empty when no peers ----

    #[tokio::test]
    async fn get_peer_info_empty_when_no_peers() {
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        let peer_info = handle.get_peer_info().await.unwrap();
        assert!(peer_info.is_empty(), "should have no peers initially");

        handle.shutdown().await.unwrap();
    }

    // ---- Test: get_download_queue empty initially ----

    #[tokio::test]
    async fn get_download_queue_empty_initially() {
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        let queue = handle.get_download_queue().await.unwrap();
        assert!(
            queue.is_empty(),
            "download queue should be empty with no active downloads"
        );

        handle.shutdown().await.unwrap();
    }

    // ---- Test: have_piece false initially ----

    #[tokio::test]
    async fn have_piece_false_initially() {
        let data = vec![0xAB; 32768]; // 32 KiB = 2 pieces
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        assert!(
            !handle.have_piece(0).await.unwrap(),
            "piece 0 should not be downloaded initially"
        );
        assert!(
            !handle.have_piece(1).await.unwrap(),
            "piece 1 should not be downloaded initially"
        );

        handle.shutdown().await.unwrap();
    }

    // ---- Test: piece_availability empty with no peers ----

    #[tokio::test]
    async fn piece_availability_empty_no_peers() {
        let data = vec![0xAB; 32768]; // 2 pieces
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        let avail = handle.piece_availability().await.unwrap();
        assert_eq!(avail.len(), 2, "should have availability for 2 pieces");
        assert!(
            avail.iter().all(|&c| c == 0),
            "all availability counts should be 0 with no peers"
        );

        handle.shutdown().await.unwrap();
    }

    // ---- Test: file_progress zeros initially ----

    #[tokio::test]
    async fn file_progress_zeros_initially() {
        let data = vec![0xAB; 32768]; // single-file, 2 pieces
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        let progress = handle.file_progress().await.unwrap();
        assert_eq!(progress.len(), 1, "single-file torrent should have 1 entry");
        assert_eq!(progress[0], 0, "no bytes should be downloaded initially");

        handle.shutdown().await.unwrap();
    }

    // ---- Test: file_progress length matches file count (multi-file) ----

    /// Build a multi-file `TorrentMetaV1` from a total data blob and file lengths.
    fn make_test_torrent_multi(
        data: &[u8],
        piece_length: u64,
        file_lengths: &[u64],
    ) -> TorrentMetaV1 {
        use serde::Serialize;

        #[derive(Serialize)]
        struct FileE {
            length: u64,
            path: Vec<String>,
        }

        #[derive(Serialize)]
        struct Info<'a> {
            name: &'a str,
            #[serde(rename = "piece length")]
            piece_length: u64,
            #[serde(with = "serde_bytes")]
            pieces: &'a [u8],
            files: Vec<FileE>,
        }

        #[derive(Serialize)]
        struct Torrent<'a> {
            info: Info<'a>,
        }

        let mut pieces = Vec::new();
        let mut offset = 0;
        while offset < data.len() {
            let end = (offset + piece_length as usize).min(data.len());
            let hash = irontide_core::sha1(&data[offset..end]);
            pieces.extend_from_slice(hash.as_bytes());
            offset = end;
        }

        let files: Vec<FileE> = file_lengths
            .iter()
            .enumerate()
            .map(|(i, &len)| FileE {
                length: len,
                path: vec![format!("file{i}.bin")],
            })
            .collect();

        let t = Torrent {
            info: Info {
                name: "test_multi",
                piece_length,
                pieces: &pieces,
                files,
            },
        };

        let bytes = irontide_bencode::to_bytes(&t).unwrap();
        torrent_from_bytes(&bytes).unwrap()
    }

    #[tokio::test]
    async fn file_progress_length_matches_file_count() {
        // 3 files: 10000 + 20000 + 2768 = 32768 bytes total, 2 pieces of 16384
        let data = vec![0xCD; 32768];
        let file_lengths = [10000u64, 20000, 2768];
        let meta = make_test_torrent_multi(&data, 16384, &file_lengths);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        let progress = handle.file_progress().await.unwrap();
        assert_eq!(
            progress.len(),
            3,
            "multi-file torrent should have 3 entries"
        );
        assert!(
            progress.iter().all(|&b| b == 0),
            "all progress should be 0 initially"
        );

        handle.shutdown().await.unwrap();
    }

    // ---- Test: is_valid returns true for active torrent ----

    #[tokio::test]
    async fn is_valid_true_for_active() {
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        assert!(
            handle.is_valid(),
            "handle should be valid while torrent actor is alive"
        );

        handle.shutdown().await.unwrap();
    }

    // ---- Test: is_valid returns false after shutdown ----

    #[tokio::test]
    async fn is_valid_false_after_remove() {
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        assert!(handle.is_valid());

        // Shutdown the torrent (simulating removal)
        handle.shutdown().await.unwrap();

        // Give the actor time to stop and close the channel
        tokio::time::sleep(std::time::Duration::from_millis(50)).await;

        assert!(
            !handle.is_valid(),
            "handle should be invalid after shutdown"
        );
    }

    // ---- Test: clear_error resets error state ----

    #[tokio::test]
    async fn clear_error_resets() {
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Initially no error
        let stats = handle.stats().await.unwrap();
        assert!(stats.error.is_empty());
        assert_eq!(stats.error_file, -1);

        // Clear error (no-op when no error) should succeed without issue
        handle.clear_error().await.unwrap();

        let stats = handle.stats().await.unwrap();
        assert!(stats.error.is_empty());
        assert_eq!(stats.error_file, -1);

        handle.shutdown().await.unwrap();
    }

    // ---- Test: flags round trip ----

    #[tokio::test]
    async fn flags_round_trip() {
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Initial flags: torrent starts downloading (not paused), no sequential, no super seeding
        let initial = handle.flags().await.unwrap();
        assert!(!initial.contains(crate::types::TorrentFlags::PAUSED));
        assert!(!initial.contains(crate::types::TorrentFlags::SEQUENTIAL_DOWNLOAD));
        assert!(!initial.contains(crate::types::TorrentFlags::SUPER_SEEDING));

        // Enable sequential download via set_flags
        handle
            .set_flags(crate::types::TorrentFlags::SEQUENTIAL_DOWNLOAD)
            .await
            .unwrap();
        let after_set = handle.flags().await.unwrap();
        assert!(after_set.contains(crate::types::TorrentFlags::SEQUENTIAL_DOWNLOAD));

        // Disable it via unset_flags
        handle
            .unset_flags(crate::types::TorrentFlags::SEQUENTIAL_DOWNLOAD)
            .await
            .unwrap();
        let after_unset = handle.flags().await.unwrap();
        assert!(!after_unset.contains(crate::types::TorrentFlags::SEQUENTIAL_DOWNLOAD));

        // Verify sequential_download state via the dedicated query
        assert!(!handle.is_sequential_download().await.unwrap());

        handle.shutdown().await.unwrap();
    }

    // ---- Test: connect_peer does not error ----

    #[tokio::test]
    async fn connect_peer_no_error() {
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None, // M96: hash_pool
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // connect_peer should not error even though the peer doesn't exist
        // (the connection attempt will fail asynchronously, but the command itself succeeds)
        let addr: SocketAddr = "127.0.0.1:12345".parse().unwrap();
        handle.connect_peer(addr).await.unwrap();

        // Give the actor a moment to process
        tokio::time::sleep(std::time::Duration::from_millis(10)).await;

        handle.shutdown().await.unwrap();
    }

    // ---- BEP 52 hash serving tests (M87) ----

    /// Build a minimal `TorrentMetaV2` with piece-layer hashes for testing.
    fn make_test_meta_v2(
        piece_hashes: &[irontide_core::Id32],
        file_root: irontide_core::Id32,
        piece_length: u64,
        file_length: u64,
    ) -> irontide_core::TorrentMetaV2 {
        use std::collections::BTreeMap;

        // Concatenate piece hashes into raw bytes
        let mut layer_bytes = Vec::with_capacity(piece_hashes.len() * 32);
        for h in piece_hashes {
            layer_bytes.extend_from_slice(&h.0);
        }

        let mut piece_layers = BTreeMap::new();
        piece_layers.insert(file_root, layer_bytes);

        let file_tree = irontide_core::FileTreeNode::Directory({
            let mut children = BTreeMap::new();
            children.insert(
                "test.dat".to_string(),
                irontide_core::FileTreeNode::File(irontide_core::V2FileAttr {
                    length: file_length,
                    pieces_root: Some(file_root),
                }),
            );
            children
        });

        irontide_core::TorrentMetaV2 {
            info_hashes: irontide_core::InfoHashes::v2_only(irontide_core::Id32::ZERO),
            info_bytes: None,
            announce: None,
            announce_list: None,
            comment: None,
            created_by: None,
            creation_date: None,
            info: irontide_core::InfoDictV2 {
                name: "test".to_string(),
                piece_length,
                meta_version: 2,
                file_tree,
                ssl_cert: None,
            },
            piece_layers,
            ssl_cert: None,
        }
    }

    #[test]
    fn test_serve_hashes_v2_piece_layer() {
        // 4 piece hashes, piece_length = 16384, chunk_size = 16384
        // => blocks_per_piece = 1, piece_layer_base = 0
        let hashes: Vec<irontide_core::Id32> = (0..4u8)
            .map(|i| {
                let mut h = [0u8; 32];
                h[0] = i;
                irontide_core::Id32(h)
            })
            .collect();
        let file_root = irontide_core::Id32([0xAA; 32]);
        let meta = make_test_meta_v2(&hashes, file_root, 16384, 16384 * 4);
        let lengths = Lengths::new(16384 * 4, 16384, DEFAULT_CHUNK_SIZE);

        let request = irontide_core::HashRequest {
            file_root,
            base: 0, // piece layer when blocks_per_piece = 1
            index: 0,
            count: 4,
            proof_layers: 0,
        };

        let result = serve_hashes(
            Some(&meta),
            irontide_core::TorrentVersion::V2Only,
            Some(&lengths),
            &request,
        );
        let served = result.expect("should serve hashes");
        assert_eq!(served.len(), 4);
        for (i, h) in served.iter().enumerate() {
            assert_eq!(h.0[0], i as u8);
        }
    }

    #[test]
    fn test_serve_hashes_rejects_v1_only() {
        let hashes: Vec<irontide_core::Id32> = vec![irontide_core::Id32([0xBB; 32])];
        let file_root = irontide_core::Id32([0xAA; 32]);
        let meta = make_test_meta_v2(&hashes, file_root, 16384, 16384);
        let lengths = Lengths::new(16384, 16384, DEFAULT_CHUNK_SIZE);

        let request = irontide_core::HashRequest {
            file_root,
            base: 0,
            index: 0,
            count: 1,
            proof_layers: 0,
        };

        let result = serve_hashes(
            Some(&meta),
            irontide_core::TorrentVersion::V1Only,
            Some(&lengths),
            &request,
        );
        assert!(result.is_none(), "V1Only should reject hash requests");
    }

    #[test]
    fn test_serve_hashes_rejects_unknown_root() {
        let hashes: Vec<irontide_core::Id32> = vec![irontide_core::Id32([0xBB; 32])];
        let file_root = irontide_core::Id32([0xAA; 32]);
        let meta = make_test_meta_v2(&hashes, file_root, 16384, 16384);
        let lengths = Lengths::new(16384, 16384, DEFAULT_CHUNK_SIZE);

        // Request a different file root that doesn't exist
        let unknown_root = irontide_core::Id32([0xFF; 32]);
        let request = irontide_core::HashRequest {
            file_root: unknown_root,
            base: 0,
            index: 0,
            count: 1,
            proof_layers: 0,
        };

        let result = serve_hashes(
            Some(&meta),
            irontide_core::TorrentVersion::V2Only,
            Some(&lengths),
            &request,
        );
        assert!(result.is_none(), "unknown file_root should reject");
    }

    #[test]
    fn test_serve_hashes_rejects_out_of_bounds() {
        // 2 piece hashes, piece_length = 16384, chunk_size = 16384
        let hashes: Vec<irontide_core::Id32> =
            (0..2u8).map(|i| irontide_core::Id32([i; 32])).collect();
        let file_root = irontide_core::Id32([0xAA; 32]);
        let meta = make_test_meta_v2(&hashes, file_root, 16384, 16384 * 2);
        let lengths = Lengths::new(16384 * 2, 16384, DEFAULT_CHUNK_SIZE);

        // Request starting at index 5, which is beyond the 2 available hashes
        let request = irontide_core::HashRequest {
            file_root,
            base: 0,
            index: 5,
            count: 1,
            proof_layers: 0,
        };

        let result = serve_hashes(
            Some(&meta),
            irontide_core::TorrentVersion::V2Only,
            Some(&lengths),
            &request,
        );
        assert!(result.is_none(), "out-of-bounds index should reject");
    }

    #[test]
    fn test_serve_hashes_includes_proofs() {
        // 4 piece hashes, piece_length = 16384, chunk_size = 16384
        // => blocks_per_piece = 1, tree has 4 leaves => depth 2
        let hashes: Vec<irontide_core::Id32> =
            (0..4u8).map(|i| irontide_core::Id32([i; 32])).collect();
        let file_root = irontide_core::Id32([0xAA; 32]);
        let meta = make_test_meta_v2(&hashes, file_root, 16384, 16384 * 4);
        let lengths = Lengths::new(16384 * 4, 16384, DEFAULT_CHUNK_SIZE);

        // Request 1 hash with 1 proof layer
        let request = irontide_core::HashRequest {
            file_root,
            base: 0,
            index: 0,
            count: 1,
            proof_layers: 1,
        };

        let result = serve_hashes(
            Some(&meta),
            irontide_core::TorrentVersion::V2Only,
            Some(&lengths),
            &request,
        );
        let served = result.expect("should serve hashes with proofs");
        // 1 requested hash + 1 proof hash (sibling of leaf 0) = 2 total
        assert_eq!(served.len(), 2, "should have 1 data hash + 1 proof hash");
        // First hash is the requested piece hash
        assert_eq!(served[0], hashes[0]);
        // Second hash is the sibling (proof) — which is hashes[1]
        assert_eq!(served[1], hashes[1]);
    }

    #[test]
    fn test_serve_hashes_proof_with_batch() {
        // 4 piece hashes, piece_length = 16384, chunk_size = 16384
        // => blocks_per_piece = 1, tree has 4 leaves => depth 2
        //
        // Tree layout (1-indexed heap):
        //          [1] root
        //        /          \
        //     [2]            [3]
        //    /    \         /    \
        //  [4]h0  [5]h1  [6]h2  [7]h3
        //
        // Request count=2 at index=0 => subtree rooted at [2] (h0, h1).
        // subtree_depth = log2(2) = 1, so we skip 1 level of the proof path.
        // proof_path(0) = [h1, hash(h2,h3)] — h1 is internal to subtree,
        // hash(h2,h3) is the uncle above. We skip h1 and send hash(h2,h3).
        let hashes: Vec<irontide_core::Id32> =
            (0..4u8).map(|i| irontide_core::Id32([i; 32])).collect();
        let file_root = irontide_core::Id32([0xAA; 32]);
        let meta = make_test_meta_v2(&hashes, file_root, 16384, 16384 * 4);
        let lengths = Lengths::new(16384 * 4, 16384, DEFAULT_CHUNK_SIZE);

        let request = irontide_core::HashRequest {
            file_root,
            base: 0,
            index: 0,
            count: 2,
            proof_layers: 1,
        };

        let result = serve_hashes(
            Some(&meta),
            irontide_core::TorrentVersion::V2Only,
            Some(&lengths),
            &request,
        );
        let served = result.expect("should serve hashes with batch proof");
        // 2 base hashes + 1 uncle hash = 3 total
        assert_eq!(served.len(), 3, "should have 2 data hashes + 1 uncle hash");
        // First two are the requested piece hashes
        assert_eq!(served[0], hashes[0]);
        assert_eq!(served[1], hashes[1]);
        // Third is the uncle: sibling of the subtree root at [2],
        // which is the node at [3] = hash(h2, h3)
        let tree = irontide_core::MerkleTree::from_leaves(&hashes);
        let expected_uncle = tree.layer(1)[1]; // layer 1 has 2 nodes; index 1 is the right one
        assert_eq!(served[2], expected_uncle);

        // Verify the proof is valid: reconstruct subtree root from base hashes,
        // then verify against the tree root using the uncle hash
        let sub_root = irontide_core::MerkleTree::root_from_hashes(&served[..2]);
        let uncle_hashes = &served[2..];
        let leaf_index = request.index as usize / 2; // 0 / 2 = 0
        assert!(
            irontide_core::MerkleTree::verify_proof(
                tree.root(),
                sub_root,
                leaf_index,
                uncle_hashes
            ),
            "subtree proof should verify against tree root"
        );
    }

    #[test]
    fn is_i2p_synthetic_addr_detects_240_range() {
        assert!(is_i2p_synthetic_addr(&"240.0.0.1:1".parse().unwrap()));
        assert!(is_i2p_synthetic_addr(
            &"255.255.255.255:65535".parse().unwrap()
        ));
        assert!(!is_i2p_synthetic_addr(&"192.168.1.1:6881".parse().unwrap()));
        assert!(!is_i2p_synthetic_addr(&"[::1]:6881".parse().unwrap()));
    }

    #[test]
    fn v6_retry_delay_progression() {
        // Verify exponential backoff: 100, 200, 400, 800, 1600, 3200, 5000, 5000...
        let expected_ms = [100, 200, 400, 800, 1600, 3200, 5000, 5000, 5000, 5000, 5000];
        for (count, &expected) in expected_ms.iter().enumerate() {
            let delay_ms = {
                let base_ms: u64 = 100;
                let max_ms: u64 = 5000;
                base_ms
                    .saturating_mul(1u64.checked_shl(count as u32).unwrap_or(u64::MAX))
                    .min(max_ms)
            };
            assert_eq!(
                delay_ms, expected,
                "count={count}: expected {expected}ms, got {delay_ms}ms"
            );
        }
    }

    // ---- M104: Per-peer backoff and max_in_flight formula tests ----

    #[test]
    fn peer_backoff_exponential() {
        // Verify the M104 backoff formula: 200ms * 2^attempt, capped at 30s.
        // attempt starts at 1 (first failure increments 0 → 1).
        let expected_ms: Vec<u64> = vec![400, 800, 1600, 3200, 6400, 12800, 25600, 30000, 30000];
        for (i, &expected) in expected_ms.iter().enumerate() {
            let attempt = (i as u32) + 1; // attempt counts start at 1
            let delay_ms = 200u64.saturating_mul(1u64 << attempt.min(10)).min(30_000);
            assert_eq!(
                delay_ms, expected,
                "attempt={attempt}: expected {expected}ms, got {delay_ms}ms"
            );
        }
    }

    #[test]
    fn peer_backoff_clears_on_data() {
        // Verify that backoff map operations work correctly:
        // insert on disconnect, remove on data received.
        let mut backoff: HashMap<SocketAddr, (std::time::Instant, u32)> = HashMap::new();
        let addr: SocketAddr = "1.2.3.4:6881".parse().unwrap();

        // No backoff initially
        assert!(!backoff.contains_key(&addr));

        // First disconnect: attempt 1
        let attempt = backoff.get(&addr).map_or(0, |&(_, a)| a);
        let next = attempt.saturating_add(1);
        let delay_ms = 200u64.saturating_mul(1u64 << next.min(10)).min(30_000);
        let earliest = std::time::Instant::now() + Duration::from_millis(delay_ms);
        backoff.insert(addr, (earliest, next));
        assert_eq!(backoff.get(&addr).unwrap().1, 1);

        // Second disconnect: attempt 2
        let attempt = backoff.get(&addr).map_or(0, |&(_, a)| a);
        let next = attempt.saturating_add(1);
        let delay_ms = 200u64.saturating_mul(1u64 << next.min(10)).min(30_000);
        let earliest = std::time::Instant::now() + Duration::from_millis(delay_ms);
        backoff.insert(addr, (earliest, next));
        assert_eq!(backoff.get(&addr).unwrap().1, 2);

        // Data received: clear
        backoff.remove(&addr);
        assert!(!backoff.contains_key(&addr));
    }

    #[test]
    fn backoff_prevents_hammering() {
        // Verify that a peer with a future backoff time would be skipped.
        let mut backoff: HashMap<SocketAddr, (std::time::Instant, u32)> = HashMap::new();
        let addr: SocketAddr = "1.2.3.4:6881".parse().unwrap();

        // Set backoff 10 seconds in the future
        let future = std::time::Instant::now() + Duration::from_secs(10);
        backoff.insert(addr, (future, 3));

        // Should be skipped (now < next_attempt)
        if let Some(&(next_attempt, _)) = backoff.get(&addr) {
            assert!(std::time::Instant::now() < next_attempt);
        }

        // Set backoff in the past — should NOT be skipped
        let past = std::time::Instant::now() - Duration::from_secs(1);
        backoff.insert(addr, (past, 3));
        if let Some(&(next_attempt, _)) = backoff.get(&addr) {
            assert!(std::time::Instant::now() >= next_attempt);
        }
    }

    #[test]
    fn max_in_flight_formula_updated() {
        // M104: max(512, connected*4) clamped to pieces/2, floored at 512.
        let formula = |connected: usize, num_pieces: u32| -> usize {
            let calculated = 512usize.max(connected.saturating_mul(4));
            calculated.min(num_pieces as usize / 2).max(512)
        };

        // Few peers: floor dominates
        assert_eq!(formula(10, 2000), 512);

        // Many peers: connected * 4 takes over
        assert_eq!(formula(200, 2000), 800);

        // Very many peers: clamped by pieces/2
        assert_eq!(formula(500, 2000), 1000); // 2000 clamped to 1000

        // Tiny torrent: floor dominates even with many peers
        assert_eq!(formula(200, 100), 512); // 800 clamped to 50, floored to 512

        // Exact boundary
        assert_eq!(formula(128, 10000), 512); // 128*4=512, max(512,512)=512
        assert_eq!(formula(129, 10000), 516); // 129*4=516, max(512,516)=516

        // Zero peers
        assert_eq!(formula(0, 10000), 512);

        // Zero pieces (edge case — would give pieces/2=0, floor=512)
        assert_eq!(formula(100, 0), 512);
    }

    // -- BEP 55 holepunch initiation tests (M112) --

    #[test]
    fn should_attempt_holepunch_reason_classification() {
        // NAT-related reasons → true
        assert!(should_attempt_holepunch("connection refused"));
        assert!(should_attempt_holepunch("Connection refused"));
        assert!(should_attempt_holepunch("timed out"));
        assert!(should_attempt_holepunch("Connection reset by peer"));
        assert!(should_attempt_holepunch("connection reset by peer"));
        // Re-entrancy guard: holepunch-originated failures → false
        assert!(!should_attempt_holepunch(
            "holepunch TCP connect failed: Connection refused"
        ));
        // Non-NAT reasons → false
        assert!(!should_attempt_holepunch("peer banned"));
        assert!(!should_attempt_holepunch("protocol error"));
        assert!(!should_attempt_holepunch(""));
    }

    #[test]
    fn holepunch_initiation_on_connect_failure() {
        // "connection refused" is the canonical NAT failure reason
        assert!(should_attempt_holepunch("connection refused"));
    }

    #[test]
    fn holepunch_cooldown_prevents_retry() {
        let mut cooldowns: HashMap<SocketAddr, Instant> = HashMap::new();
        let addr: SocketAddr = "127.0.0.1:6881".parse().expect("valid test addr");
        let now = Instant::now();
        cooldowns.insert(addr, now);
        // addr is in cooldowns, so should be skipped on subsequent attempt
        assert!(cooldowns.contains_key(&addr));
    }

    #[test]
    fn holepunch_cooldown_overflow_skips() {
        let mut cooldowns: HashMap<SocketAddr, Instant> = HashMap::new();
        let now = Instant::now();
        for i in 0..256u16 {
            let addr: SocketAddr = format!("10.0.{}.{}:6881", i / 256, i % 256)
                .parse()
                .expect("valid test addr");
            cooldowns.insert(addr, now);
        }
        assert_eq!(cooldowns.len(), HOLEPUNCH_MAX_TRACKED);
        // New entry should be skipped when at capacity
    }

    #[test]
    fn holepunch_skipped_when_disabled() {
        // should_attempt_holepunch only checks the reason string, not config.
        // Config check happens in disconnect_peer.
        assert!(should_attempt_holepunch("connection refused"));
        // This test documents that should_attempt_holepunch is reason-only.
    }

    #[test]
    fn holepunch_not_triggered_on_ban() {
        assert!(!should_attempt_holepunch("peer banned"));
        assert!(!should_attempt_holepunch("banned for bad data"));
    }

    // -- M116: CachedFileInfo tests --

    /// Helper to build a minimal `TorrentMetaV1` with multi-file entries.
    fn make_multi_file_meta(files: &[(u64, &str)], piece_length: u64) -> TorrentMetaV1 {
        let total_length: u64 = files.iter().map(|(len, _)| *len).sum();
        let num_pieces = total_length.div_ceil(piece_length) as usize;
        let file_entries: Vec<irontide_core::FileEntry> = files
            .iter()
            .map(|(length, name)| irontide_core::FileEntry {
                length: *length,
                path: vec![name.to_string()],
                attr: None,
                mtime: None,
                symlink_path: None,
            })
            .collect();
        TorrentMetaV1 {
            info_hash: Id20([0u8; 20]),
            announce: None,
            announce_list: None,
            comment: None,
            created_by: None,
            creation_date: None,
            info: irontide_core::InfoDict {
                name: "test".to_string(),
                piece_length,
                pieces: vec![0u8; num_pieces * 20],
                length: None,
                files: Some(file_entries),
                private: None,
                source: None,
                ssl_cert: None,
                similar: Vec::new(),
                collections: Vec::new(),
            },
            url_list: Vec::new(),
            httpseeds: Vec::new(),
            info_bytes: None,
            ssl_cert: None,
        }
    }

    #[test]
    fn cached_files_populated_on_registration() {
        // 3 files: 100, 200, 50 bytes; piece_length = 100
        // Total = 350 bytes, 4 pieces (0..3)
        // File 0: offset 0..100  -> pieces [0, 0]
        // File 1: offset 100..300 -> pieces [1, 2]
        // File 2: offset 300..350 -> pieces [3, 3]
        let meta = make_multi_file_meta(&[(100, "a.txt"), (200, "b.txt"), (50, "c.txt")], 100);
        let lengths = Lengths::new(350, 100, 16384);
        let cached = build_cached_file_info(&meta, &lengths);

        assert_eq!(cached.entries.len(), 3);

        assert_eq!(cached.entries[0].index, 0);
        assert_eq!(cached.entries[0].length, 100);
        assert_eq!(cached.entries[0].first_piece, 0);
        assert_eq!(cached.entries[0].last_piece, 0);

        assert_eq!(cached.entries[1].index, 1);
        assert_eq!(cached.entries[1].length, 200);
        assert_eq!(cached.entries[1].first_piece, 1);
        assert_eq!(cached.entries[1].last_piece, 2);

        assert_eq!(cached.entries[2].index, 2);
        assert_eq!(cached.entries[2].length, 50);
        assert_eq!(cached.entries[2].first_piece, 3);
        assert_eq!(cached.entries[2].last_piece, 3);
    }

    #[test]
    fn cached_files_single_file_torrent() {
        // Single-file torrent: 500 bytes, piece_length = 100
        // 5 pieces (0..4)
        let meta = TorrentMetaV1 {
            info_hash: Id20([0u8; 20]),
            announce: None,
            announce_list: None,
            comment: None,
            created_by: None,
            creation_date: None,
            info: irontide_core::InfoDict {
                name: "single.bin".to_string(),
                piece_length: 100,
                pieces: vec![0u8; 5 * 20],
                length: Some(500),
                files: None,
                private: None,
                source: None,
                ssl_cert: None,
                similar: Vec::new(),
                collections: Vec::new(),
            },
            url_list: Vec::new(),
            httpseeds: Vec::new(),
            info_bytes: None,
            ssl_cert: None,
        };
        let lengths = Lengths::new(500, 100, 16384);
        let cached = build_cached_file_info(&meta, &lengths);

        assert_eq!(cached.entries.len(), 1);
        assert_eq!(cached.entries[0].index, 0);
        assert_eq!(cached.entries[0].length, 500);
        assert_eq!(cached.entries[0].first_piece, 0);
        assert_eq!(cached.entries[0].last_piece, 4);
    }

    // ── M132: Time-based steal-queue population tests ──
    //
    // These tests verify the steal-populate logic that runs in run_steal_queue_maintenance().
    // They build AtomicPieceStates and StealCandidates directly and exercise the
    // same scan loop used by the real implementation.

    use crate::piece_reservation::{AtomicPieceStates, PieceState, StealCandidates};
    use irontide_storage::Bitfield;

    /// Helper: run the steal-populate scan (mirrors `run_steal_queue_maintenance`).
    ///
    /// Returns the number of pieces pushed into the steal queue.
    fn steal_populate_scan(states: &AtomicPieceStates, sc: &StealCandidates) -> u32 {
        let mut pushed = 0u32;
        let num = states.len();
        for piece in 0..num {
            let state = states.get(piece);
            if state == PieceState::Reserved {
                sc.push(piece);
                pushed = pushed.saturating_add(1);
            }
        }
        pushed
    }

    fn all_wanted(n: u32) -> Bitfield {
        let mut bf = Bitfield::new(n);
        for i in 0..n {
            bf.set(i);
        }
        bf
    }

    #[test]
    fn steal_populate_pushes_reserved_pieces() {
        let n = 10;
        let states = AtomicPieceStates::new(n, &Bitfield::new(n), &all_wanted(n));
        let sc = StealCandidates::new();

        // Reserve pieces 2, 5, 7
        assert!(states.try_reserve(2));
        assert!(states.try_reserve(5));
        assert!(states.try_reserve(7));

        let pushed = steal_populate_scan(&states, &sc);
        assert_eq!(pushed, 3, "should push exactly the 3 reserved pieces");

        // Verify they're in the queue
        let mut popped = Vec::new();
        while let Some(p) = sc.pop() {
            popped.push(p);
        }
        popped.sort_unstable();
        assert_eq!(popped, vec![2, 5, 7]);
    }

    #[test]
    fn steal_populate_skips_non_reserved_states() {
        let n = 8;
        let mut have = Bitfield::new(n);
        have.set(0); // piece 0 = Complete
        let mut wanted = all_wanted(n);
        wanted.clear(1); // piece 1 = Unwanted

        let states = AtomicPieceStates::new(n, &have, &wanted);
        let sc = StealCandidates::new();

        // Reserve piece 3, leave rest as Available/Complete/Unwanted
        assert!(states.try_reserve(3));

        let pushed = steal_populate_scan(&states, &sc);
        assert_eq!(pushed, 1, "only piece 3 (Reserved) should be pushed");

        assert_eq!(sc.pop(), Some(3));
        assert_eq!(sc.pop(), None);
    }

    #[test]
    fn steal_populate_deduplicates() {
        let n = 4;
        let states = AtomicPieceStates::new(n, &Bitfield::new(n), &all_wanted(n));
        let sc = StealCandidates::new();

        assert!(states.try_reserve(1));
        assert!(states.try_reserve(2));

        // First scan pushes 2 pieces
        let pushed1 = steal_populate_scan(&states, &sc);
        assert_eq!(pushed1, 2);

        // Second scan: StealCandidates.push() deduplicates, so the queue
        // should still contain exactly 2 entries, not 4.
        let pushed2 = steal_populate_scan(&states, &sc);
        assert_eq!(pushed2, 2, "scan still reports 2 reserved pieces");

        let mut count = 0u32;
        while sc.pop().is_some() {
            count = count.saturating_add(1);
        }
        assert_eq!(count, 2, "dedup means only 2 entries despite 2 scans");
    }

    #[test]
    fn steal_populate_skips_completed_pieces() {
        let n = 5;
        let states = AtomicPieceStates::new(n, &Bitfield::new(n), &all_wanted(n));
        let sc = StealCandidates::new();

        // Reserve all 5 pieces
        for i in 0..n {
            assert!(states.try_reserve(i));
        }

        // Complete pieces 1 and 3 before the scan
        states.mark_complete(1);
        states.mark_complete(3);

        let pushed = steal_populate_scan(&states, &sc);
        assert_eq!(pushed, 3, "3 pieces still Reserved (0, 2, 4)");

        let mut popped = Vec::new();
        while let Some(p) = sc.pop() {
            popped.push(p);
        }
        popped.sort_unstable();
        assert_eq!(popped, vec![0, 2, 4]);
    }

    #[test]
    fn steal_populate_empty_when_no_reserved() {
        let n = 6;
        let states = AtomicPieceStates::new(n, &Bitfield::new(n), &all_wanted(n));
        let sc = StealCandidates::new();

        // No pieces reserved — scan should push nothing
        let pushed = steal_populate_scan(&states, &sc);
        assert_eq!(pushed, 0);
        assert_eq!(sc.pop(), None);
    }

    #[test]
    fn steal_populate_with_endgame_pieces() {
        // Endgame pieces (state = Endgame) should NOT be pushed — only Reserved.
        let n = 4;
        let states = AtomicPieceStates::new(n, &Bitfield::new(n), &all_wanted(n));
        let sc = StealCandidates::new();

        assert!(states.try_reserve(0));
        assert!(states.try_reserve(1));
        states.transition_to_endgame(1);

        let pushed = steal_populate_scan(&states, &sc);
        assert_eq!(
            pushed, 1,
            "only piece 0 (Reserved) should be pushed, not piece 1 (Endgame)"
        );
        assert_eq!(sc.pop(), Some(0));
        assert_eq!(sc.pop(), None);
    }

    // -------------------------------------------------------------------
    // F8: Piece state sync on file priority change
    // -------------------------------------------------------------------

    #[test]
    fn sync_piece_states_marks_unwanted_on_skip() {
        let n = 8;
        let mut wanted = all_wanted(n);
        wanted.clear(2);
        wanted.clear(3);
        let states = AtomicPieceStates::new(n, &Bitfield::new(n), &all_wanted(n));
        // Simulate: wanted_pieces was rebuilt but atomic_states not yet synced.
        // Pieces 2 and 3 are Available but no longer wanted.
        assert_eq!(states.get(2), PieceState::Available);
        assert_eq!(states.get(3), PieceState::Available);

        // Run the sync logic directly.
        for piece in 0..n {
            let w = wanted.get(piece);
            let current = states.get(piece);
            if !w && current == PieceState::Available {
                states.mark_unwanted(piece);
            } else if w && current == PieceState::Unwanted {
                states.mark_available(piece);
            }
        }

        assert_eq!(states.get(0), PieceState::Available);
        assert_eq!(states.get(2), PieceState::Unwanted);
        assert_eq!(states.get(3), PieceState::Unwanted);
        assert_eq!(states.get(4), PieceState::Available);
    }

    #[test]
    fn sync_piece_states_restores_available_on_unskip() {
        let n = 6;
        let mut initial_wanted = all_wanted(n);
        initial_wanted.clear(1);
        initial_wanted.clear(4);
        let states = AtomicPieceStates::new(n, &Bitfield::new(n), &initial_wanted);
        assert_eq!(states.get(1), PieceState::Unwanted);
        assert_eq!(states.get(4), PieceState::Unwanted);

        // Now re-enable all pieces (simulate setting back to Normal).
        let new_wanted = all_wanted(n);
        for piece in 0..n {
            let w = new_wanted.get(piece);
            let current = states.get(piece);
            if !w && current == PieceState::Available {
                states.mark_unwanted(piece);
            } else if w && current == PieceState::Unwanted {
                states.mark_available(piece);
            }
        }

        assert_eq!(states.get(1), PieceState::Available);
        assert_eq!(states.get(4), PieceState::Available);
    }

    #[test]
    fn sync_piece_states_shared_piece_stays_available() {
        // A piece spanning a skipped and non-skipped file stays wanted
        // (build_wanted_pieces marks it wanted if any spanning file is
        // non-skip). Verify the sync leaves it Available.
        let n = 4;
        let mut wanted = all_wanted(n);
        wanted.clear(0); // exclusive to skipped file
        // Piece 1 is shared — stays wanted
        let states = AtomicPieceStates::new(n, &Bitfield::new(n), &all_wanted(n));

        for piece in 0..n {
            let w = wanted.get(piece);
            let current = states.get(piece);
            if !w && current == PieceState::Available {
                states.mark_unwanted(piece);
            } else if w && current == PieceState::Unwanted {
                states.mark_available(piece);
            }
        }

        assert_eq!(states.get(0), PieceState::Unwanted);
        assert_eq!(
            states.get(1),
            PieceState::Available,
            "shared piece stays Available"
        );
        assert_eq!(states.get(2), PieceState::Available);
        assert_eq!(states.get(3), PieceState::Available);
    }

    // -------------------------------------------------------------------
    // M133: DHT re-query tests
    // -------------------------------------------------------------------

    /// Verify the DHT re-query guard scales with `max_peers` config.
    ///
    /// The guard threshold is `max_peers * 4`. With default `max_peers = 128`,
    /// this becomes 512 (close to the old hardcoded 500).
    #[test]
    fn dht_requery_guard_scales_with_max_peers() {
        // max_peers = 128 → threshold = 512
        assert_eq!(128_usize.saturating_mul(4), 512);

        // max_peers = 200 → threshold = 800
        assert_eq!(200_usize.saturating_mul(4), 800);

        // max_peers = 50 → threshold = 200
        assert_eq!(50_usize.saturating_mul(4), 200);

        // Overflow protection: saturating_mul handles usize::MAX
        assert_eq!(usize::MAX.saturating_mul(4), usize::MAX);
    }

    // ---- M147: Pre-resolved metadata tests ----

    /// Build a raw bencoded info dict and its SHA1 hash (for magnet link testing).
    fn make_test_info_bytes() -> (Vec<u8>, Id20) {
        use serde::Serialize;

        #[derive(Serialize)]
        struct Info<'a> {
            length: u64,
            name: &'a str,
            #[serde(rename = "piece length")]
            piece_length: u64,
            #[serde(with = "serde_bytes")]
            pieces: &'a [u8],
        }

        let data = vec![0xAB; 1024];
        let piece_hash = irontide_core::sha1(&data);
        let mut pieces = Vec::new();
        pieces.extend_from_slice(piece_hash.as_bytes());

        let info = Info {
            length: 1024,
            name: "test",
            piece_length: 16384,
            pieces: &pieces,
        };

        let info_bytes = irontide_bencode::to_bytes(&info).unwrap();
        let info_hash = irontide_core::sha1(&info_bytes);
        (info_bytes, info_hash)
    }

    /// Create a magnet-based `TorrentHandle` for testing `PreResolvedMetadata`.
    async fn create_magnet_handle(info_hash: Id20) -> TorrentHandle {
        let magnet = Magnet {
            info_hashes: irontide_core::InfoHashes::v1_only(info_hash),
            display_name: Some("test".into()),
            trackers: vec![],
            peers: vec![],
            selected_files: None,
        };
        let config = test_config();
        let (atx, amask) = test_alert_channel();
        let (dm, _dj) = test_disk_manager();
        TorrentHandle::from_magnet(
            magnet,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None,
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap()
    }

    #[tokio::test]
    async fn pre_resolved_metadata_applies_when_fetching() {
        let (info_bytes, info_hash) = make_test_info_bytes();
        let handle = create_magnet_handle(info_hash).await;

        // Verify we start in FetchingMetadata state.
        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::FetchingMetadata);

        // Send pre-resolved metadata (with a fake peer for pre-seeding).
        let peer_addr: SocketAddr = "127.0.0.1:6881".parse().unwrap();
        handle.send_pre_resolved_metadata(info_bytes, vec![peer_addr]);

        // Give the actor time to process the command.
        tokio::time::sleep(Duration::from_millis(200)).await;

        // Verify transition to Downloading state.
        let stats = handle.stats().await.unwrap();
        assert_eq!(
            stats.state,
            TorrentState::Downloading,
            "should have transitioned to Downloading after pre-resolved metadata"
        );
        assert!(
            stats.pieces_total > 0,
            "should know piece count after metadata resolution"
        );

        handle.shutdown().await.unwrap();
    }

    #[tokio::test]
    async fn pre_resolved_metadata_ignored_after_resolution() {
        // Create a .torrent-based handle (already in Downloading state).
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None,
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        let stats_before = handle.stats().await.unwrap();
        assert_eq!(stats_before.state, TorrentState::Downloading);

        // Send pre-resolved metadata — should be silently ignored since
        // the actor is already past FetchingMetadata.
        let (info_bytes, _) = make_test_info_bytes();
        handle.send_pre_resolved_metadata(info_bytes, vec![]);

        // Give the actor time to process (or ignore) the command.
        tokio::time::sleep(Duration::from_millis(100)).await;

        // Verify state hasn't changed and no crash occurred.
        let stats_after = handle.stats().await.unwrap();
        assert_eq!(stats_after.state, TorrentState::Downloading);
        assert_eq!(stats_after.pieces_total, stats_before.pieces_total);

        handle.shutdown().await.unwrap();
    }

    #[tokio::test]
    async fn pre_resolved_metadata_with_invalid_hash_stays_fetching() {
        // Build info bytes with a WRONG info_hash — the SHA1 won't match
        // the magnet link's info_hash, so try_assemble_metadata should
        // fail verification and the actor should stay in FetchingMetadata.
        let (info_bytes, _correct_hash) = make_test_info_bytes();

        // Use a different (wrong) info_hash for the magnet.
        let wrong_hash = Id20::from_hex("0000000000000000000000000000000000000001").unwrap();
        let handle = create_magnet_handle(wrong_hash).await;

        let stats = handle.stats().await.unwrap();
        assert_eq!(stats.state, TorrentState::FetchingMetadata);

        // Send metadata with mismatched hash — should fail verification.
        handle.send_pre_resolved_metadata(info_bytes, vec![]);

        tokio::time::sleep(Duration::from_millis(200)).await;

        // Actor should remain in FetchingMetadata (verification failed).
        let stats = handle.stats().await.unwrap();
        assert_eq!(
            stats.state,
            TorrentState::FetchingMetadata,
            "should stay in FetchingMetadata when info_hash doesn't match"
        );

        handle.shutdown().await.unwrap();
    }

    #[test]
    fn initial_queue_depth_is_128() {
        use crate::peer_shared::INITIAL_QUEUE_DEPTH;
        assert_eq!(INITIAL_QUEUE_DEPTH, 128);
    }

    // ---- M159: seed mode scheduling-suppression integration test ----

    /// End-to-end test that seed mode actually suppresses new block request
    /// dispatch at the wire level.
    ///
    /// 1. Spin up a 2-piece torrent with no downloaded data.
    /// 2. Connect a mock seeder that advertises both pieces.
    /// 3. Wait for the actor to send at least one `Request` (normal dispatch).
    /// 4. Flip `set_seed_mode(true)`.
    /// 5. Observe that a `Cancel` is sent for the pending request, and that
    ///    no additional `Request` messages arrive within 500 ms.
    /// 6. Confirm the stats snapshot reflects `user_seed_mode == true`.
    #[tokio::test]
    #[allow(
        clippy::large_stack_arrays,
        reason = "test data buffer passed directly to make_storage"
    )]
    async fn m159_seed_mode_suppresses_new_requests_on_wire() {
        let data = vec![0xAB; 32768]; // 32 KiB
        let meta = make_test_torrent(&data, 16384); // 2 pieces
        let info_hash = meta.info_hash;
        // Leecher has empty storage — wants both pieces.
        let storage = make_storage(&[0u8; 32768], 16384);

        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let listen_addr = listener.local_addr().unwrap();
        let config = TorrentConfig {
            listen_port: listen_addr.port(),
            ..test_config()
        };
        drop(listener);

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None,
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        tokio::time::sleep(Duration::from_millis(50)).await;

        // Connect a mock seeder to the actor's listener.
        let stream = tokio::net::TcpStream::connect(listen_addr).await.unwrap();
        let (reader, writer) = tokio::io::split(stream);
        let mut writer = writer;
        let mut reader = reader;

        let hs = Handshake::new(
            info_hash,
            Id20::from_hex("dddddddddddddddddddddddddddddddddddddddd").unwrap(),
        );
        writer.write_all(&hs.to_bytes()).await.unwrap();
        writer.flush().await.unwrap();
        let mut hs_buf = [0u8; HANDSHAKE_SIZE];
        reader.read_exact(&mut hs_buf).await.unwrap();

        let mut framed_read = FramedRead::new(reader, MessageCodec::new());
        let mut framed_write = FramedWrite::new(writer, MessageCodec::new());

        // Drain the actor's ext handshake, then send ours.
        let _actor_ext_hs = framed_read.next().await;
        let ext_hs = ExtHandshake::new();
        let ext_payload = ext_hs.to_bytes().unwrap();
        framed_write
            .send(Message::Extended {
                ext_id: 0,
                payload: ext_payload,
            })
            .await
            .unwrap();

        // Announce that we (the mock seeder) have both pieces.
        let mut bf = Bitfield::new(2);
        bf.set(0);
        bf.set(1);
        framed_write
            .send(Message::Bitfield(Bytes::copy_from_slice(bf.as_bytes())))
            .await
            .unwrap();
        framed_write.send(Message::Unchoke).await.unwrap();

        // Wait for the actor to send its first Request (and any adjacent ones
        // inside one select tick). This confirms the normal dispatch path is
        // engaged before we flip into seed mode.
        let mut initial_request_seen = false;
        let wait_deadline = tokio::time::Instant::now() + Duration::from_secs(3);
        loop {
            let remaining = wait_deadline.saturating_duration_since(tokio::time::Instant::now());
            if remaining.is_zero() {
                break;
            }
            match tokio::time::timeout(remaining, framed_read.next()).await {
                Ok(Some(Ok(Message::Request { .. }))) => {
                    initial_request_seen = true;
                    break;
                }
                Ok(Some(Ok(_))) => {}
                _ => break,
            }
        }
        assert!(
            initial_request_seen,
            "actor should have sent a Request before seed mode toggle"
        );

        // Flip user seed mode on. From this point forward the actor must not
        // dispatch any new Request messages.
        handle.set_seed_mode(true).await.unwrap();

        // There's an inherent race between the actor processing the toggle
        // and the per-peer requester loop receiving its `DispatchCommand::Stop`
        // — a block may already be in the writer's queue when we flip. Drain
        // for a brief grace window, then verify the dispatch has fully halted
        // for a second longer window: if scheduling is truly suppressed, no
        // Request messages will arrive during the steady-state window.
        let grace_deadline = tokio::time::Instant::now() + Duration::from_millis(200);
        let mut cancel_seen = false;
        let mut grace_requests = 0u32;
        loop {
            let remaining = grace_deadline.saturating_duration_since(tokio::time::Instant::now());
            if remaining.is_zero() {
                break;
            }
            match tokio::time::timeout(remaining, framed_read.next()).await {
                Ok(Some(Ok(Message::Request { .. }))) => {
                    grace_requests += 1;
                }
                Ok(Some(Ok(Message::Cancel { .. }))) => {
                    cancel_seen = true;
                }
                Ok(Some(Ok(_))) => {}
                Ok(None | Some(Err(_))) | Err(_) => break,
            }
        }
        let _ = (cancel_seen, grace_requests);

        // Steady-state window: if the dispatch path is really gated, zero
        // new Request messages must arrive for the next 500 ms.
        let steady_deadline = tokio::time::Instant::now() + Duration::from_millis(500);
        let mut steady_requests = 0u32;
        loop {
            let remaining = steady_deadline.saturating_duration_since(tokio::time::Instant::now());
            if remaining.is_zero() {
                break;
            }
            match tokio::time::timeout(remaining, framed_read.next()).await {
                Ok(Some(Ok(Message::Request { .. }))) => {
                    steady_requests += 1;
                }
                Ok(Some(Ok(_))) => {}
                Ok(None | Some(Err(_))) | Err(_) => break,
            }
        }

        assert_eq!(
            steady_requests, 0,
            "after the Stop propagation grace window, no new Request messages \
             must appear during steady-state while user_seed_mode is active"
        );

        // Stats should reflect the flag.
        let stats = handle.stats().await.unwrap();
        assert!(
            stats.user_seed_mode,
            "stats.user_seed_mode should be true after set_seed_mode(true)"
        );

        handle.shutdown().await.unwrap();
    }

    // ---- M159 Task 1: Wire-level test — uploads continue in seed mode ----
    //
    // The point of user seed mode is to stop *downloading* (suppress new
    // block requests we issue to peers) while still *uploading* (honouring
    // incoming `Request` messages from peers who want pieces we have).
    // The companion test `m159_seed_mode_suppresses_new_requests_on_wire`
    // covers the download-suppression half; this one closes the loop by
    // asserting that the upload path survives a seed-mode toggle.
    //
    // Test shape:
    //   1. Pre-seed storage with two verified pieces (actor starts in
    //      `Seeding` state because `make_seeded_storage` writes the full
    //      dataset before the actor runs initial verification).
    //   2. Flip `user_seed_mode` on via `set_seed_mode(true)`. This is the
    //      load-bearing step — uploads must still work *after* seed mode
    //      is enabled.
    //   3. Connect a fake leecher via a real `TcpListener`, complete the
    //      BT + extended handshake.
    //   4. Announce an empty bitfield and send `Interested`. The choker
    //      still runs in seed mode, so the actor must respond with
    //      `Unchoke` (seed-mode choking algorithms unchoke interested
    //      peers based on upload throughput — a brand-new peer that just
    //      sent Interested is a valid candidate).
    //   5. Send `Request { index: 0, begin: 0, length: 16384 }` and assert
    //      a matching `Piece` message arrives on the wire within 2s, with
    //      a payload of the correct length and filled with the pre-seeded
    //      byte pattern.
    #[tokio::test]
    async fn m159_seed_mode_uploads_continue_on_wire() {
        const FILL_BYTE: u8 = 0x5A;
        const PIECE_LENGTH: u64 = 16384;
        const TOTAL_LEN: usize = 32768; // 2 pieces

        let data = vec![FILL_BYTE; TOTAL_LEN];
        let meta = make_test_torrent(&data, PIECE_LENGTH);
        let info_hash = meta.info_hash;
        // Pre-seeded storage — actor transitions to Seeding after verify.
        let storage = make_seeded_storage(&data, PIECE_LENGTH);

        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let listen_addr = listener.local_addr().unwrap();
        let config = TorrentConfig {
            listen_port: listen_addr.port(),
            ..test_config()
        };
        drop(listener);

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None,
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        // Wait for initial verification to complete so the actor is really
        // in Seeding state before we flip seed mode. Poll stats up to 3s.
        let seeding_deadline = tokio::time::Instant::now() + Duration::from_secs(3);
        loop {
            tokio::time::sleep(Duration::from_millis(50)).await;
            let stats = handle.stats().await.unwrap();
            if stats.state == TorrentState::Seeding && stats.pieces_have == 2 {
                break;
            }
            if tokio::time::Instant::now() > seeding_deadline {
                let stats = handle.stats().await.unwrap();
                panic!(
                    "actor did not reach Seeding state within 3s: state={:?}, have={}/{}",
                    stats.state, stats.pieces_have, stats.pieces_total
                );
            }
        }

        // Flip user seed mode on. The upload path must continue to serve
        // incoming Request messages from this point forward.
        handle.set_seed_mode(true).await.unwrap();
        let stats = handle.stats().await.unwrap();
        assert!(
            stats.user_seed_mode,
            "stats.user_seed_mode should be true after set_seed_mode(true)"
        );

        // Connect a mock leecher to the actor's listener.
        let stream = tokio::net::TcpStream::connect(listen_addr).await.unwrap();
        let (reader, writer) = tokio::io::split(stream);
        let mut writer = writer;
        let mut reader = reader;

        let hs = Handshake::new(
            info_hash,
            Id20::from_hex("eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee").unwrap(),
        );
        writer.write_all(&hs.to_bytes()).await.unwrap();
        writer.flush().await.unwrap();
        let mut hs_buf = [0u8; HANDSHAKE_SIZE];
        reader.read_exact(&mut hs_buf).await.unwrap();

        let mut framed_read = FramedRead::new(reader, MessageCodec::new());
        let mut framed_write = FramedWrite::new(writer, MessageCodec::new());

        // Drain the actor's ext handshake, then send ours.
        let _actor_ext_hs = framed_read.next().await;
        let ext_hs = ExtHandshake::new();
        let ext_payload = ext_hs.to_bytes().unwrap();
        framed_write
            .send(Message::Extended {
                ext_id: 0,
                payload: ext_payload,
            })
            .await
            .unwrap();

        // Tell the actor we (the mock leecher) have nothing.
        let bf = Bitfield::new(2);
        framed_write
            .send(Message::Bitfield(Bytes::copy_from_slice(bf.as_bytes())))
            .await
            .unwrap();
        framed_write.send(Message::Interested).await.unwrap();

        // Wait for Unchoke from the actor. The actor may also send its own
        // Bitfield/Have/Extended/Choke/etc.; we drain non-Unchoke messages
        // until we see it (or time out).
        let unchoke_deadline = tokio::time::Instant::now() + Duration::from_secs(3);
        let mut saw_unchoke = false;
        loop {
            let remaining = unchoke_deadline.saturating_duration_since(tokio::time::Instant::now());
            if remaining.is_zero() {
                break;
            }
            match tokio::time::timeout(remaining, framed_read.next()).await {
                Ok(Some(Ok(Message::Unchoke))) => {
                    saw_unchoke = true;
                    break;
                }
                Ok(Some(Ok(_))) => {}
                Ok(None | Some(Err(_))) => break,
                Err(_elapsed) => break,
            }
        }
        assert!(
            saw_unchoke,
            "actor should have unchoked the leecher while user_seed_mode is active"
        );

        // Request piece 0, full 16 KiB block. The actor is seeding with
        // seed mode on — it must still serve this upload.
        framed_write
            .send(Message::Request {
                index: 0,
                begin: 0,
                length: PIECE_LENGTH as u32,
            })
            .await
            .unwrap();

        // Expect a Piece message to arrive on the wire with matching
        // index/begin and the correct payload. Drain any other messages
        // (Have, Bitfield updates, Choke refreshes, etc.) that may arrive
        // first.
        let piece_deadline = tokio::time::Instant::now() + Duration::from_secs(2);
        let mut got_piece = false;
        loop {
            let remaining = piece_deadline.saturating_duration_since(tokio::time::Instant::now());
            if remaining.is_zero() {
                break;
            }
            match tokio::time::timeout(remaining, framed_read.next()).await {
                Ok(Some(Ok(Message::Piece {
                    index,
                    begin,
                    data_0,
                    data_1,
                }))) => {
                    assert_eq!(index, 0, "Piece index should match request");
                    assert_eq!(begin, 0, "Piece begin should match request");
                    let mut payload: Vec<u8> =
                        Vec::with_capacity(data_0.len().saturating_add(data_1.len()));
                    payload.extend_from_slice(&data_0);
                    payload.extend_from_slice(&data_1);
                    assert_eq!(
                        payload.len(),
                        PIECE_LENGTH as usize,
                        "Piece payload length should match requested length"
                    );
                    assert!(
                        payload.iter().all(|&b| b == FILL_BYTE),
                        "Piece payload should contain the pre-seeded fill byte"
                    );
                    got_piece = true;
                    break;
                }
                Ok(Some(Ok(_))) => {}
                Ok(None | Some(Err(_))) => break,
                Err(_elapsed) => break,
            }
        }
        assert!(
            got_piece,
            "actor should have served a Piece in response to Request while user_seed_mode is active"
        );

        // Stats should still reflect the seed-mode flag and accumulated
        // upload bytes for the one block we served.
        let stats = handle.stats().await.unwrap();
        assert!(
            stats.user_seed_mode,
            "stats.user_seed_mode should remain true after serving an upload"
        );
        assert!(
            stats.uploaded >= u64::from(PIECE_LENGTH as u32),
            "stats.uploaded should reflect the served block, got {}",
            stats.uploaded
        );

        handle.shutdown().await.unwrap();
    }

    // ---- M161: info dict, v2 hash, and timestamp tests ----

    #[tokio::test]
    async fn info_field_populated_for_torrent() {
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None,
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        tokio::time::sleep(Duration::from_millis(50)).await;

        let rd = handle.save_resume_data().await.unwrap();

        // info field must be populated when metadata is available
        assert!(rd.info.is_some(), "rd.info should be Some for .torrent");

        // The embedded bytes must deserialize back to a valid InfoDict
        let info_bytes = rd.info.as_ref().unwrap();
        let info: irontide_core::InfoDict =
            irontide_bencode::from_bytes(info_bytes).expect("info bytes should deserialize");
        assert_eq!(info.name, "test");
        assert_eq!(info.piece_length, 16384);

        handle.shutdown().await.unwrap();
    }

    #[tokio::test]
    async fn info_hash2_none_for_v1_only() {
        let data = vec![0xCD; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dh, dm, _dj) = test_register_disk(meta.info_hash, storage).await;
        let handle = TorrentHandle::from_torrent(
            meta,
            irontide_core::TorrentVersion::V1Only,
            None,
            dh,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None,
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        tokio::time::sleep(Duration::from_millis(50)).await;

        let rd = handle.save_resume_data().await.unwrap();

        // v1-only torrent must not have a v2 hash
        assert!(
            rd.info_hash2.is_none(),
            "v1-only torrent should have info_hash2 = None"
        );

        // Timestamps should be populated
        assert!(
            rd.added_time > 0,
            "added_time should be a positive POSIX timestamp"
        );

        handle.shutdown().await.unwrap();
    }

    #[tokio::test]
    async fn info_none_for_unresolved_magnet() {
        let magnet = Magnet {
            info_hashes: irontide_core::InfoHashes::v1_only(
                Id20::from_hex("aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d").unwrap(),
            ),
            display_name: Some("magnet-test".into()),
            trackers: vec![],
            peers: vec![],
            selected_files: None,
        };
        let config = test_config();

        let (atx, amask) = test_alert_channel();
        let (dm, _dj) = test_disk_manager();
        let handle = TorrentHandle::from_magnet(
            magnet,
            dm,
            config,
            test_dht_rx(),
            test_dht_rx(),
            None,
            None,
            crate::slot_tuner::SlotTuner::disabled(4),
            atx,
            amask,
            None,
            None,
            test_ban_manager(),
            test_ip_filter(),
            Arc::new(Vec::new()),
            None,
            None,
            Arc::new(crate::transport::NetworkFactory::tokio()),
            None,
            Arc::new(crate::stats::SessionCounters::new()),
        )
        .await
        .unwrap();

        tokio::time::sleep(Duration::from_millis(50)).await;

        let rd = handle.save_resume_data().await.unwrap();

        // Unresolved magnet has no metadata, so info must be None
        assert!(
            rd.info.is_none(),
            "unresolved magnet should have info = None"
        );

        // added_time should still be set even for magnets
        assert!(
            rd.added_time > 0,
            "added_time should be set for magnet links"
        );

        handle.shutdown().await.unwrap();
    }

    // ---- v0.173.1: TorrentCommand::GetMeta tests (Class A architectural fix) ----

    #[tokio::test]
    async fn torrent_command_get_meta_returns_none_before_metadata() {
        // v0.173.1: pre-metadata magnet handles must return None from GetMeta.
        let info_hash =
            Id20::from_hex("aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d").expect("valid hex");
        let handle = create_magnet_handle(info_hash).await;

        let (tx, rx) = oneshot::channel();
        handle
            .cmd_tx
            .send(TorrentCommand::GetMeta { reply: tx })
            .await
            .expect("cmd_tx send");
        let result = rx.await.expect("GetMeta reply");
        assert!(
            result.is_none(),
            "pre-metadata magnet must return None from GetMeta"
        );

        handle.shutdown().await.unwrap();
    }

    #[tokio::test]
    async fn torrent_command_get_meta_returns_some_after_metadata() {
        // v0.173.1: once metadata is assembled (via PreResolvedMetadata push),
        // GetMeta must return Some(meta) with the matching info hash.
        let (info_bytes, info_hash) = make_test_info_bytes();
        let handle = create_magnet_handle(info_hash).await;

        handle.send_pre_resolved_metadata(info_bytes, vec![]);

        // Poll GetMeta until it returns Some or we exceed a 2s budget — the
        // PreResolvedMetadata command runs through the actor select! loop
        // asynchronously so we can't rely on a hard sleep.
        let mut result = None;
        for _ in 0..100 {
            tokio::time::sleep(Duration::from_millis(20)).await;
            let (tx, rx) = oneshot::channel();
            handle
                .cmd_tx
                .send(TorrentCommand::GetMeta { reply: tx })
                .await
                .expect("cmd_tx send");
            let r = rx.await.expect("GetMeta reply");
            if r.is_some() {
                result = r;
                break;
            }
        }
        let meta = result.expect("GetMeta must return Some after PreResolvedMetadata");
        assert_eq!(meta.info_hash, info_hash);

        handle.shutdown().await.unwrap();
    }

    // ── M178 Lane B1: WebSeedStats actor state machine ───────────────

    #[tokio::test]
    async fn web_seed_progress_idle_to_active_on_first_success() {
        let mut actor = TorrentActor::for_throttle_test(8, 0);
        actor.handle_web_seed_progress("http://seed.example/file", 1024, 1_000_000, None);
        let stats = actor
            .web_seed_stats
            .get("http://seed.example/file")
            .expect("stats inserted");
        assert_eq!(stats.state, irontide_core::WebSeedState::Active);
        assert_eq!(stats.downloaded_bytes, 1024);
        assert_eq!(stats.last_rate_bps, 1_000_000);
        assert_eq!(stats.consecutive_failures, 0);
        assert!(stats.last_attempt_unix_secs > 0);
        assert!(actor.need_save_resume);
    }

    #[tokio::test]
    async fn web_seed_progress_active_to_errored_then_recovery_persists_last_error() {
        let mut actor = TorrentActor::for_throttle_test(8, 0);
        let url = "http://seed.example/file".to_string();

        // 1) Initial success → Active
        actor.handle_web_seed_progress(&url, 1024, 100, None);
        assert_eq!(
            actor.web_seed_stats[&url].state,
            irontide_core::WebSeedState::Active
        );

        // 2) Failure → Errored, last_error populated
        actor.handle_web_seed_progress(&url, 1024, 0, Some("503".into()));
        let stats = &actor.web_seed_stats[&url];
        assert_eq!(stats.state, irontide_core::WebSeedState::Errored);
        assert_eq!(stats.last_error.as_deref(), Some("503"));
        assert_eq!(stats.consecutive_failures, 1);

        // 3) Recovery → Active, but last_error PERSISTS (Issue 2.2)
        actor.handle_web_seed_progress(&url, 2048, 200, None);
        let stats = &actor.web_seed_stats[&url];
        assert_eq!(stats.state, irontide_core::WebSeedState::Active);
        assert_eq!(
            stats.last_error.as_deref(),
            Some("503"),
            "last_error must persist through recovery (D-eng-8)"
        );
        assert_eq!(
            stats.consecutive_failures, 0,
            "consecutive_failures resets on success"
        );
    }

    #[tokio::test]
    async fn web_seed_progress_consecutive_failures_monotonic_within_run() {
        let mut actor = TorrentActor::for_throttle_test(8, 0);
        let url = "http://seed.example/file".to_string();

        actor.handle_web_seed_progress(&url, 0, 0, Some("e1".into()));
        actor.handle_web_seed_progress(&url, 0, 0, Some("e2".into()));
        actor.handle_web_seed_progress(&url, 0, 0, Some("e3".into()));
        let stats = &actor.web_seed_stats[&url];
        assert_eq!(stats.consecutive_failures, 3);
        assert_eq!(
            stats.last_error.as_deref(),
            Some("e3"),
            "last_error reflects most recent message"
        );

        actor.handle_web_seed_progress(&url, 1024, 100, None);
        assert_eq!(
            actor.web_seed_stats[&url].consecutive_failures, 0,
            "success resets consecutive_failures"
        );
    }

    // ── M178 Lane B3: PeX + LSD peer counters ────────────────────────

    /// Inject a `PeerStates` into a synthetic actor so `handle_add_peers`
    /// can run without spinning up the full peer pipeline.
    fn install_peer_states(actor: &mut TorrentActor) {
        let (queue_tx, _queue_rx) = mpsc::unbounded_channel();
        actor.peer_states = Some(std::sync::Arc::new(crate::peer_states::PeerStates::new(
            queue_tx,
        )));
    }

    fn addr(octet: u8, port: u16) -> std::net::SocketAddr {
        std::net::SocketAddr::new(
            std::net::IpAddr::V4(std::net::Ipv4Addr::new(192, 0, 2, octet)),
            port,
        )
    }

    #[tokio::test]
    async fn pex_count_dedups_same_peer_in_two_messages() {
        let mut actor = TorrentActor::for_throttle_test(8, 0);
        install_peer_states(&mut actor);

        // Message 1: peers A and B
        actor.handle_add_peers(
            vec![addr(1, 6881), addr(2, 6881)],
            crate::peer_state::PeerSource::Pex,
        );
        // Message 2: peer A again, plus C
        actor.handle_add_peers(
            vec![addr(1, 6881), addr(3, 6881)],
            crate::peer_state::PeerSource::Pex,
        );
        assert_eq!(
            actor.pex_peer_count, 3,
            "3 unique peers across 2 PEX messages, A counted once"
        );
        assert_eq!(actor.lsd_peer_count, 0, "LSD untouched");
    }

    #[tokio::test]
    async fn lsd_count_aggregates_across_multicasts() {
        let mut actor = TorrentActor::for_throttle_test(8, 0);
        install_peer_states(&mut actor);

        actor.handle_add_peers(vec![addr(1, 6881)], crate::peer_state::PeerSource::Lsd);
        actor.handle_add_peers(
            vec![addr(2, 6881), addr(3, 6881)],
            crate::peer_state::PeerSource::Lsd,
        );
        actor.handle_add_peers(
            vec![addr(1, 6881)], // dup
            crate::peer_state::PeerSource::Lsd,
        );
        assert_eq!(actor.lsd_peer_count, 3);
    }

    #[tokio::test]
    async fn other_sources_do_not_bump_pex_or_lsd() {
        let mut actor = TorrentActor::for_throttle_test(8, 0);
        install_peer_states(&mut actor);

        actor.handle_add_peers(
            vec![addr(1, 6881), addr(2, 6881)],
            crate::peer_state::PeerSource::Tracker,
        );
        actor.handle_add_peers(vec![addr(3, 6881)], crate::peer_state::PeerSource::Dht);
        actor.handle_add_peers(vec![addr(4, 6881)], crate::peer_state::PeerSource::Incoming);
        assert_eq!(actor.pex_peer_count, 0);
        assert_eq!(actor.lsd_peer_count, 0);
    }

    #[tokio::test]
    async fn dedup_runs_against_global_seen_set() {
        // A peer first observed via tracker won't recount when later
        // re-announced via PEX, because the seen-set is shared across
        // sources. This is the intended behaviour: PEX/LSD counts measure
        // *new* peer discoveries from those subsystems, not redundant
        // re-announcements.
        let mut actor = TorrentActor::for_throttle_test(8, 0);
        install_peer_states(&mut actor);

        actor.handle_add_peers(vec![addr(1, 6881)], crate::peer_state::PeerSource::Tracker);
        actor.handle_add_peers(vec![addr(1, 6881)], crate::peer_state::PeerSource::Pex);
        assert_eq!(
            actor.pex_peer_count, 0,
            "peer already seen via tracker — PEX shouldn't re-count"
        );
    }

    #[tokio::test]
    async fn web_seed_progress_dirties_resume_flag() {
        let mut actor = TorrentActor::for_throttle_test(8, 0);
        actor.need_save_resume = false;
        actor.handle_web_seed_progress("http://x/file", 100, 50, None);
        assert!(
            actor.need_save_resume,
            "every progress event should mark fast-resume dirty"
        );
    }

    #[tokio::test]
    async fn paused_torrent_rejects_outbound_peer_connect() {
        let mut actor = TorrentActor::for_throttle_test(8, 0);
        install_peer_states(&mut actor);
        actor.state = TorrentState::Paused;

        let sem = Arc::new(tokio::sync::Semaphore::new(1));
        let permit = sem.clone().acquire_owned().await.unwrap();
        let connect = crate::peer_adder::ConnectPeer {
            addr: addr(1, 6881),
            source: crate::peer_state::PeerSource::Dht,
            permit,
        };
        actor.handle_adder_connect(connect);
        assert!(
            actor.peers.is_empty(),
            "paused torrent must not accept outbound peer connections"
        );
        assert_eq!(
            sem.available_permits(),
            1,
            "semaphore permit must be released on rejection"
        );
    }

    #[tokio::test]
    async fn resume_from_queued_restores_fetching_metadata_for_magnets() {
        let mut actor = TorrentActor::for_throttle_test(0, 0);
        actor.state = TorrentState::Queued;
        assert!(
            actor.chunk_tracker.is_none(),
            "magnet torrent has no chunk tracker before metadata"
        );
        assert_eq!(actor.num_pieces, 0);

        actor.handle_resume().await;
        assert_eq!(
            actor.state,
            TorrentState::FetchingMetadata,
            "magnet torrent must resume to FetchingMetadata, not Downloading"
        );
    }

    #[tokio::test]
    async fn resume_from_queued_restores_downloading_when_metadata_known() {
        let mut actor = TorrentActor::for_throttle_test(8, 0);
        actor.state = TorrentState::Queued;

        actor.handle_resume().await;
        assert_eq!(
            actor.state,
            TorrentState::Downloading,
            "torrent with known pieces must resume to Downloading"
        );
    }

    #[tokio::test]
    async fn queued_torrent_rejects_outbound_peer_connect() {
        let mut actor = TorrentActor::for_throttle_test(8, 0);
        install_peer_states(&mut actor);
        actor.state = TorrentState::Queued;

        let sem = Arc::new(tokio::sync::Semaphore::new(1));
        let permit = sem.clone().acquire_owned().await.unwrap();
        let connect = crate::peer_adder::ConnectPeer {
            addr: addr(1, 6881),
            source: crate::peer_state::PeerSource::Dht,
            permit,
        };
        actor.handle_adder_connect(connect);
        assert!(
            actor.peers.is_empty(),
            "queued torrent must not accept outbound peer connections"
        );
        assert_eq!(
            sem.available_permits(),
            1,
            "semaphore permit must be released on rejection"
        );
    }

    /// Inject a synthetic `PeerState` directly into `actor.peers` so
    /// `disconnect_peer` exercises the flush path without spinning up
    /// real peer tasks.
    fn inject_peer_for_flush(
        actor: &mut TorrentActor,
        peer_addr: std::net::SocketAddr,
        unchoke_started: Option<std::time::Instant>,
        prior_total: std::time::Duration,
    ) {
        let (cmd_tx, _cmd_rx) = mpsc::channel(8);
        let mut peer = crate::peer_state::PeerState::new(
            peer_addr,
            actor.num_pieces,
            cmd_tx,
            crate::peer_state::PeerSource::Tracker,
            Arc::new(AtomicU32::new(0)),
            Arc::new(AtomicU32::new(128)),
            Arc::new(tokio::sync::Notify::new()),
        );
        peer.am_unchoke_started_at = unchoke_started;
        peer.unchoke_duration_total = prior_total;
        actor.peers.insert(peer_addr, peer);
    }

    #[tokio::test]
    async fn disconnect_while_unchoked_flushes_delta_into_torrent_map() {
        let mut actor = TorrentActor::for_throttle_test(8, 0);
        let p = addr(1, 6881);

        // Seed the peer with an in-flight unchoke window opened ~50 ms ago
        // and a pre-existing 100 ms accumulator from prior toggles.
        inject_peer_for_flush(
            &mut actor,
            p,
            Some(std::time::Instant::now() - std::time::Duration::from_millis(50)),
            std::time::Duration::from_millis(100),
        );

        actor.disconnect_peer(p, "test");

        let total = actor
            .unchoke_durations
            .get(&p)
            .copied()
            .expect("disconnect must flush a non-zero delta into the torrent map");
        assert!(
            total >= std::time::Duration::from_millis(140),
            "expected ≥140 ms (100 prior + ~50 in-flight), got {total:?}"
        );
    }

    #[tokio::test]
    async fn disconnect_then_reconnect_preserves_history() {
        let mut actor = TorrentActor::for_throttle_test(8, 0);
        let p = addr(2, 6881);

        // First connection: 80 ms unchoke window already accumulated.
        inject_peer_for_flush(&mut actor, p, None, std::time::Duration::from_millis(80));
        actor.disconnect_peer(p, "test");
        let after_first = *actor
            .unchoke_durations
            .get(&p)
            .expect("first flush must populate the entry");
        assert_eq!(after_first, std::time::Duration::from_millis(80));

        // Reconnect: peer rejoins with a fresh in-flight window.
        inject_peer_for_flush(
            &mut actor,
            p,
            Some(std::time::Instant::now() - std::time::Duration::from_millis(40)),
            std::time::Duration::ZERO,
        );
        actor.disconnect_peer(p, "test");
        let after_second = *actor.unchoke_durations.get(&p).unwrap();
        assert!(
            after_second >= std::time::Duration::from_millis(120),
            "second flush must add to the existing entry, got {after_second:?}"
        );
    }

    // -- M187 Fix B: piece-verified wakes reservation_notify --

    #[tokio::test]
    async fn piece_verified_wakes_reservation_notify() {
        let mut actor = TorrentActor::for_throttle_test(8, 0);
        let notify = Arc::new(tokio::sync::Notify::new());
        actor.reservation_notify = Some(Arc::clone(&notify));

        let notified = notify.notified();
        tokio::pin!(notified);
        assert!(
            futures::poll!(&mut notified).is_pending(),
            "notify should not have fired yet"
        );

        actor.on_piece_verified(0).await;

        tokio::time::timeout(Duration::from_secs(1), notified)
            .await
            .expect("reservation_notify must be woken by on_piece_verified");
    }

    // -- 2026-05-11 state-gated pipeline-tick safety-net wake --

    /// Helper: construct an actor that already has a `PieceTracker` with the
    /// given (`queue_count`, `inflight_count`). The tracker starts empty and
    /// we mark pieces wanted/reserved as needed to land on the target shape.
    fn actor_with_tracker_state(queue: u32, inflight: u32) -> TorrentActor {
        use crate::piece_reservation::PieceTracker;
        use irontide_storage::Bitfield;
        let mut actor = TorrentActor::for_throttle_test(8, 0);
        let num_pieces = queue + inflight + 1;
        let we_have = Bitfield::new(num_pieces);
        let mut wanted = Bitfield::new(num_pieces);
        for i in 0..num_pieces {
            wanted.set(i);
        }
        let mut pt = PieceTracker::new(num_pieces, &we_have, &wanted);
        // Trim the queue down to `queue` (the rest become "completed" by
        // marking them unwanted, which clears them from queue_pieces).
        for i in queue..num_pieces {
            pt.mark_unwanted(i);
        }
        // Move `inflight` pieces from queue to inflight via record_reservation.
        for i in 0..inflight {
            pt.record_reservation(i, "10.0.0.1:6881".parse().unwrap());
        }
        // After this: queue_count() == queue - inflight, inflight_count() == inflight.
        // We started with `queue` wanted pieces, then reserved `inflight` of
        // them, leaving (queue - inflight) in the queue. Adjust caller-facing
        // semantics so the helper's name matches the assertion.
        actor.piece_tracker = Some(pt);
        actor
    }

    #[tokio::test]
    async fn pipeline_tick_skips_wake_when_dispatch_state_unchanged() {
        let mut actor = actor_with_tracker_state(10, 3);
        let notify = Arc::new(tokio::sync::Notify::new());
        actor.reservation_notify = Some(Arc::clone(&notify));

        // First tick seeds the baseline and always wakes — this matches the
        // helper's documented first-call semantics. Drop the baseline wake
        // by polling once before installing the real test waiter.
        actor.tick_dispatch_safety_wake();
        let _drain = notify.notified();

        // No dispatch state change between this tick and the next.
        let notified = notify.notified();
        tokio::pin!(notified);
        actor.tick_dispatch_safety_wake();

        // Give tokio a chance to dispatch any pending wakes before asserting.
        tokio::task::yield_now().await;
        assert!(
            futures::poll!(&mut notified).is_pending(),
            "tick must not wake when (queue_count, inflight_count) is unchanged"
        );
        // And the skip counter increments.
        let skipped = actor.counters.get(crate::stats::DISPATCH_TICK_WAKE_SKIPPED);
        assert!(
            skipped >= 1,
            "expected DISPATCH_TICK_WAKE_SKIPPED >= 1, got {skipped}"
        );
    }

    #[tokio::test]
    async fn pipeline_tick_wakes_when_inflight_changes() {
        let mut actor = actor_with_tracker_state(10, 3);
        let notify = Arc::new(tokio::sync::Notify::new());
        actor.reservation_notify = Some(Arc::clone(&notify));

        // Seed baseline.
        actor.tick_dispatch_safety_wake();

        // Mutate dispatch state: reserve another piece via the tracker. This
        // changes both queue_count (down 1) and inflight_count (up 1).
        if let Some(ref mut pt) = actor.piece_tracker {
            pt.record_reservation(5, "10.0.0.2:6881".parse().unwrap());
        }

        let notified = notify.notified();
        tokio::pin!(notified);
        actor.tick_dispatch_safety_wake();

        tokio::time::timeout(Duration::from_secs(1), notified)
            .await
            .expect("tick must wake when dispatch state changed");
    }
}