irontide_session/

session.rs

#![allow(
    clippy::cast_possible_truncation,
    clippy::cast_precision_loss,
    clippy::cast_possible_wrap,
    clippy::cast_sign_loss,
    clippy::unchecked_time_subtraction,
    reason = "M175: session-level counters/rates bounded by torrent count; time deltas use post-init Instants"
)]

//! `SessionHandle` / `SessionActor` — multi-torrent session manager.
//!
//! Actor model: `SessionHandle` is the cloneable public API (mpsc sender),
//! `SessionActor` is the single-owner event loop (internal).

use std::collections::HashMap;
use std::net::{IpAddr, SocketAddr};
use std::path::PathBuf;
use std::sync::Arc;
use std::sync::atomic::{AtomicU32, Ordering};

use dashmap::DashMap;
use tokio::sync::{broadcast, mpsc, oneshot};

use tracing::{debug, info, warn};

use irontide_core::{DEFAULT_CHUNK_SIZE, Id20, Lengths, Magnet};
use irontide_dht::DhtHandle;
use irontide_storage::TorrentStorage;

use crate::alert::{Alert, AlertCategory, AlertKind, AlertStream, post_alert};
use crate::settings_convert::SettingsConvertExt;
use crate::torrent::TorrentHandle;
use crate::types::{
    FileInfo, SessionStats, TorrentConfig, TorrentInfo, TorrentState, TorrentStats, TorrentSummary,
};
use irontide_settings::Settings;

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

/// Function signature for queue move operations (`move_up`, `move_down`, etc.).
type QueueMoveFn = fn(&mut [crate::queue::QueueEntry], Id20) -> Vec<(Id20, i32, i32)>;

// SharedBanManager / SharedIpFilter relocated to irontide-session-types at M244a
// (torrent→session back-edge break); imported here for session-local use.
use irontide_session_types::{SharedBanManager, SharedIpFilter};

/// Result of loading resume state from disk (M161 Phase 4).
#[derive(Debug, Clone)]
pub struct ResumeLoadResult {
    /// Number of torrents successfully restored.
    pub restored: usize,
    /// Number of resume files skipped (duplicate, already exists).
    pub skipped: usize,
    /// Number of resume files that failed to load.
    pub failed: usize,
}

/// Source for a torrent add (M170).
///
/// Separated from [`AddTorrentParams`] so that the builder API can name
/// the source independently of the other knobs.
#[derive(Debug, Clone)]
pub enum AddSource {
    /// Magnet URI (BEP 9 metadata fetch required post-add).
    Magnet(String),
    /// Raw `.torrent` file bytes (auto-detects v1/v2/hybrid).
    Bytes(Vec<u8>),
}

/// Unified parameters for [`SessionHandle::add_torrent`] (M170).
///
/// Replaces the ad-hoc set of `add_magnet`, `add_magnet_uri`,
/// `add_torrent_bytes` call shapes with a single params struct. Callers
/// build the struct via the static constructors ([`magnet`] or [`bytes`])
/// and chain `.with_category()` / `.with_tags()` / `.with_download_dir()`
/// / `.paused()`.
///
/// Download-dir resolution (see `add_torrent`):
/// 1. `download_dir: Some(p)` wins, if set.
/// 2. Else, if `category: Some(name)` and the registry contains `name`,
///    the registry's `save_path` is used.
/// 3. Else, if `category: Some(name)` and the registry does NOT contain
///    `name`, the call fails with [`Error::CategoryNotFound`].
/// 4. Else, falls back to `Settings.download_dir`.
///
/// `skip_checking` is reserved for M171+ (qBt `skip_hash_check=true`).
///
/// [`magnet`]: Self::magnet
/// [`bytes`]: Self::bytes
#[derive(Debug, Clone)]
pub struct AddTorrentParams {
    /// The torrent source (magnet URI or raw .torrent bytes).
    pub source: AddSource,
    /// Optional qBt-compat category label resolved via the session's
    /// [`CategoryRegistry`](crate::CategoryRegistry) at add-time.
    pub category: Option<String>,
    /// M171: Per-torrent tags baked in at add time (qBt-compat). Multi-
    /// valued. An empty vec means "no tags" and is the default.
    pub tags: Vec<String>,
    /// Explicit download directory, overrides both category lookup and
    /// `Settings.download_dir` when `Some`.
    pub download_dir: Option<PathBuf>,
    /// Whether the torrent should be added in a paused state. `None` (the
    /// constructor default) means "use [`Settings::default_add_paused`]";
    /// `Some(v)` is an explicit per-call override. The resolution happens
    /// in `dispatch_add_torrent_m170` before the M170 post-add hooks run,
    /// so the actor sees a concrete `bool` either way.
    pub paused: Option<bool>,
    /// Reserved for M171+ — skip the initial re-hash on add.
    pub skip_checking: bool,
}

impl AddTorrentParams {
    /// Build a magnet-source add with default knobs.
    #[must_use]
    pub fn magnet(uri: impl Into<String>) -> Self {
        Self {
            source: AddSource::Magnet(uri.into()),
            category: None,
            tags: Vec::new(),
            download_dir: None,
            paused: None,
            skip_checking: false,
        }
    }

    /// Build a bytes-source add with default knobs.
    #[must_use]
    pub fn bytes(data: impl Into<Vec<u8>>) -> Self {
        Self {
            source: AddSource::Bytes(data.into()),
            category: None,
            tags: Vec::new(),
            download_dir: None,
            paused: None,
            skip_checking: false,
        }
    }

    /// Assign a category label to the torrent. The session resolves the
    /// name against its registry at add-time; unknown names error out.
    #[must_use]
    pub fn with_category(mut self, name: impl Into<String>) -> Self {
        self.category = Some(name.into());
        self
    }

    /// M171: Attach tags at add time. Tags are baked into the torrent's
    /// config before `TorrentActor::new`, so the first `stats()` call
    /// returns them — no post-add spawn race.
    #[must_use]
    pub fn with_tags(mut self, tags: Vec<String>) -> Self {
        self.tags = tags;
        self
    }

    /// Override the download directory for this torrent.
    #[must_use]
    pub fn with_download_dir(mut self, dir: impl Into<PathBuf>) -> Self {
        self.download_dir = Some(dir.into());
        self
    }

    /// Toggle the paused-at-add flag. Wraps the explicit choice in `Some(_)`
    /// so the actor can distinguish "caller explicitly set this" from
    /// "caller did not touch it" (the latter falls back to
    /// [`Settings::default_add_paused`]).
    #[must_use]
    pub fn paused(mut self, paused: bool) -> Self {
        self.paused = Some(paused);
        self
    }

    /// Toggle the skip-initial-check flag (M171+).
    #[must_use]
    pub fn skip_checking(mut self, skip: bool) -> Self {
        self.skip_checking = skip;
        self
    }
}

/// Entry for a torrent managed by the session.
///
/// v0.173.1: the `meta: Option<TorrentMetaV1>` field was deleted. It was a
/// stale cache that was silently `None` forever for magnet-added torrents —
/// see the Class A archaeology in
/// `docs/plans/2026-04-22-irontide-v0.173.1-qbt-v2-bug-sweep.md`. Four reader
/// sites (`handle_torrent_info`, `handle_remove_torrent_with_files`, `is_private`,
/// `handle_ssl_incoming`) now query the `TorrentActor` via `handle.get_meta()`,
/// which is the single source of truth for torrent metadata.
struct TorrentEntry {
    handle: TorrentHandle,
    /// Queue position (-1 = not queued / not auto-managed).
    queue_position: i32,
    /// Whether the queue system controls this torrent.
    auto_managed: bool,
    /// When the torrent was last started/resumed (for startup grace period).
    started_at: Option<tokio::time::Instant>,
    /// EWMA-smoothed download rate for queue inactive classification.
    smoothed_download_rate: f64,
    /// EWMA-smoothed upload rate for queue inactive classification.
    smoothed_upload_rate: f64,
}

/// M223 — off-actor add-torrent result bundle.
///
/// `handle_add_torrent` (and the M170 path) split into two phases:
/// 1. **Prepare** — disk register, actor spawn. Runs in a `tokio::spawn`
///    task off the `SessionActor` recv loop, so concurrent adds do not
///    serialise the actor's per-command queue.
/// 2. **Commit** — mutating fixup on the actor: insert into
///    `self.torrents`, info-hash registry, queue position, alert, LSD
///    announce. Runs on the actor in response to a `CommitAddTorrent`
///    feedback command.
///
/// This bundle is the success-path payload of the prepare phase; the
/// commit phase consumes it and produces the caller-visible `Id20`.
/// `is_private` is precomputed from `meta.info.private` so the commit
/// arm needs no async query to honour BEP 27 (LSD must skip private
/// torrents).
struct PreparedAddTorrent {
    handle: TorrentHandle,
    info_hash: Id20,
    is_private: bool,
    /// M170 post-add hooks (category label + paused-on-add). `None` for
    /// the legacy `AddTorrent` path; `Some` only for the
    /// `AddTorrentM170` path which carries `AddTorrentParams`.
    m170_post: Option<M170PostAdd>,
}

/// M223 — M170 post-add side-effects deferred from the recv arm to the
/// commit arm. Both are applied via `apply_post_add_m170` after the
/// torrent is inserted into `self.torrents`.
struct M170PostAdd {
    category: Option<String>,
    paused: bool,
}

/// M223 — snapshot of session state needed by the off-actor add-torrent
/// prep phase. Built synchronously on the actor at the recv arm via
/// `SessionActor::build_add_torrent_prep_bundle`; consumed by the
/// spawned task that runs the heavy `disk_manager.register_torrent` +
/// `TorrentHandle::from_torrent` work without blocking the actor's
/// command queue.
struct AddTorrentPrepBundle {
    torrent_meta: irontide_core::TorrentMeta,
    storage_override: Option<Arc<dyn TorrentStorage>>,
    torrent_config: TorrentConfig,
    disk_manager: crate::disk::DiskManagerHandle,
    dht_v4_broadcast: irontide_dht::DhtBroadcast,
    dht_v6_broadcast: irontide_dht::DhtBroadcast,
    global_up: Option<SharedBucket>,
    global_down: 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: SharedBanManager,
    ip_filter: 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: std::sync::Arc<crate::hash_pool::HashPool>,
    counters: Arc<crate::stats::SessionCounters>,
    m170_post: Option<M170PostAdd>,
}

impl TorrentEntry {
    /// Returns `true` if this torrent has the private flag set (BEP 27).
    ///
    /// v0.173.1: now queries the `TorrentActor` for current metadata. Magnet
    /// torrents previously silently returned `false` because the session
    /// cache (`TorrentEntry.meta`) was permanently `None` for them — BEP 27
    /// enforcement was bypassed and peer IPs leaked to DHT/LSD. This method
    /// returning `false` pre-metadata is still correct per the plan's
    /// Failure-Modes table: the info dict doesn't exist yet, so the flag
    /// cannot be enforced. Once metadata resolves, subsequent calls see the
    /// real `info.private` value.
    async fn is_private(&self) -> bool {
        match self.handle.get_meta().await {
            Ok(Some(meta)) => meta.info.private == Some(1),
            // Pre-metadata or actor shut down: treat as non-private. A magnet
            // that hasn't resolved yet can't enforce privacy per BEP 27 — the
            // flag lives in the info dict, which doesn't exist yet.
            _ => false,
        }
    }
}

/// Commands sent from `SessionHandle` to `SessionActor`.
enum SessionCommand {
    AddTorrent {
        meta: Box<irontide_core::TorrentMeta>,
        storage: Option<Arc<dyn TorrentStorage>>,
        download_dir: Option<PathBuf>,
        reply: oneshot::Sender<crate::Result<Id20>>,
    },
    /// M223 — internal feedback variant. Carries the result of off-actor
    /// `handle_add_torrent` work (TCP bind + disk register + actor spawn)
    /// back to the actor's recv loop for the mutating fixup
    /// (insert into `self.torrents` + queue position + alert + LSD).
    /// Decouples the actor recv loop from per-add latency so the
    /// parallel-7 POST tail does not stack linearly with already-added
    /// torrents. Not part of the public `SessionHandle` API — only
    /// `add_torrent_via_spawn` (the recv-arm helper) emits this variant.
    CommitAddTorrent {
        result: crate::Result<PreparedAddTorrent>,
        reply: oneshot::Sender<crate::Result<Id20>>,
    },
    AddMagnet {
        magnet: Magnet,
        download_dir: Option<PathBuf>,
        reply: oneshot::Sender<crate::Result<Id20>>,
    },
    RemoveTorrent {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    PauseTorrent {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    ResumeTorrent {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    ForceResumeTorrent {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    SetTorrentSeedRatio {
        info_hash: Id20,
        limit: Option<f64>,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    TorrentStats {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<TorrentStats>>,
    },
    TorrentInfo {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<TorrentInfo>>,
    },
    ListTorrents {
        reply: oneshot::Sender<Vec<Id20>>,
    },
    SessionStats {
        reply: oneshot::Sender<SessionStats>,
    },
    SaveTorrentResumeData {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<irontide_core::FastResumeData>>,
    },
    SaveSessionState {
        reply: oneshot::Sender<crate::Result<crate::persistence::SessionState>>,
    },
    /// Load and restore torrents from per-torrent resume files on disk (M161).
    LoadResumeState {
        reply: oneshot::Sender<crate::Result<ResumeLoadResult>>,
    },
    QueuePosition {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<i32>>,
    },
    SetQueuePosition {
        info_hash: Id20,
        pos: i32,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    QueuePositionUp {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    QueuePositionDown {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    QueuePositionTop {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    QueuePositionBottom {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    BanPeer {
        ip: IpAddr,
        reply: oneshot::Sender<()>,
    },
    UnbanPeer {
        ip: IpAddr,
        reply: oneshot::Sender<bool>,
    },
    BannedPeers {
        reply: oneshot::Sender<Vec<IpAddr>>,
    },
    SetIpFilter {
        filter: crate::ip_filter::IpFilter,
        reply: oneshot::Sender<()>,
    },
    GetIpFilter {
        reply: oneshot::Sender<crate::ip_filter::IpFilter>,
    },
    GetSettings {
        reply: oneshot::Sender<Settings>,
    },
    ApplySettings {
        settings: Box<Settings>,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    MoveTorrentStorage {
        info_hash: Id20,
        new_path: std::path::PathBuf,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    AddPeers {
        info_hash: Id20,
        peers: Vec<SocketAddr>,
        source: crate::peer_state::PeerSource,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    OpenFile {
        info_hash: Id20,
        file_index: usize,
        reply: oneshot::Sender<crate::Result<crate::streaming::FileStream>>,
    },
    ForceReannounce {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    TrackerList {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<Vec<crate::tracker_manager::TrackerInfo>>>,
    },
    /// M178 Lane B3 / TODO-2: `(pex_peer_count, lsd_peer_count)` for the
    /// given torrent. Used by qBt v2 trackers endpoint + GUI Trackers tab
    /// to populate the PeX/LSD pseudo-tracker rows with real counts.
    GetPeerSourceCounts {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<(usize, usize)>>,
    },
    /// Per-peer cumulative unchoke duration for a torrent. `None` reply
    /// when the torrent does not exist (explicit contract — distinguishes
    /// "torrent missing" from "torrent exists with empty map").
    QueryUnchokeDurations {
        info_hash: Id20,
        reply: oneshot::Sender<Option<std::collections::HashMap<SocketAddr, std::time::Duration>>>,
    },
    /// M178 Lane C: per-URL web-seed stats for the qBt v2 webseeds endpoint
    /// and the GUI HTTP Sources tab.
    GetWebSeedStats {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<Vec<irontide_core::WebSeedStats>>>,
    },
    Scrape {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<Option<(String, irontide_tracker::ScrapeInfo)>>>,
    },
    SetFilePriority {
        info_hash: Id20,
        index: usize,
        priority: irontide_core::FilePriority,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    FilePriorities {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<Vec<irontide_core::FilePriority>>>,
    },
    SetDownloadLimit {
        info_hash: Id20,
        bytes_per_sec: u64,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    SetUploadLimit {
        info_hash: Id20,
        bytes_per_sec: u64,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    DownloadLimit {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<u64>>,
    },
    UploadLimit {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<u64>>,
    },
    SetSequentialDownload {
        info_hash: Id20,
        enabled: bool,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    IsSequentialDownload {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<bool>>,
    },
    SetSuperSeeding {
        info_hash: Id20,
        enabled: bool,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    IsSuperSeeding {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<bool>>,
    },
    /// Enable or disable user-requested seed-only mode for a torrent (M159).
    SetSeedMode {
        info_hash: Id20,
        enabled: bool,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    AddTracker {
        info_hash: Id20,
        url: String,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    ReplaceTrackers {
        info_hash: Id20,
        urls: Vec<String>,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// Trigger a full piece verification (force recheck) for a torrent.
    ForceRecheck {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// Rename a file within a torrent on disk.
    RenameFile {
        info_hash: Id20,
        file_index: usize,
        new_name: String,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// Set per-torrent maximum connections (0 = use global default).
    SetMaxConnections {
        info_hash: Id20,
        limit: usize,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// Get per-torrent maximum connection limit.
    MaxConnections {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<usize>>,
    },
    /// Set per-torrent maximum upload slots (unchoke slots).
    SetMaxUploads {
        info_hash: Id20,
        limit: usize,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// Get per-torrent maximum upload slots (unchoke slots).
    MaxUploads {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<usize>>,
    },
    /// Get per-peer details for all connected peers of a torrent.
    GetPeerInfo {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<Vec<crate::types::PeerInfo>>>,
    },
    /// Get in-flight piece download status for a torrent.
    GetDownloadQueue {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<Vec<crate::types::PartialPieceInfo>>>,
    },
    /// Check whether a specific piece has been downloaded.
    HavePiece {
        info_hash: Id20,
        index: u32,
        reply: oneshot::Sender<crate::Result<bool>>,
    },
    /// Get per-piece availability counts from connected peers.
    PieceAvailability {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<Vec<u32>>>,
    },
    /// Get per-file bytes-downloaded progress.
    FileProgress {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<Vec<u64>>>,
    },
    /// Get the torrent's identity hashes (v1 and/or v2).
    InfoHashesQuery {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<irontide_core::InfoHashes>>,
    },
    /// Get the full v1 metainfo for a torrent.
    TorrentFile {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<Option<irontide_core::TorrentMetaV1>>>,
    },
    /// Get the full v2 metainfo for a torrent.
    TorrentFileV2 {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<Option<irontide_core::TorrentMetaV2>>>,
    },
    /// Force an immediate DHT announce for a torrent.
    ForceDhtAnnounce {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// Force an immediate LSD announce for a torrent (session-level only).
    ForceLsdAnnounce {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// Read all data for a specific piece from disk.
    ReadPiece {
        info_hash: Id20,
        index: u32,
        reply: oneshot::Sender<crate::Result<bytes::Bytes>>,
    },
    /// Flush the disk write cache for a torrent.
    FlushCache {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// Check if a torrent handle is still valid (torrent exists and channel open).
    IsValid {
        info_hash: Id20,
        reply: oneshot::Sender<bool>,
    },
    /// Clear error state on a torrent.
    ClearError {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// Get per-file open/mode status for a torrent.
    FileStatus {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<Vec<crate::types::FileStatus>>>,
    },
    /// Read the current torrent flags.
    Flags {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<crate::types::TorrentFlags>>,
    },
    /// Set (enable) the specified torrent flags.
    SetFlags {
        info_hash: Id20,
        flags: crate::types::TorrentFlags,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// Unset (disable) the specified torrent flags.
    UnsetFlags {
        info_hash: Id20,
        flags: crate::types::TorrentFlags,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// Immediately initiate a peer connection for a torrent.
    ConnectPeer {
        info_hash: Id20,
        addr: SocketAddr,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    DhtPutImmutable {
        value: Vec<u8>,
        reply: oneshot::Sender<crate::Result<Id20>>,
    },
    DhtGetImmutable {
        target: Id20,
        reply: oneshot::Sender<crate::Result<Option<Vec<u8>>>>,
    },
    DhtPutMutable {
        keypair_bytes: [u8; 32],
        value: Vec<u8>,
        seq: i64,
        salt: Vec<u8>,
        reply: oneshot::Sender<crate::Result<Id20>>,
    },
    #[allow(clippy::type_complexity)]
    DhtGetMutable {
        public_key: [u8; 32],
        salt: Vec<u8>,
        reply: oneshot::Sender<crate::Result<Option<(Vec<u8>, i64)>>>,
    },
    /// Save per-torrent resume files for all dirty torrents (M161).
    SaveResumeState {
        reply: oneshot::Sender<crate::Result<usize>>,
    },
    /// Trigger an immediate session stats snapshot and alert (M50).
    PostSessionStats,
    // ── M170: qBt v2 *arr-minimal surface ──
    /// Unified add entry (M170) — see `AddTorrentParams`.
    AddTorrentM170 {
        params: Box<AddTorrentParams>,
        reply: oneshot::Sender<crate::Result<Id20>>,
    },
    /// Create a new category with the given `save_path`.
    CreateCategory {
        name: String,
        save_path: PathBuf,
        reply: oneshot::Sender<Result<(), crate::category_manager::CategoryError>>,
    },
    /// Update the `save_path` on an existing category.
    EditCategory {
        name: String,
        save_path: PathBuf,
        reply: oneshot::Sender<Result<(), crate::category_manager::CategoryError>>,
    },
    /// Remove zero or more categories. Returns names actually removed.
    RemoveCategories {
        names: Vec<String>,
        reply: oneshot::Sender<Vec<String>>,
    },
    /// Snapshot the current category list.
    ListCategories {
        reply: oneshot::Sender<Vec<crate::category_manager::CategoryMetadata>>,
    },
    /// Create a batch of tags (M171). One reply slot per requested name
    /// so the caller can tell which were newly created vs already-present.
    CreateTags {
        names: Vec<String>,
        reply: oneshot::Sender<Vec<Result<(), crate::tag_manager::TagError>>>,
    },
    /// Remove zero or more tags (M171). Returns names actually removed;
    /// unknown names are tolerated (matches qBt idempotent `deleteTags`).
    DeleteTags {
        names: Vec<String>,
        reply: oneshot::Sender<Vec<String>>,
    },
    /// Snapshot the current tag list (M171). Sorted.
    ListTags {
        reply: oneshot::Sender<Vec<String>>,
    },
    /// Add the given tags to each torrent in `info_hashes` (M171).
    /// Unknown info hashes are silently skipped. The engine-layer
    /// command is a wholesale replacement, so each torrent's tag set
    /// is read, unioned with the requested additions, and replayed via
    /// `TorrentHandle::set_tags`.
    AddTagsToTorrents {
        info_hashes: Vec<Id20>,
        tags: Vec<String>,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// Remove the given tags from each torrent in `info_hashes` (M171).
    /// Unknown info hashes are silently skipped.
    RemoveTagsFromTorrents {
        info_hashes: Vec<Id20>,
        tags: Vec<String>,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// Remove a torrent and delete its on-disk files (qBt
    /// `deleteFiles=true`).
    RemoveTorrentWithFiles {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    /// M171 Lane B: snapshot the web seed URLs (BEP 19 + BEP 17 merged)
    /// for a specific torrent.
    GetWebSeeds {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<Vec<String>>>,
    },
    /// M171 Lane B: snapshot the per-piece state array as qBt codes
    /// (`0`/`1`/`2`) for a specific torrent.
    GetPieceStates {
        info_hash: Id20,
        reply: oneshot::Sender<crate::Result<Vec<u8>>>,
    },
    /// M171 Lane B: paginated piece hash list for a specific torrent.
    GetPieceHashes {
        info_hash: Id20,
        offset: u32,
        limit: u32,
        reply: oneshot::Sender<crate::Result<Vec<String>>>,
    },
    /// M171 D4: sum of routing-table sizes across the IPv4 and IPv6 DHT
    /// instances. Returns 0 when neither DHT is enabled.
    DhtNodeCount {
        reply: oneshot::Sender<usize>,
    },
    /// **TEST-ONLY (v0.173.2).** Inject info-dict bytes into a torrent's
    /// actor synchronously, returning only after the actor has processed
    /// it. Used by integration tests in `irontide-api` (A9) that exercise
    /// post-metadata HTTP surface without spinning up real peers.
    /// M187: collect per-torrent and per-peer debug state for diagnostics.
    DebugState {
        reply: oneshot::Sender<crate::types::DebugState>,
    },
    #[cfg(feature = "test-util")]
    TestInjectMetadata {
        info_hash: Id20,
        info_bytes: Vec<u8>,
        reply: oneshot::Sender<crate::Result<()>>,
    },
    Shutdown,
}

impl SessionCommand {
    /// Static variant name for the `cmd` field of the M221.1a
    /// `session_cmd` tracing event. Stable across renames is *not* a
    /// goal — this is bench-instrumentation telemetry, so the variant
    /// identifier is the right label.
    fn name(&self) -> &'static str {
        match self {
            Self::AddTorrent { .. } => "AddTorrent",
            Self::CommitAddTorrent { .. } => "CommitAddTorrent",
            Self::AddMagnet { .. } => "AddMagnet",
            Self::RemoveTorrent { .. } => "RemoveTorrent",
            Self::PauseTorrent { .. } => "PauseTorrent",
            Self::ResumeTorrent { .. } => "ResumeTorrent",
            Self::ForceResumeTorrent { .. } => "ForceResumeTorrent",
            Self::SetTorrentSeedRatio { .. } => "SetTorrentSeedRatio",
            Self::TorrentStats { .. } => "TorrentStats",
            Self::TorrentInfo { .. } => "TorrentInfo",
            Self::ListTorrents { .. } => "ListTorrents",
            Self::SessionStats { .. } => "SessionStats",
            Self::SaveTorrentResumeData { .. } => "SaveTorrentResumeData",
            Self::SaveSessionState { .. } => "SaveSessionState",
            Self::LoadResumeState { .. } => "LoadResumeState",
            Self::QueuePosition { .. } => "QueuePosition",
            Self::SetQueuePosition { .. } => "SetQueuePosition",
            Self::QueuePositionUp { .. } => "QueuePositionUp",
            Self::QueuePositionDown { .. } => "QueuePositionDown",
            Self::QueuePositionTop { .. } => "QueuePositionTop",
            Self::QueuePositionBottom { .. } => "QueuePositionBottom",
            Self::BanPeer { .. } => "BanPeer",
            Self::UnbanPeer { .. } => "UnbanPeer",
            Self::BannedPeers { .. } => "BannedPeers",
            Self::SetIpFilter { .. } => "SetIpFilter",
            Self::GetIpFilter { .. } => "GetIpFilter",
            Self::GetSettings { .. } => "GetSettings",
            Self::ApplySettings { .. } => "ApplySettings",
            Self::MoveTorrentStorage { .. } => "MoveTorrentStorage",
            Self::AddPeers { .. } => "AddPeers",
            Self::OpenFile { .. } => "OpenFile",
            Self::ForceReannounce { .. } => "ForceReannounce",
            Self::TrackerList { .. } => "TrackerList",
            Self::GetPeerSourceCounts { .. } => "GetPeerSourceCounts",
            Self::QueryUnchokeDurations { .. } => "QueryUnchokeDurations",
            Self::GetWebSeedStats { .. } => "GetWebSeedStats",
            Self::Scrape { .. } => "Scrape",
            Self::SetFilePriority { .. } => "SetFilePriority",
            Self::FilePriorities { .. } => "FilePriorities",
            Self::SetDownloadLimit { .. } => "SetDownloadLimit",
            Self::SetUploadLimit { .. } => "SetUploadLimit",
            Self::DownloadLimit { .. } => "DownloadLimit",
            Self::UploadLimit { .. } => "UploadLimit",
            Self::SetSequentialDownload { .. } => "SetSequentialDownload",
            Self::IsSequentialDownload { .. } => "IsSequentialDownload",
            Self::SetSuperSeeding { .. } => "SetSuperSeeding",
            Self::IsSuperSeeding { .. } => "IsSuperSeeding",
            Self::SetSeedMode { .. } => "SetSeedMode",
            Self::AddTracker { .. } => "AddTracker",
            Self::ReplaceTrackers { .. } => "ReplaceTrackers",
            Self::ForceRecheck { .. } => "ForceRecheck",
            Self::RenameFile { .. } => "RenameFile",
            Self::SetMaxConnections { .. } => "SetMaxConnections",
            Self::MaxConnections { .. } => "MaxConnections",
            Self::SetMaxUploads { .. } => "SetMaxUploads",
            Self::MaxUploads { .. } => "MaxUploads",
            Self::GetPeerInfo { .. } => "GetPeerInfo",
            Self::GetDownloadQueue { .. } => "GetDownloadQueue",
            Self::HavePiece { .. } => "HavePiece",
            Self::PieceAvailability { .. } => "PieceAvailability",
            Self::FileProgress { .. } => "FileProgress",
            Self::InfoHashesQuery { .. } => "InfoHashesQuery",
            Self::TorrentFile { .. } => "TorrentFile",
            Self::TorrentFileV2 { .. } => "TorrentFileV2",
            Self::ForceDhtAnnounce { .. } => "ForceDhtAnnounce",
            Self::ForceLsdAnnounce { .. } => "ForceLsdAnnounce",
            Self::ReadPiece { .. } => "ReadPiece",
            Self::FlushCache { .. } => "FlushCache",
            Self::IsValid { .. } => "IsValid",
            Self::ClearError { .. } => "ClearError",
            Self::FileStatus { .. } => "FileStatus",
            Self::Flags { .. } => "Flags",
            Self::SetFlags { .. } => "SetFlags",
            Self::UnsetFlags { .. } => "UnsetFlags",
            Self::ConnectPeer { .. } => "ConnectPeer",
            Self::DhtPutImmutable { .. } => "DhtPutImmutable",
            Self::DhtGetImmutable { .. } => "DhtGetImmutable",
            Self::DhtPutMutable { .. } => "DhtPutMutable",
            Self::DhtGetMutable { .. } => "DhtGetMutable",
            Self::SaveResumeState { .. } => "SaveResumeState",
            Self::PostSessionStats => "PostSessionStats",
            Self::AddTorrentM170 { .. } => "AddTorrentM170",
            Self::CreateCategory { .. } => "CreateCategory",
            Self::EditCategory { .. } => "EditCategory",
            Self::RemoveCategories { .. } => "RemoveCategories",
            Self::ListCategories { .. } => "ListCategories",
            Self::CreateTags { .. } => "CreateTags",
            Self::DeleteTags { .. } => "DeleteTags",
            Self::ListTags { .. } => "ListTags",
            Self::AddTagsToTorrents { .. } => "AddTagsToTorrents",
            Self::RemoveTagsFromTorrents { .. } => "RemoveTagsFromTorrents",
            Self::RemoveTorrentWithFiles { .. } => "RemoveTorrentWithFiles",
            Self::GetWebSeeds { .. } => "GetWebSeeds",
            Self::GetPieceStates { .. } => "GetPieceStates",
            Self::GetPieceHashes { .. } => "GetPieceHashes",
            Self::DhtNodeCount { .. } => "DhtNodeCount",
            Self::DebugState { .. } => "DebugState",
            #[cfg(feature = "test-util")]
            Self::TestInjectMetadata { .. } => "TestInjectMetadata",
            Self::Shutdown => "Shutdown",
        }
    }
}

/// Channel sender that timestamps each outgoing `SessionCommand` with
/// the instant it was enqueued, so the actor's receive arm can split
/// `queue_wait_ms` (sender → receiver) from `handler_ms` (dispatch).
/// M221.1a — feeds the parallel-7 bench harness.
#[derive(Clone)]
struct SessionCmdSender(mpsc::Sender<(tokio::time::Instant, SessionCommand)>);

impl SessionCmdSender {
    async fn send(
        &self,
        cmd: SessionCommand,
    ) -> Result<(), mpsc::error::SendError<SessionCommand>> {
        let sent_at = tokio::time::Instant::now();
        self.0
            .send((sent_at, cmd))
            .await
            .map_err(|e| mpsc::error::SendError(e.0.1))
    }
}

/// Classification of settings-patch fields into "took effect immediately"
/// versus "requires session restart to apply".
///
/// Returned by [`SessionHandle::apply_settings_classified`]. The
/// `restart_required` list is surfaced as the `X-IronTide-Restart-Pending`
/// response header by the qBt v2 `setPreferences` handler so clients can
/// render a "restart to apply" UX affordance (M171 D3.5).
#[derive(Debug, Clone, Default)]
pub struct AppliedSettings {
    /// Settings fields that changed and took effect immediately.
    pub immediate: Vec<&'static str>,
    /// Settings fields that changed but require a session restart to
    /// activate (sub-actor reconfig, listen-socket rebind, DHT/LSD/PEX
    /// startup, encryption-handshake policy, anonymous-mode peer ID, etc.).
    pub restart_required: Vec<&'static str>,
}

// ─────────────────────────────────────────────────────────────────────────
// Settings reconfiguration classification — CODEGEN from the SSOT registry
// (M247a). The reconfiguration class (`immediate` / `restart` / `stored`) and
// qBt wire-name of every setting are declared ONCE in `irontide_settings`'
// exported `for_each_setting!` / `for_each_qbt_compat_setting!` /
// `for_each_proxy_setting!` registries (crates/irontide-settings/src/schema.rs).
// The two `classify_*` projections below are GENERATED from those registries
// rather than hand-maintained, so a field can never drift out of sync between
// its declaration and its reconfiguration class.
//
// Mechanism (tracer-proven, M247a Task 1):
//   * `push_if!` emits a `v.push(wire)` guard IFF the entry's `class` matches
//     the target class. The class is forwarded as a `:tt` (NOT captured as an
//     `:ident`) — a captured `:ident` is opaque downstream and would not
//     re-match the literal-keyword arms (Trap 3).
//   * one tiny emitter per (target-class, accessor-prefix) generates an
//     appender fn; the registry's `$(…)*` repetition expands one `push_if!`
//     per field. `stored` fields (and class-mismatches) expand to nothing, so
//     their accessor is never even referenced.
//   * the `classify_*` wrappers call the appenders in sequence. The output
//     ORDER differs from the pre-M247a hand-written interleaving, but every
//     consumer and test treats the result as a SET (`.contains()` / `HashSet`
//     equality — see the golden tests in this module), so order is immaterial.
// ─────────────────────────────────────────────────────────────────────────

/// Emits `if o.<acc> != n.<acc> { v.push(wire); }` IFF the entry's `class`
/// (arg 2, forwarded as `:tt`) equals the target class (arg 1). Every other
/// class — including `stored` — matches the final no-op arm and expands to
/// nothing, so a non-projected field's accessor is never referenced.
macro_rules! push_if {
    (immediate, immediate, $o:ident, $n:ident, ($($acc:tt)*), $wire:literal, $v:ident) => {
        if $o.$($acc)* != $n.$($acc)* { $v.push($wire); }
    };
    (restart, restart, $o:ident, $n:ident, ($($acc:tt)*), $wire:literal, $v:ident) => {
        if $o.$($acc)* != $n.$($acc)* { $v.push($wire); }
    };
    ($t:tt, $c:tt, $o:ident, $n:ident, ($($acc:tt)*), $wire:literal, $v:ident) => {};
}

// One appender per (target-class, accessor-prefix). Each emitter generates a
// free fn over its whole registry; `push_if!` keeps only the matching class.
macro_rules! emit_immediate_top {
    ( $({ name: $name:ident, class: $class:tt, wire: $wire:literal, doc: $doc:literal })* ) => {
        fn append_immediate_top(o: &Settings, n: &Settings, v: &mut Vec<&'static str>) {
            $( push_if!(immediate, $class, o, n, ($name), $wire, v); )*
        }
    };
}
irontide_settings::for_each_setting!(emit_immediate_top);

macro_rules! emit_immediate_qbt {
    ( $({ name: $name:ident, class: $class:tt, wire: $wire:literal, doc: $doc:literal })* ) => {
        fn append_immediate_qbt(o: &Settings, n: &Settings, v: &mut Vec<&'static str>) {
            $( push_if!(immediate, $class, o, n, (qbt_compat . $name), $wire, v); )*
        }
    };
}
irontide_settings::for_each_qbt_compat_setting!(emit_immediate_qbt);

macro_rules! emit_restart_top {
    ( $({ name: $name:ident, class: $class:tt, wire: $wire:literal, doc: $doc:literal })* ) => {
        fn append_restart_top(o: &Settings, n: &Settings, v: &mut Vec<&'static str>) {
            $( push_if!(restart, $class, o, n, ($name), $wire, v); )*
        }
    };
}
irontide_settings::for_each_setting!(emit_restart_top);

macro_rules! emit_restart_qbt {
    ( $({ name: $name:ident, class: $class:tt, wire: $wire:literal, doc: $doc:literal })* ) => {
        fn append_restart_qbt(o: &Settings, n: &Settings, v: &mut Vec<&'static str>) {
            $( push_if!(restart, $class, o, n, (qbt_compat . $name), $wire, v); )*
        }
    };
}
irontide_settings::for_each_qbt_compat_setting!(emit_restart_qbt);

macro_rules! emit_restart_proxy {
    ( $({ name: $name:ident, class: $class:tt, wire: $wire:literal, doc: $doc:literal })* ) => {
        fn append_restart_proxy(o: &Settings, n: &Settings, v: &mut Vec<&'static str>) {
            $( push_if!(restart, $class, o, n, (proxy . $name), $wire, v); )*
        }
    };
}
irontide_settings::for_each_proxy_setting!(emit_restart_proxy);

/// Classify fields whose runtime application is immediate — rate limiters
/// (M166), alert mask, peer cap, and enum/flag state that peer/torrent
/// actors re-read on every tick.
///
/// **M173 Lane B (B10) — graduation:** `listen_port`, `dht`, and `lsd`
/// move from `restart_required` to `immediate`. The transactional
/// apply pipeline (B1) now performs the live reconfig:
/// - `listen_port`: TCP listener rebind + uTP `shutdown_and_wait` + new
///   bind + NAT `refresh_for_port` (B2/B4/B8 primitives).
/// - dht: `shutdown_and_wait` (B7 persists routing table) + new
///   `DhtHandle` + `DhtBroadcast::replace` fans out to torrents (B5+B6).
/// - lsd: `shutdown_and_wait` (B9 multicast fd guard) + new actor.
///
/// **Body generated (M247a)** from `for_each_setting!` +
/// `for_each_qbt_compat_setting!` via `append_immediate_top` /
/// `append_immediate_qbt`.
///
/// `[REGRESSION CRITICAL]`: the wire-format pinned test in irontide-client's
/// `crates/irontide-api/tests/qbt_v2_set_preferences.rs` (cross-repo; runs
/// against the published crate) asserts the EXACT field-name set here.
/// Downstream *arr clients parse the `X-IronTide-Restart-Pending` header — a
/// silent rename = downstream regression. Change a `wire:` in the registry
/// only with that contract in mind; never reuse a field name.
fn classify_immediate(old: &Settings, new: &Settings) -> Vec<&'static str> {
    let mut v = Vec::new();
    append_immediate_top(old, new, &mut v);
    append_immediate_qbt(old, new, &mut v);
    v
}

/// Classify fields whose runtime application STILL requires a session
/// restart, post-M173 Lane B graduation:
/// - PEX (peer announcement on next handshake — propagation cost)
/// - encryption handshake policy (MSE bytes-on-wire)
/// - anonymous-mode peer ID
/// - download-dir root (in-flight torrents retain their original
///   `save_path`; only `next-add` changes — this is intentional, not
///   a bug, see HA spec non-goals)
///
/// **M173 Lane B (B10) — graduation:** `listen_port`, `dht`, `lsd` were
/// removed from this list; they now appear in [`classify_immediate`].
/// The transactional apply pipeline (B1) performs their live reconfig.
///
/// **Body generated (M247a)** from `for_each_setting!` +
/// `for_each_qbt_compat_setting!` + `for_each_proxy_setting!` via
/// `append_restart_top` / `append_restart_qbt` / `append_restart_proxy`.
fn classify_restart_required(old: &Settings, new: &Settings) -> Vec<&'static str> {
    let mut v = Vec::new();
    append_restart_top(old, new, &mut v);
    append_restart_qbt(old, new, &mut v);
    append_restart_proxy(old, new, &mut v);
    v
}

/// Cloneable handle for interacting with a running session.
#[derive(Clone)]
pub struct SessionHandle {
    cmd_tx: SessionCmdSender,
    alert_tx: broadcast::Sender<Alert>,
    alert_mask: Arc<AtomicU32>,
    counters: Arc<crate::stats::SessionCounters>,
    /// Network transport factory (M51). Used by future simulation tasks.
    #[allow(dead_code)]
    factory: Arc<crate::transport::NetworkFactory>,
    /// M173 Lane B (B11): in-flight guard for concurrent
    /// `apply_settings` / `apply_settings_classified` calls. The
    /// guard is acquired BEFORE the command is queued; if a
    /// previous reconfig is still in flight, the second caller hits
    /// `Error::ConcurrentReconfig` (HTTP 409 Conflict on the qBt
    /// v2 `setPreferences` endpoint) instead of racing the first
    /// caller's read-modify-write.
    reconfig_in_flight: crate::apply::ReconfigInFlight,
    /// M245 A1 — lock-free published read-model. Read-only callers
    /// ([`list_torrent_summaries`](Self::list_torrent_summaries)) load an
    /// `Arc` snapshot here instead of round-tripping the command mailbox.
    /// The [`SessionActor`] is the SOLE writer: it patches membership
    /// eagerly on add/remove and refreshes sampled stats once per stats
    /// tick. Same `ArcSwap` the actor holds (cloned at construction).
    snapshot: Arc<arc_swap::ArcSwap<SessionSnapshot>>,
}

impl SessionHandle {
    /// Start a new session with the given settings and no plugins.
    ///
    /// # Errors
    ///
    /// Returns an error if the connection or binding fails.
    pub async fn start(settings: Settings) -> crate::Result<Self> {
        Self::start_with_plugins(settings, Arc::new(Vec::new())).await
    }

    /// Start a new session with a custom disk I/O backend and no plugins.
    ///
    /// # Errors
    ///
    /// Returns an error if the connection or binding fails.
    pub async fn start_with_backend(
        settings: Settings,
        backend: Arc<dyn crate::disk_backend::DiskIoBackend>,
    ) -> crate::Result<Self> {
        Self::start_with_plugins_and_backend(settings, Arc::new(Vec::new()), backend).await
    }

    /// Start a new session with the given settings and extension plugins.
    ///
    /// # Errors
    ///
    /// Returns an error if the connection or binding fails.
    pub async fn start_with_plugins(
        settings: Settings,
        plugins: Arc<Vec<Box<dyn crate::extension::ExtensionPlugin>>>,
    ) -> crate::Result<Self> {
        let disk_config = crate::disk::DiskConfig::from(&settings);
        let backend = crate::disk_backend::create_backend_from_config(&disk_config);
        Self::start_with_plugins_and_backend(settings, plugins, backend).await
    }

    /// Start a new session with the given settings, extension plugins, and
    /// a custom disk I/O backend.
    ///
    /// # Errors
    ///
    /// Returns an error if the connection or binding fails.
    pub async fn start_with_plugins_and_backend(
        settings: Settings,
        plugins: Arc<Vec<Box<dyn crate::extension::ExtensionPlugin>>>,
        backend: Arc<dyn crate::disk_backend::DiskIoBackend>,
    ) -> crate::Result<Self> {
        Self::start_full(
            settings,
            plugins,
            backend,
            Arc::new(crate::transport::NetworkFactory::tokio()),
        )
        .await
    }

    /// Start a new session with the given settings and a custom transport factory.
    ///
    /// Uses default plugins (none) and default disk backend.
    ///
    /// # Errors
    ///
    /// Returns an error if the connection or binding fails.
    pub async fn start_with_transport(
        settings: Settings,
        factory: Arc<crate::transport::NetworkFactory>,
    ) -> crate::Result<Self> {
        let disk_config = crate::disk::DiskConfig::from(&settings);
        let backend = crate::disk_backend::create_backend_from_config(&disk_config);
        Self::start_full(settings, Arc::new(Vec::new()), backend, factory).await
    }

    /// Start a new session with all customizable parameters.
    ///
    /// This is the most general constructor — all other `start_*` variants
    /// delegate to this method. The `factory` parameter controls how TCP
    /// listeners and connections are created: use [`crate::transport::NetworkFactory::tokio()`]
    /// for real networking or a custom factory for simulation.
    ///
    /// # Errors
    ///
    /// Returns an error if the connection or binding fails.
    pub async fn start_full(
        settings: Settings,
        plugins: Arc<Vec<Box<dyn crate::extension::ExtensionPlugin>>>,
        backend: Arc<dyn crate::disk_backend::DiskIoBackend>,
        factory: Arc<crate::transport::NetworkFactory>,
    ) -> crate::Result<Self> {
        let mut settings = settings;

        // Force proxy mode: all connections must go through proxy.
        if settings.force_proxy {
            if settings.proxy.proxy_type == crate::proxy::ProxyType::None {
                return Err(crate::Error::Config(
                    "force_proxy requires a proxy to be configured".into(),
                ));
            }
            settings.enable_upnp = false;
            settings.enable_natpmp = false;
            settings.enable_dht = false;
            settings.enable_lsd = false;
        }

        // Anonymous mode: suppress identity and disable discovery.
        if settings.anonymous_mode {
            settings.enable_dht = false;
            settings.enable_lsd = false;
            settings.enable_upnp = false;
            settings.enable_natpmp = false;
        }

        // M172a A3/C2: legacy-plaintext → argon2id migration on the in-memory
        // Settings. The config file rewrite is a separate concern handled by
        // the CLI layer (see irontide_config::migrate_qbt_credentials_in_file)
        // — we only mutate the runtime copy here so login always uses PHC
        // hashes regardless of on-disk state.
        //
        // Failure semantics (C2): on hash error we keep the plaintext in
        // memory so verify still works, and emit a WARN. The daemon continues
        // — a startup crash would brick an operator on a transient OS error.
        match irontide_settings::migrate_qbt_credentials(&mut settings.qbt_compat) {
            Ok(irontide_settings::QbtCredentialMigration::Upgraded) => {
                warn!(
                    "qbt_compat: legacy plaintext password migrated to argon2id in memory — \
                     persist via `irontide_config::migrate_qbt_credentials_in_file` or the \
                     next config-touching CLI command to remove the plaintext from disk"
                );
            }
            Ok(irontide_settings::QbtCredentialMigration::NoOp) => {}
            Err(e) => {
                warn!(
                    error = %e,
                    "qbt_compat: in-memory password migration failed — continuing with \
                     legacy plaintext; retry on next daemon start"
                );
            }
        }

        let (raw_cmd_tx, cmd_rx) = mpsc::channel::<(tokio::time::Instant, SessionCommand)>(256);
        let cmd_tx = SessionCmdSender(raw_cmd_tx);

        // Alert broadcast channel
        let (alert_tx, _) = broadcast::channel(settings.alert_channel_size);
        let alert_mask = Arc::new(AtomicU32::new(settings.alert_mask.bits()));

        // M226 Step 5: spawn the engine-side OS notification dispatcher.
        // The dispatcher subscribes to the alert broadcast BEFORE any
        // TorrentAdded can fire (H5 — eliminates the missed-cache race
        // on first add), reads `notify_on_complete` / `notify_on_error`
        // live from a watch channel mirrored by `handle_apply_settings`,
        // and exits when either the `notification_shutdown_tx` field on
        // `SessionActor` drops OR the alert broadcast closes. Production
        // uses `LibNotifySink` (wraps `notify-rust` via spawn_blocking);
        // first D-Bus failure logs a single WARN then degrades silently.
        let (notification_settings_tx, notification_settings_rx) =
            tokio::sync::watch::channel(settings.clone());
        let (notification_shutdown_tx, notification_shutdown_rx) = oneshot::channel::<()>();
        let _notification_dispatcher_handle = crate::notification::spawn_notification_dispatcher(
            crate::notification::DispatcherOptions {
                sink: Box::new(crate::notification::LibNotifySink::new()),
                settings_rx: notification_settings_rx,
                alerts_rx: alert_tx.subscribe(),
                shutdown_rx: notification_shutdown_rx,
            },
        );

        // M226 Step 6: prepare the watched-folder dispatcher's channels.
        // The dispatcher itself is spawned at the very end of `start_full`
        // (it needs a fully-built `SessionHandle` to clone), but the
        // shutdown signal + change-notify must exist before SessionActor
        // construction so they can be stored on the actor.
        let watched_folder_changed = Arc::new(tokio::sync::Notify::new());
        let (watched_folder_shutdown_tx, watched_folder_shutdown_rx) = oneshot::channel::<()>();
        // Fresh settings subscription dedicated to the watcher (a watch
        // Receiver is single-consumer; the notification dispatcher
        // already consumed the original).
        let watched_folder_settings_rx = notification_settings_tx.subscribe();

        let (lsd, lsd_peers_rx) = if settings.enable_lsd {
            match crate::lsd::LsdHandle::start(settings.listen_port, settings.enable_ipv6).await {
                Ok((handle, rx)) => (Some(handle), Some(rx)),
                Err(e) => {
                    warn!("LSD unavailable (port 6771): {e}");
                    (None, None)
                }
            }
        } else {
            (None, None)
        };

        let global_upload_bucket = Arc::new(parking_lot::Mutex::new(
            crate::rate_limiter::TokenBucket::new(settings.upload_rate_limit),
        ));
        let global_download_bucket = Arc::new(parking_lot::Mutex::new(
            crate::rate_limiter::TokenBucket::new(settings.download_rate_limit),
        ));

        // M225 G4: build the shared admit-gate state BEFORE binding the uTP
        // socket so the SocketActor's inbound-SYN path can read from the
        // same `Arc<AtomicI32>` / `Arc<AtomicUsize>` / `SharedIpFilter` the
        // TCP listener and `handle_apply_settings` use. These three
        // allocations are otherwise constructed further down (lines below);
        // hoisting them avoids a separate setter on `UtpSocket` and the
        // race window it would open.
        let ip_filter: SharedIpFilter =
            Arc::new(parking_lot::RwLock::new(crate::ip_filter::IpFilter::new()));
        let max_connections_global = Arc::new(std::sync::atomic::AtomicI32::new(
            settings.max_connections_global,
        ));
        let live_connections = Arc::new(std::sync::atomic::AtomicUsize::new(0));

        let utp_admit = {
            let ip_filter_for_utp = Arc::clone(&ip_filter);
            irontide_utp::AdmitGate::new(
                Arc::clone(&max_connections_global),
                Arc::clone(&live_connections),
                Arc::new(move |addr| ip_filter_for_utp.read().is_blocked(addr)),
            )
        };

        // uTP socket (shared across all torrents).
        //
        // Stage U: when the factory exposes a `bind_udp` closure (sim
        // path), bind the production `UtpSocket` on top of the factory's
        // `UdpTransport` so BEP 29 runs unmodified through the in-memory
        // packet bus. The tokio factory leaves `bind_udp` unset and the
        // direct `UtpSocket::bind` path runs (it owns the FD-level DSCP /
        // TCLASS setsockopt, which the sim has no equivalent for).
        let (utp_socket, utp_listener) = if settings.enable_utp {
            let utp_config = settings.to_utp_config(settings.listen_port);
            let bind_addr = utp_config.bind_addr;
            let result = if factory.has_bind_udp() {
                match factory.bind_udp(bind_addr).await {
                    Ok(transport) => irontide_utp::UtpSocket::bind_with_transport_and_admit_gate(
                        transport,
                        utp_config,
                        utp_admit.clone(),
                    ),
                    Err(e) => Err(irontide_utp::Error::Io(e)),
                }
            } else {
                irontide_utp::UtpSocket::bind_with_admit_gate(utp_config, utp_admit.clone()).await
            };
            match result {
                Ok((socket, listener)) => (Some(socket), Some(listener)),
                Err(e) => {
                    warn!("uTP bind failed: {e}");
                    (None, None)
                }
            }
        } else {
            (None, None)
        };

        // IPv6 uTP socket (dual-stack). Sim path skips IPv6 — the sim
        // network only models v4 today.
        let (utp_socket_v6, utp_listener_v6) =
            if settings.enable_utp && settings.enable_ipv6 && !factory.has_bind_udp() {
                match irontide_utp::UtpSocket::bind_with_admit_gate(
                    settings.to_utp_config_v6(settings.listen_port),
                    utp_admit.clone(),
                )
                .await
                {
                    Ok((socket, listener)) => (Some(socket), Some(listener)),
                    Err(e) => {
                        debug!("uTP IPv6 bind failed (non-fatal): {e}");
                        (None, None)
                    }
                }
            } else {
                (None, None)
            };

        // NAT port mapping (PCP / NAT-PMP / UPnP)
        let (nat, nat_events_rx) = if settings.enable_upnp || settings.enable_natpmp {
            let nat_config = settings.to_nat_config();
            let (handle, events_rx) = irontide_nat::NatHandle::start(nat_config);
            let udp_port = if settings.enable_utp {
                Some(settings.listen_port)
            } else {
                None
            };
            handle.map_ports(settings.listen_port, udp_port).await;
            (Some(handle), Some(events_rx))
        } else {
            (None, None)
        };

        // I2P SAM session
        let sam_session = if settings.enable_i2p {
            let tunnel_config = settings.to_sam_tunnel_config();
            match crate::i2p::SamSession::create(
                &settings.i2p_hostname,
                settings.i2p_port,
                "torrent",
                tunnel_config,
            )
            .await
            {
                Ok(session) => {
                    let b32 = session.destination().to_b32_address();
                    info!("I2P SAM session created: {}", b32);
                    post_alert(
                        &alert_tx,
                        &alert_mask,
                        AlertKind::I2pSessionCreated { b32_address: b32 },
                    );
                    Some(Arc::new(session))
                }
                Err(e) => {
                    warn!("I2P SAM session failed: {e}");
                    post_alert(
                        &alert_tx,
                        &alert_mask,
                        AlertKind::I2pError {
                            message: format!("SAM session creation failed: {e}"),
                        },
                    );
                    None
                }
            }
        } else {
            None
        };

        // SSL manager (M42): create if ssl_listen_port != 0 or cert paths are provided
        let ssl_manager = if settings.ssl_listen_port != 0 || settings.ssl_cert_path.is_some() {
            match crate::ssl_manager::SslManager::new(&settings) {
                Ok(mgr) => {
                    info!("SSL manager initialized");
                    Some(Arc::new(mgr))
                }
                Err(e) => {
                    warn!(error = %e, "SSL manager initialization failed");
                    None
                }
            }
        } else {
            None
        };

        // TCP listener: bind on the main listen port for incoming peer connections.
        let tcp_listener: Option<Box<dyn crate::transport::TransportListener>> = match factory
            .bind_tcp(SocketAddr::from(([0, 0, 0, 0], settings.listen_port)))
            .await
        {
            Ok(l) => {
                info!(port = settings.listen_port, "TCP listener started");
                Some(l)
            }
            Err(e) => {
                warn!(port = settings.listen_port, error = %e, "TCP listener bind failed");
                None
            }
        };

        // SSL listener (M42): bind if ssl_listen_port != 0
        let ssl_listener: Option<Box<dyn crate::transport::TransportListener>> = if settings
            .ssl_listen_port
            != 0
        {
            match factory
                .bind_tcp(SocketAddr::from(([0, 0, 0, 0], settings.ssl_listen_port)))
                .await
            {
                Ok(l) => {
                    info!(port = settings.ssl_listen_port, "SSL listener started");
                    Some(l)
                }
                Err(e) => {
                    warn!(port = settings.ssl_listen_port, error = %e, "SSL listener bind failed");
                    None
                }
            }
        } else {
            None
        };

        // Start DHT instances
        let (dht_v4, dht_v4_ip_rx) = if settings.enable_dht {
            match DhtHandle::start(settings.to_dht_config()).await {
                Ok((handle, ip_rx)) => {
                    info!("DHT v4 started");
                    (Some(handle), Some(ip_rx))
                }
                Err(e) => {
                    warn!("DHT v4 start failed: {e}");
                    (None, None)
                }
            }
        } else {
            (None, None)
        };

        let (dht_v6, dht_v6_ip_rx) = if settings.enable_dht && settings.enable_ipv6 {
            match DhtHandle::start(settings.to_dht_config_v6()).await {
                Ok((handle, ip_rx)) => {
                    info!("DHT v6 started");
                    (Some(handle), Some(ip_rx))
                }
                Err(e) => {
                    debug!("DHT v6 start failed (non-fatal): {e}");
                    (None, None)
                }
            }
        } else {
            (None, None)
        };

        // M173 Lane B (B6): seed the broadcast surfaces with the
        // initial DHT handles so consumers see exactly the same
        // value via the broadcast as the legacy `dht_v4`/`dht_v6`
        // fields. B11's apply_settings DHT-restart phase later
        // updates the broadcasts via `replace`.
        let dht_v4_broadcast = irontide_dht::DhtBroadcast::new(dht_v4.clone());
        let dht_v6_broadcast = irontide_dht::DhtBroadcast::new(dht_v6.clone());

        let ban_config = crate::ban::BanConfig::from(&settings);
        let ban_manager: SharedBanManager = Arc::new(parking_lot::RwLock::new(
            crate::ban::BanManager::new(ban_config),
        ));

        // M225 G4: `ip_filter` was hoisted above the uTP bind so the
        // SocketActor's admit-gate closure captures the same Arc.

        let disk_config = crate::disk::DiskConfig::from(&settings);
        let spawner = crate::blocking_spawner::BlockingSpawner::new(settings.max_blocking_threads);
        let (disk_manager, disk_actor_handle) =
            crate::disk::DiskManagerHandle::new_with_backend(disk_config, backend, spawner);

        let counters = Arc::new(crate::stats::SessionCounters::new_with_diagnostics(
            settings.enable_diagnostic_counters,
        ));

        // M96: Create shared hash pool for parallel piece verification
        let hash_pool = std::sync::Arc::new(crate::hash_pool::HashPool::new(
            settings.hashing_threads,
            64,
        ));

        // M114: Spawn isolated listener task for TCP/uTP accepts.
        let info_hash_registry = Arc::new(DashMap::new());
        let (validated_tx, validated_conn_rx) = mpsc::channel(64);
        // M224 D3 / M225 G4: `max_connections_global` and `live_connections`
        // were hoisted above the uTP bind so the SocketActor's admit gate
        // shares them with this listener. handle_apply_settings updates the
        // i32 atomic in-place; both transports read it on the next admit.
        let listener_task = crate::listener::ListenerTask::new(
            tcp_listener,
            utp_listener,
            utp_listener_v6,
            Arc::clone(&info_hash_registry),
            validated_tx,
            Arc::clone(&max_connections_global),
            Arc::clone(&live_connections),
        );
        // M173 Lane B (B2): spawn via ListenerHandle::spawn so the
        // shutdown channel is plumbed in. We hold the full
        // `ListenerHandle` (not just the JoinHandle) so the future
        // listen-port rebind path (B4) can call
        // `shutdown_with_timeout` for a clean port swap. Session
        // teardown still works via Drop on the `ListenerHandle` →
        // shutdown sender Drop → receiver fires `RecvError` → loop
        // exits.
        let listener_handle = crate::listener::ListenerHandle::spawn(listener_task);

        let external_ip = settings.external_ip;

        // M170: load the category registry once on startup. Errors are
        // soft-recovered inside `CategoryRegistry::load`, so this call
        // cannot fail in practice.
        let category_registry_path = crate::category_manager::resolve_category_registry_path(
            settings.category_registry_path.as_deref(),
        );
        let category_registry = Arc::new(parking_lot::RwLock::new(
            crate::category_manager::CategoryRegistry::load(category_registry_path),
        ));
        // M171: same pattern as the category registry — soft-recover inside
        // `TagRegistry::load`, so this never fails in practice.
        let tag_registry_path =
            crate::tag_manager::resolve_tag_registry_path(settings.tag_registry_path.as_deref());
        let tag_registry = Arc::new(parking_lot::RwLock::new(
            crate::tag_manager::TagRegistry::load(tag_registry_path),
        ));
        let deletion_grace = Arc::new(parking_lot::Mutex::new(std::collections::HashSet::new()));
        let reconfig_in_flight = crate::apply::ReconfigInFlight::new();
        // M245 A1 — the lock-free published read-model. Built empty (the
        // `torrents` map starts empty too); the actor patches it on every
        // add/remove and refreshes stats each tick. `Arc::clone`d into the
        // actor (sole writer) and moved into the handle (reader) below.
        let snapshot = Arc::new(arc_swap::ArcSwap::from_pointee(SessionSnapshot::default()));

        let actor = SessionActor {
            settings,
            // M223 — clone so the actor can self-emit CommitAddTorrent
            // from off-actor prep tasks. The handle still owns the
            // original sender; both feed the same recv queue.
            commit_tx: cmd_tx.clone(),
            torrents: HashMap::new(),
            snapshot: Arc::clone(&snapshot),
            dht_v4,
            dht_v6,
            dht_v4_broadcast,
            dht_v6_broadcast,
            lsd,
            lsd_peers_rx,
            cmd_rx,
            alert_tx: alert_tx.clone(),
            alert_mask: Arc::clone(&alert_mask),
            global_upload_bucket,
            global_download_bucket,
            utp_socket,
            utp_socket_v6,
            nat,
            nat_events_rx,
            ban_manager,
            ip_filter,
            disk_manager,
            disk_actor_handle,
            external_ip,
            dht_v4_ip_rx,
            dht_v6_ip_rx,
            plugins,
            sam_session,
            ssl_manager,
            ssl_listener,
            validated_conn_rx,
            info_hash_registry,
            _listener_task: listener_handle,
            max_connections_global,
            live_connections,
            counters: Arc::clone(&counters),
            factory: Arc::clone(&factory),
            hash_pool,
            category_registry,
            tag_registry,
            deletion_grace,
            // Clone so the SessionHandle can hold the same guard.
            reconfig_in_flight: reconfig_in_flight.clone(),
            self_alert_rx: alert_tx.subscribe(),
            resume_save_notify: Arc::new(tokio::sync::Notify::new()),
            resume_save_lock: Arc::new(tokio::sync::Mutex::new(())),
            notification_settings_tx,
            notification_shutdown_tx,
            watched_folder_changed: Arc::clone(&watched_folder_changed),
            watched_folder_shutdown_tx,
        };

        let join_handle = tokio::spawn(actor.run());
        tokio::spawn(async move {
            match join_handle.await {
                Ok(()) => {
                    tracing::warn!("session 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!("session actor PANICKED: {msg}");
                }
                Err(e) => {
                    tracing::error!("session actor task error: {e}");
                }
            }
        });
        let handle = Self {
            cmd_tx,
            alert_tx,
            alert_mask,
            counters,
            factory,
            // M173 Lane B (B11): share the in-flight guard with the
            // SessionActor — the actor's apply pipeline can also
            // check it for symmetric guarantees, but the HANDLE-side
            // try_lock is what catches caller-side races (two
            // concurrent setPreferences requests).
            reconfig_in_flight,
            // M245 A1 — same ArcSwap the actor writes; this is the read side.
            snapshot,
        };

        // M226 Step 6: spawn the watched-folder dispatcher AFTER the
        // SessionHandle is built so we can hand it a `.clone()`. The
        // dispatcher calls `handle.add_torrent(params)` for every
        // .torrent file dropped in `settings.watched_folder`. Drop of
        // the matching `watched_folder_shutdown_tx` on the actor (or
        // explicit send) signals the dispatcher to exit.
        let _watched_folder_join = crate::watched_folder::spawn_watched_folder_dispatcher(
            handle.clone(),
            watched_folder_settings_rx,
            watched_folder_changed,
            watched_folder_shutdown_rx,
        );

        Ok(handle)
    }

    /// Add a torrent from parsed .torrent metadata (v1, v2, or hybrid).
    ///
    /// Low-level entry point; used by the `irontide` facade and internal
    /// sim/test code. For user-facing adds, prefer
    /// [`add_torrent`](Self::add_torrent) with [`AddTorrentParams`],
    /// which resolves categories and `download_dir` via M170 semantics.
    ///
    /// # Errors
    ///
    /// Returns an error if the torrent cannot be added or the session is shut down.
    pub async fn add_torrent_with_meta(
        &self,
        meta: irontide_core::TorrentMeta,
        storage: Option<Arc<dyn TorrentStorage>>,
    ) -> crate::Result<Id20> {
        self.add_torrent_with_dir(meta, storage, None).await
    }

    /// Unified add entry (M170).
    ///
    /// Resolves the download directory using the precedence documented
    /// on [`AddTorrentParams`] and the category registry, then delegates
    /// to the magnet or bytes-add path as appropriate. Returns the v1
    /// info hash of the new torrent.
    ///
    /// # Errors
    ///
    /// - [`Error::CategoryNotFound`](crate::Error::CategoryNotFound) when
    ///   `params.category` names a category that is not in the registry.
    /// - [`Error::TorrentBeingRemoved`](crate::Error::TorrentBeingRemoved)
    ///   when another task is currently deleting files for the same info
    ///   hash (mapped to 409 Conflict by the qBt API).
    /// - Propagates parsing errors for bad magnet URIs / .torrent bytes.
    /// - Propagates the existing `DuplicateTorrent` / `SessionAtCapacity`
    ///   error shapes unchanged.
    pub async fn add_torrent(&self, params: AddTorrentParams) -> crate::Result<Id20> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::AddTorrentM170 {
                params: Box::new(params),
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Create a new qBt-compat category (M170).
    ///
    /// # Errors
    ///
    /// Returns [`CategoryError`](crate::CategoryError) on name validation
    /// failure, duplicate name, or persistence I/O error.
    pub async fn create_category(
        &self,
        name: String,
        save_path: PathBuf,
    ) -> Result<(), crate::category_manager::CategoryError> {
        let (tx, rx) = oneshot::channel();
        if self
            .cmd_tx
            .send(SessionCommand::CreateCategory {
                name,
                save_path,
                reply: tx,
            })
            .await
            .is_err()
        {
            return Err(crate::category_manager::CategoryError::Persistence(
                std::io::Error::other("session shutting down"),
            ));
        }
        rx.await.unwrap_or_else(|_| {
            Err(crate::category_manager::CategoryError::Persistence(
                std::io::Error::other("session shutting down"),
            ))
        })
    }

    /// Update the `save_path` on an existing category (M170).
    ///
    /// # Errors
    ///
    /// Returns [`CategoryError::NotFound`](crate::CategoryError::NotFound)
    /// when the category does not exist, plus the same persistence /
    /// validation error shapes as [`create_category`](Self::create_category).
    pub async fn edit_category(
        &self,
        name: String,
        save_path: PathBuf,
    ) -> Result<(), crate::category_manager::CategoryError> {
        let (tx, rx) = oneshot::channel();
        if self
            .cmd_tx
            .send(SessionCommand::EditCategory {
                name,
                save_path,
                reply: tx,
            })
            .await
            .is_err()
        {
            return Err(crate::category_manager::CategoryError::Persistence(
                std::io::Error::other("session shutting down"),
            ));
        }
        rx.await.unwrap_or_else(|_| {
            Err(crate::category_manager::CategoryError::Persistence(
                std::io::Error::other("session shutting down"),
            ))
        })
    }

    /// Remove zero or more categories (M170). Unknown names are tolerated
    /// (qBt behaviour). Returns the names that were actually removed.
    /// After removal, any torrent assigned to a removed category has its
    /// `category` label cleared and its resume data marked dirty.
    pub async fn remove_categories(&self, names: Vec<String>) -> Vec<String> {
        let (tx, rx) = oneshot::channel();
        if self
            .cmd_tx
            .send(SessionCommand::RemoveCategories { names, reply: tx })
            .await
            .is_err()
        {
            return Vec::new();
        }
        rx.await.unwrap_or_default()
    }

    /// Snapshot the current category list (M170).
    pub async fn list_categories(&self) -> Vec<crate::category_manager::CategoryMetadata> {
        let (tx, rx) = oneshot::channel();
        if self
            .cmd_tx
            .send(SessionCommand::ListCategories { reply: tx })
            .await
            .is_err()
        {
            return Vec::new();
        }
        rx.await.unwrap_or_default()
    }

    /// List every tag name currently in the registry (M171). Sorted.
    pub async fn list_tags(&self) -> Vec<String> {
        let (tx, rx) = oneshot::channel();
        if self
            .cmd_tx
            .send(SessionCommand::ListTags { reply: tx })
            .await
            .is_err()
        {
            return Vec::new();
        }
        rx.await.unwrap_or_default()
    }

    /// Create a batch of tags (M171). Returns one
    /// `Result<(), TagError>` per requested name so the caller can
    /// distinguish which names already existed and which were newly
    /// created. Persistence is best-effort on success; any partial
    /// persistence failure warns but does not change the per-call reply.
    pub async fn create_tags(
        &self,
        names: Vec<String>,
    ) -> Vec<Result<(), crate::tag_manager::TagError>> {
        let (tx, rx) = oneshot::channel();
        if self
            .cmd_tx
            .send(SessionCommand::CreateTags { names, reply: tx })
            .await
            .is_err()
        {
            return Vec::new();
        }
        rx.await.unwrap_or_default()
    }

    /// Delete a batch of tags (M171). Returns the subset of names that
    /// were actually present at call time (unknown names are silently
    /// skipped, matching qBt's idempotent `deleteTags`).
    pub async fn delete_tags(&self, names: Vec<String>) -> Vec<String> {
        let (tx, rx) = oneshot::channel();
        if self
            .cmd_tx
            .send(SessionCommand::DeleteTags { names, reply: tx })
            .await
            .is_err()
        {
            return Vec::new();
        }
        rx.await.unwrap_or_default()
    }

    /// Add the given tags to each torrent in `hashes` (M171).
    /// Idempotent — tags that a torrent already has are left alone.
    /// Unknown info hashes are silently skipped.
    ///
    /// # Errors
    ///
    /// Returns [`Error::Shutdown`](crate::Error::Shutdown) if the
    /// session's command channel has closed.
    pub async fn add_tags_to_torrents(
        &self,
        hashes: Vec<Id20>,
        tags: Vec<String>,
    ) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::AddTagsToTorrents {
                info_hashes: hashes,
                tags,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Remove the given tags from each torrent in `hashes` (M171).
    /// Unknown info hashes are silently skipped.
    ///
    /// # Errors
    ///
    /// Returns [`Error::Shutdown`](crate::Error::Shutdown) if the
    /// session's command channel has closed.
    pub async fn remove_tags_from_torrents(
        &self,
        hashes: Vec<Id20>,
        tags: Vec<String>,
    ) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::RemoveTagsFromTorrents {
                info_hashes: hashes,
                tags,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Remove a torrent and delete its on-disk files (M170,
    /// `deleteFiles=true`).
    ///
    /// Pauses the torrent, closes storage handles, then dispatches a
    /// `spawn_blocking` file-removal walk via
    /// [`delete_torrent_files_sync`](irontide_storage::delete_torrent_files_sync).
    /// The info hash is placed in a deletion grace set for the duration of
    /// the walk; concurrent calls to [`add_torrent`](Self::add_torrent)
    /// with the same hash return [`Error::TorrentBeingRemoved`](crate::Error::TorrentBeingRemoved).
    ///
    /// # Errors
    ///
    /// Returns [`Error::TorrentNotFound`](crate::Error::TorrentNotFound)
    /// if the info hash is not in the session. I/O failures during file
    /// removal are logged and swallowed — always returns `Ok(())` when
    /// the torrent is found.
    pub async fn remove_torrent_with_files(&self, info_hash: Id20) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::RemoveTorrentWithFiles {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Add a torrent with an optional per-torrent download directory override.
    ///
    /// # Errors
    ///
    /// Returns an error if the torrent cannot be added or the session is shut down.
    pub async fn add_torrent_with_dir(
        &self,
        meta: irontide_core::TorrentMeta,
        storage: Option<Arc<dyn TorrentStorage>>,
        download_dir: Option<PathBuf>,
    ) -> crate::Result<Id20> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::AddTorrent {
                meta: Box::new(meta),
                storage,
                download_dir,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Add a torrent from a magnet link (metadata fetched via BEP 9).
    ///
    /// # Errors
    ///
    /// Returns an error if the torrent cannot be added or the session is shut down.
    pub async fn add_magnet(&self, magnet: Magnet) -> crate::Result<Id20> {
        self.add_magnet_with_dir(magnet, None).await
    }

    /// Add a magnet link with an optional per-torrent download directory override.
    ///
    /// # Errors
    ///
    /// Returns an error if the torrent cannot be added or the session is shut down.
    pub async fn add_magnet_with_dir(
        &self,
        magnet: Magnet,
        download_dir: Option<PathBuf>,
    ) -> crate::Result<Id20> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::AddMagnet {
                magnet,
                download_dir,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Remove a torrent from the session.
    ///
    /// # Errors
    ///
    /// Returns an error if the torrent is not found or the session is shut down.
    pub async fn remove_torrent(&self, info_hash: Id20) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::RemoveTorrent {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Pause a torrent.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn pause_torrent(&self, info_hash: Id20) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::PauseTorrent {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Resume a paused torrent.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn resume_torrent(&self, info_hash: Id20) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::ResumeTorrent {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Force-resume a torrent, bypassing queue limits.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn force_resume_torrent(&self, info_hash: Id20) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::ForceResumeTorrent {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Set a per-torrent seed ratio limit override (`None` = use session default).
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn set_torrent_seed_ratio(
        &self,
        info_hash: Id20,
        limit: Option<f64>,
    ) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::SetTorrentSeedRatio {
                info_hash,
                limit,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Get statistics for a specific torrent.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn torrent_stats(&self, info_hash: Id20) -> crate::Result<TorrentStats> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::TorrentStats {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Snapshot per-peer cumulative unchoke duration for the given torrent.
    ///
    /// Returns `Ok(Some(map))` when the torrent exists. Each entry is the
    /// total time we (this session) had that peer unchoked over the
    /// torrent's lifetime, including reconnects (durations are flushed
    /// into a per-(SocketAddr × torrent) map on disconnect and re-merged
    /// here at query time).
    ///
    /// Returns `Ok(None)` when the torrent is unknown to this session —
    /// the explicit contract distinguishes "torrent missing" from "exists
    /// but no peers were ever unchoked".
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn peer_unchoke_durations(
        &self,
        info_hash: Id20,
    ) -> crate::Result<Option<std::collections::HashMap<SocketAddr, std::time::Duration>>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::QueryUnchokeDurations {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Get metadata info for a specific torrent.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn torrent_info(&self, info_hash: Id20) -> crate::Result<TorrentInfo> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::TorrentInfo {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// List all active torrent info hashes.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn list_torrents(&self) -> crate::Result<Vec<Id20>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::ListTorrents { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Get aggregate session statistics.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn session_stats(&self) -> crate::Result<SessionStats> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::SessionStats { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Collect per-torrent and per-peer debug state for diagnosing dispatch
    /// throughput regressions (M187).
    ///
    /// Individual torrents that do not respond within 500 ms are skipped so
    /// the endpoint always returns partial results rather than failing.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn debug_state(&self) -> crate::Result<crate::types::DebugState> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::DebugState { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        // Use a generous 5 s overall timeout — the per-torrent timeouts are
        // 500 ms inside the actor, but with many torrents the total can add up.
        tokio::time::timeout(std::time::Duration::from_secs(5), rx)
            .await
            .map_err(|_| crate::Error::Shutdown)?
            .map_err(|_| crate::Error::Shutdown)
    }

    /// Subscribe to all alerts passing the session-level mask.
    #[must_use]
    pub fn subscribe(&self) -> broadcast::Receiver<Alert> {
        self.alert_tx.subscribe()
    }

    /// Subscribe with per-subscriber category filtering.
    #[must_use]
    pub fn subscribe_filtered(&self, filter: AlertCategory) -> AlertStream {
        AlertStream::new(self.alert_tx.subscribe(), filter)
    }

    /// Trigger an immediate session stats snapshot and alert.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn post_session_stats(&self) -> crate::Result<()> {
        self.cmd_tx
            .send(SessionCommand::PostSessionStats)
            .await
            .map_err(|_| crate::Error::Shutdown)
    }

    /// Access the shared atomic counters (read-only handle).
    #[must_use]
    pub fn counters(&self) -> &Arc<crate::stats::SessionCounters> {
        &self.counters
    }

    /// Atomically update the session-level alert mask.
    pub fn set_alert_mask(&self, mask: AlertCategory) {
        self.alert_mask.store(mask.bits(), Ordering::Relaxed);
    }

    /// Read the current session-level alert mask.
    #[must_use]
    pub fn alert_mask(&self) -> AlertCategory {
        AlertCategory::from_bits_truncate(self.alert_mask.load(Ordering::Relaxed))
    }

    /// Add peers to a specific torrent by info hash.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn add_peers(
        &self,
        info_hash: Id20,
        peers: Vec<SocketAddr>,
        source: crate::peer_state::PeerSource,
    ) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::AddPeers {
                info_hash,
                peers,
                source,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Gracefully shut down the session and all torrents.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn shutdown(&self) -> crate::Result<()> {
        // Timeout prevents hang if SessionActor is processing a heavy batch
        let _ = tokio::time::timeout(
            std::time::Duration::from_secs(10),
            self.cmd_tx.send(SessionCommand::Shutdown),
        )
        .await;
        Ok(())
    }

    /// Save resume data for a specific torrent.
    ///
    /// # Errors
    ///
    /// Returns an error if the I/O operation fails.
    pub async fn save_torrent_resume_data(
        &self,
        info_hash: Id20,
    ) -> crate::Result<irontide_core::FastResumeData> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::SaveTorrentResumeData {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Save full session state (all torrent resume data + DHT node cache).
    ///
    /// # Errors
    ///
    /// Returns an error if the I/O operation fails.
    pub async fn save_session_state(&self) -> crate::Result<crate::persistence::SessionState> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::SaveSessionState { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Load and restore torrents from per-torrent resume files on disk.
    ///
    /// Scans the resume directory for `.resume` files, deserializes each one,
    /// reconstructs the torrent metadata, and re-adds it to the session. For
    /// resolved torrents (with stored info dict), the piece bitmap is restored.
    /// Unresolved magnets are re-added as magnet links.
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Shutdown`] if the session has been shut down.
    pub async fn load_resume_state(&self) -> crate::Result<ResumeLoadResult> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::LoadResumeState { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Save per-torrent resume files for all dirty torrents.
    ///
    /// Iterates every torrent in the session, checks the `need_save_resume`
    /// dirty flag, serializes resume data to disk, and clears the flag.
    /// Returns the number of files written.
    ///
    /// # Errors
    ///
    /// Returns [`Error::Shutdown`] if the session actor has stopped.
    pub async fn save_resume_state(&self) -> crate::Result<usize> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::SaveResumeState { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Get the queue position of a torrent. Returns -1 if not auto-managed.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn queue_position(&self, info_hash: Id20) -> crate::Result<i32> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::QueuePosition {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Set the absolute queue position of a torrent. Shifts other torrents.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn set_queue_position(&self, info_hash: Id20, pos: i32) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::SetQueuePosition {
                info_hash,
                pos,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Move a torrent one position up (lower number = higher priority).
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn queue_position_up(&self, info_hash: Id20) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::QueuePositionUp {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Move a torrent one position down.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn queue_position_down(&self, info_hash: Id20) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::QueuePositionDown {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Move a torrent to position 0 (highest priority).
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn queue_position_top(&self, info_hash: Id20) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::QueuePositionTop {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Move a torrent to the last position (lowest priority).
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn queue_position_bottom(&self, info_hash: Id20) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::QueuePositionBottom {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Ban a peer IP session-wide. All torrents will disconnect and refuse this IP.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn ban_peer(&self, ip: IpAddr) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::BanPeer { ip, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Remove a ban and clear strikes for an IP. Returns `true` if the IP was banned.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn unban_peer(&self, ip: IpAddr) -> crate::Result<bool> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::UnbanPeer { ip, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Replace the session-wide IP filter. Connected peers that are now blocked will
    /// be refused on subsequent connection attempts.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn set_ip_filter(&self, filter: crate::ip_filter::IpFilter) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::SetIpFilter { filter, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Get a clone of the current IP filter.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn ip_filter(&self) -> crate::Result<crate::ip_filter::IpFilter> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::GetIpFilter { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Get a clone of the current session settings.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn settings(&self) -> crate::Result<Settings> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::GetSettings { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Apply new settings at runtime.
    ///
    /// Validates the settings, updates rate limiters immediately, and stores
    /// the new settings. Sub-actor reconfiguration (disk, DHT, NAT) takes
    /// effect on next session restart for the fields that remain in
    /// `restart_required`; `listen_port`, `dht`, `lsd` are now applied
    /// live (M173 Lane B B10).
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::ConcurrentReconfig`] if another
    /// `apply_settings` / `apply_settings_classified` call is still in
    /// flight (M173 Lane B B11). Caller should retry shortly.
    pub async fn apply_settings(&self, settings: Settings) -> crate::Result<()> {
        let _guard = self
            .reconfig_in_flight
            .try_lock()
            .ok_or(crate::Error::ConcurrentReconfig)?;
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::ApplySettings {
                settings: Box::new(settings),
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Apply new settings and return a classification of which fields took
    /// effect immediately versus which require a session restart (M171 D3.5).
    ///
    /// Identical behaviour to [`apply_settings`](Self::apply_settings), but
    /// the return value lets callers surface the "restart to apply" UX —
    /// specifically the `X-IronTide-Restart-Pending` response header on the
    /// qBt v2 `setPreferences` endpoint and the GUI restart-banner.
    ///
    /// M173 Lane B (B11): the in-flight guard is acquired BEFORE the
    /// snapshot read, so concurrent callers cannot race the
    /// read-modify-write. The second caller hits
    /// [`crate::Error::ConcurrentReconfig`].
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::ConcurrentReconfig`] if another reconfig
    /// is still in flight. Returns [`crate::Error::InvalidSettings`] if
    /// the patch fails validation. Returns [`crate::Error::Shutdown`]
    /// if the session has shut down.
    pub async fn apply_settings_classified(
        &self,
        settings: Settings,
    ) -> crate::Result<AppliedSettings> {
        let _guard = self
            .reconfig_in_flight
            .try_lock()
            .ok_or(crate::Error::ConcurrentReconfig)?;
        // Snapshot AFTER acquiring the guard so the classification is
        // computed against a stable pre-call state.
        let snapshot = self.settings().await?;
        let immediate = classify_immediate(&snapshot, &settings);
        let restart_required = classify_restart_required(&snapshot, &settings);
        // Inner apply_settings tries to re-acquire the guard. To avoid
        // a self-deadlock, we send the command directly here rather
        // than calling self.apply_settings(), which would error out
        // with ConcurrentReconfig because we already hold the lock.
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::ApplySettings {
                settings: Box::new(settings),
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)??;
        Ok(AppliedSettings {
            immediate,
            restart_required,
        })
    }

    /// Get the current DHT routing-table size, summed across IPv4 and IPv6
    /// instances (M171 D4).
    ///
    /// Returns `Ok(0)` when DHT is disabled for both address families, or
    /// when neither instance has bootstrapped yet. Wired into the qBt v2
    /// `transferInfo.dht_nodes` field and the DHT pseudo-tracker's
    /// `num_peers` column on `/api/v2/torrents/trackers`.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn dht_node_count(&self) -> crate::Result<usize> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::DhtNodeCount { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Get the list of currently banned peer IPs.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn banned_peers(&self) -> crate::Result<Vec<IpAddr>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::BannedPeers { reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    /// Move a torrent's data files to a new download directory.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn move_torrent_storage(
        &self,
        info_hash: Id20,
        new_path: std::path::PathBuf,
    ) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::MoveTorrentStorage {
                info_hash,
                new_path,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Opens a file stream for sequential reading (`AsyncRead` + `AsyncSeek`).
    ///
    /// The returned [`FileStream`](crate::streaming::FileStream) reads data from
    /// a specific file within a torrent, blocking on pieces that haven't been
    /// downloaded yet.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn open_file(
        &self,
        info_hash: Id20,
        file_index: usize,
    ) -> crate::Result<crate::streaming::FileStream> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::OpenFile {
                info_hash,
                file_index,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Force all trackers for a torrent to re-announce immediately.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn force_reannounce(&self, info_hash: Id20) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::ForceReannounce {
                info_hash,
                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 for a torrent.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn tracker_list(
        &self,
        info_hash: Id20,
    ) -> crate::Result<Vec<crate::tracker_manager::TrackerInfo>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::TrackerList {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// M178 Lane B3 / TODO-2: cumulative count of UNIQUE peers received via
    /// PEX (BEP 11) for this torrent since the actor started.
    ///
    /// # Errors
    /// - [`Error::TorrentNotFound`](crate::Error::TorrentNotFound) when
    ///   the hash is unknown.
    /// - [`Error::Shutdown`](crate::Error::Shutdown) on actor shutdown.
    pub async fn pex_peer_count(&self, info_hash: Id20) -> crate::Result<usize> {
        let counts = self.peer_source_counts(info_hash).await?;
        Ok(counts.0)
    }

    /// M178 Lane B3 / TODO-2: cumulative count of UNIQUE peers received via
    /// LSD (BEP 14) multicast for this torrent since the actor started.
    ///
    /// # Errors
    /// - [`Error::TorrentNotFound`](crate::Error::TorrentNotFound) when
    ///   the hash is unknown.
    /// - [`Error::Shutdown`](crate::Error::Shutdown) on actor shutdown.
    pub async fn lsd_peer_count(&self, info_hash: Id20) -> crate::Result<usize> {
        let counts = self.peer_source_counts(info_hash).await?;
        Ok(counts.1)
    }

    async fn peer_source_counts(&self, info_hash: Id20) -> crate::Result<(usize, usize)> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::GetPeerSourceCounts {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// M178 Lane C: per-URL web-seed stats snapshot for the qBt v2
    /// webseeds endpoint and the GUI HTTP Sources tab.
    ///
    /// # Errors
    /// - [`Error::TorrentNotFound`](crate::Error::TorrentNotFound) when
    ///   the hash is unknown.
    /// - [`Error::Shutdown`](crate::Error::Shutdown) on actor shutdown.
    pub async fn web_seed_stats(
        &self,
        info_hash: Id20,
    ) -> crate::Result<Vec<irontide_core::WebSeedStats>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::GetWebSeedStats {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// M171 Lane B: list the web seed URLs (BEP 19 + BEP 17 merged) for a torrent.
    ///
    /// BEP 19 `url-list` URLs come first, followed by BEP 17 `httpseeds`
    /// URLs — the wire order. Returns an empty vec when the torrent's
    /// metadata has not yet been fetched (magnet still resolving the
    /// info dictionary).
    ///
    /// # Errors
    /// - [`Error::TorrentNotFound`](crate::Error::TorrentNotFound) if the
    ///   info-hash is unknown.
    /// - [`Error::Shutdown`](crate::Error::Shutdown) if the session's
    ///   command channel has closed.
    pub async fn get_web_seeds(&self, info_hash: Id20) -> crate::Result<Vec<String>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::GetWebSeeds {
                info_hash,
                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 for a torrent.
    ///
    /// Returns a `Vec<u8>` one byte per piece — `0` = not downloaded,
    /// `1` = downloading, `2` = downloaded + checked. An empty vec is
    /// returned when metadata hasn't resolved yet (magnet still fetching
    /// the info dictionary) — callers should map that to a 404.
    ///
    /// # Errors
    /// - [`Error::TorrentNotFound`](crate::Error::TorrentNotFound) if the
    ///   info-hash is unknown.
    /// - [`Error::Shutdown`](crate::Error::Shutdown) if the session's
    ///   command channel has closed.
    pub async fn get_piece_states(&self, info_hash: Id20) -> crate::Result<Vec<u8>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::GetPieceStates {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// M171 Lane B: paginated piece hash list for a torrent.
    ///
    /// v1 / hybrid torrents return SHA-1 hashes (40-char hex strings);
    /// v2-only torrents return SHA-256 hashes (64-char hex strings).
    /// `offset` and `limit` are clamped to the real hash count inside
    /// the actor — callers can pass arbitrary values without overflow
    /// concerns. An empty vec is returned when metadata hasn't resolved
    /// yet — callers should map that to a 404.
    ///
    /// # Errors
    /// - [`Error::TorrentNotFound`](crate::Error::TorrentNotFound) if the
    ///   info-hash is unknown.
    /// - [`Error::Shutdown`](crate::Error::Shutdown) if the session's
    ///   command channel has closed.
    pub async fn get_piece_hashes(
        &self,
        info_hash: Id20,
        offset: u32,
        limit: u32,
    ) -> crate::Result<Vec<String>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::GetPieceHashes {
                info_hash,
                offset,
                limit,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

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

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

    /// Get the current per-file priorities for a torrent.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn file_priorities(
        &self,
        info_hash: Id20,
    ) -> crate::Result<Vec<irontide_core::FilePriority>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::FilePriorities {
                info_hash,
                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,
        info_hash: Id20,
        bytes_per_sec: u64,
    ) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::SetDownloadLimit {
                info_hash,
                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, info_hash: Id20, bytes_per_sec: u64) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::SetUploadLimit {
                info_hash,
                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, info_hash: Id20) -> crate::Result<u64> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::DownloadLimit {
                info_hash,
                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, info_hash: Id20) -> crate::Result<u64> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::UploadLimit {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

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

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

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

    /// Enable or disable user-requested seed-only mode for a torrent (M159).
    ///
    /// When `enabled` is `true`, the engine stops scheduling new block requests
    /// and cancels all in-flight requests for the torrent, but continues to
    /// serve uploads to interested peers. This is distinct from "naturally
    /// seeding" (all pieces downloaded): it represents an explicit user toggle
    /// layered on top of the download state.
    ///
    /// Toggling back to `false` resumes normal piece scheduling.
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::TorrentNotFound`] if `info_hash` is not registered
    /// in the session, or [`crate::Error::Shutdown`] if the session actor has
    /// terminated.
    pub async fn set_seed_mode(&self, info_hash: Id20, enabled: bool) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::SetSeedMode {
                info_hash,
                enabled,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Add a new tracker URL to a torrent.
    ///
    /// 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, info_hash: Id20, url: String) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::AddTracker {
                info_hash,
                url,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

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

    /// Trigger a full piece verification (force recheck) for a torrent.
    ///
    /// Clears all piece completion data, re-verifies every piece, and
    /// transitions to `Seeding` or `Downloading` depending on the result.
    /// Returns after the recheck is complete.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn force_recheck(&self, info_hash: Id20) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::ForceRecheck {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Rename a file within a 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,
        info_hash: Id20,
        file_index: usize,
        new_name: String,
    ) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::RenameFile {
                info_hash,
                file_index,
                new_name,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.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, info_hash: Id20, limit: usize) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::SetMaxConnections {
                info_hash,
                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, info_hash: Id20) -> crate::Result<usize> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::MaxConnections {
                info_hash,
                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, info_hash: Id20, limit: usize) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::SetMaxUploads {
                info_hash,
                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, info_hash: Id20) -> crate::Result<usize> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::MaxUploads {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

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

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

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

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

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

    /// Get the full v1 metainfo for a torrent.
    ///
    /// 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,
        info_hash: Id20,
    ) -> crate::Result<Option<irontide_core::TorrentMetaV1>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::TorrentFile {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Get the full v2 metainfo for a torrent.
    ///
    /// 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,
        info_hash: Id20,
    ) -> crate::Result<Option<irontide_core::TorrentMetaV2>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::TorrentFileV2 {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// **TEST-ONLY.** Synchronously inject an info-dict into a torrent's
    /// `MetadataDownloader` queue. Returns only after the actor has processed
    /// the message. Reuses the existing M147 internal handler at
    /// `torrent.rs:3665` via a separate test-only `TorrentCommand` variant
    /// (the production [`TorrentHandle::send_pre_resolved_metadata`] is
    /// fire-and-forget and stays unchanged).
    ///
    /// Introduced in v0.173.2 as a cross-crate test escape hatch for the
    /// `irontide-api` A9 HTTP integration test — it lets tests exercise the
    /// post-metadata HTTP surface without spinning up real peers.
    ///
    /// # Errors
    /// - [`crate::Error::TorrentNotFound`] if `info_hash` is not registered.
    /// - [`crate::Error::Shutdown`] if the session or torrent command
    ///   channel is closed.
    #[cfg(feature = "test-util")]
    pub async fn debug_inject_metadata(
        &self,
        info_hash: Id20,
        info_bytes: Vec<u8>,
    ) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::TestInjectMetadata {
                info_hash,
                info_bytes,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Force an immediate DHT announce for a torrent.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn force_dht_announce(&self, info_hash: Id20) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::ForceDhtAnnounce {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Force an immediate LSD (Local Service Discovery) announce for a torrent.
    ///
    /// LSD is a session-level component — this does not go through the torrent actor.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn force_lsd_announce(&self, info_hash: Id20) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::ForceLsdAnnounce {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Read all data for a specific piece from disk.
    ///
    /// # Errors
    ///
    /// Returns an error if the data cannot be parsed or I/O fails.
    pub async fn read_piece(&self, info_hash: Id20, index: u32) -> crate::Result<bytes::Bytes> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::ReadPiece {
                info_hash,
                index,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

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

    /// Check if a torrent exists in the session and its handle is still valid.
    pub async fn is_valid(&self, info_hash: Id20) -> bool {
        let (tx, rx) = oneshot::channel();
        if self
            .cmd_tx
            .send(SessionCommand::IsValid {
                info_hash,
                reply: tx,
            })
            .await
            .is_err()
        {
            return false;
        }
        rx.await.unwrap_or(false)
    }

    /// Clear the error state on a torrent, resuming it if it was paused due to error.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn clear_error(&self, info_hash: Id20) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::ClearError {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Get per-file open/mode status for a torrent.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn file_status(
        &self,
        info_hash: Id20,
    ) -> crate::Result<Vec<crate::types::FileStatus>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::FileStatus {
                info_hash,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

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

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

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

    /// Immediately initiate a peer connection for a torrent.
    ///
    /// # Errors
    ///
    /// Returns an error if the connection or binding fails.
    pub async fn connect_peer(&self, info_hash: Id20, addr: SocketAddr) -> crate::Result<()> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::ConnectPeer {
                info_hash,
                addr,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Store an immutable item in the DHT (BEP 44).
    ///
    /// Returns the SHA-1 target hash of the stored value.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn dht_put_immutable(&self, value: Vec<u8>) -> crate::Result<Id20> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::DhtPutImmutable { value, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Retrieve an immutable item from the DHT (BEP 44).
    ///
    /// Returns `Some(value)` if found, `None` otherwise.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn dht_get_immutable(&self, target: Id20) -> crate::Result<Option<Vec<u8>>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::DhtGetImmutable { target, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Store a mutable item in the DHT (BEP 44).
    ///
    /// `keypair_bytes` is a 32-byte Ed25519 seed. Returns the target hash.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn dht_put_mutable(
        &self,
        keypair_bytes: [u8; 32],
        value: Vec<u8>,
        seq: i64,
        salt: Vec<u8>,
    ) -> crate::Result<Id20> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::DhtPutMutable {
                keypair_bytes,
                value,
                seq,
                salt,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    /// Retrieve a mutable item from the DHT (BEP 44).
    ///
    /// Returns `Some((value, seq))` if found, `None` otherwise.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is shut down.
    pub async fn dht_get_mutable(
        &self,
        public_key: [u8; 32],
        salt: Vec<u8>,
    ) -> crate::Result<Option<(Vec<u8>, i64)>> {
        let (tx, rx) = oneshot::channel();
        self.cmd_tx
            .send(SessionCommand::DhtGetMutable {
                public_key,
                salt,
                reply: tx,
            })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)?
    }

    // ── M121: Convenience API for future HTTP endpoints ──

    /// List all torrents as lightweight summaries.
    ///
    /// M245 A1: reads the lock-free published [`SessionSnapshot`] — a single
    /// `Arc` load, no per-torrent command round-trips (the pre-M245 body issued
    /// one `stats()` round-trip per torrent on the actor's recv loop).
    /// Membership is read-after-write consistent (the actor patches it eagerly
    /// on add/remove); sampled stats are eventually-consistent to one stats
    /// tick. Summaries are ascending by info-hash.
    ///
    /// # Errors
    ///
    /// Never errors — the snapshot read is infallible. The `Result` is retained
    /// for facade API stability (M245 D5).
    #[allow(
        clippy::unused_async,
        reason = "async + Result signature kept for facade API stability (M245 D5); the snapshot read is synchronous and infallible"
    )]
    pub async fn list_torrent_summaries(&self) -> crate::Result<Vec<TorrentSummary>> {
        Ok(self.snapshot.load().summaries())
    }

    /// Add a torrent from a magnet URI string.
    ///
    /// Parses the URI, extracts info hashes, and adds the magnet to the session.
    /// Returns the info hashes (v1 and/or v2) for the added torrent.
    ///
    /// # Errors
    ///
    /// Returns an error if the torrent cannot be added or the session is shut down.
    pub async fn add_magnet_uri(&self, uri: &str) -> crate::Result<irontide_core::InfoHashes> {
        let magnet = irontide_core::Magnet::parse(uri)?;
        let info_hashes = magnet.info_hashes.clone();
        self.add_magnet(magnet).await?;
        Ok(info_hashes)
    }

    /// Add a torrent from raw .torrent file bytes.
    ///
    /// Auto-detects v1, v2, or hybrid format. Returns the info hashes for the
    /// added torrent.
    ///
    /// # Errors
    ///
    /// Returns an error if the torrent cannot be added or the session is shut down.
    pub async fn add_torrent_bytes(
        &self,
        bytes: &[u8],
    ) -> crate::Result<irontide_core::InfoHashes> {
        let meta = irontide_core::torrent_from_bytes_any(bytes)?;
        let info_hashes = meta.info_hashes();
        self.add_torrent_with_meta(meta, None).await?;
        Ok(info_hashes)
    }
}

// ---------------------------------------------------------------------------
// SessionSnapshot — M245 A1 published lock-free read-model
// ---------------------------------------------------------------------------

/// Lock-free read-model published by the [`SessionActor`] (M245 A1).
///
/// **Consistency contract (hybrid):**
/// - *Membership* (which torrents exist) is **read-after-write consistent** — the
///   actor patches this map synchronously on add/remove, so a torrent is visible
///   the instant its add commits.
/// - *Sampled stats* (rates, progress, peer counts) are **eventually-consistent to
///   one stats tick** — the same skew any sampled counter already carries.
///
/// Held in an [`arc_swap::ArcSwap`] so read-only callers clone an `Arc` snapshot
/// without touching the mutating command mailbox.
#[derive(Debug, Default, Clone)]
pub struct SessionSnapshot {
    by_id: std::collections::BTreeMap<Id20, TorrentSummary>,
}

impl SessionSnapshot {
    /// All torrent summaries, ascending by info-hash. Owned clone — callers that
    /// only need the count or a scan can use [`SessionSnapshot::as_map`] instead.
    #[must_use]
    pub fn summaries(&self) -> Vec<TorrentSummary> {
        self.by_id.values().cloned().collect()
    }

    /// Internal: the keyed map, for the actor's O(log n) membership patches
    /// (eager add/remove) and the per-tick stats refresh carry-forward.
    pub(crate) fn as_map(&self) -> &std::collections::BTreeMap<Id20, TorrentSummary> {
        &self.by_id
    }

    /// Internal: build a snapshot from a patched map (actor-side only).
    pub(crate) fn from_map(by_id: std::collections::BTreeMap<Id20, TorrentSummary>) -> Self {
        Self { by_id }
    }
}

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

struct SessionActor {
    settings: Settings,
    /// M223 — self-loopback sender, so the spawned `handle_add_torrent`
    /// prep tasks can route their `CommitAddTorrent` result back through
    /// the same recv loop that owns the mutating session state.
    /// Cloned from the same sender the `SessionHandle` holds; carries
    /// the M221.1a timing wrapper so the commit hop is observable in
    /// the `queue_wait_ms` / `handler_ms` telemetry.
    commit_tx: SessionCmdSender,
    torrents: HashMap<Id20, TorrentEntry>,
    /// M245 A1 — the published read-model the [`SessionHandle`] reads from.
    /// Same `ArcSwap` the handle holds (cloned at construction). The actor is
    /// the SOLE writer: an eager membership patch on every add/remove (so
    /// reads are read-after-write consistent) plus a sampled-stats refresh
    /// derived from the per-tick fan-out in [`make_session_stats`](Self::make_session_stats).
    snapshot: Arc<arc_swap::ArcSwap<SessionSnapshot>>,
    dht_v4: Option<DhtHandle>,
    dht_v6: Option<DhtHandle>,
    /// M173 Lane B (B6): broadcast surface for runtime `DhtHandle`
    /// replacement. `TorrentActor` consumers borrow a `DhtReceiver`
    /// instead of cloning `DhtHandle`, so a session-side DHT restart
    /// (B11) propagates to every torrent on the next `borrow()`.
    /// Initialised once at session start with the same value as the
    /// `dht_v4`/`dht_v6` clones; never written until B11.
    dht_v4_broadcast: irontide_dht::DhtBroadcast,
    dht_v6_broadcast: irontide_dht::DhtBroadcast,
    lsd: Option<crate::lsd::LsdHandle>,
    lsd_peers_rx: Option<mpsc::Receiver<(Id20, SocketAddr)>>,
    cmd_rx: mpsc::Receiver<(tokio::time::Instant, SessionCommand)>,
    alert_tx: broadcast::Sender<Alert>,
    alert_mask: Arc<AtomicU32>,
    global_upload_bucket: SharedBucket,
    global_download_bucket: SharedBucket,
    utp_socket: Option<irontide_utp::UtpSocket>,
    utp_socket_v6: Option<irontide_utp::UtpSocket>,
    nat: Option<irontide_nat::NatHandle>,
    nat_events_rx: Option<mpsc::Receiver<irontide_nat::NatEvent>>,
    ban_manager: SharedBanManager,
    ip_filter: SharedIpFilter,
    disk_manager: crate::disk::DiskManagerHandle,
    #[allow(dead_code)]
    disk_actor_handle: tokio::task::JoinHandle<()>,
    /// External IP discovered via NAT traversal or configured manually (BEP 40).
    external_ip: Option<std::net::IpAddr>,
    /// BEP 42: External IP consensus from DHT v4 KRPC responses.
    dht_v4_ip_rx: Option<mpsc::Receiver<std::net::IpAddr>>,
    /// BEP 42: External IP consensus from DHT v6 KRPC responses.
    dht_v6_ip_rx: Option<mpsc::Receiver<std::net::IpAddr>>,
    /// Registered extension plugins, shared with all `TorrentActors`.
    plugins: Arc<Vec<Box<dyn crate::extension::ExtensionPlugin>>>,
    /// I2P SAM session (if enabled).
    sam_session: Option<Arc<crate::i2p::SamSession>>,
    /// SSL manager for SSL torrent certificate handling (M42).
    ssl_manager: Option<Arc<crate::ssl_manager::SslManager>>,
    /// SSL/TLS TCP listener (separate port from the main listener) (M42).
    ssl_listener: Option<Box<dyn crate::transport::TransportListener>>,
    /// Channel receiving pre-validated inbound connections from the `ListenerTask` (M114).
    validated_conn_rx: mpsc::Receiver<crate::listener::IdentifiedConnection>,
    /// Registry of active info hashes shared with the `ListenerTask` (M114).
    /// INVARIANT: Must be updated whenever torrents are added/removed.
    /// If a new torrent-add path is added without updating this registry,
    /// inbound connections for that torrent will be silently rejected.
    info_hash_registry: Arc<DashMap<Id20, ()>>,
    /// Handle to keep the listener task alive; dropped on session shutdown
    /// (M114). M173 Lane B (B2) replaced the bare `JoinHandle` with
    /// `ListenerHandle` so the listen-port rebind path (B4) can call
    /// `shutdown_with_timeout` for a clean port swap.
    #[allow(dead_code)] // used by Drop sequence + B4 listen-port rebind
    _listener_task: crate::listener::ListenerHandle,
    /// M224 D3: global TCP-inbound connection cap, shared with the
    /// `ListenerTask`. `-1` = unlimited. Updated atomically from
    /// `handle_apply_settings` so the listener sees the new value on the
    /// next accept without restarting the task.
    max_connections_global: Arc<std::sync::atomic::AtomicI32>,
    /// M224 D3: live TCP-inbound connection count, shared with the
    /// `ListenerTask`. Incremented at TCP accept; decremented when the
    /// `LiveConnectionGuard` attached to the accepted connection drops.
    /// Kept here so future milestones (M225 outbound, observability) can
    /// read the live count without touching the listener.
    #[allow(dead_code)] // read via the M224 G1 integration test + future M225 observability.
    live_connections: Arc<std::sync::atomic::AtomicUsize>,
    /// Shared atomic session counters (M50).
    counters: Arc<crate::stats::SessionCounters>,
    /// Network transport factory for TCP operations (M51).
    factory: Arc<crate::transport::NetworkFactory>,
    /// Shared hash pool for parallel piece verification (M96).
    hash_pool: std::sync::Arc<crate::hash_pool::HashPool>,
    /// M170: qBt-compat category registry, shared with CRUD call paths.
    category_registry: Arc<parking_lot::RwLock<crate::category_manager::CategoryRegistry>>,
    /// M171: qBt-compat tag registry, shared with CRUD call paths.
    tag_registry: Arc<parking_lot::RwLock<crate::tag_manager::TagRegistry>>,
    /// M170: info hashes currently in the `remove_torrent_with_files`
    /// grace period. Guards against fast delete-then-re-add sequences
    /// that would otherwise race the file-deletion walker.
    deletion_grace: Arc<parking_lot::Mutex<std::collections::HashSet<Id20>>>,
    /// M173 Lane B: in-flight `apply_settings` guard. Concurrent
    /// `setPreferences` calls hit `ApplyError::ConcurrentReconfig`
    /// rather than interleaving rate-limiter / listener-rebind /
    /// DHT-restart phases. Wired by B11.
    #[allow(dead_code)] // wired by B11 — concurrent setPreferences guard
    reconfig_in_flight: crate::apply::ReconfigInFlight,
    self_alert_rx: broadcast::Receiver<Alert>,
    resume_save_notify: Arc<tokio::sync::Notify>,
    /// M241 L1 / F4: single-flight guard serializing every off-loop resume save.
    /// `atomic_write` uses a fixed `<hash>.resume.tmp` temp path, so two
    /// concurrent saves of the same torrent would race that temp and corrupt the
    /// file. The periodic tick uses `try_lock_owned` (skip when busy); the
    /// `SaveResumeState` RPC + the inline shutdown save wait on it.
    resume_save_lock: Arc<tokio::sync::Mutex<()>>,
    /// M226 Step 5: live settings broadcast to the engine-side OS
    /// notification dispatcher spawned in `start_full`. Updated from
    /// `handle_apply_settings` so `notify_on_complete` /
    /// `notify_on_error` toggles take effect on the very next alert
    /// without restarting the dispatcher task.
    notification_settings_tx: tokio::sync::watch::Sender<Settings>,
    /// M226 Step 5: held alive only for its `Drop` — when the
    /// `SessionActor` ends and this field drops, the matching
    /// `oneshot::Receiver` in the dispatcher resolves and the
    /// dispatcher loop exits cleanly. Belt-and-suspenders with the
    /// `alert_tx` broadcast closure (the dispatcher also exits on
    /// `RecvError::Closed`), since `alert_tx` is held by every
    /// outstanding `SessionHandle::subscribe()` consumer and may
    /// outlive the actor.
    #[allow(dead_code)]
    notification_shutdown_tx: oneshot::Sender<()>,
    /// M226 Step 6: triggers the watched-folder dispatcher to drop
    /// its current debouncer (releasing inotify FDs) and rebuild
    /// against the new path. Pinged by `handle_apply_settings` when
    /// the `SettingsDelta` carries a change on `watched_folder` or
    /// `delete_torrent_after_add`. Separate from the Settings watch
    /// channel because rate-limit / DHT / mask changes shouldn't
    /// cause inotify churn.
    watched_folder_changed: Arc<tokio::sync::Notify>,
    /// M226 Step 6: same Drop-as-shutdown pattern as
    /// [`Self::notification_shutdown_tx`].
    #[allow(dead_code)]
    watched_folder_shutdown_tx: oneshot::Sender<()>,
}

impl SessionActor {
    /// v0.173.1: shared helper for reader sites that used to read
    /// `TorrentEntry.meta` (a stale cache that was silently `None` forever
    /// for magnet-added torrents). Always queries the `TorrentActor` — the
    /// single source of truth for torrent metadata post-v0.173.1.
    ///
    /// Returns [`crate::Error::TorrentNotFound`] if `info_hash` isn't in the
    /// registry, [`crate::Error::MetadataNotReady`] if the actor has not yet
    /// assembled metadata (magnet pre-resolution), or propagates
    /// [`crate::Error::Shutdown`] if the actor has already exited.
    async fn get_entry_meta(&self, info_hash: Id20) -> crate::Result<irontide_core::TorrentMetaV1> {
        let entry = self
            .torrents
            .get(&info_hash)
            .ok_or(crate::Error::TorrentNotFound(info_hash))?;
        entry
            .handle
            .get_meta()
            .await?
            .ok_or(crate::Error::MetadataNotReady(info_hash))
    }

    async fn run(mut self) {
        let mut refill_interval = tokio::time::interval(std::time::Duration::from_millis(100));
        refill_interval.tick().await; // skip first immediate tick

        let auto_manage_secs = self.settings.auto_manage_interval.max(1);
        let mut auto_manage_interval =
            tokio::time::interval(std::time::Duration::from_secs(auto_manage_secs));
        auto_manage_interval.tick().await; // skip first immediate tick

        // Periodic session stats timer (M50)
        let stats_interval_ms = self.settings.stats_report_interval;
        let mut stats_timer = if stats_interval_ms > 0 {
            Some(tokio::time::interval(std::time::Duration::from_millis(
                stats_interval_ms,
            )))
        } else {
            None
        };
        if let Some(ref mut t) = stats_timer {
            t.tick().await; // skip first immediate tick
        }

        // Periodic sample_infohashes timer (BEP 51, M111)
        let sample_interval_secs = self.settings.dht_sample_infohashes_interval;
        let mut sample_timer = if sample_interval_secs > 0 {
            Some(tokio::time::interval(std::time::Duration::from_secs(
                sample_interval_secs,
            )))
        } else {
            None
        };
        if let Some(ref mut t) = sample_timer {
            t.tick().await; // skip first immediate tick
        }

        // Periodic resume file save timer (M161)
        let mut resume_save_interval = if self.settings.save_resume_interval_secs > 0 {
            Some(tokio::time::interval(std::time::Duration::from_secs(
                self.settings.save_resume_interval_secs,
            )))
        } else {
            None
        };
        if let Some(ref mut t) = resume_save_interval {
            t.tick().await; // skip first immediate tick
        }

        // Auto-restore torrents from resume files on startup (M161 Phase 5).
        {
            let resume_dir = self.effective_resume_dir();
            let resume_files = crate::resume_file::scan_resume_dir(&resume_dir);
            if !resume_files.is_empty() {
                // Reuse the existing sequential restore logic from Phase 4.
                match self.handle_load_resume_state().await {
                    Ok(result) => {
                        info!(
                            restored = result.restored,
                            skipped = result.skipped,
                            failed = result.failed,
                            "auto-restored torrents on startup"
                        );
                    }
                    Err(e) => {
                        warn!("auto-restore on startup failed: {e}");
                    }
                }

                // Init throttle: restored torrents were queued inside
                // handle_load_resume_state when queueing_enabled. Run one
                // immediate evaluate_queue() so up to active_checking
                // torrents enter Checking right away (don't wait 30s).
                if self.settings.queueing_enabled {
                    self.evaluate_queue().await;
                }

                // Orphan cleanup: delete .resume files whose hex stem does not
                // match any info hash currently in the session.
                let active_hashes: std::collections::HashSet<String> = self
                    .torrents
                    .keys()
                    .map(|h| hex::encode(h.as_bytes()))
                    .collect();

                // Re-scan after load — some files may have been consumed.
                let current_files = crate::resume_file::scan_resume_dir(&resume_dir);
                for path in &current_files {
                    if let Some(stem) = path.file_stem().and_then(|s| s.to_str())
                        && !active_hashes.contains(stem)
                    {
                        if let Err(e) = std::fs::remove_file(path) {
                            warn!(path = %path.display(), "failed to remove orphan resume file: {e}");
                        } else {
                            debug!(path = %path.display(), "removed orphan resume file");
                        }
                    }
                }
            }
        }

        loop {
            tokio::select! {
                cmd = self.cmd_rx.recv() => {
                    // M221.1a — per-command timing. `sent_at` is the
                    // instant the sender enqueued the command (via
                    // `SessionCmdSender::send`); `recv_at` is now.
                    // `queue_wait_ms` measures actor backlog; the
                    // post-match `handler_ms` covers the dispatch.
                    // Shutdown/None paths return early and skip the
                    // tracing emit — telemetry is intentionally absent
                    // for the terminal command.
                    let recv_at = tokio::time::Instant::now();
                    let queue_wait_ms = cmd.as_ref().map_or(0.0, |(sent_at, _)| {
                        recv_at.saturating_duration_since(*sent_at).as_secs_f64() * 1000.0
                    });
                    let cmd_name = cmd.as_ref().map_or("<closed>", |(_, c)| c.name());
                    let handler_start = tokio::time::Instant::now();
                    let cmd = cmd.map(|(_sent_at, c)| c);
                    match cmd {
                        Some(SessionCommand::AddTorrent {
                            meta,
                            storage,
                            download_dir,
                            reply,
                        }) => {
                            // M223 — spawn-per-add path. The heavy
                            // `disk_manager.register_torrent` +
                            // `TorrentHandle::from_torrent` work runs in a
                            // `tokio::spawn`'d task; results route back via
                            // `SessionCommand::CommitAddTorrent`. Legacy entry
                            // point: no tags available from the pre-M171
                            // command shape.
                            let setup: crate::Result<AddTorrentPrepBundle> = (|| {
                                let info_hash = meta.as_v1().map_or_else(
                                    || meta.info_hashes().best_v1(),
                                    |v| v.info_hash,
                                );
                                if self.torrents.contains_key(&info_hash) {
                                    return Err(crate::Error::DuplicateTorrent(info_hash));
                                }
                                if self.torrents.len() >= self.settings.max_torrents {
                                    return Err(crate::Error::SessionAtCapacity(
                                        self.settings.max_torrents,
                                    ));
                                }
                                Ok(self.build_add_torrent_prep_bundle(
                                    *meta,
                                    storage,
                                    download_dir,
                                    Vec::new(),
                                    None,
                                ))
                            })();
                            match setup {
                                Ok(bundle) => self.try_spawn_add_torrent(bundle, reply),
                                Err(e) => {
                                    let _ = reply.send(Err(e));
                                }
                            }
                        }
                        Some(SessionCommand::CommitAddTorrent { result, reply }) => {
                            // M223 — feedback variant: the spawn-per-add prep
                            // phase finished. `commit_add_torrent` does the
                            // mutating fixup on the actor (insert into
                            // `self.torrents`, queue position, alert, LSD,
                            // M170 post-hooks) using the precomputed
                            // `is_private` from the bundle.
                            let id = self.commit_add_torrent(result).await;
                            let _ = reply.send(id);
                        }
                        Some(SessionCommand::AddMagnet { magnet, download_dir, reply }) => {
                            // Legacy entry point: no tags available from the
                            // pre-M171 command shape.
                            let result = self
                                .handle_add_magnet(magnet, download_dir, Vec::new())
                                .await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::RemoveTorrent { info_hash, reply }) => {
                            let result = self.handle_remove_torrent(info_hash).await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::PauseTorrent { info_hash, reply }) => {
                            let result = self.handle_pause_torrent(info_hash).await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::ResumeTorrent { info_hash, reply }) => {
                            let result = self.handle_resume_torrent(info_hash).await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::ForceResumeTorrent { info_hash, reply }) => {
                            let result = self.handle_force_resume_torrent(info_hash).await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::SetTorrentSeedRatio { info_hash, limit, reply }) => {
                            let result = self.handle_set_torrent_seed_ratio(info_hash, limit).await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::TorrentStats { info_hash, reply }) => {
                            let result = self.handle_torrent_stats(info_hash).await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::TorrentInfo { info_hash, reply }) => {
                            // v0.173.1: handle_torrent_info is now async because
                            // it queries the TorrentActor for metadata (Class A
                            // architectural fix — no more TorrentEntry.meta cache).
                            let result = self.handle_torrent_info(info_hash).await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::ListTorrents { reply }) => {
                            let list: Vec<Id20> = self.torrents.keys().copied().collect();
                            let _ = reply.send(list);
                        }
                        Some(SessionCommand::SessionStats { reply }) => {
                            let stats = self.make_session_stats().await;
                            let _ = reply.send(stats);
                        }
                        Some(SessionCommand::SaveTorrentResumeData { info_hash, reply }) => {
                            let result = self.handle_save_torrent_resume(info_hash).await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::SaveSessionState { reply }) => {
                            let result = self.handle_save_session_state().await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::LoadResumeState { reply }) => {
                            let result = self.handle_load_resume_state().await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::QueuePosition { info_hash, reply }) => {
                            let result = match self.torrents.get(&info_hash) {
                                Some(entry) => Ok(entry.queue_position),
                                None => Err(crate::Error::TorrentNotFound(info_hash)),
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::SetQueuePosition { info_hash, pos, reply }) => {
                            let result = self.handle_set_queue_position(info_hash, pos);
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::QueuePositionUp { info_hash, reply }) => {
                            let result = self.handle_queue_move(info_hash, crate::queue::move_up);
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::QueuePositionDown { info_hash, reply }) => {
                            let result = self.handle_queue_move(info_hash, crate::queue::move_down);
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::QueuePositionTop { info_hash, reply }) => {
                            let result = self.handle_queue_move(info_hash, crate::queue::move_top);
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::QueuePositionBottom { info_hash, reply }) => {
                            let result = self.handle_queue_move(info_hash, crate::queue::move_bottom);
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::BanPeer { ip, reply }) => {
                            self.ban_manager.write().ban(ip);
                            let _ = reply.send(());
                        }
                        Some(SessionCommand::UnbanPeer { ip, reply }) => {
                            let was_banned = self.ban_manager.write().unban(&ip);
                            let _ = reply.send(was_banned);
                        }
                        Some(SessionCommand::BannedPeers { reply }) => {
                            let list: Vec<IpAddr> = self.ban_manager.read()
                                .banned_list().iter().copied().collect();
                            let _ = reply.send(list);
                        }
                        Some(SessionCommand::SetIpFilter { filter, reply }) => {
                            *self.ip_filter.write() = filter;
                            let _ = reply.send(());
                        }
                        Some(SessionCommand::GetIpFilter { reply }) => {
                            let filter = self.ip_filter.read().clone();
                            let _ = reply.send(filter);
                        }
                        Some(SessionCommand::GetSettings { reply }) => {
                            let _ = reply.send(self.settings.clone());
                        }
                        Some(SessionCommand::ApplySettings { settings, reply }) => {
                            let result = self.handle_apply_settings(*settings);
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::DhtNodeCount { reply }) => {
                            // Sum routing-table sizes across both DHT
                            // instances. Either instance erroring or being
                            // absent contributes 0 — the qBt wire field is
                            // a best-effort gauge, not a strict invariant.
                            let mut total: usize = 0;
                            if let Some(dht) = &self.dht_v4
                                && let Ok(c) = dht.node_count().await
                            {
                                total += c;
                            }
                            if let Some(dht) = &self.dht_v6
                                && let Ok(c) = dht.node_count().await
                            {
                                total += c;
                            }
                            let _ = reply.send(total);
                        }
                        Some(SessionCommand::MoveTorrentStorage { info_hash, new_path, reply }) => {
                            let result = self.handle_move_torrent_storage(info_hash, new_path).await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::AddPeers { info_hash, peers, source, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.add_peers(peers, source).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::OpenFile { info_hash, file_index, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.open_file(file_index).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::ForceReannounce { info_hash, reply }) => {
                            let result = match self.torrents.get(&info_hash) {
                                Some(entry) => {
                                    entry.handle.force_reannounce().await
                                }
                                None => Err(crate::Error::TorrentNotFound(info_hash)),
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::TrackerList { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.tracker_list().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::GetPeerSourceCounts { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.peer_source_counts().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::QueryUnchokeDurations { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.query_unchoke_durations().await.ok()
                            } else {
                                None
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::GetWebSeedStats { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.get_web_seed_stats().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::GetWebSeeds { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.get_web_seeds().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::GetPieceStates { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.get_piece_states().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::GetPieceHashes { info_hash, offset, limit, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.get_piece_hashes(offset, limit).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::Scrape { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.scrape().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::SetFilePriority { info_hash, index, priority, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.set_file_priority(index, priority).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::FilePriorities { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.file_priorities().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::SetDownloadLimit { info_hash, bytes_per_sec, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.set_download_limit(bytes_per_sec).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::SetUploadLimit { info_hash, bytes_per_sec, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.set_upload_limit(bytes_per_sec).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::DownloadLimit { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.download_limit().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::UploadLimit { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.upload_limit().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::SetSequentialDownload { info_hash, enabled, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.set_sequential_download(enabled).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::IsSequentialDownload { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.is_sequential_download().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::SetSuperSeeding { info_hash, enabled, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.set_super_seeding(enabled).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::IsSuperSeeding { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.is_super_seeding().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::SetSeedMode { info_hash, enabled, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.set_seed_mode(enabled).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::AddTracker { info_hash, url, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.add_tracker(url).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::ReplaceTrackers { info_hash, urls, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.replace_trackers(urls).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::ForceRecheck { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.force_recheck().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::RenameFile { info_hash, file_index, new_name, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.rename_file(file_index, new_name).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::SetMaxConnections { info_hash, limit, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.set_max_connections(limit).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::MaxConnections { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.max_connections().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::SetMaxUploads { info_hash, limit, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.set_max_uploads(limit).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::MaxUploads { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.max_uploads().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::GetPeerInfo { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.get_peer_info().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::GetDownloadQueue { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.get_download_queue().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::HavePiece { info_hash, index, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.have_piece(index).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::PieceAvailability { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.piece_availability().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::FileProgress { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.file_progress().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::InfoHashesQuery { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.info_hashes().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::TorrentFile { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.torrent_file().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::TorrentFileV2 { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.torrent_file_v2().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        #[cfg(feature = "test-util")]
                        Some(SessionCommand::TestInjectMetadata {
                            info_hash,
                            info_bytes,
                            reply,
                        }) => {
                            let result = match self.torrents.get(&info_hash) {
                                Some(entry) => {
                                    entry.handle.test_inject_metadata(info_bytes).await
                                }
                                None => Err(crate::Error::TorrentNotFound(info_hash)),
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::ForceDhtAnnounce { info_hash, reply }) => {
                            // v0.173.2: BEP 27 enforcement on the DHT path. M173.1 fixed the
                            // LSD leak vector but missed DHT — private torrents would still
                            // announce their info hash to DHT and leak peer IPs. Mirrors the
                            // LSD pattern at session.rs:3541-3563.
                            let result = match self.torrents.get(&info_hash) {
                                Some(entry) => {
                                    if entry.is_private().await {
                                        Err(crate::Error::InvalidSettings(
                                            "DHT disabled for private torrent".into(),
                                        ))
                                    } else {
                                        entry.handle.force_dht_announce().await
                                    }
                                }
                                None => Err(crate::Error::TorrentNotFound(info_hash)),
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::ForceLsdAnnounce { info_hash, reply }) => {
                            // LSD is session-level: verify the torrent exists, then announce directly.
                            //
                            // v0.173.1: is_private is now async. Match guards can't be async, so
                            // evaluate the flag up front and branch on the bool.
                            let result = match self.torrents.get(&info_hash) {
                                Some(entry) => {
                                    if entry.is_private().await {
                                        // BEP 27: private torrents must not use LSD
                                        Err(crate::Error::InvalidSettings(
                                            "LSD disabled for private torrent".into(),
                                        ))
                                    } else {
                                        if let Some(ref lsd) = self.lsd {
                                            lsd.announce(vec![info_hash]).await;
                                        }
                                        Ok(())
                                    }
                                }
                                None => Err(crate::Error::TorrentNotFound(info_hash)),
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::ReadPiece { info_hash, index, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.read_piece(index).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::FlushCache { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.flush_cache().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::IsValid { info_hash, reply }) => {
                            let valid = self.torrents.get(&info_hash)
                                .is_some_and(|e| e.handle.is_valid());
                            let _ = reply.send(valid);
                        }
                        Some(SessionCommand::ClearError { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.clear_error().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::FileStatus { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.file_status().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::Flags { info_hash, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.flags().await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::SetFlags { info_hash, flags, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.set_flags(flags).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::UnsetFlags { info_hash, flags, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.unset_flags(flags).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::ConnectPeer { info_hash, addr, reply }) => {
                            let result = if let Some(entry) = self.torrents.get(&info_hash) {
                                entry.handle.connect_peer(addr).await
                            } else {
                                Err(crate::Error::TorrentNotFound(info_hash))
                            };
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::DhtPutImmutable { value, reply }) => {
                            let result = self.handle_dht_put_immutable(value).await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::DhtGetImmutable { target, reply }) => {
                            let result = self.handle_dht_get_immutable(target).await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::DhtPutMutable { keypair_bytes, value, seq, salt, reply }) => {
                            let result = self.handle_dht_put_mutable(keypair_bytes, value, seq, salt).await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::DhtGetMutable { public_key, salt, reply }) => {
                            let result = self.handle_dht_get_mutable(public_key, salt).await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::PostSessionStats) => {
                            self.fire_stats_alert();
                        }
                        Some(SessionCommand::SaveResumeState { reply }) => {
                            // M241 L1: run the save OFF the recv loop. The spawned
                            // task owns the reply and answers the caller once the
                            // write completes, so a slow disk / many torrents no
                            // longer freeze the whole session. It waits on
                            // resume_save_lock (lock_owned) so it never races an
                            // in-flight periodic save onto the same temp path (F4);
                            // unlike the periodic tick it always eventually persists,
                            // honouring the caller's explicit "save now" intent.
                            let lock = Arc::clone(&self.resume_save_lock);
                            let (resume_dir, jobs) = self.snapshot_resume_jobs();
                            tokio::spawn(async move {
                                let _guard = lock.lock_owned().await;
                                let count = run_resume_save_jobs(resume_dir, jobs).await;
                                let _ = reply.send(Ok(count));
                            });
                        }
                        Some(SessionCommand::AddTorrentM170 { params, reply }) => {
                            // M223 — bytes branch goes through the
                            // spawn-per-add path; magnet branch stays inline.
                            // The dispatcher consumes `reply` directly.
                            self.dispatch_add_torrent_m170(*params, reply).await;
                        }
                        Some(SessionCommand::CreateCategory { name, save_path, reply }) => {
                            let result = self.handle_create_category(name, save_path).await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::EditCategory { name, save_path, reply }) => {
                            let result = self.handle_edit_category(name, save_path).await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::RemoveCategories { names, reply }) => {
                            let result = self.handle_remove_categories(names).await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::ListCategories { reply }) => {
                            let snapshot = self.category_registry.read().list();
                            let _ = reply.send(snapshot);
                        }
                        Some(SessionCommand::CreateTags { names, reply }) => {
                            let results: Vec<_> = {
                                let mut reg = self.tag_registry.write();
                                names.into_iter().map(|n| reg.create(n)).collect()
                            };
                            // Persist any successful creates. Persistence failures
                            // warn but don't change the per-call reply (matches
                            // CreateCategory).
                            if let Err(e) = self.persist_tag_registry().await {
                                tracing::warn!(
                                    error = %e,
                                    "failed to persist tag registry after CreateTags"
                                );
                            }
                            let _ = reply.send(results);
                        }
                        Some(SessionCommand::DeleteTags { names, reply }) => {
                            let removed = self.handle_delete_tags(names).await;
                            let _ = reply.send(removed);
                        }
                        Some(SessionCommand::ListTags { reply }) => {
                            let names = self.tag_registry.read().list();
                            let _ = reply.send(names);
                        }
                        Some(SessionCommand::AddTagsToTorrents { info_hashes, tags, reply }) => {
                            let res = self.handle_add_tags_to_torrents(info_hashes, tags).await;
                            let _ = reply.send(res);
                        }
                        Some(SessionCommand::RemoveTagsFromTorrents { info_hashes, tags, reply }) => {
                            let res = self
                                .handle_remove_tags_from_torrents(info_hashes, tags)
                                .await;
                            let _ = reply.send(res);
                        }
                        Some(SessionCommand::RemoveTorrentWithFiles { info_hash, reply }) => {
                            let result = self.handle_remove_torrent_with_files(info_hash).await;
                            let _ = reply.send(result);
                        }
                        Some(SessionCommand::DebugState { reply }) => {
                            let state = self.make_debug_state().await;
                            let _ = reply.send(state);
                        }
                        Some(SessionCommand::Shutdown) | None => {
                            self.shutdown_all().await;
                            return;
                        }
                    }
                    // M221.1a — emit per-command timing on the
                    // bench-harness target. Filtering happens in the
                    // tracing subscriber (parallel-7 harness sets
                    // RUST_LOG=irontide_session::cmd_timing=info); the
                    // emit is unconditional so any external consumer
                    // can opt in.
                    let handler_ms = handler_start.elapsed().as_secs_f64() * 1000.0;
                    info!(
                        target: "irontide_session::cmd_timing",
                        cmd = cmd_name,
                        queue_wait_ms = queue_wait_ms,
                        handler_ms = handler_ms,
                        "session_cmd"
                    );
                }
                result = async {
                    match &mut self.lsd_peers_rx {
                        Some(rx) => rx.recv().await,
                        None => std::future::pending().await,
                    }
                } => {
                    if let Some((info_hash, peer_addr)) = result
                        && let Some(entry) = self.torrents.get(&info_hash)
                    {
                        // v0.173.1: is_private is async — can't chain it into the let-else
                        // condition list, evaluate separately before add_peers.
                        let is_priv = entry.is_private().await;
                        if !is_priv {
                            // BEP 27: reject LSD peers for private torrents
                            let _ = entry.handle.add_peers(vec![peer_addr], crate::peer_state::PeerSource::Lsd).await;
                        }
                    }
                }
                // Pre-validated inbound connections from ListenerTask (M114)
                Some(conn) = self.validated_conn_rx.recv() => {
                    self.handle_identified_inbound(conn);
                }
                // SSL inbound connections (M42)
                result = async {
                    if let Some(ref mut listener) = self.ssl_listener {
                        listener.accept().await
                    } else {
                        std::future::pending().await
                    }
                } => {
                    if let Ok((stream, addr)) = result {
                        self.handle_ssl_incoming(stream, addr).await;
                    }
                }
                // Global rate limiter refill (100ms)
                _ = refill_interval.tick() => {
                    let elapsed = std::time::Duration::from_millis(100);
                    self.global_upload_bucket.lock().refill(elapsed);
                    self.global_download_bucket.lock().refill(elapsed);
                }
                // Auto-manage queue evaluation
                _ = auto_manage_interval.tick() => {
                    self.evaluate_queue().await;
                }
                // Checking-complete trigger: when a torrent exits Checking
                // state, re-evaluate immediately so the next candidate
                // promotes without waiting for the 30s periodic tick.
                alert = self.self_alert_rx.recv() => {
                    if let Ok(alert) = alert
                        && matches!(
                            alert.kind,
                            AlertKind::StateChanged {
                                prev_state: TorrentState::Checking,
                                new_state,
                                ..
                            } if new_state != TorrentState::Checking
                        )
                    {
                        self.evaluate_queue().await;
                    }
                }
                // NAT port mapping events
                event = recv_nat_event(&mut self.nat_events_rx) => {
                    match event {
                        irontide_nat::NatEvent::MappingSucceeded { port, protocol } => {
                            info!(port, %protocol, "port mapping succeeded");
                            post_alert(
                                &self.alert_tx,
                                &self.alert_mask,
                                AlertKind::PortMappingSucceeded { port, protocol },
                            );
                        }
                        irontide_nat::NatEvent::MappingFailed { port, message } => {
                            warn!(port, %message, "port mapping failed");
                            post_alert(
                                &self.alert_tx,
                                &self.alert_mask,
                                AlertKind::PortMappingFailed { port, message },
                            );
                        }
                        irontide_nat::NatEvent::ExternalIpDiscovered { ip } => {
                            info!(%ip, "external IP discovered via NAT traversal");
                            self.external_ip = Some(ip);
                            // Propagate to all active torrents for BEP 40 peer priority.
                            for entry in self.torrents.values() {
                                let _ = entry.handle.update_external_ip(ip).await;
                            }
                            // BEP 42: notify DHT instances of external IP
                            if let Some(dht) = &self.dht_v4 {
                                let _ = dht.update_external_ip(ip, irontide_dht::IpVoteSource::Nat).await;
                            }
                            if let Some(dht) = &self.dht_v6 {
                                let _ = dht.update_external_ip(ip, irontide_dht::IpVoteSource::Nat).await;
                            }
                        }
                    }
                }
                // BEP 42: DHT v4 external IP consensus
                Some(ip) = recv_dht_ip(&mut self.dht_v4_ip_rx) => {
                    info!(%ip, "external IP discovered via DHT v4 (BEP 42)");
                    self.external_ip = Some(ip);
                    for entry in self.torrents.values() {
                        let _ = entry.handle.update_external_ip(ip).await;
                    }
                }
                // BEP 42: DHT v6 external IP consensus
                Some(ip) = recv_dht_ip(&mut self.dht_v6_ip_rx) => {
                    info!(%ip, "external IP discovered via DHT v6 (BEP 42)");
                    self.external_ip = Some(ip);
                    for entry in self.torrents.values() {
                        let _ = entry.handle.update_external_ip(ip).await;
                    }
                }
                // Periodic session stats (M50)
                _ = async {
                    match &mut stats_timer {
                        Some(t) => t.tick().await,
                        None => std::future::pending().await,
                    }
                } => {
                    // M245 A1 (phase-4 grounding fix): refresh the published
                    // read-model on the SAME periodic cadence that fires the
                    // stats alert. The ratified plan assumed `make_session_stats`
                    // ran on this tick, but it only ran on-demand via
                    // `SessionCommand::SessionStats`. Without this, a client that
                    // polls `list_torrent_summaries` (P1) but not `session_stats`
                    // would see the snapshot's sampled fields (state, rates,
                    // progress) frozen at each torrent's add-time eager publish —
                    // membership stayed correct, but state never advanced. Reuse
                    // the single bounded fan-out (C1) for its snapshot side
                    // effect; the alert below stays counter-based, so the summed
                    // result is intentionally discarded.
                    let _ = self.make_session_stats().await;
                    self.fire_stats_alert();
                }
                // Periodic sample_infohashes (BEP 51, M111)
                _ = async {
                    match &mut sample_timer {
                        Some(t) => t.tick().await,
                        None => std::future::pending().await,
                    }
                } => {
                    self.fire_sample_infohashes().await;
                }
                // Periodic resume file save (M161) — runs OFF the recv loop (M241 L1).
                _ = async {
                    match &mut resume_save_interval {
                        Some(t) => t.tick().await,
                        None => std::future::pending().await,
                    }
                } => {
                    // try_lock_owned: if a save is already in flight (this tick's
                    // predecessor on a slow disk, or a SaveResumeState RPC), skip —
                    // don't pile up concurrent writers onto the same temp path (F4).
                    match Arc::clone(&self.resume_save_lock).try_lock_owned() {
                        Ok(guard) => {
                            let (resume_dir, jobs) = self.snapshot_resume_jobs();
                            tokio::spawn(async move {
                                let _guard = guard;
                                let count = run_resume_save_jobs(resume_dir, jobs).await;
                                if count > 0 {
                                    info!(count, "periodic resume save completed");
                                }
                            });
                        }
                        Err(_) => {
                            debug!("resume save already in flight — skipping this periodic tick");
                        }
                    }
                }
                // Periodic resume save interval rebuild (M225)
                () = self.resume_save_notify.notified() => {
                    resume_save_interval = if self.settings.save_resume_interval_secs > 0 {
                        Some(tokio::time::interval(std::time::Duration::from_secs(
                            self.settings.save_resume_interval_secs,
                        )))
                    } else {
                        None
                    };
                    if let Some(ref mut t) = resume_save_interval {
                        t.tick().await; // skip first immediate tick
                    }
                }
            }
        }
    }

    /// Return clones of global buckets if they have a non-zero rate, else None.
    fn global_buckets_if_limited(&self) -> (Option<SharedBucket>, Option<SharedBucket>) {
        let up = if self.settings.upload_rate_limit > 0 {
            Some(Arc::clone(&self.global_upload_bucket))
        } else {
            None
        };
        let down = if self.settings.download_rate_limit > 0 {
            Some(Arc::clone(&self.global_download_bucket))
        } else {
            None
        };
        (up, down)
    }

    fn make_slot_tuner(&self) -> crate::slot_tuner::SlotTuner {
        if self.settings.auto_upload_slots {
            crate::slot_tuner::SlotTuner::new(
                4, // initial slots
                self.settings.auto_upload_slots_min,
                self.settings.auto_upload_slots_max,
            )
        } else {
            crate::slot_tuner::SlotTuner::disabled(4)
        }
    }

    fn make_torrent_config(&self) -> TorrentConfig {
        TorrentConfig::from(&self.settings)
    }

    /// Returns the next available queue position (one past the max).
    fn next_queue_position(&self) -> i32 {
        self.torrents
            .values()
            .filter(|e| e.auto_managed)
            .map(|e| e.queue_position)
            .max()
            .map_or(0, |m| m + 1)
    }

    /// Inline add-torrent path: builds the prep bundle on the actor,
    /// runs prepare + commit phases sequentially without spawning. Used
    /// by the resume-restore startup path (single-threaded by
    /// construction) and the `handle_add_torrent_with_params` M170
    /// helper. The `AddTorrent` and `AddTorrentM170` recv arms call
    /// `try_spawn_add_torrent` instead — same prep + commit primitives,
    /// but the prep runs in a `tokio::spawn` and the commit hop returns
    /// via `SessionCommand::CommitAddTorrent` (M223).
    async fn handle_add_torrent(
        &mut self,
        torrent_meta: irontide_core::TorrentMeta,
        storage: Option<Arc<dyn TorrentStorage>>,
        download_dir: Option<PathBuf>,
        tags: Vec<String>,
    ) -> crate::Result<Id20> {
        let info_hash = torrent_meta
            .as_v1()
            .map_or_else(|| torrent_meta.info_hashes().best_v1(), |v| v.info_hash);
        if self.torrents.contains_key(&info_hash) {
            return Err(crate::Error::DuplicateTorrent(info_hash));
        }
        if self.torrents.len() >= self.settings.max_torrents {
            return Err(crate::Error::SessionAtCapacity(self.settings.max_torrents));
        }
        let bundle =
            self.build_add_torrent_prep_bundle(torrent_meta, storage, download_dir, tags, None);
        let prep = prepare_add_torrent_off_actor(bundle).await;
        self.commit_add_torrent(prep).await
    }

    /// M223 — build the off-actor add-torrent prep bundle synchronously
    /// from session state. Cheap Arc-clones + a single
    /// `make_torrent_config` snapshot; never awaits, so it stays on the
    /// actor without contributing to the queue-wait stack.
    fn build_add_torrent_prep_bundle(
        &self,
        torrent_meta: irontide_core::TorrentMeta,
        storage: Option<Arc<dyn TorrentStorage>>,
        download_dir: Option<PathBuf>,
        tags: Vec<String>,
        m170_post: Option<M170PostAdd>,
    ) -> AddTorrentPrepBundle {
        let mut torrent_config = self.make_torrent_config();
        if let Some(dir) = download_dir {
            torrent_config.download_dir = dir;
        }
        // M171: bake tags into the config BEFORE the actor is constructed so
        // the first `stats()` snapshot already carries them — no post-add
        // spawn race. An empty vec is a no-op but still replaces any
        // session-level default (currently also empty).
        torrent_config.tags = tags;

        let (global_up, global_down) = self.global_buckets_if_limited();
        let slot_tuner = self.make_slot_tuner();

        AddTorrentPrepBundle {
            torrent_meta,
            storage_override: storage,
            torrent_config,
            disk_manager: self.disk_manager.clone(),
            dht_v4_broadcast: self.dht_v4_broadcast.clone(),
            dht_v6_broadcast: self.dht_v6_broadcast.clone(),
            global_up,
            global_down,
            slot_tuner,
            alert_tx: self.alert_tx.clone(),
            alert_mask: Arc::clone(&self.alert_mask),
            utp_socket: self.utp_socket.clone(),
            utp_socket_v6: self.utp_socket_v6.clone(),
            ban_manager: Arc::clone(&self.ban_manager),
            ip_filter: Arc::clone(&self.ip_filter),
            plugins: Arc::clone(&self.plugins),
            sam_session: self.sam_session.clone(),
            ssl_manager: self.ssl_manager.clone(),
            factory: Arc::clone(&self.factory),
            hash_pool: Arc::clone(&self.hash_pool),
            counters: Arc::clone(&self.counters),
            m170_post,
        }
    }

    /// M223 — commit phase of the spawn-per-add fix. Mutates session
    /// state (insert into `self.torrents`, info-hash registry, queue
    /// position, alert, LSD announce, M170 post-hooks) using the
    /// success-path payload from `prepare_add_torrent_off_actor`. On
    /// `Err` from prep, returns the error untouched.
    async fn commit_add_torrent(
        &mut self,
        prep: crate::Result<PreparedAddTorrent>,
    ) -> crate::Result<Id20> {
        let PreparedAddTorrent {
            handle,
            info_hash,
            is_private,
            m170_post,
        } = prep?;
        // Re-check dup + capacity: parallel adds may both pass the
        // pre-spawn check, then race the commit. The later one fails
        // here, and dropping `handle` triggers the spawned TorrentActor's
        // graceful shutdown (its cmd_tx receiver hangs up → recv returns
        // None → actor exits).
        if self.torrents.contains_key(&info_hash) {
            drop(handle);
            return Err(crate::Error::DuplicateTorrent(info_hash));
        }
        if self.torrents.len() >= self.settings.max_torrents {
            drop(handle);
            return Err(crate::Error::SessionAtCapacity(self.settings.max_torrents));
        }
        self.torrents.insert(
            info_hash,
            TorrentEntry {
                handle,
                queue_position: -1,
                auto_managed: true,
                started_at: Some(tokio::time::Instant::now()),
                smoothed_download_rate: f64::MAX,
                smoothed_upload_rate: f64::MAX,
            },
        );
        self.info_hash_registry.insert(info_hash, ());

        // Assign queue position for auto-managed torrents
        let pos = self.next_queue_position();
        if let Some(entry) = self.torrents.get_mut(&info_hash)
            && entry.auto_managed
        {
            entry.queue_position = pos;
        }

        info!(%info_hash, "torrent added to session");
        // M223 — `TorrentAdded` is posted in `prepare_add_torrent_off_actor`
        // (BEFORE the `commit_tx.send.await` yield) to preserve the alert
        // ordering invariant under spawn-per-add. See the comment there.
        // BEP 27: private torrents must not use LSD. `is_private` is
        // precomputed from `meta.info.private == Some(1)` in the prep
        // bundle, so the commit arm needs no async query.
        if let Some(ref lsd) = self.lsd
            && !is_private
        {
            lsd.announce(vec![info_hash]).await;
        }
        // M170 post-add hooks (category + paused-on-add) for the
        // `AddTorrentM170` path. Always `None` for the legacy
        // `AddTorrent` path.
        if let Some(M170PostAdd { category, paused }) = m170_post {
            self.apply_post_add_m170(info_hash, category, paused);
        }
        // M245 A1 — eager membership publish. This is the SOLE non-magnet
        // insert site: it covers spawn-per-add commits AND startup restore
        // (`handle_load_resume_state` → `handle_add_torrent` → here), so reads
        // see the torrent the instant its add commits.
        self.snapshot_publish_one(info_hash).await;
        Ok(info_hash)
    }

    /// M223 — recv-arm helper: spawn the prep phase off the actor,
    /// route the result back via `CommitAddTorrent`. Consumes `reply`,
    /// so callers must not also send to it.
    fn try_spawn_add_torrent(
        &self,
        bundle: AddTorrentPrepBundle,
        reply: oneshot::Sender<crate::Result<Id20>>,
    ) {
        let commit_tx = self.commit_tx.clone();
        tokio::spawn(async move {
            let result = prepare_add_torrent_off_actor(bundle).await;
            if commit_tx
                .send(SessionCommand::CommitAddTorrent { result, reply })
                .await
                .is_err()
            {
                // Session is shutting down; the receiver is gone too.
                // The `reply` oneshot was moved into the variant which
                // got dropped, so the original caller observes a closed
                // channel — the right shutdown signal.
                warn!("M223 prep task: commit_tx send failed (session shutting down)");
            }
        });
    }

    async fn handle_add_magnet(
        &mut self,
        magnet: Magnet,
        download_dir: Option<PathBuf>,
        tags: Vec<String>,
    ) -> crate::Result<Id20> {
        let info_hash = magnet.info_hash();
        let display_name = magnet.display_name.clone().unwrap_or_default();
        if self.torrents.contains_key(&info_hash) {
            return Err(crate::Error::DuplicateTorrent(info_hash));
        }
        if self.torrents.len() >= self.settings.max_torrents {
            return Err(crate::Error::SessionAtCapacity(self.settings.max_torrents));
        }
        let mut config = self.make_torrent_config();
        if let Some(dir) = download_dir {
            config.download_dir = dir;
        }
        // M171: bake tags into the config BEFORE the actor is constructed so
        // the first `stats()` snapshot already carries them — no post-add
        // spawn race. An empty vec is a no-op but still replaces any
        // session-level default (currently also empty).
        config.tags = tags;
        let (global_up, global_down) = self.global_buckets_if_limited();
        let slot_tuner = self.make_slot_tuner();
        let handle = TorrentHandle::from_magnet(
            magnet,
            self.disk_manager.clone(),
            config,
            self.dht_v4_broadcast.subscribe(),
            self.dht_v6_broadcast.subscribe(),
            global_up,
            global_down,
            slot_tuner,
            self.alert_tx.clone(),
            Arc::clone(&self.alert_mask),
            self.utp_socket.clone(),
            self.utp_socket_v6.clone(),
            Arc::clone(&self.ban_manager),
            Arc::clone(&self.ip_filter),
            Arc::clone(&self.plugins),
            self.sam_session.clone(),
            self.ssl_manager.clone(),
            Arc::clone(&self.factory),
            Some(Arc::clone(&self.hash_pool)),
            Arc::clone(&self.counters),
        )
        .await?;
        // M147: Spawn background metadata resolver before registering.
        // This races against the TorrentActor's own FetchingMetadata phase —
        // first to resolve wins.
        self.spawn_metadata_resolver(info_hash, &handle);

        self.torrents.insert(
            info_hash,
            TorrentEntry {
                handle,
                queue_position: -1,
                auto_managed: true,
                started_at: Some(tokio::time::Instant::now()),
                smoothed_download_rate: f64::MAX,
                smoothed_upload_rate: f64::MAX,
            },
        );
        self.info_hash_registry.insert(info_hash, ());

        // Assign queue position for auto-managed torrents
        let pos = self.next_queue_position();
        if let Some(entry) = self.torrents.get_mut(&info_hash)
            && entry.auto_managed
        {
            entry.queue_position = pos;
        }

        info!(%info_hash, "magnet torrent added to session");
        post_alert(
            &self.alert_tx,
            &self.alert_mask,
            AlertKind::TorrentAdded {
                info_hash,
                name: display_name,
            },
        );
        // BEP 27: magnet metadata not available yet — we allow this one-time LAN
        // announce. Once metadata resolves, all subsequent LSD ops are gated by
        // is_private() checks in ForceLsdAnnounce and lsd_peers_rx handlers.
        if let Some(ref lsd) = self.lsd {
            lsd.announce(vec![info_hash]).await;
        }
        // M245 A1 — eager membership publish (magnet add site). At this point
        // metadata is unresolved, so the published summary carries the magnet's
        // display name + zeroed size/rates; the tick refreshes it once the
        // actor reports real stats.
        self.snapshot_publish_one(info_hash).await;
        Ok(info_hash)
    }

    /// M147: Spawn a background task that pre-resolves magnet metadata via DHT.
    ///
    /// The resolver connects to peers discovered via DHT `get_peers`, performs
    /// BT + BEP 10 extension + BEP 9 `ut_metadata` exchanges, and sends the
    /// assembled metadata back to the `TorrentActor` via `PreResolvedMetadata`.
    /// This races against the `TorrentActor`'s own `FetchingMetadata` phase.
    fn spawn_metadata_resolver(&self, info_hash: Id20, torrent_handle: &TorrentHandle) {
        let dht = match self.dht_v4 {
            Some(ref dht) => dht.clone(),
            None => return, // No DHT = skip background resolution
        };
        let factory = Arc::clone(&self.factory);
        let connect_timeout = std::time::Duration::from_secs(self.settings.peer_connect_timeout);
        let handle = torrent_handle.clone();

        tokio::spawn(async move {
            let peer_rx = match dht.get_peers(info_hash).await {
                Ok(rx) => rx,
                Err(e) => {
                    debug!(
                        %info_hash,
                        "metadata resolver: failed to start DHT get_peers: {e}"
                    );
                    return;
                }
            };

            let peer_id = irontide_core::PeerId::generate().0;
            match crate::metadata_resolver::resolve_metadata(
                info_hash,
                peer_id,
                peer_rx,
                factory,
                connect_timeout,
                crate::metadata_resolver::DEFAULT_MAX_CONCURRENT,
            )
            .await
            {
                Ok((meta, peers)) => {
                    let info_bytes = if let Some(b) = meta.info_bytes {
                        b.to_vec()
                    } else {
                        match irontide_bencode::to_bytes(&meta.info) {
                            Ok(bytes) => bytes,
                            Err(e) => {
                                debug!(
                                    %info_hash,
                                    "metadata resolver: failed to re-encode info dict: {e}"
                                );
                                return;
                            }
                        }
                    };
                    debug!(
                        %info_hash,
                        num_peers = peers.len(),
                        "metadata resolver: pre-resolved metadata, sending to torrent actor"
                    );
                    handle.send_pre_resolved_metadata(info_bytes, peers);
                }
                Err(e) => {
                    debug!(
                        %info_hash,
                        "metadata resolver: failed to resolve metadata: {e}"
                    );
                }
            }
        });
    }

    async fn handle_remove_torrent(&mut self, info_hash: Id20) -> crate::Result<()> {
        let entry = self
            .torrents
            .remove(&info_hash)
            .ok_or(crate::Error::TorrentNotFound(info_hash))?;
        self.info_hash_registry.remove(&info_hash);
        // M245 A1 — eager membership drop. This is the SOLE remove site:
        // `handle_remove_torrent_with_files` delegates here, so reads stop
        // seeing the torrent the instant its removal commits.
        self.snapshot_drop_one(info_hash);
        let was_auto_managed = entry.auto_managed;
        let removed_position = entry.queue_position;
        entry.handle.shutdown().await?;
        self.disk_manager.unregister_torrent(info_hash).await;

        // Shift queue positions for remaining auto-managed torrents
        if was_auto_managed && removed_position >= 0 {
            let mut entries = self.queue_entries();
            let changed = crate::queue::remove_position(&mut entries, removed_position);
            self.apply_queue_changes(&changed);
        }

        // Delete the resume file for this torrent so it is not restored
        // on the next startup. Errors are logged but not propagated — the
        // torrent is already removed from the in-memory state.
        let resume_dir = self.effective_resume_dir();
        if let Err(e) = crate::resume_file::delete_resume_file(&resume_dir, &info_hash) {
            // NotFound is expected when no resume file was ever written.
            if e.kind() != std::io::ErrorKind::NotFound {
                warn!(%info_hash, "failed to delete resume file on removal: {e}");
            }
        }

        info!(%info_hash, "torrent removed from session");
        post_alert(
            &self.alert_tx,
            &self.alert_mask,
            AlertKind::TorrentRemoved { info_hash },
        );
        Ok(())
    }

    // ── M170 handlers ──────────────────────────────────────────────────

    /// M170: unified add entry. Parses magnet or bytes, resolves the
    /// download directory via category precedence, and dispatches to the
    /// existing add paths.
    /// M223 — dispatcher for the `AddTorrentM170` recv arm. The bytes
    /// branch goes through the spawn-per-add path
    /// (`try_spawn_add_torrent`); the magnet branch stays inline because
    /// it is dominated by metadata fetch latency, not by
    /// `TorrentHandle::from_torrent` cost, and is out of M223 scope.
    /// Consumes `reply` directly — either sends an error synchronously
    /// or hands `reply` to the spawned prep task (which routes it back
    /// via `CommitAddTorrent`).
    async fn dispatch_add_torrent_m170(
        &mut self,
        params: AddTorrentParams,
        reply: oneshot::Sender<crate::Result<Id20>>,
    ) {
        // Resolve download_dir + prepare category label early so that
        // an unknown category fails fast (before any parsing work).
        let (resolved_dir, resolved_category) =
            match self.resolve_download_dir_and_category(&params) {
                Ok(x) => x,
                Err(e) => {
                    let _ = reply.send(Err(e));
                    return;
                }
            };

        let AddTorrentParams {
            source,
            tags,
            paused,
            skip_checking: _, // reserved for M171+
            ..
        } = params;

        // M226: resolve None → engine `default_add_paused`. `Some(v)` is an
        // explicit per-call override and wins over the engine setting.
        let paused = paused.unwrap_or(self.settings.default_add_paused);

        match source {
            AddSource::Magnet(uri) => {
                // Magnet path: stays inline (out of M223 scope).
                let result: crate::Result<Id20> = async {
                    let magnet = irontide_core::Magnet::parse(&uri)?;
                    let info_hash = magnet.info_hash();
                    self.reject_if_in_deletion_grace(info_hash)?;
                    let id = self.handle_add_magnet(magnet, resolved_dir, tags).await?;
                    self.apply_post_add_m170(id, resolved_category, paused);
                    Ok(id)
                }
                .await;
                let _ = reply.send(result);
            }
            AddSource::Bytes(bytes) => {
                // Bytes path: spawn-per-add.
                let setup: crate::Result<AddTorrentPrepBundle> = (|| {
                    let meta = irontide_core::torrent_from_bytes_any(&bytes)?;
                    let info_hash = meta
                        .as_v1()
                        .map_or_else(|| meta.info_hashes().best_v1(), |v| v.info_hash);
                    self.reject_if_in_deletion_grace(info_hash)?;
                    if self.torrents.contains_key(&info_hash) {
                        return Err(crate::Error::DuplicateTorrent(info_hash));
                    }
                    if self.torrents.len() >= self.settings.max_torrents {
                        return Err(crate::Error::SessionAtCapacity(self.settings.max_torrents));
                    }
                    Ok(self.build_add_torrent_prep_bundle(
                        meta,
                        None,
                        resolved_dir,
                        tags,
                        Some(M170PostAdd {
                            category: resolved_category,
                            paused,
                        }),
                    ))
                })();
                match setup {
                    Ok(bundle) => self.try_spawn_add_torrent(bundle, reply),
                    Err(e) => {
                        let _ = reply.send(Err(e));
                    }
                }
            }
        }
    }

    /// Resolve the effective download directory + the category label to
    /// store on the `TorrentConfig`, following the M170 precedence rules.
    fn resolve_download_dir_and_category(
        &self,
        params: &AddTorrentParams,
    ) -> crate::Result<(Option<PathBuf>, Option<String>)> {
        match (&params.download_dir, &params.category) {
            (Some(explicit), cat) => {
                // Explicit path wins even when a category is set — qBt
                // preserves the category label either way.
                Ok((Some(explicit.clone()), cat.clone()))
            }
            (None, Some(name)) => {
                let registry = self.category_registry.read();
                match registry.get(name) {
                    Some(meta) => Ok((Some(meta.save_path.clone()), Some(name.clone()))),
                    None => Err(crate::Error::CategoryNotFound(name.clone())),
                }
            }
            (None, None) => Ok((None, None)),
        }
    }

    /// Return an error if `info_hash` is currently being removed by a
    /// deleteFiles=true call in another task.
    fn reject_if_in_deletion_grace(&self, info_hash: Id20) -> crate::Result<()> {
        if self.deletion_grace.lock().contains(&info_hash) {
            return Err(crate::Error::TorrentBeingRemoved(info_hash));
        }
        Ok(())
    }

    /// Post-add M170 hooks: stash the category label and mark the torrent
    /// paused if requested. Category is recorded for the initial stats
    /// snapshot; paused-on-add uses the existing pause path.
    fn apply_post_add_m170(&self, info_hash: Id20, category: Option<String>, paused: bool) {
        if let Some(entry) = self.torrents.get(&info_hash) {
            // Category label: stored on the torrent handle's config mirror
            // so future `stats()` calls include it. Fire-and-forget
            // because the field is non-load-bearing for the add path.
            if let Some(name) = category {
                let handle = entry.handle.clone();
                tokio::spawn(async move {
                    if let Err(e) = handle.set_category(Some(name)).await {
                        warn!(%info_hash, "failed to propagate category: {e}");
                    }
                });
            }
            if paused {
                let handle = entry.handle.clone();
                tokio::spawn(async move {
                    if let Err(e) = handle.pause().await {
                        warn!(%info_hash, "failed to pause on add: {e}");
                    }
                });
            }
        }
    }

    /// M170: create a category, persist the registry on success.
    async fn handle_create_category(
        &self,
        name: String,
        save_path: PathBuf,
    ) -> Result<(), crate::category_manager::CategoryError> {
        {
            let mut registry = self.category_registry.write();
            registry.create(name, save_path)?;
        }
        self.persist_category_registry().await
    }

    /// M170: edit a category, persist the registry on success.
    async fn handle_edit_category(
        &self,
        name: String,
        save_path: PathBuf,
    ) -> Result<(), crate::category_manager::CategoryError> {
        {
            let mut registry = self.category_registry.write();
            registry.edit(&name, save_path)?;
        }
        self.persist_category_registry().await
    }

    /// M170: remove categories, clear labels on affected torrents, and
    /// persist the registry. Returns the names that were actually
    /// removed so the CLI / qBt handler can log or echo them.
    async fn handle_remove_categories(&self, names: Vec<String>) -> Vec<String> {
        let removed: Vec<String> = {
            let mut registry = self.category_registry.write();
            registry.remove(&names)
        };
        if removed.is_empty() {
            return removed;
        }

        // Clear the `category` label on every torrent assigned to a
        // removed name. Fire-and-forget per torrent — failure only
        // costs us label-sync (not data).
        for entry in self.torrents.values() {
            let handle = entry.handle.clone();
            let to_check: Vec<String> = removed.clone();
            tokio::spawn(async move {
                if let Ok(stats) = handle.stats().await
                    && let Some(current) = stats.category
                    && to_check.iter().any(|n| n.as_str() == current.as_str())
                    && let Err(e) = handle.set_category(None).await
                {
                    warn!(
                        cat = %current,
                        "failed to clear category label after removeCategories: {e}"
                    );
                }
            });
        }

        if let Err(e) = self.persist_category_registry().await {
            warn!("failed to persist category registry after remove: {e}");
        }
        removed
    }

    /// Spawn a blocking task to persist the registry to disk.
    async fn persist_category_registry(
        &self,
    ) -> Result<(), crate::category_manager::CategoryError> {
        let registry = Arc::clone(&self.category_registry);
        // Clone the current registry state out of the lock to avoid
        // holding it across the spawn_blocking boundary.
        let snapshot = registry.read().clone();
        tokio::task::spawn_blocking(move || snapshot.save())
            .await
            .map_err(|join_err| {
                crate::category_manager::CategoryError::Persistence(std::io::Error::other(format!(
                    "category registry save join error: {join_err}"
                )))
            })?
    }

    /// M171: delete a batch of tags. Returns the subset of names that
    /// were actually present at call time (unknown names are silently
    /// ignored, matching qBt `deleteTags`).
    ///
    /// After removal, any torrent carrying a deleted tag has that tag
    /// pruned from its label set via `TorrentHandle::set_tags`.
    async fn handle_delete_tags(&self, names: Vec<String>) -> Vec<String> {
        let removed = {
            let mut reg = self.tag_registry.write();
            reg.delete(&names)
        };
        if !removed.is_empty() {
            let to_remove: std::collections::HashSet<String> = removed.iter().cloned().collect();
            for entry in self.torrents.values() {
                let handle = entry.handle.clone();
                let to_remove = to_remove.clone();
                tokio::spawn(async move {
                    if let Ok(stats) = handle.stats().await {
                        let new_tags: Vec<String> = stats
                            .tags
                            .into_iter()
                            .filter(|t| !to_remove.contains(t))
                            .collect();
                        if let Err(e) = handle.set_tags(new_tags).await {
                            tracing::warn!(error = %e, "failed to apply tag deletion to torrent");
                        }
                    }
                });
            }
            if let Err(e) = self.persist_tag_registry().await {
                tracing::warn!(error = %e, "persist tag registry after DeleteTags");
            }
        }
        removed
    }

    /// M171: add the given tags to each torrent in `info_hashes`. The
    /// engine-layer command is a wholesale replacement, so this reads
    /// the current tag set for each torrent, unions in the requested
    /// tags (sorted + deduped), and replays the result via
    /// `TorrentHandle::set_tags`. Unknown info hashes are silently
    /// skipped — qBt's `addTags` behaviour.
    ///
    /// # Errors
    ///
    /// Propagates [`crate::Error::Shutdown`] if a torrent actor has
    /// stopped while the batch was in flight.
    async fn handle_add_tags_to_torrents(
        &self,
        info_hashes: Vec<Id20>,
        tags_to_add: Vec<String>,
    ) -> crate::Result<()> {
        for hash in info_hashes {
            let Some(entry) = self.torrents.get(&hash) else {
                continue;
            };
            let current = entry.handle.stats().await?;
            let mut new_tags = current.tags;
            for t in &tags_to_add {
                if !new_tags.contains(t) {
                    new_tags.push(t.clone());
                }
            }
            new_tags.sort();
            new_tags.dedup();
            entry.handle.set_tags(new_tags).await?;
        }
        Ok(())
    }

    /// M171: remove the given tags from each torrent in `info_hashes`.
    /// Unknown info hashes are silently skipped — qBt's `removeTags`
    /// behaviour.
    ///
    /// # Errors
    ///
    /// Propagates [`crate::Error::Shutdown`] if a torrent actor has
    /// stopped while the batch was in flight.
    async fn handle_remove_tags_from_torrents(
        &self,
        info_hashes: Vec<Id20>,
        tags_to_remove: Vec<String>,
    ) -> crate::Result<()> {
        for hash in info_hashes {
            let Some(entry) = self.torrents.get(&hash) else {
                continue;
            };
            let current = entry.handle.stats().await?;
            let new_tags: Vec<String> = current
                .tags
                .into_iter()
                .filter(|t| !tags_to_remove.contains(t))
                .collect();
            entry.handle.set_tags(new_tags).await?;
        }
        Ok(())
    }

    /// M171: spawn a blocking task to persist the tag registry to disk.
    /// Mirrors `persist_category_registry`.
    async fn persist_tag_registry(&self) -> Result<(), crate::tag_manager::TagError> {
        let to_save: crate::tag_manager::TagRegistry = { self.tag_registry.read().clone() };
        tokio::task::spawn_blocking(move || to_save.save())
            .await
            .unwrap_or_else(|_| {
                Err(crate::tag_manager::TagError::Persistence(
                    std::io::Error::other("spawn_blocking failed"),
                ))
            })
    }

    /// M170: remove a torrent and delete its files from disk.
    async fn handle_remove_torrent_with_files(&mut self, info_hash: Id20) -> crate::Result<()> {
        // v0.173.1: query the TorrentActor for metadata instead of reading
        // the deleted `TorrentEntry.meta` cache. For magnet torrents with
        // resolved metadata this returns the real file list (fixing the
        // v0.173.0 silent-no-op-on-disk bug). For magnets *still resolving*
        // we treat it as an empty file list and still proceed with the
        // session-level removal — matches the pre-v0.173.1 observable
        // behaviour that the *arr e2e test relies on (`deleteFiles=true` on
        // a pre-metadata magnet leaves `download_dir` untouched but cleanly
        // removes the torrent from the registry).
        let handle = {
            let entry = self
                .torrents
                .get(&info_hash)
                .ok_or(crate::Error::TorrentNotFound(info_hash))?;
            entry.handle.clone()
        };
        let file_paths: Vec<PathBuf> = match handle.get_meta().await {
            Ok(Some(meta)) => meta
                .info
                .files()
                .iter()
                .map(|f| f.path.iter().collect::<PathBuf>())
                .collect(),
            // Meta not yet resolved (pre-metadata magnet) or actor shut down:
            // nothing to walk on disk. Session-level removal still proceeds.
            Ok(None) | Err(_) => Vec::new(),
        };
        let download_dir = self.settings.download_dir.clone();
        let _ = handle.pause().await;

        // Enter the deletion grace window BEFORE dropping the in-memory
        // entry — any add that races in during the walk will see the
        // grace set and get 409'd.
        self.deletion_grace.lock().insert(info_hash);

        // Remove from session (same as the existing path — closes
        // storage handles, deletes resume file, etc.).
        let remove_result = self.handle_remove_torrent(info_hash).await;
        if let Err(e) = &remove_result {
            warn!(
                %info_hash,
                error = %e,
                "remove_torrent_with_files: in-memory removal failed; continuing with file delete"
            );
        }

        // Now blast the files. `download_dir` is the session default (good
        // enough for M170 because add_torrent threads the same dir through
        // to storage). Once per-torrent save path is recorded (future
        // milestone), swap this out.
        let grace = Arc::clone(&self.deletion_grace);
        tokio::task::spawn_blocking(move || {
            irontide_storage::delete_torrent_files_sync(download_dir, file_paths);
            grace.lock().remove(&info_hash);
        });

        Ok(())
    }

    async fn handle_pause_torrent(&mut self, info_hash: Id20) -> crate::Result<()> {
        let entry = self
            .torrents
            .get(&info_hash)
            .ok_or(crate::Error::TorrentNotFound(info_hash))?;
        entry.handle.pause().await
    }

    async fn handle_resume_torrent(&mut self, info_hash: Id20) -> crate::Result<()> {
        let entry = self
            .torrents
            .get(&info_hash)
            .ok_or(crate::Error::TorrentNotFound(info_hash))?;
        entry.handle.resume().await
    }

    async fn handle_force_resume_torrent(&mut self, info_hash: Id20) -> crate::Result<()> {
        let entry = self
            .torrents
            .get(&info_hash)
            .ok_or(crate::Error::TorrentNotFound(info_hash))?;
        entry
            .handle
            .cmd_tx
            .send(crate::types::TorrentCommand::ForceResume)
            .await
            .map_err(|_| crate::Error::Shutdown)
    }

    async fn handle_set_torrent_seed_ratio(
        &self,
        info_hash: Id20,
        limit: Option<f64>,
    ) -> crate::Result<()> {
        let entry = self
            .torrents
            .get(&info_hash)
            .ok_or(crate::Error::TorrentNotFound(info_hash))?;
        let (tx, rx) = oneshot::channel();
        entry
            .handle
            .cmd_tx
            .send(crate::types::TorrentCommand::SetSeedRatioLimit { limit, reply: tx })
            .await
            .map_err(|_| crate::Error::Shutdown)?;
        rx.await.map_err(|_| crate::Error::Shutdown)
    }

    async fn handle_move_torrent_storage(
        &self,
        info_hash: Id20,
        new_path: std::path::PathBuf,
    ) -> crate::Result<()> {
        let entry = self
            .torrents
            .get(&info_hash)
            .ok_or(crate::Error::TorrentNotFound(info_hash))?;
        entry.handle.move_storage(new_path).await
    }

    async fn handle_torrent_stats(&self, info_hash: Id20) -> crate::Result<TorrentStats> {
        let entry = self
            .torrents
            .get(&info_hash)
            .ok_or(crate::Error::TorrentNotFound(info_hash))?;
        let mut stats = entry.handle.stats().await?;
        // Enrich with session-level data that the torrent actor doesn't own.
        stats.queue_position = entry.queue_position;
        stats.auto_managed = entry.auto_managed;
        Ok(stats)
    }

    async fn handle_torrent_info(&self, info_hash: Id20) -> crate::Result<TorrentInfo> {
        // v0.173.1: queries the TorrentActor (single source of truth) instead
        // of reading the deleted `TorrentEntry.meta` cache. For magnet torrents
        // this returns the real meta once assembled, where v0.173.0 always saw
        // `None` → 404 on `/api/v2/torrents/files`.
        let meta = self.get_entry_meta(info_hash).await?;
        let files: Vec<FileInfo> = if let Some(ref file_list) = meta.info.files {
            file_list
                .iter()
                .map(|f| FileInfo {
                    path: f.path.iter().collect::<PathBuf>(),
                    length: f.length,
                })
                .collect()
        } else {
            vec![FileInfo {
                path: PathBuf::from(&meta.info.name),
                length: meta.info.total_length(),
            }]
        };

        Ok(TorrentInfo {
            info_hash,
            name: meta.info.name.clone(),
            total_length: meta.info.total_length(),
            piece_length: meta.info.piece_length,
            num_pieces: meta.info.num_pieces() as u32,
            files,
            private: meta.info.private == Some(1),
        })
    }

    /// Update gauge metrics that come from session-level state.
    fn update_session_gauges(&self) {
        use crate::stats::{
            DHT_NODES, DHT_NODES_V4, DHT_NODES_V6, PEER_NUM_BANNED, SES_ACTIVE_TORRENTS,
            SES_NUM_TORRENTS,
        };
        let c = &self.counters;
        c.set(SES_NUM_TORRENTS, self.torrents.len() as i64);
        c.set(SES_ACTIVE_TORRENTS, self.torrents.len() as i64);

        // DHT presence (instance count, not routing table size)
        let dht_nodes = i64::from(self.dht_v4.is_some()) + i64::from(self.dht_v6.is_some());
        c.set(DHT_NODES, dht_nodes);
        c.set(DHT_NODES_V4, i64::from(self.dht_v4.is_some()));
        c.set(DHT_NODES_V6, i64::from(self.dht_v6.is_some()));

        // Ban count
        let ban_count = self.ban_manager.read().banned_list().len() as i64;
        c.set(PEER_NUM_BANNED, ban_count);
    }

    /// Snapshot counters and fire a `SessionStatsAlert`.
    fn fire_stats_alert(&self) {
        self.update_session_gauges();
        let values = self.counters.snapshot();
        crate::alert::post_alert(
            &self.alert_tx,
            &self.alert_mask,
            crate::alert::AlertKind::SessionStatsAlert { values },
        );
    }

    /// Fire a periodic BEP 51 `sample_infohashes` query to the DHT (M111).
    async fn fire_sample_infohashes(&self) {
        let ((Some(dht), _) | (_, Some(dht))) = (&self.dht_v4, &self.dht_v6) else {
            return;
        };
        let mut buf = [0u8; 20];
        irontide_core::random_bytes(&mut buf);
        let target = Id20::from(buf);
        match dht.sample_infohashes(target).await {
            Ok(result) => {
                post_alert(
                    &self.alert_tx,
                    &self.alert_mask,
                    AlertKind::DhtSampleInfohashes {
                        num_samples: result.samples.len(),
                        total_estimate: result.num,
                    },
                );
            }
            Err(e) => {
                debug!("sample_infohashes failed: {e}");
            }
        }
    }

    /// M245 C1 — fan out `stats()` to every torrent ONCE (bounded per-torrent),
    /// returning the `(info_hash, stats)` pairs that answered within budget.
    ///
    /// L2 (M241): issue every per-torrent `stats()` request up front and collect
    /// replies as they arrive, instead of awaiting each sequentially (audit
    /// Tier-2 L2 — head-of-line blocking on the recv loop). Each request is
    /// bounded by a 500 ms timeout mirroring `make_debug_state` (eng-review F5):
    /// this runs ON the recv loop, so without a bound a single wedged
    /// `TorrentActor` would freeze all session commands indefinitely. A torrent
    /// that times out contributes nothing to THIS sample (a rare transient
    /// counter dip — the same trade-off `make_debug_state` already makes) rather
    /// than hanging the whole engine.
    ///
    /// The single fan-out feeds BOTH the [`SessionStats`] sums and the published
    /// [`SessionSnapshot`] refresh in [`make_session_stats`](Self::make_session_stats)
    /// — there is no second per-torrent round-trip per tick.
    async fn collect_torrent_stats(&self) -> Vec<(Id20, TorrentStats)> {
        use futures::stream::{FuturesUnordered, StreamExt};

        let mut futs: FuturesUnordered<_> = self
            .torrents
            .iter()
            .map(|(&info_hash, entry)| {
                let handle = entry.handle.clone();
                async move {
                    tokio::time::timeout(std::time::Duration::from_millis(500), handle.stats())
                        .await
                        .ok()
                        .and_then(Result::ok)
                        .map(|stats| (info_hash, stats))
                }
            })
            .collect();

        let mut out = Vec::with_capacity(self.torrents.len());
        while let Some(maybe) = futs.next().await {
            if let Some(pair) = maybe {
                out.push(pair);
            }
        }
        out
    }

    /// M245 A1 — eager membership: publish ONE torrent's current summary into
    /// the snapshot the instant its add commits, so reads are read-after-write
    /// consistent (the torrent is visible immediately, not one stats tick
    /// later). One bounded round-trip for THIS torrent only — NOT a fan-out.
    /// If the freshly-spawned actor doesn't answer within the budget, the
    /// torrent simply appears on the next tick (the snapshot rebuilds its
    /// membership from `self.torrents` every tick — see `make_session_stats`).
    async fn snapshot_publish_one(&self, info_hash: Id20) {
        let handle = match self.torrents.get(&info_hash) {
            Some(entry) => entry.handle.clone(),
            None => return,
        };
        if let Ok(Ok(stats)) =
            tokio::time::timeout(std::time::Duration::from_millis(500), handle.stats()).await
        {
            let mut map = self.snapshot.load().as_map().clone();
            map.insert(info_hash, TorrentSummary::from(&stats));
            self.snapshot
                .store(Arc::new(SessionSnapshot::from_map(map)));
        }
    }

    /// M245 A1 — eager membership: drop ONE torrent from the snapshot the
    /// instant its removal commits (read-after-write). Pure map edit, no
    /// round-trip.
    fn snapshot_drop_one(&self, info_hash: Id20) {
        let mut map = self.snapshot.load().as_map().clone();
        if map.remove(&info_hash).is_some() {
            self.snapshot
                .store(Arc::new(SessionSnapshot::from_map(map)));
        }
    }

    async fn make_session_stats(&self) -> SessionStats {
        self.update_session_gauges();

        let active_torrents = self.torrents.len();
        let dht_nodes = usize::from(self.dht_v4.is_some()) + usize::from(self.dht_v6.is_some());

        // C1 (M245): ONE fan-out per tick. Sum the session counters AND refresh
        // the published snapshot from the SAME (id, stats) pairs — no second
        // round-trip.
        let collected = self.collect_torrent_stats().await;

        let mut total_downloaded = 0u64;
        let mut total_uploaded = 0u64;
        let mut responded = std::collections::HashMap::with_capacity(collected.len());
        for (info_hash, stats) in collected {
            total_downloaded = total_downloaded.saturating_add(stats.downloaded);
            total_uploaded = total_uploaded.saturating_add(stats.uploaded);
            responded.insert(info_hash, stats);
        }

        // Rebuild the snapshot keyed by the LIVE membership (`self.torrents` is
        // the source of truth — this self-heals any eager-hook drift). A torrent
        // that answered gets a fresh summary; one that timed out THIS tick
        // carries forward its previous summary (eventually-consistent to one
        // tick — the D2 contract) rather than vanishing from reads.
        let prev = self.snapshot.load();
        let mut map = std::collections::BTreeMap::new();
        for &info_hash in self.torrents.keys() {
            if let Some(stats) = responded.get(&info_hash) {
                map.insert(info_hash, TorrentSummary::from(stats));
            } else if let Some(prev_summary) = prev.as_map().get(&info_hash) {
                map.insert(info_hash, prev_summary.clone());
            }
        }
        self.snapshot
            .store(Arc::new(SessionSnapshot::from_map(map)));

        SessionStats {
            active_torrents,
            total_downloaded,
            total_uploaded,
            dht_nodes,
        }
    }

    /// Build a debug state snapshot across all torrents, collecting per-torrent
    /// stats and per-peer details. Torrents that time out are skipped so a
    /// single slow actor never blocks the whole response.
    async fn make_debug_state(&self) -> crate::types::DebugState {
        use crate::stats::{
            DISPATCH_ACQUIRE_NONE_TOTAL, DISPATCH_ACQUIRE_TOTAL, DISPATCH_ACQUIRE_US,
            DISPATCH_NOTIFY_WAKEUP_TOTAL,
        };

        // Session-wide dispatch counters from the atomic counters array.
        let snap = self.counters.snapshot();
        let dispatch = crate::types::DebugDispatchState {
            acquire_total: snap[DISPATCH_ACQUIRE_TOTAL],
            acquire_none_total: snap[DISPATCH_ACQUIRE_NONE_TOTAL],
            acquire_us: snap[DISPATCH_ACQUIRE_US],
            notify_wakeup_total: snap[DISPATCH_NOTIFY_WAKEUP_TOTAL],
            pieces_queued: 0,
            pieces_inflight: 0,
        };

        let mut torrents = Vec::with_capacity(self.torrents.len());
        for (&info_hash, entry) in &self.torrents {
            // Per-torrent stats — skip if the actor is slow.
            let Ok(Ok(stats)) =
                tokio::time::timeout(std::time::Duration::from_millis(500), entry.handle.stats())
                    .await
            else {
                continue;
            };

            // Per-peer details — skip on timeout.
            let peers_raw = match tokio::time::timeout(
                std::time::Duration::from_millis(500),
                entry.handle.get_peer_info(),
            )
            .await
            {
                Ok(Ok(p)) => p,
                _ => Vec::new(),
            };

            let peers: Vec<crate::types::DebugPeerState> = peers_raw
                .iter()
                .map(|p| crate::types::DebugPeerState {
                    addr: p.addr,
                    in_flight: p.in_flight_requests,
                    target_depth: p.target_pipeline_depth,
                    choking: p.peer_choking,
                    download_rate: p.download_rate,
                })
                .collect();

            let mut per_torrent_dispatch = dispatch.clone();
            per_torrent_dispatch.pieces_queued = stats.dispatch_pieces_queued;
            per_torrent_dispatch.pieces_inflight = stats.dispatch_pieces_inflight;

            torrents.push(crate::types::DebugTorrentState {
                info_hash: info_hash.to_hex(),
                state: format!("{:?}", stats.state),
                num_peers: stats.peers_connected,
                dispatch: per_torrent_dispatch,
                peers,
            });
        }

        crate::types::DebugState { torrents }
    }

    async fn handle_save_torrent_resume(
        &self,
        info_hash: Id20,
    ) -> crate::Result<irontide_core::FastResumeData> {
        let entry = self
            .torrents
            .get(&info_hash)
            .ok_or(crate::Error::TorrentNotFound(info_hash))?;
        let mut resume = entry.handle.save_resume_data().await?;
        // Patch in queue state from SessionActor's TorrentEntry (the
        // TorrentHandle doesn't know about queue position / auto-managed).
        resume.queue_position = i64::from(entry.queue_position);
        resume.auto_managed = i64::from(entry.auto_managed);
        Ok(resume)
    }

    async fn handle_save_session_state(&self) -> crate::Result<crate::persistence::SessionState> {
        use crate::persistence::SessionState;

        let mut torrents = Vec::new();
        for (info_hash, entry) in &self.torrents {
            match entry.handle.save_resume_data().await {
                Ok(rd) => torrents.push(rd),
                Err(e) => {
                    warn!(%info_hash, "failed to save resume data: {e}");
                }
            }
        }

        // Serialize smart ban state (scoped to drop RwLockReadGuard before awaits)
        let (banned_peers, peer_strikes) = {
            let ban_mgr = self.ban_manager.read();
            let banned_peers: Vec<String> = ban_mgr
                .banned_list()
                .iter()
                .map(std::string::ToString::to_string)
                .collect();
            let peer_strikes: Vec<crate::persistence::PeerStrikeEntry> = ban_mgr
                .strikes_map()
                .iter()
                .map(|(ip, &count)| crate::persistence::PeerStrikeEntry {
                    ip: ip.to_string(),
                    count: i64::from(count),
                })
                .collect();
            (banned_peers, peer_strikes)
        };

        let mut dht_entries = Vec::new();
        let mut dht_node_id = None;
        if let Some(ref dht) = self.dht_v4 {
            // Save the (possibly BEP 42-regenerated) node ID for next session
            if let Ok(stats) = dht.stats().await {
                dht_node_id = Some(stats.node_id.to_hex());
            }
            for (_id, addr) in dht.get_routing_nodes().await {
                dht_entries.push(crate::persistence::DhtNodeEntry {
                    host: addr.ip().to_string(),
                    port: i64::from(addr.port()),
                });
            }
        }
        if let Some(ref dht) = self.dht_v6 {
            for (_id, addr) in dht.get_routing_nodes().await {
                dht_entries.push(crate::persistence::DhtNodeEntry {
                    host: addr.ip().to_string(),
                    port: i64::from(addr.port()),
                });
            }
        }

        Ok(SessionState {
            dht_nodes: dht_entries,
            dht_node_id,
            torrents,
            banned_peers,
            peer_strikes,
        })
    }

    /// Compute the effective resume data directory from settings.
    fn effective_resume_dir(&self) -> PathBuf {
        self.settings
            .resume_data_dir
            .clone()
            .unwrap_or_else(crate::resume_file::default_resume_dir)
    }

    /// Load and restore torrents from per-torrent resume files on disk.
    ///
    /// Scans the resume directory, deserializes each `.resume` file, reconstructs
    /// the torrent metadata or magnet, adds it to the session, and restores the
    /// piece bitmap where available.
    async fn handle_load_resume_state(&mut self) -> crate::Result<ResumeLoadResult> {
        let resume_dir = self.effective_resume_dir();
        let paths = crate::resume_file::scan_resume_dir(&resume_dir);

        let mut restored = 0usize;
        let mut skipped = 0usize;
        let mut failed = 0usize;

        for path in &paths {
            let file_name = path
                .file_name()
                .and_then(|n| n.to_str())
                .unwrap_or("<unknown>");

            // Read and deserialize
            let bytes = match std::fs::read(path) {
                Ok(b) => b,
                Err(e) => {
                    warn!(file = %file_name, "failed to read resume file: {e}");
                    failed = failed.saturating_add(1);
                    continue;
                }
            };

            let rd = match crate::resume_file::deserialize_resume(&bytes) {
                Ok(rd) => rd,
                Err(e) => {
                    warn!(file = %file_name, "failed to deserialize resume file: {e}");
                    failed = failed.saturating_add(1);
                    continue;
                }
            };

            // Try to reconstruct as a resolved torrent (info dict present).
            if let Some(meta) = crate::resume_file::reconstruct_torrent_meta(&rd) {
                let info_hash = meta.info_hash;
                let pieces = rd.pieces.clone();
                let torrent_meta = irontide_core::TorrentMeta::V1(meta);

                // Restore to the original save_path (per-torrent download dir).
                let restore_dir = if rd.save_path.is_empty() {
                    None
                } else {
                    Some(PathBuf::from(&rd.save_path))
                };
                // M171: restore tags by baking them into the TorrentConfig
                // at add-time, matching the `AddTorrentParams::with_tags`
                // semantics. Category still goes through the post-add
                // fire-and-forget path (M170 behaviour preserved).
                let restore_tags = rd.tags.clone();
                match self
                    .handle_add_torrent(torrent_meta, None, restore_dir, restore_tags)
                    .await
                {
                    Ok(added_hash) => {
                        // Restore the piece bitmap if non-empty.
                        if !pieces.is_empty()
                            && let Some(entry) = self.torrents.get(&added_hash)
                            && let Err(e) = entry.handle.restore_resume_bitmap(pieces).await
                        {
                            warn!(
                                %info_hash,
                                "failed to restore piece bitmap, torrent will recheck: {e}"
                            );
                        }
                        // M170: restore the category label if persisted.
                        if let Some(ref cat) = rd.category
                            && let Some(entry) = self.torrents.get(&added_hash)
                        {
                            let handle = entry.handle.clone();
                            let cat_owned = cat.clone();
                            tokio::spawn(async move {
                                let _ = handle.set_category(Some(cat_owned)).await;
                            });
                        }
                        // M178: restore per-URL web-seed stats so cumulative
                        // bytes and error history survive app restart.
                        if !rd.web_seed_stats.is_empty()
                            && let Some(entry) = self.torrents.get(&added_hash)
                        {
                            let handle = entry.handle.clone();
                            let stats_owned = rd.web_seed_stats.clone();
                            tokio::spawn(async move {
                                let _ = handle.restore_web_seed_stats(stats_owned).await;
                            });
                        }
                        if self.settings.queueing_enabled
                            && let Some(entry) = self.torrents.get(&added_hash)
                        {
                            let _ = entry.handle.queue().await;
                        }
                        if let Some(entry) = self.torrents.get_mut(&added_hash) {
                            entry.queue_position = rd.queue_position as i32;
                            entry.auto_managed = rd.auto_managed != 0;
                        }
                        info!(%info_hash, "restored torrent from resume file");
                        restored = restored.saturating_add(1);
                    }
                    Err(crate::Error::DuplicateTorrent(_)) => {
                        debug!(%info_hash, "skipped duplicate torrent from resume");
                        skipped = skipped.saturating_add(1);
                    }
                    Err(e) => {
                        warn!(%info_hash, "failed to add restored torrent: {e}");
                        failed = failed.saturating_add(1);
                    }
                }
            } else if let Some(magnet) = crate::resume_file::reconstruct_magnet(&rd) {
                // Unresolved magnet: re-add as magnet link.
                let info_hash = magnet.info_hash();
                let restore_dir = if rd.save_path.is_empty() {
                    None
                } else {
                    Some(PathBuf::from(&rd.save_path))
                };
                // M171: restore tags via the add-time config bake path.
                let restore_tags = rd.tags.clone();
                match self
                    .handle_add_magnet(magnet, restore_dir, restore_tags)
                    .await
                {
                    Ok(added_hash) => {
                        // M170: restore category on magnet too.
                        if let Some(ref cat) = rd.category
                            && let Some(entry) = self.torrents.get(&added_hash)
                        {
                            let handle = entry.handle.clone();
                            let cat_owned = cat.clone();
                            tokio::spawn(async move {
                                let _ = handle.set_category(Some(cat_owned)).await;
                            });
                        }
                        // M178: restore per-URL web-seed stats on magnet too,
                        // so resumes from a magnet-added torrent that already
                        // had web-seed activity recover correctly.
                        if !rd.web_seed_stats.is_empty()
                            && let Some(entry) = self.torrents.get(&added_hash)
                        {
                            let handle = entry.handle.clone();
                            let stats_owned = rd.web_seed_stats.clone();
                            tokio::spawn(async move {
                                let _ = handle.restore_web_seed_stats(stats_owned).await;
                            });
                        }
                        if self.settings.queueing_enabled
                            && let Some(entry) = self.torrents.get(&added_hash)
                        {
                            let _ = entry.handle.queue().await;
                        }
                        if let Some(entry) = self.torrents.get_mut(&added_hash) {
                            entry.queue_position = rd.queue_position as i32;
                            entry.auto_managed = rd.auto_managed != 0;
                        }
                        info!(%info_hash, "restored magnet from resume file");
                        restored = restored.saturating_add(1);
                    }
                    Err(crate::Error::DuplicateTorrent(_)) => {
                        debug!(%info_hash, "skipped duplicate magnet from resume");
                        skipped = skipped.saturating_add(1);
                    }
                    Err(e) => {
                        warn!(%info_hash, "failed to add restored magnet: {e}");
                        failed = failed.saturating_add(1);
                    }
                }
            } else {
                warn!(file = %file_name, "resume file has no valid info dict and no valid info hash");
                failed = failed.saturating_add(1);
            }
        }

        // Renormalize queue positions to contiguous 0..N-1. Handles
        // duplicate positions from crash mid-save, manual edits, or
        // older resume formats that default all positions to 0.
        {
            let mut entries: Vec<(Id20, i32)> = self
                .torrents
                .iter()
                .filter(|(_, e)| e.auto_managed)
                .map(|(h, e)| (*h, e.queue_position))
                .collect();
            entries.sort_by_key(|&(_, pos)| pos);
            for (new_pos, (hash, _)) in entries.into_iter().enumerate() {
                if let Some(entry) = self.torrents.get_mut(&hash) {
                    entry.queue_position = new_pos as i32;
                }
            }
        }

        info!(restored, skipped, failed, "resume state loaded");
        Ok(ResumeLoadResult {
            restored,
            skipped,
            failed,
        })
    }

    /// Save resume files for all torrents with a dirty `need_save_resume` flag.
    ///
    /// Returns the number of resume files successfully written.
    /// Snapshot the data `run_resume_save_jobs` needs while we hold `&self` on
    /// the actor. Cheap — clones channel-sender handles + copies queue metadata.
    fn snapshot_resume_jobs(&self) -> (std::path::PathBuf, Vec<ResumeSaveJob>) {
        let resume_dir = self.effective_resume_dir();
        let jobs = self
            .torrents
            .iter()
            .map(|(info_hash, entry)| ResumeSaveJob {
                info_hash: *info_hash,
                handle: entry.handle.clone(),
                queue_position: i64::from(entry.queue_position),
                auto_managed: i64::from(entry.auto_managed),
            })
            .collect();
        (resume_dir, jobs)
    }

    /// Save resume files for all dirty torrents, inline. Retained for the
    /// shutdown path, which MUST await the save to completion before the process
    /// exits (terminal — recv-loop liveness no longer matters there). Acquires
    /// `resume_save_lock` first so it waits behind any in-flight spawned save
    /// rather than racing it onto the same temp path (F4); since shutdown runs
    /// this BEFORE draining torrents, the awaited periodic save still completes.
    /// The periodic timer + `SaveResumeState` RPC instead spawn
    /// `run_resume_save_jobs` while holding the lock, so they never block the loop.
    async fn save_dirty_resume_files(&self) -> usize {
        let _guard = self.resume_save_lock.lock().await;
        let (resume_dir, jobs) = self.snapshot_resume_jobs();
        run_resume_save_jobs(resume_dir, jobs).await
    }

    /// Apply new settings at runtime, transactionally (M173 Lane B, B1).
    ///
    /// Phases (executed in order; rollback in REVERSE on first failure):
    ///
    /// 1. Rate limits + alert mask (cheap; rollback restores)
    /// 2. Listen-port rebind (B4 wires the real reconfig — B1 stub no-op)
    /// 3. DHT enable/disable (B5-B7 wire — B1 stub no-op)
    /// 4. LSD enable/disable (B9 wires — B1 stub no-op)
    ///
    /// On any phase failure, already-applied phases roll back (LIFO) and
    /// the caller sees the original [`crate::Error`] that triggered the
    /// failure. Until B4-B9 land, phases 2-4 are no-ops, so this method
    /// behaves identically to the M171 implementation for callers that
    /// only patch rate limits / alert mask. Listen-port / DHT / LSD
    /// changes are still classified as "`restart_required`" by
    /// [`classify_restart_required`] until B10 graduates them.
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::InvalidSettings`] if `Settings::validate`
    /// rejects the new patch. Future variants from B4-B9 will surface
    /// listener / DHT / LSD restart failures via [`crate::apply::ApplyError`].
    fn handle_apply_settings(&mut self, new: Settings) -> crate::Result<()> {
        // Validate FIRST so that an invalid patch never even enters the
        // transactional pipeline. This matches the M171 behaviour.
        new.validate()?;

        // Snapshot pre-call values for rollback closures. These are
        // captured by-value so the rollback closures can run without
        // borrowing `self` (the executor needs `&mut self`).
        let old_upload_rate = self.settings.upload_rate_limit;
        let old_download_rate = self.settings.download_rate_limit;
        let old_alert_mask = self.settings.alert_mask;
        let old_settings = self.settings.clone();
        let old_settings_for_delta = self.settings.clone();

        let new_upload_rate = new.upload_rate_limit;
        let new_download_rate = new.download_rate_limit;
        let new_alert_mask = new.alert_mask;

        // Phase 1: rate limits + alert mask + Settings struct.
        // The rollback restores all four mutations (rate buckets +
        // mask atomic + Settings struct) — Settings is cloned for
        // restoration so the caller sees the original on failure.
        let upload_bucket = Arc::clone(&self.global_upload_bucket);
        let download_bucket = Arc::clone(&self.global_download_bucket);
        let alert_mask = Arc::clone(&self.alert_mask);

        let phase1: crate::apply::Phase<Self> = crate::apply::Phase {
            name: "rate_limits_and_mask",
            forward: Box::new(move |this: &mut Self| {
                if new_upload_rate != old_upload_rate {
                    upload_bucket.lock().set_rate(new_upload_rate);
                }
                if new_download_rate != old_download_rate {
                    download_bucket.lock().set_rate(new_download_rate);
                }
                if new_alert_mask != old_alert_mask {
                    alert_mask.store(new_alert_mask.bits(), Ordering::Relaxed);
                }
                this.settings = new;
                Ok(())
            }),
            rollback: Box::new(move |this: &mut Self| {
                // Restore in the reverse order of forward mutations.
                this.settings = old_settings;
                if new_alert_mask != old_alert_mask {
                    this.alert_mask
                        .store(old_alert_mask.bits(), Ordering::Relaxed);
                }
                if new_download_rate != old_download_rate {
                    this.global_download_bucket
                        .lock()
                        .set_rate(old_download_rate);
                }
                if new_upload_rate != old_upload_rate {
                    this.global_upload_bucket.lock().set_rate(old_upload_rate);
                }
            }),
        };

        // Phase 2 (listen_port) and Phase 4 (LSD) remain unimplemented.
        let phases = vec![phase1];

        match crate::apply::apply_phases_with_rollback(self, phases) {
            Ok(()) => {
                // M226 Step 5: broadcast the new Settings to the
                // notification dispatcher. `send` on a watch channel
                // returns Err only when every receiver has dropped,
                // which means the dispatcher has already exited — at
                // that point the toggle is academic and we silently
                // discard the error so apply_settings stays infallible
                // on the notification axis.
                let _ = self.notification_settings_tx.send(self.settings.clone());

                // Phase 3: DHT toggle (v0.187.1).
                if (old_settings_for_delta.enable_dht != self.settings.enable_dht
                    || old_settings_for_delta.anonymous_mode != self.settings.anonymous_mode)
                    && (!self.settings.enable_dht || self.settings.anonymous_mode)
                {
                    tracing::info!("DHT disabled via settings");
                    self.dht_v4 = None;
                    self.dht_v6 = None;
                    self.dht_v4_broadcast.replace(None);
                    self.dht_v6_broadcast.replace(None);
                }

                // M224 D3: keep the listener's cap atomic in sync. The
                // listener reads this on every TCP accept, so the new cap
                // applies to the next accepted connection without a restart.
                // Update is unconditional — `store` is cheap, and skipping
                // when unchanged would require an additional read first.
                self.max_connections_global.store(
                    self.settings.max_connections_global,
                    std::sync::atomic::Ordering::SeqCst,
                );

                let delta =
                    crate::types::SettingsDelta::from_diff(&old_settings_for_delta, &self.settings);
                if delta.save_resume_interval_secs.is_some() {
                    self.resume_save_notify.notify_one();
                }
                if let Some(enabled) = delta.ip_filter_enabled {
                    self.ip_filter.write().enabled = enabled;
                }
                // M226 Step 6: poke the watched-folder dispatcher to
                // rebuild its debouncer against the new path. We only
                // fire when the path itself OR the delete-after-add
                // flag changed — rate-limit / DHT tweaks must NOT
                // churn inotify FDs.
                if delta.watched_folder.is_some() || delta.delete_torrent_after_add.is_some() {
                    self.watched_folder_changed.notify_one();
                }
                if !delta.is_empty() {
                    // v0.187.3 / 1A: SettingsDelta fan-out. We use try_send so a
                    // saturated per-torrent channel doesn't block the apply call;
                    // the trade-off is that the dropped torrent will retain its
                    // old config until the next apply. Pre-v0.187.3 this was a
                    // silent `let _`; now we log at WARN so partial-failure
                    // events are observable without becoming fatal.
                    let mut failed: Vec<irontide_core::Id20> = Vec::new();
                    for (hash, entry) in &self.torrents {
                        if entry
                            .handle
                            .cmd_tx
                            .try_send(crate::types::TorrentCommand::UpdateSettings(delta.clone()))
                            .is_err()
                        {
                            failed.push(*hash);
                        }
                    }
                    if !failed.is_empty() {
                        tracing::warn!(
                            count = failed.len(),
                            "SettingsDelta fan-out: per-torrent channel saturated; \
                             affected torrents will pick up the change on the next apply"
                        );
                    }
                }
                post_alert(&self.alert_tx, &self.alert_mask, AlertKind::SettingsChanged);
                Ok(())
            }
            Err(crate::apply::ApplyError::ValidationFailed(msg)) => {
                Err(crate::Error::InvalidSettings(msg))
            }
            Err(e) => Err(crate::Error::Config(format!("apply settings: {e}"))),
        }
    }

    /// Build a `QueueEntry` snapshot from current auto-managed torrents.
    fn queue_entries(&self) -> Vec<crate::queue::QueueEntry> {
        self.torrents
            .iter()
            .filter(|(_, e)| e.auto_managed)
            .map(|(&hash, e)| crate::queue::QueueEntry {
                info_hash: hash,
                position: e.queue_position,
            })
            .collect()
    }

    fn handle_set_queue_position(&mut self, info_hash: Id20, pos: i32) -> crate::Result<()> {
        if !self.torrents.contains_key(&info_hash) {
            return Err(crate::Error::TorrentNotFound(info_hash));
        }
        let mut entries = self.queue_entries();
        let changed = crate::queue::set_position(&mut entries, info_hash, pos);
        self.apply_queue_changes(&changed);
        Ok(())
    }

    fn handle_queue_move(&mut self, info_hash: Id20, op: QueueMoveFn) -> crate::Result<()> {
        if !self.torrents.contains_key(&info_hash) {
            return Err(crate::Error::TorrentNotFound(info_hash));
        }
        let mut entries = self.queue_entries();
        let changed = op(&mut entries, info_hash);
        self.apply_queue_changes(&changed);
        Ok(())
    }

    /// Apply position changes back to `TorrentEntry` fields and fire alerts.
    fn apply_queue_changes(&mut self, changed: &[(Id20, i32, i32)]) {
        for &(hash, old_pos, new_pos) in changed {
            if let Some(entry) = self.torrents.get_mut(&hash) {
                entry.queue_position = new_pos;
            }
            crate::alert::post_alert(
                &self.alert_tx,
                &self.alert_mask,
                crate::alert::AlertKind::TorrentQueuePositionChanged {
                    info_hash: hash,
                    old_pos,
                    new_pos,
                },
            );
        }
    }

    async fn evaluate_queue(&mut self) {
        if !self.settings.queueing_enabled {
            return;
        }
        let now = tokio::time::Instant::now();
        let startup_duration = std::time::Duration::from_secs(self.settings.auto_manage_startup);
        let mut candidates = Vec::new();

        // Collect info hashes first to avoid borrow issues with async calls
        let hashes: Vec<Id20> = self.torrents.keys().copied().collect();

        for &info_hash in &hashes {
            let (queue_position, started_at) = {
                let Some(entry) = self.torrents.get(&info_hash) else {
                    continue;
                };
                if !entry.auto_managed {
                    continue;
                }
                (entry.queue_position, entry.started_at)
            };

            // Get current stats (async call — self.torrents is not borrowed here)
            let stats = match self.torrents.get(&info_hash) {
                Some(entry) => match entry.handle.stats().await {
                    Ok(s) => s,
                    Err(_) => continue,
                },
                None => continue,
            };

            let category = match stats.state {
                TorrentState::Checking | TorrentState::FetchingMetadata => {
                    crate::queue::QueueCategory::Checking
                }
                TorrentState::Downloading => crate::queue::QueueCategory::Downloading,
                TorrentState::Seeding | TorrentState::Complete => {
                    crate::queue::QueueCategory::Seeding
                }
                TorrentState::Queued => {
                    if stats.progress >= 1.0 {
                        crate::queue::QueueCategory::Seeding
                    } else {
                        crate::queue::QueueCategory::Downloading
                    }
                }
                TorrentState::Paused | TorrentState::Stopped | TorrentState::Sharing => continue,
            };

            let is_active = !matches!(stats.state, TorrentState::Paused | TorrentState::Queued);

            // EWMA-smooth the rates for stable inactive classification.
            let alpha = self.settings.queue_rate_ewma_alpha.clamp(0.0, 1.0);
            let (smoothed_dl, smoothed_ul) = if let Some(entry) = self.torrents.get_mut(&info_hash)
            {
                let raw_dl = stats.download_rate as f64;
                let raw_ul = stats.upload_rate as f64;
                entry.smoothed_download_rate =
                    alpha.mul_add(raw_dl, (1.0 - alpha) * entry.smoothed_download_rate);
                entry.smoothed_upload_rate =
                    alpha.mul_add(raw_ul, (1.0 - alpha) * entry.smoothed_upload_rate);
                (entry.smoothed_download_rate, entry.smoothed_upload_rate)
            } else {
                continue;
            };

            let past_startup = started_at.is_none_or(|t| now.duration_since(t) > startup_duration);

            let is_inactive = past_startup
                && match category {
                    crate::queue::QueueCategory::Downloading => {
                        (smoothed_dl as u64) < self.settings.inactive_down_rate
                    }
                    crate::queue::QueueCategory::Seeding => {
                        (smoothed_ul as u64) < self.settings.inactive_up_rate
                    }
                    crate::queue::QueueCategory::Checking => false,
                };

            let anti_flap_duration = if category == crate::queue::QueueCategory::Seeding {
                std::time::Duration::from_secs(self.settings.seed_queue_min_active_secs)
            } else {
                startup_duration
            };
            let recently_started =
                started_at.is_some_and(|t| now.duration_since(t) < anti_flap_duration);

            let seed_rank = if category == crate::queue::QueueCategory::Seeding {
                Some(crate::queue::compute_seed_rank(
                    stats.num_complete,
                    stats.num_incomplete,
                ))
            } else {
                None
            };

            candidates.push(crate::queue::QueueCandidate {
                info_hash,
                position: queue_position,
                category,
                is_active,
                is_inactive,
                recently_started,
                seed_rank,
            });
        }

        let config = crate::queue::QueueConfig {
            active_downloads: self.settings.active_downloads,
            active_seeds: self.settings.active_seeds,
            active_checking: self.settings.active_checking,
            active_limit: self.settings.active_limit,
            dont_count_slow: self.settings.dont_count_slow_torrents,
            prefer_seeds: self.settings.auto_manage_prefer_seeds,
        };
        let mut decision = crate::queue::evaluate(&candidates, &config);
        crate::queue::apply_preemption(&mut decision, &candidates);

        // Apply decisions
        for hash in &decision.to_pause {
            if let Some(entry) = self.torrents.get(hash) {
                let _ = entry.handle.queue().await;
            }
            post_alert(
                &self.alert_tx,
                &self.alert_mask,
                AlertKind::TorrentAutoManaged {
                    info_hash: *hash,
                    paused: true,
                },
            );
        }

        for hash in &decision.to_resume {
            if let Some(entry) = self.torrents.get_mut(hash) {
                let _ = entry.handle.resume().await;
                entry.started_at = Some(tokio::time::Instant::now());
            }
            post_alert(
                &self.alert_tx,
                &self.alert_mask,
                AlertKind::TorrentAutoManaged {
                    info_hash: *hash,
                    paused: false,
                },
            );
        }
    }

    /// Handle a pre-validated inbound connection from the `ListenerTask` (M114).
    fn handle_identified_inbound(&self, conn: crate::listener::IdentifiedConnection) {
        if let Some(entry) = self.torrents.get(&conn.info_hash) {
            debug!(%conn.addr, %conn.info_hash, "routing validated inbound peer");
            let handle = entry.handle.clone();
            tokio::spawn(async move {
                let _ = handle.send_incoming_peer(conn.stream, conn.addr).await;
            });
        } else {
            // Race: torrent removed between validation and receipt.
            debug!(%conn.addr, %conn.info_hash, "validated peer for removed torrent, dropping");
        }
    }

    /// Handle an incoming SSL/TLS connection (M42).
    ///
    /// Uses `LazyConfigAcceptor` to peek at the TLS `ClientHello` and extract
    /// the SNI (hex-encoded info hash) to route the connection to the right
    /// torrent. The full TLS handshake uses the torrent's CA cert to build
    /// the server config.
    async fn handle_ssl_incoming(
        &mut self,
        stream: crate::transport::BoxedStream,
        addr: std::net::SocketAddr,
    ) {
        use tokio_rustls::LazyConfigAcceptor;

        let acceptor = LazyConfigAcceptor::new(rustls::server::Acceptor::default(), stream);

        let start_handshake = match acceptor.await {
            Ok(sh) => sh,
            Err(e) => {
                debug!(%addr, error = %e, "SSL ClientHello read failed");
                return;
            }
        };

        // Extract SNI from ClientHello
        let client_hello = start_handshake.client_hello();
        let sni = if let Some(name) = client_hello.server_name() {
            name.to_string()
        } else {
            debug!(%addr, "SSL connection missing SNI");
            return;
        };

        // SNI is hex-encoded info hash (40 chars for SHA-1)
        let Ok(info_hash) = Id20::from_hex(&sni) else {
            debug!(%addr, sni = %sni, "SSL SNI is not a valid info hash");
            return;
        };

        // Look up the torrent
        let Some(torrent) = self.torrents.get(&info_hash) else {
            debug!(%addr, %info_hash, "SSL connection for unknown torrent");
            return;
        };

        // Get the SSL CA cert from the torrent's metadata.
        //
        // v0.173.1: `TorrentEntry.meta` was deleted. Query the TorrentActor
        // directly (single source of truth). Magnet torrents previously hit
        // the "non-SSL torrent" branch here because their entry.meta was
        // always None — BEP 4A handshakes silently dropped.
        let meta = match torrent.handle.get_meta().await {
            Ok(Some(m)) => m,
            Ok(None) => {
                debug!(%addr, %info_hash, "SSL connection for torrent still resolving metadata");
                return;
            }
            Err(_) => {
                debug!(%addr, %info_hash, "SSL connection but TorrentActor shut down");
                return;
            }
        };
        let ssl_cert = if let Some(cert) = meta.ssl_cert.as_ref() {
            cert.clone()
        } else {
            debug!(%addr, %info_hash, "SSL connection for non-SSL torrent (no ssl_cert in info dict)");
            return;
        };

        // Build server config using the torrent's CA cert
        let server_config = if let Some(mgr) = self.ssl_manager.as_ref() {
            match mgr.server_config(&ssl_cert) {
                Ok(cfg) => cfg,
                Err(e) => {
                    warn!(%addr, %info_hash, error = %e, "failed to build SSL server config");
                    return;
                }
            }
        } else {
            debug!(%addr, "SSL manager not initialized");
            return;
        };

        // Complete the TLS handshake
        let tls_stream = match start_handshake.into_stream(server_config).await {
            Ok(s) => s,
            Err(e) => {
                warn!(%addr, %info_hash, error = %e, "SSL handshake failed");
                post_alert(
                    &self.alert_tx,
                    &self.alert_mask,
                    AlertKind::SslTorrentError {
                        info_hash,
                        message: format!("inbound TLS handshake from {addr}: {e}"),
                    },
                );
                return;
            }
        };

        // Route to the torrent actor via SpawnSslPeer command
        let _ = torrent.handle.spawn_ssl_peer(addr, tls_stream).await;
    }

    async fn handle_dht_put_immutable(&self, value: Vec<u8>) -> crate::Result<Id20> {
        let dht = self.dht_v4.as_ref().ok_or(crate::Error::DhtDisabled)?;
        match dht.put_immutable(value.clone()).await {
            Ok(target) => {
                post_alert(
                    &self.alert_tx,
                    &self.alert_mask,
                    AlertKind::DhtPutComplete { target },
                );
                Ok(target)
            }
            Err(e) => {
                let target = irontide_core::sha1(&value);
                post_alert(
                    &self.alert_tx,
                    &self.alert_mask,
                    AlertKind::DhtItemError {
                        target,
                        message: e.to_string(),
                    },
                );
                Err(crate::Error::Dht(e))
            }
        }
    }

    async fn handle_dht_get_immutable(&self, target: Id20) -> crate::Result<Option<Vec<u8>>> {
        let dht = self.dht_v4.as_ref().ok_or(crate::Error::DhtDisabled)?;
        match dht.get_immutable(target).await {
            Ok(value) => {
                post_alert(
                    &self.alert_tx,
                    &self.alert_mask,
                    AlertKind::DhtGetResult {
                        target,
                        value: value.clone(),
                    },
                );
                Ok(value)
            }
            Err(e) => {
                post_alert(
                    &self.alert_tx,
                    &self.alert_mask,
                    AlertKind::DhtItemError {
                        target,
                        message: e.to_string(),
                    },
                );
                Err(crate::Error::Dht(e))
            }
        }
    }

    async fn handle_dht_put_mutable(
        &self,
        keypair_bytes: [u8; 32],
        value: Vec<u8>,
        seq: i64,
        salt: Vec<u8>,
    ) -> crate::Result<Id20> {
        let dht = self.dht_v4.as_ref().ok_or(crate::Error::DhtDisabled)?;
        match dht.put_mutable(keypair_bytes, value, seq, salt).await {
            Ok(target) => {
                post_alert(
                    &self.alert_tx,
                    &self.alert_mask,
                    AlertKind::DhtMutablePutComplete { target, seq },
                );
                Ok(target)
            }
            Err(e) => {
                post_alert(
                    &self.alert_tx,
                    &self.alert_mask,
                    AlertKind::DhtItemError {
                        target: Id20::from([0u8; 20]),
                        message: e.to_string(),
                    },
                );
                Err(crate::Error::Dht(e))
            }
        }
    }

    async fn handle_dht_get_mutable(
        &self,
        public_key: [u8; 32],
        salt: Vec<u8>,
    ) -> crate::Result<Option<(Vec<u8>, i64)>> {
        let dht = self.dht_v4.as_ref().ok_or(crate::Error::DhtDisabled)?;
        let target = irontide_dht::compute_mutable_target(&public_key, &salt);
        match dht.get_mutable(public_key, salt).await {
            Ok(result) => {
                let (value, seq) = match &result {
                    Some((v, s)) => (Some(v.clone()), Some(*s)),
                    None => (None, None),
                };
                post_alert(
                    &self.alert_tx,
                    &self.alert_mask,
                    AlertKind::DhtMutableGetResult {
                        target,
                        value,
                        seq,
                        public_key,
                    },
                );
                Ok(result)
            }
            Err(e) => {
                post_alert(
                    &self.alert_tx,
                    &self.alert_mask,
                    AlertKind::DhtItemError {
                        target,
                        message: e.to_string(),
                    },
                );
                Err(crate::Error::Dht(e))
            }
        }
    }

    async fn shutdown_all(&mut self) {
        // Save resume files before draining torrents (M161 Phase 5).
        let save_count = self.save_dirty_resume_files().await;
        if save_count > 0 {
            info!(save_count, "saved resume files on shutdown");
        }

        for (info_hash, entry) in self.torrents.drain() {
            debug!(%info_hash, "shutting down torrent");
            let _ = entry.handle.shutdown().await;
        }
        if let Some(ref dht) = self.dht_v4 {
            let _ = dht.shutdown().await;
        }
        if let Some(ref dht) = self.dht_v6 {
            let _ = dht.shutdown().await;
        }
        if let Some(ref nat) = self.nat {
            nat.shutdown().await;
        }
        if let Some(ref lsd) = self.lsd {
            lsd.shutdown().await;
        }
        if let Some(ref socket) = self.utp_socket
            && let Err(e) = socket.shutdown().await
        {
            debug!(error = %e, "uTP socket shutdown error");
        }
        if let Some(ref socket) = self.utp_socket_v6
            && let Err(e) = socket.shutdown().await
        {
            debug!(error = %e, "uTP v6 socket shutdown error");
        }
        self.disk_manager.shutdown().await;
    }
}

/// Helper to receive NAT events from an optional receiver.
/// Returns `pending` if no receiver is available, so the `select!` branch is skipped.
async fn recv_nat_event(
    rx: &mut Option<mpsc::Receiver<irontide_nat::NatEvent>>,
) -> irontide_nat::NatEvent {
    match rx {
        Some(r) => match r.recv().await {
            Some(event) => event,
            None => std::future::pending().await,
        },
        None => std::future::pending().await,
    }
}

/// Receive from an optional DHT IP consensus channel, pending forever if absent.
async fn recv_dht_ip(
    rx: &mut Option<mpsc::Receiver<std::net::IpAddr>>,
) -> Option<std::net::IpAddr> {
    match rx {
        Some(r) => r.recv().await,
        None => std::future::pending().await,
    }
}

/// Synthesize a minimal `TorrentMetaV1` from a `TorrentMetaV2` for session compatibility.
///
/// The session engine uses v1 structures internally (info hash as Id20, `InfoDict` for
/// piece hashing, etc.). For v2-only torrents, we create a "virtual" v1 representation
/// with the truncated SHA-256 hash as the `info_hash`.
/// M223 — off-actor add-torrent prep phase. Runs in a `tokio::spawn`'d
/// task launched by `SessionActor::try_spawn_add_torrent` so concurrent
/// adds do not serialise the actor's command queue. Performs the heavy
/// work that previously caused super-linear handler-cost growth in the
/// parallel-7 POST tail:
/// - synthesise / clone v1 metadata
/// - create the storage backend (filesystem or memory)
/// - `disk_manager.register_torrent` (async ack from disk actor)
/// - `TorrentHandle::from_torrent` (spawns the `TorrentActor`)
///
/// Returns `PreparedAddTorrent` on success — the `SessionActor` commit
/// arm then inserts it into `self.torrents` + queue position + alert +
/// LSD. Failures propagate untouched so the commit arm can reply with
/// the original error.
async fn prepare_add_torrent_off_actor(
    bundle: AddTorrentPrepBundle,
) -> crate::Result<PreparedAddTorrent> {
    let AddTorrentPrepBundle {
        torrent_meta,
        storage_override,
        torrent_config,
        disk_manager,
        dht_v4_broadcast,
        dht_v6_broadcast,
        global_up,
        global_down,
        slot_tuner,
        alert_tx,
        alert_mask,
        utp_socket,
        utp_socket_v6,
        ban_manager,
        ip_filter,
        plugins,
        sam_session,
        ssl_manager,
        factory,
        hash_pool,
        counters,
        m170_post,
    } = bundle;

    let version = torrent_meta.version();
    let meta_v2 = torrent_meta.as_v2().cloned();

    // For v2-only torrents, synthesize a minimal v1 metadata wrapper.
    // The session uses info_hash (Id20) as the primary key, so we use
    // the SHA-256 truncated to 20 bytes (per BEP 52 tracker/DHT compat).
    let meta = if let Some(v1) = torrent_meta.as_v1() {
        v1.clone()
    } else {
        let v2 = torrent_meta.as_v2().unwrap();
        synthesize_v1_from_v2(v2)
    };
    let info_hash = meta.info_hash;
    let is_private = meta.info.private == Some(1);

    // Create or use provided storage, then register with disk manager
    let storage: Arc<dyn TorrentStorage> = if let Some(s) = storage_override {
        s
    } else {
        let lengths = Lengths::new(
            meta.info.total_length(),
            meta.info.piece_length,
            DEFAULT_CHUNK_SIZE,
        );
        let files = meta.info.files();
        let file_paths: Vec<PathBuf> = files
            .iter()
            .map(|f| f.path.iter().collect::<PathBuf>())
            .collect();
        let file_lengths: Vec<u64> = files.iter().map(|f| f.length).collect();
        let prealloc_mode = torrent_config.preallocate_mode.unwrap_or_else(|| {
            irontide_storage::PreallocateMode::from(
                torrent_config.storage_mode == irontide_core::StorageMode::Full,
            )
        });
        match irontide_storage::FilesystemStorage::new(
            &torrent_config.download_dir,
            file_paths,
            file_lengths,
            lengths.clone(),
            None,
            prealloc_mode,
            torrent_config.filesystem_direct_io,
        ) {
            Ok(s) => Arc::new(s),
            Err(e) => {
                warn!("failed to create filesystem storage: {e}, falling back to memory");
                Arc::new(irontide_storage::MemoryStorage::new(lengths))
            }
        }
    };
    let disk_handle = disk_manager.register_torrent(info_hash, storage).await;

    let handle = TorrentHandle::from_torrent(
        meta.clone(),
        version,
        meta_v2,
        disk_handle,
        disk_manager,
        torrent_config,
        dht_v4_broadcast.subscribe(),
        dht_v6_broadcast.subscribe(),
        global_up,
        global_down,
        slot_tuner,
        alert_tx.clone(),
        Arc::clone(&alert_mask),
        utp_socket,
        utp_socket_v6,
        ban_manager,
        ip_filter,
        plugins,
        sam_session,
        ssl_manager,
        factory,
        Some(hash_pool),
        counters,
    )
    .await?;

    // M223 — post `TorrentAdded` here (sync, in the prep task) rather
    // than in `commit_add_torrent` (on the session actor) so the alert
    // ordering invariant survives spawn-per-add. `TorrentHandle::from_torrent`
    // spawns the `TorrentActor` internally but doesn't yield between
    // the spawn and its return, so this post races only with the
    // following `commit_tx.send.await` yield. The `TorrentActor`'s
    // first alert (`StateChanged → Checking` from `verify_existing_pieces`)
    // therefore fires AFTER this `TorrentAdded`.
    //
    // **Limitation**: parallel adds with the same info-hash both reach
    // here and both post `TorrentAdded`, even though the commit re-check
    // will fail one of them with `DuplicateTorrent`. The losing
    // `TorrentActor` shuts down cleanly when its `TorrentHandle` is
    // dropped in `commit_add_torrent`, but its `TorrentAdded` is a
    // false positive. Production callers do not parallelise same-hash
    // adds; accepted edge case.
    post_alert(
        &alert_tx,
        &alert_mask,
        AlertKind::TorrentAdded {
            info_hash,
            name: meta.info.name.clone(),
        },
    );
    Ok(PreparedAddTorrent {
        handle,
        info_hash,
        is_private,
        m170_post,
    })
}

/// A per-torrent snapshot captured cheaply on the `SessionActor` so the actual
/// resume-file write can run OFF the recv loop (audit Tier-2 L1, M241).
/// `TorrentHandle` is `#[derive(Clone)]` over a channel sender, so cloning is
/// cheap; `queue_position`/`auto_managed` are copied as the `i64` the resume
/// format stores (matching the old inline conversion).
struct ResumeSaveJob {
    info_hash: Id20,
    handle: TorrentHandle,
    queue_position: i64,
    auto_managed: i64,
}

/// Write resume files for every dirty torrent in `jobs`. Touches no
/// `SessionActor` state — only the cloned per-torrent handles + the snapshotted
/// queue metadata — so it is safe to `tokio::spawn` off the recv loop. Returns
/// the number of files successfully written. Per-torrent failures `warn` and
/// continue: one stopped/removed torrent must never abort the whole batch
/// (eng-review F2).
async fn run_resume_save_jobs(resume_dir: std::path::PathBuf, jobs: Vec<ResumeSaveJob>) -> usize {
    // F3 (eng-review): create_dir_all is blocking — run it on the blocking pool
    // so it never occupies an async worker thread.
    let torrents_dir = resume_dir.join("torrents");
    match tokio::task::spawn_blocking(move || std::fs::create_dir_all(&torrents_dir)).await {
        Ok(Ok(())) => {}
        Ok(Err(e)) => {
            warn!("failed to create resume dir: {e}");
            return 0;
        }
        Err(e) => {
            warn!("resume dir create task panicked: {e}");
            return 0;
        }
    }

    let mut saved = 0usize;
    for job in &jobs {
        // F1 (M245) — atomically take resume data IFF dirty. One command turn
        // reads `need_save_resume`, builds the data, and clears the flag with no
        // `.await` between read and clear, closing the pre-M245 race where a
        // dirty mark set between the old `stats()` check and the separate
        // `clear_save_resume_flag()` was silently lost. `Ok(None)` => clean,
        // nothing to write. `Err(_)` => torrent shut down; warn+continue.
        let mut rd = match job.handle.take_resume_if_dirty().await {
            Ok(Some(rd)) => rd,
            Ok(None) => continue,
            Err(e) => {
                warn!(info_hash = %job.info_hash, "failed to take resume data: {e}");
                continue;
            }
        };
        rd.queue_position = job.queue_position;
        rd.auto_managed = job.auto_managed;

        // From here the flag is already cleared. Any failure before the write
        // lands must re-arm it (D3) so the torrent is retried next cycle rather
        // than silently dropped. `resume_save_lock` serializes whole batches, so
        // no save-sequence number is needed to order concurrent writers.
        let bytes = match crate::resume_file::serialize_resume(&rd) {
            Ok(b) => b,
            Err(e) => {
                warn!(info_hash = %job.info_hash, "failed to serialize resume data: {e}");
                redirty_after_failed_save(&job.handle, &job.info_hash).await;
                continue;
            }
        };

        // Atomic write — blocking, so run it on the blocking pool (F3).
        let path = crate::resume_file::resume_file_path(&resume_dir, &job.info_hash);
        let write_res =
            tokio::task::spawn_blocking(move || crate::resume_file::atomic_write(&path, &bytes))
                .await;
        match write_res {
            Ok(Ok(())) => {}
            Ok(Err(e)) => {
                warn!(info_hash = %job.info_hash, "failed to write resume file: {e}");
                redirty_after_failed_save(&job.handle, &job.info_hash).await;
                continue;
            }
            Err(e) => {
                warn!(info_hash = %job.info_hash, "resume write task panicked: {e}");
                redirty_after_failed_save(&job.handle, &job.info_hash).await;
                continue;
            }
        }

        saved = saved.saturating_add(1);
    }
    saved
}

/// Re-arm a torrent's `need_save_resume` flag after [`run_resume_save_jobs`]
/// already cleared it (via `take_resume_if_dirty`) but the subsequent serialize
/// or disk write failed (M245 F1, eng-review D3). Without this the dirty state
/// would be lost and the torrent would not be retried until it next mutates.
async fn redirty_after_failed_save(handle: &TorrentHandle, info_hash: &Id20) {
    if let Err(e) = handle.mark_resume_dirty().await {
        warn!(info_hash = %info_hash, "failed to re-mark resume dirty after save failure: {e}");
    }
}

fn synthesize_v1_from_v2(v2: &irontide_core::TorrentMetaV2) -> irontide_core::TorrentMetaV1 {
    use irontide_core::{FileEntry, InfoDict};

    let info_hash = v2.info_hashes.best_v1();

    // Build file entries from v2 file tree
    let v2_files = v2.info.files();
    let file_entries: Vec<FileEntry> = v2_files
        .iter()
        .map(|f| FileEntry {
            length: f.attr.length,
            path: f.path.clone(),
            attr: None,
            mtime: None,
            symlink_path: None,
        })
        .collect();

    // v2-only torrents have no v1 piece hashes — use placeholder pieces field.
    // Verification is done via v2 Merkle trees, not v1 SHA-1 hashes.
    let num_pieces = v2.info.num_pieces() as usize;
    let pieces = vec![0u8; num_pieces * 20];

    let info = InfoDict {
        name: v2.info.name.clone(),
        piece_length: v2.info.piece_length,
        pieces,
        length: if file_entries.len() == 1 {
            Some(file_entries[0].length)
        } else {
            None
        },
        files: if file_entries.len() > 1 {
            Some(file_entries)
        } else {
            None
        },
        private: None,
        source: None,
        ssl_cert: v2.ssl_cert.clone(),
        similar: Vec::new(),
        collections: Vec::new(),
    };

    irontide_core::TorrentMetaV1 {
        info_hash,
        announce: v2.announce.clone(),
        announce_list: v2.announce_list.clone(),
        comment: v2.comment.clone(),
        created_by: v2.created_by.clone(),
        creation_date: v2.creation_date,
        info,
        info_bytes: None,
        url_list: Vec::new(),
        httpseeds: Vec::new(),
        ssl_cert: v2.ssl_cert.clone(),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::types::TorrentState;
    use irontide_core::{DEFAULT_CHUNK_SIZE, Lengths, TorrentMetaV1, torrent_from_bytes};
    use irontide_storage::MemoryStorage;
    use std::time::Duration;

    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 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))
    }

    static TEST_COUNTER: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);

    fn test_settings() -> Settings {
        let n = TEST_COUNTER.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        let pid = std::process::id();
        let dl_dir = std::env::temp_dir().join(format!("irontide-session-lib-dl-{pid}-{n}"));
        let resume_dir =
            std::env::temp_dir().join(format!("irontide-session-lib-resume-{pid}-{n}"));
        let _ = std::fs::remove_dir_all(&dl_dir);
        let _ = std::fs::remove_dir_all(&resume_dir);
        let _ = std::fs::create_dir_all(&dl_dir);

        Settings {
            listen_port: 0,
            download_dir: dl_dir,
            resume_data_dir: Some(resume_dir),
            max_torrents: 10,
            enable_dht: false,
            enable_pex: false,
            enable_lsd: false,
            enable_fast_extension: false,
            enable_utp: false,
            enable_upnp: false,
            enable_natpmp: false,
            enable_ipv6: false,
            alert_channel_size: 64,
            disk_io_threads: 2,
            storage_mode: irontide_core::StorageMode::Sparse,
            disk_cache_size: 1024 * 1024,
            ..Settings::default()
        }
    }

    // ---- Test 1: Start and shutdown ----

    #[tokio::test]
    async fn session_start_and_shutdown() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let stats = session.session_stats().await.unwrap();
        assert_eq!(stats.active_torrents, 0);
        session.shutdown().await.unwrap();
    }

    #[tokio::test]
    async fn peer_unchoke_durations_returns_none_for_missing_torrent() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let bogus = Id20([0u8; 20]);
        let result = session.peer_unchoke_durations(bogus).await.unwrap();
        assert!(
            result.is_none(),
            "missing torrent must yield None, not an empty map"
        );
        session.shutdown().await.unwrap();
    }

    #[tokio::test]
    async fn peer_unchoke_durations_returns_empty_map_for_known_torrent_with_no_peers() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();
        let result = session
            .peer_unchoke_durations(info_hash)
            .await
            .unwrap()
            .expect("known torrent must yield Some, even with no peers");
        assert!(
            result.is_empty(),
            "fresh torrent with no peers has no unchoke history"
        );
        session.shutdown().await.unwrap();
    }

    // ---- Test 2: Add and list torrent ----

    #[tokio::test]
    async fn add_and_list_torrent() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let expected_hash = meta.info_hash;

        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();
        assert_eq!(info_hash, expected_hash);

        let list = session.list_torrents().await.unwrap();
        assert_eq!(list.len(), 1);
        assert!(list.contains(&info_hash));

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

    // ---- Test 3: Remove torrent ----

    #[tokio::test]
    async fn remove_torrent() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);

        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();
        session.remove_torrent(info_hash).await.unwrap();

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

        let list = session.list_torrents().await.unwrap();
        assert!(list.is_empty());

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

    // ---- Test 4: Duplicate rejection ----

    #[tokio::test]
    async fn duplicate_torrent_rejected() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage1 = make_storage(&data, 16384);
        let storage2 = make_storage(&data, 16384);

        session
            .add_torrent_with_meta(meta.clone().into(), Some(storage1))
            .await
            .unwrap();
        let result = session
            .add_torrent_with_meta(meta.into(), Some(storage2))
            .await;
        assert!(result.is_err());
        assert!(result.unwrap_err().to_string().contains("duplicate"));

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

    // ---- Test 5: Max capacity ----

    #[tokio::test]
    async fn session_at_capacity() {
        let mut config = test_settings();
        config.max_torrents = 1;
        let session = SessionHandle::start(config).await.unwrap();

        let data1 = vec![0xAA; 16384];
        let meta1 = make_test_torrent(&data1, 16384);
        let storage1 = make_storage(&data1, 16384);
        session
            .add_torrent_with_meta(meta1.into(), Some(storage1))
            .await
            .unwrap();

        let data2 = vec![0xBB; 16384];
        let meta2 = make_test_torrent(&data2, 16384);
        let storage2 = make_storage(&data2, 16384);
        let result = session
            .add_torrent_with_meta(meta2.into(), Some(storage2))
            .await;
        assert!(result.is_err());
        assert!(result.unwrap_err().to_string().contains("capacity"));

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

    // ---- Test 6: Torrent stats ----

    #[tokio::test]
    async fn torrent_stats_via_session() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);

        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();
        let stats = session.torrent_stats(info_hash).await.unwrap();
        assert_eq!(stats.state, TorrentState::Downloading);
        assert_eq!(stats.pieces_total, 2);

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

    // ---- Test 7: Torrent info ----

    #[tokio::test]
    async fn torrent_info_via_session() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);

        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();
        let info = session.torrent_info(info_hash).await.unwrap();
        assert_eq!(info.info_hash, info_hash);
        assert_eq!(info.name, "test");
        assert_eq!(info.total_length, 32768);
        assert_eq!(info.num_pieces, 2);
        assert!(!info.private);
        assert_eq!(info.files.len(), 1);
        assert_eq!(info.files[0].length, 32768);

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

    // ---- Test 8: Pause/resume via session ----

    #[tokio::test]
    async fn pause_resume_via_session() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);

        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        session.pause_torrent(info_hash).await.unwrap();
        tokio::time::sleep(Duration::from_millis(50)).await;
        let stats = session.torrent_stats(info_hash).await.unwrap();
        assert_eq!(stats.state, TorrentState::Paused);

        session.resume_torrent(info_hash).await.unwrap();
        tokio::time::sleep(Duration::from_millis(50)).await;
        let stats = session.torrent_stats(info_hash).await.unwrap();
        assert_eq!(stats.state, TorrentState::Downloading);

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

    // ---- Test 9: Not-found errors ----

    #[tokio::test]
    async fn not_found_errors() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let fake_hash = Id20::from_hex("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").unwrap();

        assert!(session.torrent_stats(fake_hash).await.is_err());
        assert!(session.torrent_info(fake_hash).await.is_err());
        assert!(session.pause_torrent(fake_hash).await.is_err());
        assert!(session.resume_torrent(fake_hash).await.is_err());
        assert!(session.remove_torrent(fake_hash).await.is_err());

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

    // ---- Test 10: Session stats ----

    #[tokio::test]
    async fn session_stats_aggregate() {
        let session = SessionHandle::start(test_settings()).await.unwrap();

        let data1 = vec![0xAA; 16384];
        let meta1 = make_test_torrent(&data1, 16384);
        let storage1 = make_storage(&data1, 16384);
        session
            .add_torrent_with_meta(meta1.into(), Some(storage1))
            .await
            .unwrap();

        let data2 = vec![0xBB; 16384];
        let meta2 = make_test_torrent(&data2, 16384);
        let storage2 = make_storage(&data2, 16384);
        session
            .add_torrent_with_meta(meta2.into(), Some(storage2))
            .await
            .unwrap();

        let stats = session.session_stats().await.unwrap();
        assert_eq!(stats.active_torrents, 2);

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

    // ---- Test 11: Add magnet and list ----

    #[tokio::test]
    async fn add_magnet_and_list() {
        use irontide_core::Magnet;

        let session = SessionHandle::start(test_settings()).await.unwrap();
        let magnet = Magnet {
            info_hashes: irontide_core::InfoHashes::v1_only(
                Id20::from_hex("aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d").unwrap(),
            ),
            display_name: Some("test-magnet".into()),
            trackers: vec![],
            peers: vec![],
            selected_files: None,
        };
        let expected_hash = magnet.info_hash();

        let info_hash = session.add_magnet(magnet).await.unwrap();
        assert_eq!(info_hash, expected_hash);

        let list = session.list_torrents().await.unwrap();
        assert_eq!(list.len(), 1);
        assert!(list.contains(&info_hash));

        // torrent_info should fail with MetadataNotReady
        let err = session.torrent_info(info_hash).await.unwrap_err();
        assert!(err.to_string().contains("metadata not yet available"));

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

    // ---- Test 12: Duplicate magnet rejected ----

    #[tokio::test]
    async fn add_magnet_duplicate_rejected() {
        use irontide_core::Magnet;

        let session = SessionHandle::start(test_settings()).await.unwrap();
        let magnet = Magnet {
            info_hashes: irontide_core::InfoHashes::v1_only(
                Id20::from_hex("aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d").unwrap(),
            ),
            display_name: Some("test-magnet".into()),
            trackers: vec![],
            peers: vec![],
            selected_files: None,
        };

        session.add_magnet(magnet.clone()).await.unwrap();
        let result = session.add_magnet(magnet).await;
        assert!(result.is_err());
        assert!(result.unwrap_err().to_string().contains("duplicate"));

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

    // ---- Test 13: Session with LSD enabled ----

    #[tokio::test]
    async fn session_with_lsd_enabled() {
        use irontide_core::Magnet;

        // LSD may fail to bind port 6771 — session should still start
        let mut config = test_settings();
        config.enable_lsd = true;

        let session = SessionHandle::start(config).await.unwrap();

        // Add a torrent (triggers LSD announce if available)
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Add a magnet (also triggers LSD announce)
        let magnet = Magnet {
            info_hashes: irontide_core::InfoHashes::v1_only(
                Id20::from_hex("bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb").unwrap(),
            ),
            display_name: Some("lsd-test".into()),
            trackers: vec![],
            peers: vec![],
            selected_files: None,
        };
        session.add_magnet(magnet).await.unwrap();

        let list = session.list_torrents().await.unwrap();
        assert_eq!(list.len(), 2);

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

    // ---- Test: v2-only torrent addition ----

    #[tokio::test]
    async fn add_v2_only_torrent() {
        use irontide_bencode::BencodeValue;
        use std::collections::BTreeMap;

        let session = SessionHandle::start(test_settings()).await.unwrap();

        // Build a minimal v2-only torrent
        let mut attr_map: BTreeMap<Vec<u8>, BencodeValue> = BTreeMap::new();
        attr_map.insert(b"length".to_vec(), BencodeValue::Integer(16384));
        let mut file_node: BTreeMap<Vec<u8>, BencodeValue> = BTreeMap::new();
        file_node.insert(b"".to_vec(), BencodeValue::Dict(attr_map));
        let mut ft_map: BTreeMap<Vec<u8>, BencodeValue> = BTreeMap::new();
        ft_map.insert(b"test.dat".to_vec(), BencodeValue::Dict(file_node));

        let mut info_map: BTreeMap<Vec<u8>, BencodeValue> = BTreeMap::new();
        info_map.insert(b"file tree".to_vec(), BencodeValue::Dict(ft_map));
        info_map.insert(b"meta version".to_vec(), BencodeValue::Integer(2));
        info_map.insert(b"name".to_vec(), BencodeValue::Bytes(b"v2test".to_vec()));
        info_map.insert(b"piece length".to_vec(), BencodeValue::Integer(16384));

        let mut root_map: BTreeMap<Vec<u8>, BencodeValue> = BTreeMap::new();
        root_map.insert(b"info".to_vec(), BencodeValue::Dict(info_map));

        let bytes = irontide_bencode::to_bytes(&BencodeValue::Dict(root_map)).unwrap();
        let meta = irontide_core::torrent_from_bytes_any(&bytes).unwrap();
        assert!(meta.is_v2());

        // This should NOT return an error now (v2-only is supported)
        let info_hash = session.add_torrent_with_meta(meta, None).await.unwrap();
        let list = session.list_torrents().await.unwrap();
        assert!(list.contains(&info_hash));

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

    // ---- Test 14: Save torrent resume data via session ----

    #[tokio::test]
    async fn save_torrent_resume_data_via_session() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;
        let storage = make_storage(&data, 16384);
        session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        let rd = session.save_torrent_resume_data(info_hash).await.unwrap();
        assert_eq!(rd.info_hash, info_hash.as_bytes().as_slice());
        assert_eq!(rd.name, "test");
        assert_eq!(rd.file_format, "libtorrent resume file");
        assert_eq!(rd.file_version, 1);
        assert!(!rd.pieces.is_empty());
        assert_eq!(rd.paused, 0);

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

    // ---- Test 15: Save session state captures all torrents ----

    #[tokio::test]
    async fn save_session_state_captures_all_torrents() {
        let session = SessionHandle::start(test_settings()).await.unwrap();

        let data1 = vec![0xAA; 16384];
        let meta1 = make_test_torrent(&data1, 16384);
        let storage1 = make_storage(&data1, 16384);
        session
            .add_torrent_with_meta(meta1.into(), Some(storage1))
            .await
            .unwrap();

        let data2 = vec![0xBB; 16384];
        let meta2 = make_test_torrent(&data2, 16384);
        let storage2 = make_storage(&data2, 16384);
        session
            .add_torrent_with_meta(meta2.into(), Some(storage2))
            .await
            .unwrap();

        let state = session.save_session_state().await.unwrap();
        assert_eq!(state.torrents.len(), 2);

        for rd in &state.torrents {
            assert_eq!(rd.file_format, "libtorrent resume file");
            assert_eq!(rd.info_hash.len(), 20);
        }

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

    // ---- Test 16: Save resume data not found ----

    #[tokio::test]
    async fn save_resume_data_not_found() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let fake_hash = Id20::from_hex("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").unwrap();
        let result = session.save_torrent_resume_data(fake_hash).await;
        assert!(result.is_err());
        assert!(result.unwrap_err().to_string().contains("not found"));
        session.shutdown().await.unwrap();
    }

    // ---- Test 17: Subscribe receives TorrentAdded alert ----

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

        let session = SessionHandle::start(test_settings()).await.unwrap();
        let mut alerts = session.subscribe();

        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let _info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        let alert = tokio::time::timeout(Duration::from_secs(2), alerts.recv())
            .await
            .unwrap()
            .unwrap();
        assert!(matches!(alert.kind, AlertKind::TorrentAdded { .. }));
        session.shutdown().await.unwrap();
    }

    // ---- Test 18: Subscribe receives TorrentRemoved alert ----

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

        let session = SessionHandle::start(test_settings()).await.unwrap();
        let mut alerts = session.subscribe();

        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Drain TorrentAdded and any checking alerts
        while let Ok(Ok(a)) = tokio::time::timeout(Duration::from_secs(1), alerts.recv()).await {
            if matches!(
                a.kind,
                AlertKind::StateChanged {
                    new_state: TorrentState::Downloading,
                    ..
                }
            ) {
                break;
            }
        }

        session.remove_torrent(info_hash).await.unwrap();

        // Find TorrentRemoved (skip any interleaved alerts)
        loop {
            let alert = tokio::time::timeout(Duration::from_secs(2), alerts.recv())
                .await
                .unwrap()
                .unwrap();
            if matches!(alert.kind, AlertKind::TorrentRemoved { .. }) {
                break;
            }
        }
        session.shutdown().await.unwrap();
    }

    // ---- Test 19: Multiple subscribers each receive alerts ----

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

        let session = SessionHandle::start(test_settings()).await.unwrap();
        let mut sub1 = session.subscribe();
        let mut sub2 = session.subscribe();

        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        let a1 = tokio::time::timeout(Duration::from_secs(2), sub1.recv())
            .await
            .unwrap()
            .unwrap();
        let a2 = tokio::time::timeout(Duration::from_secs(2), sub2.recv())
            .await
            .unwrap()
            .unwrap();

        assert!(matches!(a1.kind, AlertKind::TorrentAdded { .. }));
        assert!(matches!(a2.kind, AlertKind::TorrentAdded { .. }));
        session.shutdown().await.unwrap();
    }

    // ---- Test 20: set_alert_mask filters at runtime ----

    #[tokio::test]
    async fn set_alert_mask_filters_at_runtime() {
        use crate::alert::{AlertCategory, AlertKind};

        let session = SessionHandle::start(test_settings()).await.unwrap();
        let mut alerts = session.subscribe();

        // Start with ALL — TorrentAdded (STATUS) should arrive
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        let alert = tokio::time::timeout(Duration::from_secs(2), alerts.recv())
            .await
            .unwrap()
            .unwrap();
        assert!(matches!(alert.kind, AlertKind::TorrentAdded { .. }));

        // Drain any remaining alerts from the first torrent (StateChanged, CheckingProgress, etc.)
        while tokio::time::timeout(Duration::from_millis(200), alerts.recv())
            .await
            .is_ok()
        {}

        // Change mask to empty — no alerts should pass
        session.set_alert_mask(AlertCategory::empty());

        let data2 = vec![0xBB; 16384];
        let meta2 = make_test_torrent(&data2, 16384);
        let storage2 = make_storage(&data2, 16384);
        session
            .add_torrent_with_meta(meta2.into(), Some(storage2))
            .await
            .unwrap();

        // Give a small window — nothing should arrive
        let result = tokio::time::timeout(Duration::from_millis(200), alerts.recv()).await;
        assert!(result.is_err(), "should have timed out with empty mask");

        // Restore STATUS — adding another torrent should arrive
        session.set_alert_mask(AlertCategory::STATUS);

        let data3 = vec![0xCC; 16384];
        let meta3 = make_test_torrent(&data3, 16384);
        let storage3 = make_storage(&data3, 16384);
        session
            .add_torrent_with_meta(meta3.into(), Some(storage3))
            .await
            .unwrap();

        let alert = tokio::time::timeout(Duration::from_secs(2), alerts.recv())
            .await
            .unwrap()
            .unwrap();
        assert!(matches!(alert.kind, AlertKind::TorrentAdded { .. }));

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

    // ---- Test 21: AlertStream filters per subscriber ----

    #[tokio::test]
    async fn alert_stream_filters_per_subscriber() {
        use crate::alert::{AlertCategory, AlertKind};

        let session = SessionHandle::start(test_settings()).await.unwrap();

        // subscriber A: STATUS only
        let mut status_sub = session.subscribe_filtered(AlertCategory::STATUS);
        // subscriber B: PEER only
        let mut peer_sub = session.subscribe_filtered(AlertCategory::PEER);

        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // STATUS sub gets TorrentAdded
        let alert = tokio::time::timeout(Duration::from_secs(2), status_sub.recv())
            .await
            .unwrap()
            .unwrap();
        assert!(matches!(alert.kind, AlertKind::TorrentAdded { .. }));

        // PEER sub should NOT receive TorrentAdded (it's STATUS category)
        let result = tokio::time::timeout(Duration::from_millis(200), peer_sub.recv()).await;
        assert!(
            result.is_err(),
            "PEER subscriber should not get STATUS alerts"
        );

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

    // ---- Test 22: State changed tracks transitions ----

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

        let session = SessionHandle::start(test_settings()).await.unwrap();
        let mut alerts = session.subscribe();

        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Drain TorrentAdded
        let _ = tokio::time::timeout(Duration::from_secs(1), alerts.recv())
            .await
            .unwrap();

        // Pause — should get StateChanged(Downloading → Paused) + TorrentPaused
        session.pause_torrent(info_hash).await.unwrap();
        tokio::time::sleep(Duration::from_millis(100)).await;

        // Collect alerts over a short window
        let mut state_changes = Vec::new();
        let mut paused_alerts = Vec::new();
        while let Ok(Ok(a)) = tokio::time::timeout(Duration::from_millis(200), alerts.recv()).await
        {
            match &a.kind {
                AlertKind::StateChanged {
                    prev_state,
                    new_state,
                    ..
                } => {
                    state_changes.push((*prev_state, *new_state));
                }
                AlertKind::TorrentPaused { .. } => {
                    paused_alerts.push(a);
                }
                _ => {} // other alerts (PeerConnected etc)
            }
        }

        assert!(
            state_changes.contains(&(TorrentState::Downloading, TorrentState::Paused)),
            "expected Downloading→Paused, got: {state_changes:?}"
        );
        assert!(!paused_alerts.is_empty(), "expected TorrentPaused alert");

        // Resume — should get StateChanged(Paused → Downloading) + TorrentResumed
        session.resume_torrent(info_hash).await.unwrap();
        tokio::time::sleep(Duration::from_millis(100)).await;

        let mut resume_state_changes = Vec::new();
        let mut resumed_alerts = Vec::new();
        while let Ok(Ok(a)) = tokio::time::timeout(Duration::from_millis(200), alerts.recv()).await
        {
            match &a.kind {
                AlertKind::StateChanged {
                    prev_state,
                    new_state,
                    ..
                } => {
                    resume_state_changes.push((*prev_state, *new_state));
                }
                AlertKind::TorrentResumed { .. } => {
                    resumed_alerts.push(a);
                }
                _ => {}
            }
        }

        assert!(
            resume_state_changes.contains(&(TorrentState::Paused, TorrentState::Downloading)),
            "expected Paused→Downloading, got: {resume_state_changes:?}"
        );
        assert!(!resumed_alerts.is_empty(), "expected TorrentResumed alert");

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

    #[tokio::test]
    async fn session_config_creates_utp_socket() {
        // Start session with uTP enabled — should succeed without errors
        let mut config = test_settings();
        config.enable_utp = true;
        let session = SessionHandle::start(config).await.unwrap();
        let stats = session.session_stats().await.unwrap();
        assert_eq!(stats.active_torrents, 0);
        session.shutdown().await.unwrap();
    }

    #[test]
    fn settings_nat_defaults() {
        let s = Settings::default();
        assert!(s.enable_upnp, "enable_upnp should default to true");
        assert!(s.enable_natpmp, "enable_natpmp should default to true");
    }

    #[tokio::test]
    async fn session_with_nat_disabled() {
        let config = test_settings();
        // test_session_config already sets enable_upnp: false, enable_natpmp: false
        assert!(!config.enable_upnp);
        assert!(!config.enable_natpmp);
        let session = SessionHandle::start(config).await.unwrap();
        let stats = session.session_stats().await.unwrap();
        assert_eq!(stats.active_torrents, 0);
        session.shutdown().await.unwrap();
    }

    // ---- M29: Anonymous mode, force proxy, proxy config tests ----

    #[test]
    fn anonymous_mode_disables_discovery() {
        let mut config = test_settings();
        config.anonymous_mode = true;
        config.enable_dht = true;
        config.enable_lsd = true;
        config.enable_upnp = true;
        config.enable_natpmp = true;

        // SessionHandle::start() will override these when anonymous_mode is true.
        // We test the enforcement logic directly here.
        if config.anonymous_mode {
            config.enable_dht = false;
            config.enable_lsd = false;
            config.enable_upnp = false;
            config.enable_natpmp = false;
        }

        assert!(!config.enable_dht);
        assert!(!config.enable_lsd);
        assert!(!config.enable_upnp);
        assert!(!config.enable_natpmp);
    }

    #[tokio::test]
    async fn anonymous_mode_session_starts_with_discovery_disabled() {
        let mut config = test_settings();
        config.anonymous_mode = true;
        // Even if we enable these, anonymous_mode should override
        config.enable_dht = true;
        config.enable_lsd = true;

        let session = SessionHandle::start(config).await.unwrap();
        let stats = session.session_stats().await.unwrap();
        assert_eq!(stats.active_torrents, 0);
        session.shutdown().await.unwrap();
    }

    #[test]
    fn force_proxy_requires_proxy_configured() {
        let mut config = test_settings();
        config.force_proxy = true;
        config.proxy = crate::proxy::ProxyConfig::default(); // no proxy

        // Validate the config error
        assert_eq!(config.proxy.proxy_type, crate::proxy::ProxyType::None);
        assert!(config.force_proxy);
        // This would error in SessionHandle::start()
    }

    #[tokio::test]
    async fn force_proxy_errors_without_proxy() {
        let mut config = test_settings();
        config.force_proxy = true;
        // proxy_type is None by default

        let result = SessionHandle::start(config).await;
        assert!(result.is_err());
        match result {
            Err(e) => assert!(
                e.to_string().contains("force_proxy"),
                "error should mention force_proxy: {e}"
            ),
            Ok(_) => panic!("expected error"),
        }
    }

    #[test]
    fn force_proxy_disables_features() {
        let mut config = test_settings();
        config.force_proxy = true;
        config.proxy = crate::proxy::ProxyConfig {
            proxy_type: crate::proxy::ProxyType::Socks5,
            hostname: "proxy.example.com".into(),
            port: 1080,
            ..Default::default()
        };
        config.enable_dht = true;
        config.enable_lsd = true;
        config.enable_upnp = true;
        config.enable_natpmp = true;

        // Simulate the enforcement from start()
        if config.force_proxy {
            config.enable_upnp = false;
            config.enable_natpmp = false;
            config.enable_dht = false;
            config.enable_lsd = false;
        }

        assert!(!config.enable_dht);
        assert!(!config.enable_lsd);
        assert!(!config.enable_upnp);
        assert!(!config.enable_natpmp);
    }

    #[test]
    fn proxy_config_round_trip() {
        let s = Settings {
            proxy: crate::proxy::ProxyConfig {
                proxy_type: crate::proxy::ProxyType::Socks5Password,
                hostname: "localhost".into(),
                port: 9050,
                username: Some("user".into()),
                password: Some("pass".into()),
                ..Default::default()
            },
            force_proxy: true,
            anonymous_mode: true,
            ..test_settings()
        };

        assert_eq!(s.proxy.proxy_type, crate::proxy::ProxyType::Socks5Password);
        assert_eq!(s.proxy.hostname, "localhost");
        assert_eq!(s.proxy.port, 9050);
        assert!(s.force_proxy);
        assert!(s.anonymous_mode);
        assert_eq!(s.proxy.to_url(), "socks5://user:pass@localhost:9050");
    }

    #[tokio::test]
    async fn apply_settings_runtime() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let original = session.settings().await.unwrap();
        assert_eq!(original.max_torrents, 10);

        let mut new = original.clone();
        new.max_torrents = 200;
        new.upload_rate_limit = 1_000_000;
        session.apply_settings(new).await.unwrap();

        let updated = session.settings().await.unwrap();
        assert_eq!(updated.max_torrents, 200);
        assert_eq!(updated.upload_rate_limit, 1_000_000);

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

    #[tokio::test]
    async fn apply_settings_validation_error() {
        let session = SessionHandle::start(test_settings()).await.unwrap();

        // force_proxy=true without a proxy configured should fail validation
        let bad = Settings {
            force_proxy: true,
            ..Settings::default()
        };
        let result = session.apply_settings(bad).await;
        assert!(result.is_err());

        // Original settings should be unchanged
        let current = session.settings().await.unwrap();
        assert!(!current.force_proxy);

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

    // ---- M50: Session stats counters tests ----

    #[tokio::test]
    async fn session_stats_counters_accessible() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let counters = session.counters();
        // Exercise the uptime accessor (returns u64, so >= 0 is tautological;
        // the meaningful check is that the call doesn't panic and counters
        // are wired up).
        let _ = counters.uptime_secs();
        assert_eq!(counters.len(), crate::stats::NUM_METRICS);
        session.shutdown().await.unwrap();
    }

    #[tokio::test]
    async fn post_session_stats_fires_alert() {
        use crate::alert::{AlertCategory, AlertKind};

        let session = SessionHandle::start(test_settings()).await.unwrap();
        let mut stats_sub = session.subscribe_filtered(AlertCategory::STATS);

        session.post_session_stats().await.unwrap();

        let alert = tokio::time::timeout(Duration::from_secs(2), stats_sub.recv())
            .await
            .expect("timed out waiting for SessionStatsAlert")
            .expect("recv error");
        assert!(
            matches!(alert.kind, AlertKind::SessionStatsAlert { ref values } if values.len() == crate::stats::NUM_METRICS),
            "expected SessionStatsAlert with {} values, got {:?}",
            crate::stats::NUM_METRICS,
            alert.kind,
        );
        session.shutdown().await.unwrap();
    }

    #[tokio::test]
    async fn session_stats_include_torrent_count() {
        use crate::alert::{AlertCategory, AlertKind};

        let session = SessionHandle::start(test_settings()).await.unwrap();
        let mut stats_sub = session.subscribe_filtered(AlertCategory::STATS);

        // Add a torrent
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        session.post_session_stats().await.unwrap();

        let alert = tokio::time::timeout(Duration::from_secs(2), stats_sub.recv())
            .await
            .expect("timed out waiting for SessionStatsAlert")
            .expect("recv error");
        match alert.kind {
            AlertKind::SessionStatsAlert { values } => {
                assert!(
                    values[crate::stats::SES_NUM_TORRENTS] > 0,
                    "SES_NUM_TORRENTS should be > 0 after adding a torrent, got {}",
                    values[crate::stats::SES_NUM_TORRENTS],
                );
            }
            other => panic!("expected SessionStatsAlert, got {other:?}"),
        }
        session.shutdown().await.unwrap();
    }

    #[tokio::test]
    async fn stats_timer_disabled_when_zero() {
        use crate::alert::AlertCategory;

        let mut config = test_settings();
        config.stats_report_interval = 0;
        let session = SessionHandle::start(config).await.unwrap();
        let mut stats_sub = session.subscribe_filtered(AlertCategory::STATS);

        // Wait 200ms — no periodic stats alert should arrive
        let result = tokio::time::timeout(Duration::from_millis(200), stats_sub.recv()).await;
        assert!(
            result.is_err(),
            "no SessionStatsAlert should fire when stats_report_interval is 0"
        );
        session.shutdown().await.unwrap();
    }

    #[tokio::test]
    async fn sample_infohashes_timer_disabled_when_zero() {
        use crate::alert::AlertCategory;

        let mut config = test_settings();
        config.dht_sample_infohashes_interval = 0;
        let session = SessionHandle::start(config).await.unwrap();
        let mut dht_sub = session.subscribe_filtered(AlertCategory::DHT);

        // Wait 200ms — no DhtSampleInfohashes alert should arrive
        let result = tokio::time::timeout(Duration::from_millis(200), dht_sub.recv()).await;
        assert!(
            result.is_err(),
            "no DhtSampleInfohashes alert should fire when interval is 0"
        );
        session.shutdown().await.unwrap();
    }

    // ---- Test: open_file returns TorrentNotFound for unknown hash ----

    #[tokio::test]
    async fn open_file_not_found() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let fake_hash = Id20::from_hex("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").unwrap();
        let result = session.open_file(fake_hash, 0).await;
        assert!(result.is_err());
        let err = result.err().unwrap();
        assert!(err.to_string().contains("not found"));
        session.shutdown().await.unwrap();
    }

    // ---- Test: open_file on a real torrent routes to TorrentHandle ----

    #[tokio::test]
    async fn open_file_routes_to_torrent() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);

        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // open_file should succeed for file_index 0 (single-file torrent)
        let stream = session.open_file(info_hash, 0).await;
        assert!(stream.is_ok(), "open_file should succeed for file_index 0");

        // open_file should fail for out-of-range file_index
        let result = session.open_file(info_hash, 999).await;
        assert!(
            result.is_err(),
            "open_file should fail for invalid file_index"
        );

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

    // ---- Test: force_reannounce via session ----

    #[tokio::test]
    async fn session_force_reannounce() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Should succeed for a known torrent.
        let result = session.force_reannounce(info_hash).await;
        assert!(
            result.is_ok(),
            "force_reannounce should succeed: {result:?}"
        );

        // Should fail for unknown torrent.
        let fake = Id20::from_hex("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").unwrap();
        assert!(session.force_reannounce(fake).await.is_err());

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

    // ---- Test: tracker_list via session ----

    #[tokio::test]
    async fn session_tracker_list() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Should succeed (empty list since test torrent has no announce URL).
        let trackers = session.tracker_list(info_hash).await.unwrap();
        assert!(trackers.is_empty(), "test torrent has no trackers");

        // Should fail for unknown torrent.
        let fake = Id20::from_hex("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").unwrap();
        assert!(session.tracker_list(fake).await.is_err());

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

    // ---- Test: scrape via session ----

    #[tokio::test]
    async fn session_scrape() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Should succeed (None since test torrent has no trackers to scrape).
        let scrape = session.scrape(info_hash).await.unwrap();
        assert!(scrape.is_none(), "test torrent has no trackers to scrape");

        // Should fail for unknown torrent.
        let fake = Id20::from_hex("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").unwrap();
        assert!(session.scrape(fake).await.is_err());

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

    // ---- Test: set_file_priority via session ----

    #[tokio::test]
    async fn session_set_file_priority() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Should succeed for file index 0 (single-file torrent).
        let result = session
            .set_file_priority(info_hash, 0, irontide_core::FilePriority::Normal)
            .await;
        assert!(
            result.is_ok(),
            "set_file_priority should succeed: {result:?}"
        );

        // Should fail for unknown torrent.
        let fake = Id20::from_hex("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").unwrap();
        assert!(
            session
                .set_file_priority(fake, 0, irontide_core::FilePriority::Normal)
                .await
                .is_err()
        );

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

    // ---- Test: file_priorities via session ----

    #[tokio::test]
    async fn session_file_priorities() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Should return priorities for the single file.
        let priorities = session.file_priorities(info_hash).await.unwrap();
        assert_eq!(
            priorities.len(),
            1,
            "single-file torrent should have 1 file priority"
        );
        assert_eq!(priorities[0], irontide_core::FilePriority::Normal);

        // Should fail for unknown torrent.
        let fake = Id20::from_hex("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").unwrap();
        assert!(session.file_priorities(fake).await.is_err());

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

    // ---- Test: set_download_limit zero means unlimited ----

    #[tokio::test]
    async fn set_download_limit_zero_means_unlimited() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Set limit to non-zero, then back to zero (unlimited).
        session.set_download_limit(info_hash, 50_000).await.unwrap();
        session.set_download_limit(info_hash, 0).await.unwrap();
        let limit = session.download_limit(info_hash).await.unwrap();
        assert_eq!(limit, 0, "0 means unlimited");

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

    // ---- Test: set_upload_limit persists ----

    #[tokio::test]
    async fn set_upload_limit_persists() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        session.set_upload_limit(info_hash, 100_000).await.unwrap();
        let limit = session.upload_limit(info_hash).await.unwrap();
        assert_eq!(limit, 100_000);

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

    // ---- Test: download_limit default is zero ----

    #[tokio::test]
    async fn download_limit_default_is_zero() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Default config has download_rate_limit = 0.
        let limit = session.download_limit(info_hash).await.unwrap();
        assert_eq!(limit, 0, "default download limit should be 0 (unlimited)");

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

    // ---- Test: rate_limit_round_trip ----

    #[tokio::test]
    async fn rate_limit_round_trip() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Set both limits.
        session
            .set_download_limit(info_hash, 1_000_000)
            .await
            .unwrap();
        session.set_upload_limit(info_hash, 500_000).await.unwrap();

        // Read them back.
        let dl = session.download_limit(info_hash).await.unwrap();
        let ul = session.upload_limit(info_hash).await.unwrap();
        assert_eq!(dl, 1_000_000);
        assert_eq!(ul, 500_000);

        // Update and verify again.
        session
            .set_download_limit(info_hash, 2_000_000)
            .await
            .unwrap();
        let dl = session.download_limit(info_hash).await.unwrap();
        assert_eq!(dl, 2_000_000);

        // Unknown torrent should fail.
        let fake = Id20::from_hex("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").unwrap();
        assert!(session.download_limit(fake).await.is_err());
        assert!(session.upload_limit(fake).await.is_err());
        assert!(session.set_download_limit(fake, 100).await.is_err());
        assert!(session.set_upload_limit(fake, 100).await.is_err());

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

    // ---- Test: sequential_download_toggle ----

    #[tokio::test]
    async fn sequential_download_toggle() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Enable sequential download.
        session
            .set_sequential_download(info_hash, true)
            .await
            .unwrap();
        assert!(session.is_sequential_download(info_hash).await.unwrap());

        // Disable it again.
        session
            .set_sequential_download(info_hash, false)
            .await
            .unwrap();
        assert!(!session.is_sequential_download(info_hash).await.unwrap());

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

    // ---- Test: super_seeding_toggle ----

    #[tokio::test]
    async fn super_seeding_toggle() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Enable super seeding.
        session.set_super_seeding(info_hash, true).await.unwrap();
        assert!(session.is_super_seeding(info_hash).await.unwrap());

        // Disable it again.
        session.set_super_seeding(info_hash, false).await.unwrap();
        assert!(!session.is_super_seeding(info_hash).await.unwrap());

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

    // ---- Test: sequential_download_default_false ----

    #[tokio::test]
    async fn sequential_download_default_false() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Default config has sequential_download = false.
        assert!(!session.is_sequential_download(info_hash).await.unwrap());

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

    // ---- Test: super_seeding_default_false ----

    #[tokio::test]
    async fn super_seeding_default_false() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Default config has super_seeding = false.
        assert!(!session.is_super_seeding(info_hash).await.unwrap());

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

    // ---- M159 Test: seed_mode_flips_user_flag ----

    #[tokio::test]
    async fn seed_mode_flips_user_flag() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Initial state: user_seed_mode defaults to false.
        let stats_before = session.torrent_stats(info_hash).await.unwrap();
        assert!(
            !stats_before.user_seed_mode,
            "new torrent should not start in user seed mode"
        );

        // Enable user seed mode.
        session.set_seed_mode(info_hash, true).await.unwrap();
        let stats_on = session.torrent_stats(info_hash).await.unwrap();
        assert!(
            stats_on.user_seed_mode,
            "stats should reflect user_seed_mode=true after enabling"
        );

        // Disable it again.
        session.set_seed_mode(info_hash, false).await.unwrap();
        let stats_off = session.torrent_stats(info_hash).await.unwrap();
        assert!(
            !stats_off.user_seed_mode,
            "stats should reflect user_seed_mode=false after disabling"
        );

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

    // ---- M159 Test: seed_mode_round_trip ----

    #[tokio::test]
    async fn seed_mode_round_trip() {
        // Five flips in a row, exercising the actor's toggle idempotency and
        // piece-reservation cleanup logic. Must not panic and must leave the
        // flag consistent with the most recent call.
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        for (i, enabled) in [true, false, true, true, false].iter().enumerate() {
            session.set_seed_mode(info_hash, *enabled).await.unwrap();
            let stats = session.torrent_stats(info_hash).await.unwrap();
            assert_eq!(
                stats.user_seed_mode, *enabled,
                "iteration {i}: stats.user_seed_mode should track the toggle"
            );
        }

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

    // ---- M159 Test: seed_mode_missing_info_hash_errors ----

    #[tokio::test]
    async fn seed_mode_missing_info_hash_errors() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let fake =
            irontide_core::Id20::from_hex("ffffffffffffffffffffffffffffffffffffffff").unwrap();
        let err = session
            .set_seed_mode(fake, true)
            .await
            .expect_err("set_seed_mode on unknown info hash must return an error");
        match err {
            crate::Error::TorrentNotFound(h) => assert_eq!(h, fake),
            other => panic!("expected TorrentNotFound, got {other:?}"),
        }
        session.shutdown().await.unwrap();
    }

    // ---- M159 Test: seed_mode_idempotent ----

    #[tokio::test]
    async fn seed_mode_idempotent() {
        // Setting the same value twice must not panic or corrupt state.
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Set true twice — second call is a no-op.
        session.set_seed_mode(info_hash, true).await.unwrap();
        session.set_seed_mode(info_hash, true).await.unwrap();
        assert!(
            session
                .torrent_stats(info_hash)
                .await
                .unwrap()
                .user_seed_mode
        );

        // Set false twice — also a no-op the second time.
        session.set_seed_mode(info_hash, false).await.unwrap();
        session.set_seed_mode(info_hash, false).await.unwrap();
        assert!(
            !session
                .torrent_stats(info_hash)
                .await
                .unwrap()
                .user_seed_mode
        );

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

    // ---- Test: add_tracker_increases_count ----

    #[tokio::test]
    async fn add_tracker_increases_count() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Test torrent has no trackers initially.
        let before = session.tracker_list(info_hash).await.unwrap();
        assert!(before.is_empty());

        // Add a tracker.
        session
            .add_tracker(info_hash, "udp://tracker.example.com:6969/announce".into())
            .await
            .unwrap();

        let after = session.tracker_list(info_hash).await.unwrap();
        assert_eq!(after.len(), 1);
        assert_eq!(after[0].url, "udp://tracker.example.com:6969/announce");

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

    // ---- Test: replace_trackers_replaces_all ----

    #[tokio::test]
    async fn replace_trackers_replaces_all() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Add 2 trackers.
        session
            .add_tracker(info_hash, "udp://tracker1.example.com:6969/announce".into())
            .await
            .unwrap();
        session
            .add_tracker(info_hash, "http://tracker2.example.com/announce".into())
            .await
            .unwrap();
        assert_eq!(session.tracker_list(info_hash).await.unwrap().len(), 2);

        // Replace with 1 different tracker.
        session
            .replace_trackers(
                info_hash,
                vec!["http://replacement.example.com/announce".into()],
            )
            .await
            .unwrap();

        let after = session.tracker_list(info_hash).await.unwrap();
        assert_eq!(after.len(), 1);
        assert_eq!(after[0].url, "http://replacement.example.com/announce");

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

    // ---- Test: add_tracker_deduplicates ----

    #[tokio::test]
    async fn add_tracker_deduplicates() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Add the same tracker URL twice.
        session
            .add_tracker(info_hash, "udp://tracker.example.com:6969/announce".into())
            .await
            .unwrap();
        session
            .add_tracker(info_hash, "udp://tracker.example.com:6969/announce".into())
            .await
            .unwrap();

        // Should only have 1 tracker (deduplicated).
        let trackers = session.tracker_list(info_hash).await.unwrap();
        assert_eq!(trackers.len(), 1);

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

    // ---- Test: info_hashes_matches_added_torrent ----

    #[tokio::test]
    async fn info_hashes_matches_added_torrent() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let expected_v1 = meta.info_hash;
        let storage = make_storage(&data, 16384);

        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();
        let hashes = session.info_hashes(info_hash).await.unwrap();
        assert_eq!(hashes.v1, Some(expected_v1));
        // v1-only torrent should not have v2 hash
        assert!(hashes.v2.is_none());

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

    // ---- Test: torrent_file_returns_meta ----

    #[tokio::test]
    async fn torrent_file_returns_meta() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 32768];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);

        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();
        let torrent = session.torrent_file(info_hash).await.unwrap();
        assert!(torrent.is_some());
        let torrent = torrent.unwrap();
        assert_eq!(torrent.info_hash, info_hash);
        assert_eq!(torrent.info.name, "test");
        assert_eq!(torrent.info.total_length(), 32768);

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

    // ---- Test: torrent_file_none_before_metadata ----

    #[tokio::test]
    async fn torrent_file_none_before_metadata() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let magnet = irontide_core::Magnet::parse(
            "magnet:?xt=urn:btih:aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d&dn=test",
        )
        .unwrap();

        let info_hash = session.add_magnet(magnet).await.unwrap();
        let torrent = session.torrent_file(info_hash).await.unwrap();
        // Before metadata is received, torrent_file should return None.
        assert!(torrent.is_none());

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

    // ---- Test: force_dht_announce_no_error ----

    #[tokio::test]
    async fn force_dht_announce_no_error() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Should succeed even without DHT enabled (no-op, no error).
        let result = session.force_dht_announce(info_hash).await;
        assert!(
            result.is_ok(),
            "force_dht_announce should succeed: {result:?}"
        );

        // Should fail for unknown torrent.
        let fake = Id20::from_hex("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").unwrap();
        assert!(session.force_dht_announce(fake).await.is_err());

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

    // ---- Test: force_lsd_announce_no_error ----

    #[tokio::test]
    async fn force_lsd_announce_no_error() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Should succeed even without LSD enabled (no-op announce, no error).
        let result = session.force_lsd_announce(info_hash).await;
        assert!(
            result.is_ok(),
            "force_lsd_announce should succeed: {result:?}"
        );

        // Should fail for unknown torrent.
        let fake = Id20::from_hex("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").unwrap();
        assert!(session.force_lsd_announce(fake).await.is_err());

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

    // ---- Test: read_piece_after_download ----

    #[tokio::test]
    async fn read_piece_after_download() {
        let data = vec![0xCD; 32768]; // 2 pieces of 16384
        let meta = make_test_torrent(&data, 16384);
        let lengths = Lengths::new(data.len() as u64, 16384, DEFAULT_CHUNK_SIZE);
        let storage = Arc::new(MemoryStorage::new(lengths));
        // Pre-fill storage with the data
        storage.write_chunk(0, 0, &data[..16384]).unwrap();
        storage.write_chunk(1, 0, &data[16384..]).unwrap();

        let session = SessionHandle::start(test_settings()).await.unwrap();
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Read piece 0
        let piece_data = session.read_piece(info_hash, 0).await.unwrap();
        assert_eq!(piece_data.len(), 16384);
        assert!(piece_data.iter().all(|&b| b == 0xCD));

        // Read piece 1
        let piece_data = session.read_piece(info_hash, 1).await.unwrap();
        assert_eq!(piece_data.len(), 16384);
        assert!(piece_data.iter().all(|&b| b == 0xCD));

        // Out-of-range piece should fail
        let result = session.read_piece(info_hash, 999).await;
        assert!(result.is_err(), "read_piece out of range should fail");

        // Unknown torrent should fail
        let fake = Id20::from_hex("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").unwrap();
        assert!(session.read_piece(fake, 0).await.is_err());

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

    // ---- Test: flush_cache_completes ----

    #[tokio::test]
    async fn flush_cache_completes() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // flush_cache should succeed.
        let result = session.flush_cache(info_hash).await;
        assert!(result.is_ok(), "flush_cache should succeed: {result:?}");

        // Should fail for unknown torrent.
        let fake = Id20::from_hex("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").unwrap();
        assert!(session.flush_cache(fake).await.is_err());

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

    // ---- BEP 44 session API tests ----

    fn test_settings_with_dht() -> Settings {
        let mut s = test_settings();
        s.enable_dht = true;
        s
    }

    fn test_settings_with_lsd() -> Settings {
        let mut s = test_settings();
        s.enable_lsd = true;
        s
    }

    #[tokio::test]
    async fn test_dht_disabled_returns_error() {
        let session = SessionHandle::start(test_settings()).await.unwrap();

        // All 4 methods should fail with DhtDisabled when DHT is off
        let err = session
            .dht_put_immutable(b"test".to_vec())
            .await
            .unwrap_err();
        assert!(
            format!("{err:?}").contains("DhtDisabled"),
            "expected DhtDisabled, got {err:?}"
        );

        let target = Id20::from([0u8; 20]);
        let err = session.dht_get_immutable(target).await.unwrap_err();
        assert!(
            format!("{err:?}").contains("DhtDisabled"),
            "expected DhtDisabled, got {err:?}"
        );

        let err = session
            .dht_put_mutable([42u8; 32], b"val".to_vec(), 1, Vec::new())
            .await
            .unwrap_err();
        assert!(
            format!("{err:?}").contains("DhtDisabled"),
            "expected DhtDisabled, got {err:?}"
        );

        let err = session
            .dht_get_mutable([42u8; 32], Vec::new())
            .await
            .unwrap_err();
        assert!(
            format!("{err:?}").contains("DhtDisabled"),
            "expected DhtDisabled, got {err:?}"
        );

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

    #[tokio::test]
    async fn test_dht_put_get_immutable_round_trip() {
        let session = SessionHandle::start(test_settings_with_dht())
            .await
            .unwrap();

        // Give DHT a moment to bootstrap (it won't find real nodes, but the handle should work)
        let value = b"hello BEP 44".to_vec();
        let target = session.dht_put_immutable(value.clone()).await.unwrap();

        // The target should be the SHA-1 of the bencoded value
        // Try to get it back — since we're the only node, the local store should have it
        let got = session.dht_get_immutable(target).await.unwrap();
        assert_eq!(got, Some(value));

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

    #[tokio::test]
    async fn test_dht_put_immutable_fires_alert() {
        use crate::alert::{AlertCategory, AlertKind};

        let session = SessionHandle::start(test_settings_with_dht())
            .await
            .unwrap();
        let mut alerts = session.subscribe_filtered(AlertCategory::DHT);

        let value = b"alert test".to_vec();
        let target = session.dht_put_immutable(value).await.unwrap();

        // Should receive DhtPutComplete alert
        let alert = tokio::time::timeout(Duration::from_secs(5), alerts.recv())
            .await
            .expect("timeout waiting for alert")
            .expect("alert channel closed");

        match alert.kind {
            AlertKind::DhtPutComplete { target: t } => {
                assert_eq!(t, target);
            }
            other => panic!("expected DhtPutComplete, got {other:?}"),
        }

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

    // ---- BEP 27: Private torrent LSD tests ----

    /// Creates a private torrent (.torrent bytes with private=1 in the info dict).
    fn make_private_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],
            private: i64,
        }

        #[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: "private-test",
                piece_length,
                pieces: &pieces,
                private: 1,
            },
        };

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

    #[test]
    fn is_private_true_via_parsed_meta() {
        // Verify that a torrent parsed from private .torrent bytes has private == Some(1)
        let data = vec![0xAB; 16384];
        let meta = make_private_torrent(&data, 16384);
        assert_eq!(
            meta.info.private,
            Some(1),
            "private field should be Some(1)"
        );
    }

    #[test]
    fn is_private_false_for_public_torrent() {
        // Verify that a regular torrent has private == None
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        assert_eq!(
            meta.info.private, None,
            "public torrent should have no private flag"
        );
    }

    #[test]
    fn private_torrent_config_disables_lsd() {
        // Verify that TorrentConfig::default() has LSD enabled (so disable is meaningful)
        let config = TorrentConfig::default();
        assert!(
            config.enable_lsd,
            "default TorrentConfig should have LSD enabled"
        );
    }

    #[tokio::test]
    async fn force_lsd_announce_private_torrent_returns_error() {
        let session = SessionHandle::start(test_settings()).await.unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_private_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // BEP 27: force_lsd_announce on a private torrent must return an error
        let result = session.force_lsd_announce(info_hash).await;
        assert!(
            result.is_err(),
            "force_lsd_announce on private torrent should return error, got: {result:?}"
        );
        let err_str = format!("{:?}", result.unwrap_err());
        assert!(
            err_str.contains("InvalidSettings") || err_str.contains("LSD disabled"),
            "expected InvalidSettings error, got: {err_str}"
        );

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

    #[tokio::test]
    async fn force_lsd_announce_public_torrent_does_not_trigger_bep27_error() {
        // v0.173.2 A10 companion to the DHT negative-form test added in T1.
        //
        // NEGATIVE form (codex finding #2): we only assert the BEP 27 gate doesn't
        // reject. We do NOT assert Ok — LSD may return Ok for a different reason
        // (e.g., self.lsd is None per session.rs:945's startup-failure swallow),
        // and asserting Ok would mask that case while still passing. We also
        // don't assert a specific Err — public torrents on an enabled-LSD session
        // typically return Ok, but a test-sandbox LSD init glitch could legitimately
        // error without the BEP 27 gate being involved.
        let session = SessionHandle::start(test_settings_with_lsd())
            .await
            .unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        let result = session.force_lsd_announce(info_hash).await;
        if let Err(e) = &result {
            assert!(
                !format!("{e:?}").contains("LSD disabled for private torrent"),
                "public torrent must NOT trigger BEP 27 error; got {e:?}"
            );
        }

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

    #[tokio::test]
    async fn force_dht_announce_private_torrent_returns_error() {
        let session = SessionHandle::start(test_settings_with_dht())
            .await
            .unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_private_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // BEP 27: force_dht_announce on a private torrent must return an error
        let result = session.force_dht_announce(info_hash).await;
        assert!(
            result.is_err(),
            "force_dht_announce on private torrent should return error, got: {result:?}"
        );
        let err_str = format!("{:?}", result.unwrap_err());
        assert!(
            err_str.contains("InvalidSettings")
                || err_str.contains("DHT disabled for private torrent"),
            "expected InvalidSettings / DHT-disabled error, got: {err_str}"
        );

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

    #[tokio::test]
    async fn force_dht_announce_public_torrent_does_not_trigger_bep27_error() {
        let session = SessionHandle::start(test_settings_with_dht())
            .await
            .unwrap();
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        let result = session.force_dht_announce(info_hash).await;
        // NEGATIVE form: we only assert the BEP 27 gate doesn't reject. We do NOT
        // assert Ok — DHT may not be initialised in the test sandbox, returning a
        // different error. Asserting Ok here would mask both the test sandbox
        // limitation AND a future regression where the BEP 27 gate accidentally
        // catches public torrents.
        if let Err(e) = &result {
            assert!(
                !format!("{e:?}").contains("DHT disabled for private torrent"),
                "public torrent must NOT trigger BEP 27 error; got {e:?}"
            );
        }

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

    // ---- M161: save_resume_state tests ----

    fn resume_test_settings(dir: &std::path::Path) -> Settings {
        Settings {
            resume_data_dir: Some(dir.to_path_buf()),
            save_resume_interval_secs: 0, // disable periodic timer for tests
            ..test_settings()
        }
    }

    #[tokio::test]
    async fn save_resume_state_empty_session_returns_zero() {
        let tmp = tempfile::TempDir::new().unwrap();
        let session = SessionHandle::start(resume_test_settings(tmp.path()))
            .await
            .unwrap();

        let count = session.save_resume_state().await.unwrap();
        assert_eq!(count, 0, "empty session should save 0 resume files");

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

    #[tokio::test]
    async fn save_resume_state_saves_dirty_torrents() {
        let tmp = tempfile::TempDir::new().unwrap();
        let session = SessionHandle::start(resume_test_settings(tmp.path()))
            .await
            .unwrap();

        // Add two torrents with different data so they get different hashes
        let data1 = vec![0xAA; 16384];
        let meta1 = make_test_torrent(&data1, 16384);
        let hash1 = meta1.info_hash;
        let storage1 = make_storage(&data1, 16384);
        session
            .add_torrent_with_meta(meta1.into(), Some(storage1))
            .await
            .unwrap();

        let data2 = vec![0xBB; 16384];
        let meta2 = make_test_torrent(&data2, 16384);
        let hash2 = meta2.info_hash;
        let storage2 = make_storage(&data2, 16384);
        session
            .add_torrent_with_meta(meta2.into(), Some(storage2))
            .await
            .unwrap();

        // Both torrents should be dirty (newly added → need_save_resume = true
        // after any state change). Give the actors a moment to settle.
        tokio::time::sleep(Duration::from_millis(50)).await;

        let count = session.save_resume_state().await.unwrap();
        // Newly created torrents may or may not have the dirty flag set
        // depending on whether state changes have occurred. Verify that
        // at least the files are created for any that were dirty.
        assert!(count <= 2, "should save at most 2 resume files");

        // Verify files exist on disk for saved torrents
        let torrents_dir = tmp.path().join("torrents");
        if count > 0 {
            assert!(torrents_dir.exists(), "torrents/ directory should exist");
        }

        // Check specific file paths
        let path1 = crate::resume_file::resume_file_path(tmp.path(), &hash1);
        let path2 = crate::resume_file::resume_file_path(tmp.path(), &hash2);
        let files_exist = usize::from(path1.exists()) + usize::from(path2.exists());
        assert_eq!(
            files_exist, count,
            "number of files on disk should match returned count"
        );

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

    #[tokio::test]
    async fn save_resume_state_round_trip() {
        let tmp = tempfile::TempDir::new().unwrap();
        let session = SessionHandle::start(resume_test_settings(tmp.path()))
            .await
            .unwrap();

        let data = vec![0xCD; 32768];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;
        let storage = make_storage(&data, 16384);
        session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Let the actor settle so dirty flag is set
        tokio::time::sleep(Duration::from_millis(50)).await;

        let count = session.save_resume_state().await.unwrap();

        // If the torrent was dirty and saved, verify round-trip
        if count > 0 {
            let path = crate::resume_file::resume_file_path(tmp.path(), &info_hash);
            assert!(path.exists(), "resume file should exist after save");

            let bytes = std::fs::read(&path).unwrap();
            let rd = crate::resume_file::deserialize_resume(&bytes).unwrap();
            assert_eq!(
                rd.info_hash,
                info_hash.as_bytes().to_vec(),
                "deserialized info_hash should match"
            );
            assert_eq!(rd.name, "test", "deserialized name should match");
        }

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

    #[tokio::test]
    async fn save_resume_state_clears_dirty_flag() {
        let tmp = tempfile::TempDir::new().unwrap();
        let session = SessionHandle::start(resume_test_settings(tmp.path()))
            .await
            .unwrap();

        let data = vec![0xEE; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

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

        let first_count = session.save_resume_state().await.unwrap();

        // Second save should return 0 because dirty flag was cleared
        let second_count = session.save_resume_state().await.unwrap();
        assert_eq!(
            second_count, 0,
            "second save should return 0 after dirty flag cleared (first saved {first_count})"
        );

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

    #[tokio::test]
    async fn save_resume_state_second_save_skips_clean() {
        let tmp = tempfile::TempDir::new().unwrap();
        let session = SessionHandle::start(resume_test_settings(tmp.path()))
            .await
            .unwrap();

        let data1 = vec![0xAA; 16384];
        let meta1 = make_test_torrent(&data1, 16384);
        let storage1 = make_storage(&data1, 16384);
        session
            .add_torrent_with_meta(meta1.into(), Some(storage1))
            .await
            .unwrap();

        let data2 = vec![0xBB; 16384];
        let meta2 = make_test_torrent(&data2, 16384);
        let storage2 = make_storage(&data2, 16384);
        session
            .add_torrent_with_meta(meta2.into(), Some(storage2))
            .await
            .unwrap();

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

        // First save
        let first = session.save_resume_state().await.unwrap();

        // Second save — all flags should be cleared, nothing to write
        let second = session.save_resume_state().await.unwrap();
        assert_eq!(
            second, 0,
            "second save should skip all clean torrents (first saved {first})"
        );

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

    // ==== M161 Phase 4: load_resume_state tests ====

    // ---- Test: empty dir → zeros ----

    #[tokio::test]
    async fn load_resume_empty_dir_returns_zeros() {
        let tmp = tempfile::TempDir::new().unwrap();
        let mut settings = test_settings();
        settings.resume_data_dir = Some(tmp.path().to_path_buf());

        let session = SessionHandle::start(settings).await.unwrap();
        let result = session.load_resume_state().await.unwrap();
        assert_eq!(result.restored, 0);
        assert_eq!(result.skipped, 0);
        assert_eq!(result.failed, 0);

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

    // ---- Test: corrupt file skipped ----

    #[tokio::test]
    async fn load_resume_corrupt_file_counted_as_failed() {
        let tmp = tempfile::TempDir::new().unwrap();
        let torrents_dir = tmp.path().join("torrents");
        std::fs::create_dir_all(&torrents_dir).unwrap();

        let mut settings = test_settings();
        settings.resume_data_dir = Some(tmp.path().to_path_buf());

        // Start session first (auto-restore runs but dir is empty).
        let session = SessionHandle::start(settings).await.unwrap();

        // Wait for auto-restore to complete before writing the file,
        // otherwise the actor may race with file creation.
        tokio::time::sleep(Duration::from_millis(50)).await;

        // Write garbage to a .resume file *after* startup so auto-restore
        // does not consume it.
        std::fs::write(
            torrents_dir.join("deadbeefdeadbeefdeadbeefdeadbeefdeadbeef.resume"),
            b"this is not valid bencode",
        )
        .unwrap();

        let result = session.load_resume_state().await.unwrap();
        assert_eq!(result.restored, 0);
        assert_eq!(result.skipped, 0);
        assert_eq!(result.failed, 1);

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

    // ---- Test: duplicate torrent skipped ----

    #[tokio::test]
    async fn load_resume_duplicate_skipped() {
        let tmp = tempfile::TempDir::new().unwrap();
        let mut settings = test_settings();
        settings.resume_data_dir = Some(tmp.path().to_path_buf());

        let session = SessionHandle::start(settings).await.unwrap();

        // Add a torrent first.
        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;
        let storage = make_storage(&data, 16384);
        session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Wait for the torrent to settle.
        tokio::time::sleep(Duration::from_millis(50)).await;

        // Save resume state so we have a file on disk.
        let _ = session.save_resume_state().await;

        // Load again — the torrent already exists so it should be skipped.
        let result = session.load_resume_state().await.unwrap();
        assert!(
            session.list_torrents().await.unwrap().contains(&info_hash),
            "original torrent should still exist"
        );
        assert_eq!(result.skipped, 1, "duplicate should be skipped");
        assert_eq!(result.failed, 0);

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

    // ---- Test: reconstruct_torrent_meta with info present ----

    #[test]
    fn reconstruct_torrent_meta_returns_some_with_correct_fields() {
        use crate::resume_file::reconstruct_torrent_meta;
        use irontide_core::FastResumeData;

        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;

        // Create resume data with a stored info dict.
        let info_bytes = irontide_bencode::to_bytes(&meta.info).unwrap();
        let mut rd = FastResumeData::new(
            info_hash.as_bytes().to_vec(),
            "test-torrent".into(),
            "/downloads".into(),
        );
        rd.info = Some(info_bytes);
        rd.trackers = vec![
            vec!["http://tracker1.example.com/announce".into()],
            vec!["http://tracker2.example.com/announce".into()],
        ];
        rd.url_seeds = vec!["http://seed.example.com/".into()];
        rd.http_seeds = vec!["http://httpseed.example.com/".into()];

        let reconstructed = reconstruct_torrent_meta(&rd).expect("should reconstruct");

        assert_eq!(reconstructed.info_hash, info_hash);
        assert_eq!(
            reconstructed.announce.as_deref(),
            Some("http://tracker1.example.com/announce")
        );
        assert!(reconstructed.announce_list.is_some());
        assert_eq!(reconstructed.announce_list.as_ref().unwrap().len(), 2);
        assert_eq!(
            reconstructed.url_list,
            vec!["http://seed.example.com/".to_string()]
        );
        assert_eq!(
            reconstructed.httpseeds,
            vec!["http://httpseed.example.com/".to_string()]
        );
        assert!(reconstructed.info_bytes.is_some());
        assert!(reconstructed.comment.is_none());
        assert!(reconstructed.created_by.is_none());
        assert!(reconstructed.creation_date.is_none());
    }

    // ---- Test: reconstruct_torrent_meta returns None for unresolved magnet ----

    #[test]
    fn reconstruct_torrent_meta_returns_none_without_info() {
        use crate::resume_file::reconstruct_torrent_meta;
        use irontide_core::FastResumeData;

        let rd = FastResumeData::new(vec![0xAB; 20], "magnet".into(), "/tmp".into());
        // info is None by default — simulates unresolved magnet.
        assert!(rd.info.is_none());
        assert!(reconstruct_torrent_meta(&rd).is_none());
    }

    // ---- Test: reconstruct_magnet returns Some ----

    #[test]
    fn reconstruct_magnet_returns_some_with_correct_fields() {
        use crate::resume_file::reconstruct_magnet;
        use irontide_core::FastResumeData;

        let mut rd = FastResumeData::new(vec![0xCC; 20], "my-torrent".into(), "/downloads".into());
        rd.trackers = vec![
            vec!["http://tracker1.com/announce".into()],
            vec![
                "http://tracker2.com/announce".into(),
                "http://tracker3.com/announce".into(),
            ],
        ];

        let magnet = reconstruct_magnet(&rd).expect("should reconstruct magnet");

        assert!(magnet.info_hashes.v1.is_some());
        assert!(magnet.info_hashes.v2.is_none());
        assert_eq!(magnet.display_name.as_deref(), Some("my-torrent"));
        // Trackers flattened: 3 total from 2 tiers.
        assert_eq!(magnet.trackers.len(), 3);
        assert!(magnet.peers.is_empty());
        assert!(magnet.selected_files.is_none());
    }

    // ---- Test: reconstruct_magnet with info_hash2 preserved ----

    #[test]
    fn reconstruct_magnet_preserves_info_hash2() {
        use crate::resume_file::reconstruct_magnet;
        use irontide_core::FastResumeData;

        let mut rd = FastResumeData::new(vec![0xDD; 20], "v2-magnet".into(), "/tmp".into());
        rd.info_hash2 = Some(vec![0xEE; 32]);

        let magnet = reconstruct_magnet(&rd).expect("should reconstruct");
        assert!(magnet.info_hashes.v1.is_some());
        assert!(magnet.info_hashes.v2.is_some());

        let v2 = magnet.info_hashes.v2.unwrap();
        assert_eq!(v2.as_bytes(), &[0xEE; 32]);
    }

    // ---- Test: reconstruct_magnet with empty name ----

    #[test]
    fn reconstruct_magnet_empty_name_is_none() {
        use crate::resume_file::reconstruct_magnet;
        use irontide_core::FastResumeData;

        let rd = FastResumeData::new(vec![0xFF; 20], String::new(), "/tmp".into());
        let magnet = reconstruct_magnet(&rd).expect("should reconstruct");
        assert!(
            magnet.display_name.is_none(),
            "empty name should map to None"
        );
    }

    // ==== M161 Phase 5: auto-save / auto-restore / orphan cleanup ====

    // ---- Test: shutdown writes resume files ----

    #[tokio::test]
    async fn shutdown_saves_resume_files() {
        let tmp = tempfile::TempDir::new().unwrap();
        let session = SessionHandle::start(resume_test_settings(tmp.path()))
            .await
            .unwrap();

        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;
        let storage = make_storage(&data, 16384);
        session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Force a state change to set the dirty flag: pause then resume.
        session.pause_torrent(info_hash).await.unwrap();
        tokio::time::sleep(Duration::from_millis(50)).await;
        session.resume_torrent(info_hash).await.unwrap();
        tokio::time::sleep(Duration::from_millis(50)).await;

        let path = crate::resume_file::resume_file_path(tmp.path(), &info_hash);

        // Shutdown triggers save_dirty_resume_files internally.
        // SessionHandle::shutdown() is fire-and-forget, so we need to
        // wait briefly for the actor to finish writing to disk.
        session.shutdown().await.unwrap();
        tokio::time::sleep(Duration::from_millis(200)).await;

        assert!(path.exists(), "resume file should exist after shutdown");
    }

    // ---- Test: auto-restore on startup ----

    #[tokio::test]
    async fn auto_restore_on_startup() {
        let tmp = tempfile::TempDir::new().unwrap();

        let info_hash;
        {
            // First session: add a torrent, save, and shut down.
            let session = SessionHandle::start(resume_test_settings(tmp.path()))
                .await
                .unwrap();

            let data = vec![0xAB; 16384];
            let meta = make_test_torrent(&data, 16384);
            info_hash = meta.info_hash;
            let storage = make_storage(&data, 16384);
            session
                .add_torrent_with_meta(meta.into(), Some(storage))
                .await
                .unwrap();

            tokio::time::sleep(Duration::from_millis(50)).await;
            let _ = session.save_resume_state().await;
            session.shutdown().await.unwrap();
        }

        // Verify the resume file exists before starting a new session.
        let path = crate::resume_file::resume_file_path(tmp.path(), &info_hash);
        assert!(path.exists(), "resume file should exist before restart");

        {
            // Second session: should auto-restore the torrent on startup.
            let session = SessionHandle::start(resume_test_settings(tmp.path()))
                .await
                .unwrap();

            // Give the actor a moment to process the auto-restore.
            tokio::time::sleep(Duration::from_millis(100)).await;

            let list = session.list_torrents().await.unwrap();
            assert!(
                list.contains(&info_hash),
                "torrent should be auto-restored on startup"
            );

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

    // ---- Test: shutdown with read-only resume dir completes without error ----

    #[tokio::test]
    async fn shutdown_with_readonly_resume_dir_completes() {
        let tmp = tempfile::TempDir::new().unwrap();
        // Point resume_data_dir to a non-existent path under a read-only root.
        // On Linux, /proc is always read-only for directory creation.
        let readonly_dir = PathBuf::from("/proc/irontide-test-nonexistent");
        let mut settings = test_settings();
        settings.resume_data_dir = Some(readonly_dir);

        let session = SessionHandle::start(settings).await.unwrap();

        let data = vec![0xAB; 16384];
        let meta = make_test_torrent(&data, 16384);
        let storage = make_storage(&data, 16384);
        session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

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

        // Shutdown should complete without panic or error even though
        // the resume dir is not writable.
        session.shutdown().await.unwrap();

        // If we got here, the test passed — errors were logged, not propagated.
        drop(tmp);
    }

    // ---- Test: orphan resume file deleted on startup ----

    #[tokio::test]
    async fn orphan_resume_file_deleted_on_startup() {
        let tmp = tempfile::TempDir::new().unwrap();
        let torrents_dir = tmp.path().join("torrents");
        std::fs::create_dir_all(&torrents_dir).unwrap();

        // Write a fake .resume file that does not match any torrent.
        // Use valid bencode so it parses but with a hash that won't match
        // anything added to the session. The file must parse correctly for
        // the load to attempt adding it (which will fail or produce a torrent
        // with a mismatched hash that gets cleaned up as orphan).
        // Simplest: write garbage bencode — it will fail to deserialize,
        // not be added, and then orphan cleanup should remove it.
        let orphan_path = torrents_dir.join("deadbeefdeadbeefdeadbeefdeadbeefdeadbeef.resume");
        std::fs::write(&orphan_path, b"not valid bencode").unwrap();
        assert!(orphan_path.exists(), "orphan file should exist before test");

        let session = SessionHandle::start(resume_test_settings(tmp.path()))
            .await
            .unwrap();

        // Give the actor time to auto-restore + orphan cleanup.
        tokio::time::sleep(Duration::from_millis(100)).await;

        assert!(
            !orphan_path.exists(),
            "orphan resume file should be deleted on startup"
        );

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

    // ==== M161 Phase 7: integration tests for resume file lifecycle ====

    // ---- Test: multi-torrent save-load round-trip ----
    //
    // Creates 3 torrents in session 1, saves resume state, verifies 3 `.resume`
    // files on disk. Starts session 2 with the same resume dir and verifies all
    // 3 torrents are restored via `load_resume_state()`.

    #[tokio::test]
    async fn multi_torrent_save_load_round_trip() {
        let tmp = tempfile::TempDir::new().unwrap();

        // Distinct data per torrent to produce unique info hashes.
        let datasets: [u8; 3] = [0xAA, 0xBB, 0xCC];
        let mut hashes = Vec::with_capacity(3);

        {
            // Session 1: add 3 torrents, save resume state.
            let session = SessionHandle::start(resume_test_settings(tmp.path()))
                .await
                .unwrap();

            for &byte in &datasets {
                let data = vec![byte; 16384];
                let meta = make_test_torrent(&data, 16384);
                let info_hash = meta.info_hash;
                let storage = make_storage(&data, 16384);
                session
                    .add_torrent_with_meta(meta.into(), Some(storage))
                    .await
                    .unwrap();
                hashes.push(info_hash);
            }

            // Let actors settle so dirty flags are set.
            tokio::time::sleep(Duration::from_millis(100)).await;

            let saved = session.save_resume_state().await.unwrap();
            assert_eq!(saved, 3, "all 3 torrents should be saved");

            // Verify .resume files exist on disk.
            let files = crate::resume_file::scan_resume_dir(tmp.path());
            assert_eq!(files.len(), 3, "3 .resume files should be on disk");

            for hash in &hashes {
                let path = crate::resume_file::resume_file_path(tmp.path(), hash);
                assert!(
                    path.exists(),
                    "resume file for {} should exist",
                    hex::encode(hash.as_bytes())
                );
            }

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

        {
            // Session 2: fresh session with the same resume dir.
            // Disable auto-restore by starting first, then calling
            // load_resume_state manually.
            //
            // NOTE: the auto-restore runs during `start()` before we get the
            // handle back, so the torrents will already be loaded. Use
            // list_torrents to verify instead.
            let session = SessionHandle::start(resume_test_settings(tmp.path()))
                .await
                .unwrap();

            // Give the actor time to process auto-restore.
            tokio::time::sleep(Duration::from_millis(200)).await;

            let list = session.list_torrents().await.unwrap();
            assert_eq!(list.len(), 3, "all 3 torrents should be auto-restored");

            for hash in &hashes {
                assert!(
                    list.contains(hash),
                    "torrent {} should be present after restore",
                    hex::encode(hash.as_bytes())
                );
            }

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

    // ---- Test: corrupt 1 of 3 resume files → 2 restored + 1 failed ----
    //
    // Saves 3 torrents to resume files, corrupts one with garbage bytes,
    // then starts a fresh session and verifies that 2 are restored and 1 failed.

    #[tokio::test]
    async fn corrupt_one_of_three_resume_files() {
        let tmp = tempfile::TempDir::new().unwrap();

        let datasets: [u8; 3] = [0xDD, 0xEE, 0xFF];
        let mut hashes = Vec::with_capacity(3);

        {
            // Session 1: add 3 torrents, save resume state.
            let session = SessionHandle::start(resume_test_settings(tmp.path()))
                .await
                .unwrap();

            for &byte in &datasets {
                let data = vec![byte; 16384];
                let meta = make_test_torrent(&data, 16384);
                let info_hash = meta.info_hash;
                let storage = make_storage(&data, 16384);
                session
                    .add_torrent_with_meta(meta.into(), Some(storage))
                    .await
                    .unwrap();
                hashes.push(info_hash);
            }

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

            let saved = session.save_resume_state().await.unwrap();
            assert_eq!(saved, 3, "all 3 torrents should be saved");

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

        // Corrupt the second resume file with garbage bytes.
        let corrupt_path = crate::resume_file::resume_file_path(tmp.path(), &hashes[1]);
        assert!(
            corrupt_path.exists(),
            "file to corrupt must exist before overwrite"
        );
        std::fs::write(&corrupt_path, b"CORRUPTED GARBAGE DATA 0xDEAD").unwrap();

        {
            // Session 2: auto-restore should recover 2, fail 1, and the
            // orphan cleanup should delete the corrupt file.
            let session = SessionHandle::start(resume_test_settings(tmp.path()))
                .await
                .unwrap();

            // Give actor time for auto-restore + orphan cleanup.
            tokio::time::sleep(Duration::from_millis(200)).await;

            let list = session.list_torrents().await.unwrap();
            assert_eq!(
                list.len(),
                2,
                "2 torrents should be restored (1 corrupt skipped)"
            );

            // The good hashes should be present.
            assert!(
                list.contains(&hashes[0]),
                "first torrent should be restored"
            );
            assert!(
                list.contains(&hashes[2]),
                "third torrent should be restored"
            );

            // The corrupt hash should NOT be present.
            assert!(
                !list.contains(&hashes[1]),
                "corrupted torrent should not be restored"
            );

            // Also verify the corrupt file was cleaned up as orphan.
            assert!(
                !corrupt_path.exists(),
                "corrupt resume file should be deleted by orphan cleanup"
            );

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

    // ---- Test: remove torrent → `.resume` file deleted from disk ----
    //
    // Adds a torrent, saves resume state (creates the `.resume` file), then
    // removes the torrent via `session.remove_torrent()`. The removal handler
    // eagerly deletes the `.resume` file so it is not orphaned.

    #[tokio::test]
    async fn remove_torrent_deletes_resume_file() {
        let tmp = tempfile::TempDir::new().unwrap();

        let data = vec![0x42; 16384];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;
        let storage = make_storage(&data, 16384);

        let session = SessionHandle::start(resume_test_settings(tmp.path()))
            .await
            .unwrap();

        session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Let the actor settle so the dirty flag is set.
        tokio::time::sleep(Duration::from_millis(100)).await;

        let saved = session.save_resume_state().await.unwrap();
        assert!(saved > 0, "torrent should be saved to a resume file");

        let resume_path = crate::resume_file::resume_file_path(tmp.path(), &info_hash);
        assert!(resume_path.exists(), "resume file should exist after save");

        // Remove the torrent — this should also delete the .resume file.
        session.remove_torrent(info_hash).await.unwrap();
        tokio::time::sleep(Duration::from_millis(50)).await;

        let list = session.list_torrents().await.unwrap();
        assert!(
            !list.contains(&info_hash),
            "torrent should be gone from session after removal"
        );

        assert!(
            !resume_path.exists(),
            "resume file should be deleted when torrent is removed"
        );

        // Verify no .resume files remain in the torrents directory.
        let remaining = crate::resume_file::scan_resume_dir(tmp.path());
        assert!(
            remaining.is_empty(),
            "no resume files should remain after removing the only torrent"
        );

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

    // ── M170: session-level storage-path tests ─────────────────────────

    /// Test settings that use an isolated `resume_data_dir` so that
    /// auto-restore from a prior test run doesn't pollute `torrents`.
    /// Matches the precedent set by `test_settings_with_dht`.
    fn test_settings_isolated_resume(resume_dir: &std::path::Path) -> Settings {
        Settings {
            resume_data_dir: Some(resume_dir.to_path_buf()),
            ..test_settings()
        }
    }

    #[tokio::test]
    async fn remove_torrent_with_files_deletes_disk_files() {
        // Build a real on-disk torrent via FilesystemStorage, then call
        // remove_torrent_with_files. The files MUST be gone from disk
        // after the spawn_blocking walk completes.
        let download_dir = tempfile::tempdir().unwrap();
        let resume_dir = tempfile::tempdir().unwrap();
        let mut settings = test_settings_isolated_resume(resume_dir.path());
        settings.download_dir = download_dir.path().to_path_buf();
        let session = SessionHandle::start(settings).await.unwrap();

        let data = vec![0xAB_u8; 16384];
        let meta = make_test_torrent(&data, 16384);
        let lengths = Lengths::new(data.len() as u64, 16384, DEFAULT_CHUNK_SIZE);
        let storage: Arc<dyn TorrentStorage> = Arc::new(
            irontide_storage::FilesystemStorage::new(
                download_dir.path(),
                vec![PathBuf::from("test")],
                vec![data.len() as u64],
                lengths,
                None,
                irontide_storage::PreallocateMode::None,
                false,
            )
            .unwrap(),
        );

        // Write actual piece data so the file is non-empty and cannot
        // be mistaken for a sparse leftover.
        storage.write_chunk(0, 0, &data).unwrap();

        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        let file_on_disk = download_dir.path().join("test");
        assert!(file_on_disk.exists(), "file should exist before delete");

        session.remove_torrent_with_files(info_hash).await.unwrap();

        // The spawn_blocking task is fire-and-forget; poll briefly.
        for _ in 0..20 {
            if !file_on_disk.exists() {
                break;
            }
            tokio::time::sleep(Duration::from_millis(50)).await;
        }
        assert!(
            !file_on_disk.exists(),
            "file should have been removed from disk"
        );
        assert!(
            download_dir.path().exists(),
            "download_dir root must never be removed"
        );

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

    #[tokio::test]
    async fn remove_torrent_with_files_tolerates_already_deleted_files() {
        // Partial-failure semantics: the user removed files out-of-band
        // before the session got the deleteFiles command. The call must
        // still succeed (always returns Ok).
        let download_dir = tempfile::tempdir().unwrap();
        let resume_dir = tempfile::tempdir().unwrap();
        let mut settings = test_settings_isolated_resume(resume_dir.path());
        settings.download_dir = download_dir.path().to_path_buf();
        let session = SessionHandle::start(settings).await.unwrap();

        let data = vec![0xCD_u8; 16384];
        let meta = make_test_torrent(&data, 16384);
        let lengths = Lengths::new(data.len() as u64, 16384, DEFAULT_CHUNK_SIZE);
        let storage: Arc<dyn TorrentStorage> = Arc::new(
            irontide_storage::FilesystemStorage::new(
                download_dir.path(),
                vec![PathBuf::from("test")],
                vec![data.len() as u64],
                lengths,
                None,
                irontide_storage::PreallocateMode::None,
                false,
            )
            .unwrap(),
        );
        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Manually delete the file before calling remove_torrent_with_files.
        std::fs::remove_file(download_dir.path().join("test")).unwrap();

        // Must still succeed.
        let result = session.remove_torrent_with_files(info_hash).await;
        assert!(
            result.is_ok(),
            "remove_torrent_with_files must return Ok on missing files"
        );

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

    #[tokio::test]
    async fn remove_torrent_with_files_grace_guards_fast_re_add() {
        // Fast re-add during an in-flight delete must 409 until the
        // deletion grace window closes. Because the delete is fire-and-
        // forget, we simulate by calling remove_torrent_with_files and
        // then immediately re-adding the same info hash via
        // add_torrent(AddTorrentParams::bytes(...)).  The grace set is
        // populated synchronously inside the actor so the re-add sees it.
        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 download_dir = tempfile::tempdir().unwrap();
        let resume_dir = tempfile::tempdir().unwrap();
        let mut settings = test_settings_isolated_resume(resume_dir.path());
        settings.download_dir = download_dir.path().to_path_buf();
        let session = SessionHandle::start(settings).await.unwrap();

        // Build + serialize a single-file torrent so we can re-add via
        // bytes after deleting.
        let data = vec![0xEE_u8; 16384];
        let meta = make_test_torrent(&data, 16384);
        let lengths = Lengths::new(data.len() as u64, 16384, DEFAULT_CHUNK_SIZE);
        let storage: Arc<dyn TorrentStorage> = Arc::new(
            irontide_storage::FilesystemStorage::new(
                download_dir.path(),
                vec![PathBuf::from("test")],
                vec![data.len() as u64],
                lengths,
                None,
                irontide_storage::PreallocateMode::None,
                false,
            )
            .unwrap(),
        );
        // Re-serialise the TorrentMetaV1 so we can feed the bytes back
        // through AddTorrentParams::bytes.
        let mut pieces = Vec::new();
        let hash = irontide_core::sha1(&data);
        pieces.extend_from_slice(hash.as_bytes());
        let bytes = irontide_bencode::to_bytes(&Torrent {
            info: Info {
                length: data.len() as u64,
                name: "test",
                piece_length: 16384,
                pieces: &pieces,
            },
        })
        .unwrap();

        let info_hash = session
            .add_torrent_with_meta(meta.into(), Some(storage))
            .await
            .unwrap();

        // Kick off the delete — the deletion_grace set is populated
        // inside the actor before we return.
        session.remove_torrent_with_files(info_hash).await.unwrap();

        // Immediately try to re-add. The grace window may still be
        // open; if it is, we expect 409/CategoryBeingRemoved. If the
        // spawn_blocking happened to finish first, we expect success.
        // Either way the system must NOT panic or leak a half-deleted
        // torrent.
        let params = AddTorrentParams::bytes(bytes);
        let result = session.add_torrent(params).await;
        match result {
            Ok(_) => {
                // grace window closed before the re-add — fine.
            }
            Err(crate::Error::TorrentBeingRemoved(h)) => {
                assert_eq!(h, info_hash, "grace error must name the same hash");
            }
            Err(e) => panic!("unexpected error on re-add: {e}"),
        }

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

    // ---- v0.173.2 T2: synchronous debug_inject_metadata ----

    /// Synthesise a v1 info dict and its SHA-1 info hash. Returns
    /// `(info_bytes, info_hash)` where `info_bytes` is the bencoded info
    /// dict alone (not the outer .torrent wrapper) and `info_hash` is the
    /// SHA-1 of those bytes.
    ///
    /// The injected info hash MUST match the magnet URI's info hash, so
    /// this helper owns that invariant: hash exactly the bytes that will
    /// later be injected.
    #[cfg(feature = "test-util")]
    fn make_debug_inject_info() -> (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_u8; 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: data.len() as u64,
            name: "sync-inject-test",
            piece_length: 1024,
            pieces: &pieces,
        };

        let info_bytes = irontide_bencode::to_bytes(&info).unwrap();
        let info_hash = irontide_core::sha1(&info_bytes);
        (info_bytes, info_hash)
    }

    #[cfg(feature = "test-util")]
    #[tokio::test]
    async fn debug_inject_metadata_resolves_magnet_meta_synchronously() {
        use crate::session::AddTorrentParams;

        let (info_bytes, info_hash) = make_debug_inject_info();

        // Isolate resume dir — magnet adds persist .resume files; without
        // isolation, parallel tests and re-runs pollute one another. See
        // feedback_irontide_resume_test_isolation memory entry.
        let resume_dir = tempfile::tempdir().unwrap();
        let session = SessionHandle::start(test_settings_isolated_resume(resume_dir.path()))
            .await
            .unwrap();

        let magnet_uri = format!(
            "magnet:?xt=urn:btih:{}&dn=sync-inject-test",
            info_hash.to_hex()
        );
        let added = session
            .add_torrent(AddTorrentParams::magnet(magnet_uri))
            .await
            .unwrap();
        assert_eq!(
            added, info_hash,
            "magnet info hash must equal synth info hash"
        );

        // The synchronous contract: when `debug_inject_metadata` returns
        // Ok, the metadata must already be visible via `torrent_file` — no
        // polling, no sleep. This is what distinguishes it from the M147
        // fire-and-forget path.
        session
            .debug_inject_metadata(info_hash, info_bytes)
            .await
            .expect("debug_inject_metadata must succeed");

        let meta = session
            .torrent_file(info_hash)
            .await
            .expect("torrent_file call")
            .expect("metadata must be present immediately after sync inject");
        assert_eq!(meta.info_hash, info_hash);

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

    #[cfg(feature = "test-util")]
    #[tokio::test]
    async fn debug_inject_metadata_returns_torrent_not_found_for_unknown_hash() {
        let resume_dir = tempfile::tempdir().unwrap();
        let session = SessionHandle::start(test_settings_isolated_resume(resume_dir.path()))
            .await
            .unwrap();

        let bogus = Id20::from_hex("ffffffffffffffffffffffffffffffffffffffff").unwrap();
        let result = session.debug_inject_metadata(bogus, vec![]).await;
        assert!(
            matches!(result, Err(crate::Error::TorrentNotFound(_))),
            "expected TorrentNotFound for unknown hash; got {result:?}"
        );

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

    // ---- v0.173.2 T7: A11 ssl_cert metadata propagation regression ----

    /// Synthesise a v1 info dict with optional `private` and `ssl-cert`
    /// fields. Unlike [`make_debug_inject_info`], this helper exists
    /// specifically to exercise the BEP 35 `ssl-cert` propagation path
    /// from the bencoded info dict into `TorrentMetaV1::info.ssl_cert`
    /// after synchronous metadata injection (T2's `debug_inject_metadata`).
    ///
    /// The bencode key name is `ssl-cert` (with hyphen) per BEP 35; serde
    /// renames it on the synthesised `Info` struct below so the emitted
    /// bytes match `InfoDict`'s deserialiser exactly.
    ///
    /// The caller hashes the returned bytes directly to compute the info
    /// hash — the returned bytes are the info dict alone (no wrapper).
    #[cfg(feature = "test-util")]
    fn build_synth_info_bytes_with_options(
        name: &str,
        length_bytes: u64,
        piece_length: u64,
        private: Option<i64>,
        ssl_cert: Option<Vec<u8>>,
    ) -> Vec<u8> {
        use serde::Serialize;

        #[derive(Serialize)]
        struct Info {
            length: u64,
            name: String,
            #[serde(rename = "piece length")]
            piece_length: u64,
            pieces: serde_bytes::ByteBuf,
            #[serde(skip_serializing_if = "Option::is_none")]
            private: Option<i64>,
            #[serde(rename = "ssl-cert", skip_serializing_if = "Option::is_none")]
            ssl_cert: Option<serde_bytes::ByteBuf>,
        }

        // pieces = SHA-1 of an all-zero piece, repeated. The injected data
        // is never verified against disk during these tests — we only care
        // that the bencoded info dict round-trips through the session's
        // metadata-resolution path with ssl_cert intact.
        let num_pieces = length_bytes.div_ceil(piece_length);
        let zero_piece_hash = irontide_core::sha1(&vec![0_u8; piece_length as usize]);
        let mut pieces = Vec::with_capacity(20 * num_pieces as usize);
        for _ in 0..num_pieces {
            pieces.extend_from_slice(zero_piece_hash.as_bytes());
        }

        let info = Info {
            length: length_bytes,
            name: name.to_owned(),
            piece_length,
            pieces: serde_bytes::ByteBuf::from(pieces),
            private,
            ssl_cert: ssl_cert.map(serde_bytes::ByteBuf::from),
        };
        irontide_bencode::to_bytes(&info).expect("bencode synth info dict")
    }

    #[cfg(feature = "test-util")]
    #[tokio::test]
    async fn ssl_cert_propagates_to_meta_after_inject() {
        use crate::session::AddTorrentParams;

        let resume_dir = tempfile::tempdir().unwrap();
        let session = SessionHandle::start(test_settings_isolated_resume(resume_dir.path()))
            .await
            .unwrap();

        let cert_pem = b"-----BEGIN CERT-----\nfake\n-----END CERT-----\n".to_vec();
        let info_bytes = build_synth_info_bytes_with_options(
            "ssl-fixture",
            16_384,
            16_384,
            None,
            Some(cert_pem.clone()),
        );
        let info_hash = irontide_core::sha1(&info_bytes);

        let magnet = format!("magnet:?xt=urn:btih:{}&dn=ssl-fixture", info_hash.to_hex());
        let added = session
            .add_torrent(AddTorrentParams::magnet(magnet))
            .await
            .unwrap();
        assert_eq!(
            added, info_hash,
            "magnet info hash must equal synth info hash"
        );

        session
            .debug_inject_metadata(info_hash, info_bytes)
            .await
            .expect("debug_inject_metadata must succeed");

        let meta = session
            .torrent_file(info_hash)
            .await
            .expect("torrent_file Ok")
            .expect("metadata must be present immediately after sync inject");
        assert_eq!(
            meta.info.ssl_cert.as_ref(),
            Some(&cert_pem),
            "ssl_cert from synth info dict must propagate to meta.info.ssl_cert"
        );

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

    #[cfg(feature = "test-util")]
    #[tokio::test]
    async fn ssl_cert_absent_remains_none_in_meta_after_inject() {
        use crate::session::AddTorrentParams;

        let resume_dir = tempfile::tempdir().unwrap();
        let session = SessionHandle::start(test_settings_isolated_resume(resume_dir.path()))
            .await
            .unwrap();

        let info_bytes =
            build_synth_info_bytes_with_options("no-ssl-fixture", 16_384, 16_384, None, None);
        let info_hash = irontide_core::sha1(&info_bytes);

        let magnet = format!(
            "magnet:?xt=urn:btih:{}&dn=no-ssl-fixture",
            info_hash.to_hex()
        );
        let added = session
            .add_torrent(AddTorrentParams::magnet(magnet))
            .await
            .unwrap();
        assert_eq!(
            added, info_hash,
            "magnet info hash must equal synth info hash"
        );

        session
            .debug_inject_metadata(info_hash, info_bytes)
            .await
            .expect("debug_inject_metadata must succeed");

        let meta = session
            .torrent_file(info_hash)
            .await
            .expect("torrent_file Ok")
            .expect("metadata must be present immediately after sync inject");
        assert!(
            meta.info.ssl_cert.is_none(),
            "absent ssl-cert in info dict must remain None in meta; got {:?}",
            meta.info.ssl_cert
        );

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

    // ---- P2C4: Startup init throttle tests ----

    #[tokio::test]
    async fn init_throttle_queues_restored_torrents() {
        let tmp = tempfile::TempDir::new().unwrap();
        let resume_dir = tmp.path().to_path_buf();

        // Phase 1: create a session, add 5 torrents, save resume data.
        {
            let mut settings = resume_test_settings(&resume_dir);
            settings.queueing_enabled = false;
            let session = SessionHandle::start(settings).await.unwrap();
            for i in 0u8..5 {
                let data = vec![i.wrapping_add(0xA0); 16384];
                let meta = make_test_torrent(&data, 16384);
                let storage = make_storage(&data, 16384);
                session
                    .add_torrent_with_meta(meta.into(), Some(storage))
                    .await
                    .unwrap();
            }
            tokio::time::sleep(Duration::from_millis(100)).await;
            let saved = session.save_resume_state().await.unwrap();
            assert!(saved >= 3, "should save most resume files, got {saved}");
            session.shutdown().await.unwrap();
        }

        // Phase 2: restart with queueing_enabled and active_checking=2.
        {
            let mut settings = resume_test_settings(&resume_dir);
            settings.queueing_enabled = true;
            settings.active_checking = 2;
            settings.active_downloads = 2;
            settings.active_seeds = 2;
            settings.active_limit = 4;
            let session = SessionHandle::start(settings).await.unwrap();
            // M245 P1: `list_torrent_summaries` is now snapshot-backed. The
            // per-torrent `state` field is a SAMPLED value refreshed on the
            // periodic stats tick (`stats_report_interval`, 1000 ms by default),
            // NOT re-published on every state transition (ratified D2:
            // membership is eager + read-after-write, sampled fields are
            // eventually-consistent to one tick). The init-throttle queues a
            // torrent in the actor promptly, but the snapshot reflects it on the
            // next tick — so poll until the tick converges instead of reading
            // once at a fixed delay. The bounded timeout still fails the test if
            // the throttle never queues anything (a genuine regression).
            let mut queued = 0;
            let mut active = 0;
            for _ in 0..60 {
                let list = session.list_torrent_summaries().await.unwrap();
                queued = list
                    .iter()
                    .filter(|t| t.state == TorrentState::Queued)
                    .count();
                active = list
                    .iter()
                    .filter(|t| t.state != TorrentState::Queued)
                    .count();
                if queued > 0 {
                    break;
                }
                tokio::time::sleep(Duration::from_millis(50)).await;
            }

            assert!(
                queued > 0,
                "at least one torrent should be Queued after a stats tick, but all {active} are active"
            );
            assert!(
                active <= 4,
                "active torrents ({active}) should not exceed active_limit (4)"
            );
            session.shutdown().await.unwrap();
        }
    }

    #[tokio::test]
    async fn init_throttle_disabled_restores_all_immediately() {
        let tmp = tempfile::TempDir::new().unwrap();
        let resume_dir = tmp.path().to_path_buf();

        // Phase 1: add torrents, save resume.
        {
            let settings = resume_test_settings(&resume_dir);
            let session = SessionHandle::start(settings).await.unwrap();
            for i in 0u8..3 {
                let data = vec![i.wrapping_add(0xC0); 16384];
                let meta = make_test_torrent(&data, 16384);
                let storage = make_storage(&data, 16384);
                session
                    .add_torrent_with_meta(meta.into(), Some(storage))
                    .await
                    .unwrap();
            }
            tokio::time::sleep(Duration::from_millis(100)).await;
            session.save_resume_state().await.unwrap();
            session.shutdown().await.unwrap();
        }

        // Phase 2: restart with queueing DISABLED.
        {
            let mut settings = resume_test_settings(&resume_dir);
            settings.queueing_enabled = false;
            let session = SessionHandle::start(settings).await.unwrap();
            tokio::time::sleep(Duration::from_millis(200)).await;

            let list = session.list_torrent_summaries().await.unwrap();
            let queued = list
                .iter()
                .filter(|t| t.state == TorrentState::Queued)
                .count();
            assert_eq!(
                queued, 0,
                "with queueing disabled, no torrents should be Queued"
            );
            session.shutdown().await.unwrap();
        }
    }

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

        let mut settings = test_settings();
        settings.queueing_enabled = true;
        settings.active_checking = 1;
        settings.active_downloads = 5;
        settings.active_seeds = 5;
        settings.active_limit = 10;
        settings.auto_manage_interval = 300;
        let session = SessionHandle::start(settings).await.unwrap();
        let mut alerts = session.subscribe();

        // Add 3 small torrents with correct data so checking completes.
        let mut hashes = Vec::new();
        for i in 0u8..3 {
            let data = vec![i.wrapping_add(0xD0); 16384];
            let meta = make_test_torrent(&data, 16384);
            let storage = make_storage(&data, 16384);
            let h = session
                .add_torrent_with_meta(meta.into(), Some(storage))
                .await
                .unwrap();
            hashes.push(h);
        }

        // Wait for at least one checking-complete state change. The trigger
        // should cause evaluate_queue to promote the next candidate without
        // waiting for the 300s auto_manage_interval.
        let deadline = tokio::time::Instant::now() + Duration::from_secs(5);
        let mut saw_checking_transition = false;
        while tokio::time::Instant::now() < deadline {
            if let Ok(Ok(alert)) =
                tokio::time::timeout(Duration::from_millis(500), alerts.recv()).await
                && matches!(
                    alert.kind,
                    AlertKind::StateChanged {
                        prev_state: TorrentState::Checking,
                        ..
                    }
                )
            {
                saw_checking_transition = true;
                break;
            }
        }

        assert!(
            saw_checking_transition,
            "should have seen a Checking→* state transition"
        );

        // After the checking-complete trigger, the evaluator should have
        // promoted another torrent. Give a moment for the evaluate_queue
        // triggered by the alert arm to run.
        tokio::time::sleep(Duration::from_millis(200)).await;

        let list = session.list_torrent_summaries().await.unwrap();
        let active = list
            .iter()
            .filter(|t| t.state != TorrentState::Queued)
            .count();
        assert!(
            active >= 1,
            "at least one torrent should be active after checking-complete trigger"
        );

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

    // ---- P2C5: Restore queue position from resume data tests ----

    #[tokio::test]
    async fn resume_restores_queue_position() {
        let tmp = tempfile::TempDir::new().unwrap();
        let resume_dir = tmp.path().to_path_buf();

        let data = vec![0xF0; 16384];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;

        // Phase 1: add torrent, set queue position, save resume.
        {
            let settings = resume_test_settings(&resume_dir);
            let session = SessionHandle::start(settings).await.unwrap();
            let storage = make_storage(&data, 16384);
            session
                .add_torrent_with_meta(meta.clone().into(), Some(storage))
                .await
                .unwrap();
            session.set_queue_position(info_hash, 3).await.unwrap();
            tokio::time::sleep(Duration::from_millis(100)).await;
            session.save_resume_state().await.unwrap();
            session.shutdown().await.unwrap();
        }

        // Phase 2: restart and verify position survived.
        {
            let settings = resume_test_settings(&resume_dir);
            let session = SessionHandle::start(settings).await.unwrap();
            tokio::time::sleep(Duration::from_millis(200)).await;

            let pos = session.queue_position(info_hash).await.unwrap();
            // Renormalization reassigns 0..N-1; with a single torrent
            // the position is 0 regardless of saved value.
            assert_eq!(pos, 0, "single torrent renormalizes to position 0");
            session.shutdown().await.unwrap();
        }
    }

    #[tokio::test]
    async fn resume_restores_auto_managed_false() {
        let tmp = tempfile::TempDir::new().unwrap();
        let resume_dir = tmp.path().to_path_buf();

        let data = vec![0xF1; 16384];
        let meta = make_test_torrent(&data, 16384);
        let info_hash = meta.info_hash;

        // Phase 1: add torrent, disable auto-manage, save resume.
        {
            let settings = resume_test_settings(&resume_dir);
            let session = SessionHandle::start(settings).await.unwrap();
            let storage = make_storage(&data, 16384);
            session
                .add_torrent_with_meta(meta.clone().into(), Some(storage))
                .await
                .unwrap();
            // Currently there's no direct API to set auto_managed on
            // SessionHandle — it's internal to TorrentEntry. Verify that
            // the resume round-trip preserves the default (true → 1).
            tokio::time::sleep(Duration::from_millis(100)).await;
            session.save_resume_state().await.unwrap();
            session.shutdown().await.unwrap();
        }

        // Manually patch the resume file to set auto_managed=0.
        {
            let path = crate::resume_file::resume_file_path(&resume_dir, &info_hash);
            if path.exists() {
                let bytes = std::fs::read(&path).unwrap();
                let mut rd = crate::resume_file::deserialize_resume(&bytes).unwrap();
                rd.auto_managed = 0;
                let patched = crate::resume_file::serialize_resume(&rd).unwrap();
                std::fs::write(&path, patched).unwrap();
            }
        }

        // Phase 2: restart and verify auto_managed was restored as false.
        {
            let settings = resume_test_settings(&resume_dir);
            let session = SessionHandle::start(settings).await.unwrap();
            tokio::time::sleep(Duration::from_millis(200)).await;

            let stats = session.torrent_stats(info_hash).await.unwrap();
            assert!(
                !stats.auto_managed,
                "auto_managed should be false after restore"
            );
            session.shutdown().await.unwrap();
        }
    }

    #[tokio::test]
    async fn resume_renormalizes_duplicate_positions() {
        let tmp = tempfile::TempDir::new().unwrap();
        let resume_dir = tmp.path().to_path_buf();

        // Phase 1: add 3 torrents, save resume.
        let mut hashes = Vec::new();
        {
            let settings = resume_test_settings(&resume_dir);
            let session = SessionHandle::start(settings).await.unwrap();
            for i in 0u8..3 {
                let data = vec![i.wrapping_add(0xE0); 16384];
                let meta = make_test_torrent(&data, 16384);
                let storage = make_storage(&data, 16384);
                let h = session
                    .add_torrent_with_meta(meta.into(), Some(storage))
                    .await
                    .unwrap();
                hashes.push(h);
            }
            tokio::time::sleep(Duration::from_millis(100)).await;
            session.save_resume_state().await.unwrap();
            session.shutdown().await.unwrap();
        }

        // Manually patch ALL resume files to have queue_position=0.
        for hash in &hashes {
            let path = crate::resume_file::resume_file_path(&resume_dir, hash);
            if path.exists() {
                let bytes = std::fs::read(&path).unwrap();
                let mut rd = crate::resume_file::deserialize_resume(&bytes).unwrap();
                rd.queue_position = 0;
                let patched = crate::resume_file::serialize_resume(&rd).unwrap();
                std::fs::write(&path, patched).unwrap();
            }
        }

        // Phase 2: restart and verify positions are contiguous 0,1,2.
        {
            let settings = resume_test_settings(&resume_dir);
            let session = SessionHandle::start(settings).await.unwrap();
            tokio::time::sleep(Duration::from_millis(200)).await;

            let mut positions = Vec::new();
            for hash in &hashes {
                if let Ok(pos) = session.queue_position(*hash).await {
                    positions.push(pos);
                }
            }
            positions.sort_unstable();
            let expected: Vec<i32> = (0..positions.len() as i32).collect();
            assert_eq!(
                positions, expected,
                "positions should be contiguous 0..N-1 after renormalization"
            );
            session.shutdown().await.unwrap();
        }
    }

    // ---- P2C6: EWMA rate smoothing tests ----

    #[test]
    fn ewma_smooths_transient_drop() {
        let alpha = 0.3_f64;
        let prev = 100_000.0_f64;
        let sample = 0.0_f64;
        let smoothed = alpha.mul_add(sample, (1.0 - alpha) * prev);
        assert!(
            (smoothed - 70_000.0).abs() < 1.0,
            "smoothed rate should be ~70000, got {smoothed}"
        );
    }

    #[test]
    fn ewma_alpha_one_equals_raw() {
        let alpha = 1.0_f64;
        let prev = 100_000.0_f64;
        let sample = 42_000.0_f64;
        let smoothed = alpha.mul_add(sample, (1.0 - alpha) * prev);
        assert!(
            (smoothed - sample).abs() < 0.001,
            "alpha=1.0 should produce raw rate, got {smoothed}"
        );
    }

    // ---- P2C7: Configurable seed anti-flap duration tests ----

    #[test]
    fn seed_anti_flap_uses_longer_duration() {
        let seed_queue_min_active_secs = 1800_u64;
        let auto_manage_startup = 60_u64;
        let started_5_min_ago = std::time::Duration::from_mins(5);
        let seed_duration = std::time::Duration::from_secs(seed_queue_min_active_secs);

        // Seeding torrent started 5 min ago: still recently_started
        // with seed_queue_min_active_secs=1800.
        assert!(
            started_5_min_ago < seed_duration,
            "5 min < 30 min, seeding torrent should be recently_started"
        );

        // Downloading torrent started 5 min ago: NOT recently_started
        // with auto_manage_startup=60.
        let dl_duration = std::time::Duration::from_secs(auto_manage_startup);
        assert!(
            started_5_min_ago > dl_duration,
            "5 min > 60s, downloading torrent should NOT be recently_started"
        );
    }

    #[test]
    fn download_anti_flap_uses_startup_duration() {
        let auto_manage_startup = 60_u64;
        let started_5_min_ago = std::time::Duration::from_mins(5);
        let dl_duration = std::time::Duration::from_secs(auto_manage_startup);
        assert!(
            started_5_min_ago > dl_duration,
            "downloading torrent started 5 min ago should NOT be recently_started"
        );
    }

    // ── M214: classify round-trip for Connection + Speed fields ──────

    #[test]
    fn classify_restart_required_upnp_change() {
        let old = Settings::default();
        let mut new = old.clone();
        new.enable_upnp = !old.enable_upnp;
        assert_eq!(classify_immediate(&old, &new), Vec::<&str>::new());
        assert_eq!(classify_restart_required(&old, &new), vec!["upnp"]);
    }

    #[test]
    fn classify_restart_required_natpmp_change() {
        let old = Settings::default();
        let mut new = old.clone();
        new.enable_natpmp = !old.enable_natpmp;
        assert_eq!(classify_immediate(&old, &new), Vec::<&str>::new());
        assert_eq!(classify_restart_required(&old, &new), vec!["natpmp"]);
    }

    #[test]
    fn classify_immediate_max_connec_global_change() {
        let old = Settings::default();
        let mut new = old.clone();
        new.max_connections_global = if old.max_connections_global == 500 {
            501
        } else {
            500
        };
        assert_eq!(classify_immediate(&old, &new), vec!["max_connec_global"]);
        assert_eq!(classify_restart_required(&old, &new), Vec::<&str>::new());
    }

    #[test]
    fn classify_immediate_max_uploads_per_torrent_change() {
        // M224: per-torrent upload slot cap is classified immediate; the
        // choker reads the new cap at its next unchoke tick. Mirrors the
        // max_connec_global pattern from M214.
        let old = Settings::default();
        let mut new = old.clone();
        new.max_uploads_per_torrent = 4;
        assert_eq!(
            classify_immediate(&old, &new),
            vec!["max_uploads_per_torrent"]
        );
        assert_eq!(classify_restart_required(&old, &new), Vec::<&str>::new());
    }

    #[test]
    fn classify_restart_required_proxy_type_change() {
        let old = Settings::default();
        let mut new = old.clone();
        new.proxy.proxy_type = crate::proxy::ProxyType::Socks5;
        assert_eq!(classify_immediate(&old, &new), Vec::<&str>::new());
        assert_eq!(classify_restart_required(&old, &new), vec!["proxy_type"]);
    }

    #[test]
    fn classify_restart_required_proxy_credentials_change() {
        let old = Settings::default();
        let mut new = old.clone();
        new.proxy.username = Some("alice".into());
        new.proxy.password = Some("secret".into());
        assert_eq!(classify_immediate(&old, &new), Vec::<&str>::new());
        let restart = classify_restart_required(&old, &new);
        // Both fields must surface; order is implementation-defined but the
        // set must equal {proxy_username, proxy_password}.
        let set: std::collections::HashSet<&str> = restart.iter().copied().collect();
        assert_eq!(
            set,
            ["proxy_username", "proxy_password"]
                .into_iter()
                .collect::<std::collections::HashSet<_>>()
        );
    }

    #[test]
    fn classify_combined_immediate_and_restart() {
        // Multi-field diff: max_connec_global + max_uploads_per_torrent
        // (both immediate) + upnp + proxy_type (both restart) should populate
        // both lists. M224 extends the immediate side.
        let old = Settings::default();
        let mut new = old.clone();
        new.max_connections_global = old.max_connections_global + 1;
        new.max_uploads_per_torrent = 4;
        new.enable_upnp = !old.enable_upnp;
        new.proxy.proxy_type = crate::proxy::ProxyType::Http;

        let immediate = classify_immediate(&old, &new);
        let imm_set: std::collections::HashSet<&str> = immediate.iter().copied().collect();
        assert_eq!(
            imm_set,
            ["max_connec_global", "max_uploads_per_torrent"]
                .into_iter()
                .collect::<std::collections::HashSet<_>>()
        );
        let restart = classify_restart_required(&old, &new);
        let set: std::collections::HashSet<&str> = restart.iter().copied().collect();
        assert_eq!(
            set,
            ["upnp", "proxy_type"]
                .into_iter()
                .collect::<std::collections::HashSet<_>>()
        );
    }

    // ── M215: BitTorrent + Advanced classify-list verification ──────

    #[test]
    fn classify_immediate_seed_time_limit_change() {
        let old = Settings::default();
        let mut new = old.clone();
        new.seed_time_limit_secs = Some(3600);
        assert_eq!(classify_immediate(&old, &new), vec!["max_seeding_time"]);
        assert_eq!(classify_restart_required(&old, &new), Vec::<&str>::new());
    }

    #[test]
    fn classify_immediate_inactive_seed_time_limit_change() {
        let old = Settings::default();
        let mut new = old.clone();
        new.inactive_seed_time_limit_secs = Some(1800);
        assert_eq!(
            classify_immediate(&old, &new),
            vec!["max_inactive_seeding_time"]
        );
        assert_eq!(classify_restart_required(&old, &new), Vec::<&str>::new());
    }

    // M225: `classify_restart_required_hashing_threads_change` and
    // `classify_restart_required_save_resume_interval_change` (formerly here)
    // were DELETED in M225 — those fields are now `classify_immediate` per
    // OV F2c / F4. Replacement immediate-dispatch coverage follows.

    #[test]
    fn classify_immediate_save_resume_interval_change() {
        // M225 Step 1: save_resume_interval graduated from restart_required
        // to immediate. SessionActor rebuilds the resume_save_interval timer
        // via Arc<Notify> on dispatch — no daemon restart needed.
        let old = Settings::default();
        let mut new = old.clone();
        new.save_resume_interval_secs = old.save_resume_interval_secs.saturating_add(60);
        assert_eq!(classify_immediate(&old, &new), vec!["save_resume_interval"]);
        assert_eq!(classify_restart_required(&old, &new), Vec::<&str>::new());
    }

    #[test]
    fn classify_immediate_hashing_threads_change() {
        // M225 Step 2: hashing_threads graduated from restart_required to
        // immediate. The per-torrent piece-verify batch reads
        // self.config.hashing_threads at the start of each batch, so a value
        // change applies on the NEXT batch via the existing
        // TorrentCommand::UpdateSettings(SettingsDelta) fan-out path.
        let old = Settings::default();
        let mut new = old.clone();
        new.hashing_threads = old.hashing_threads.saturating_add(2);
        assert_eq!(classify_immediate(&old, &new), vec!["hashing_threads"]);
        assert_eq!(classify_restart_required(&old, &new), Vec::<&str>::new());
    }

    #[test]
    fn classify_immediate_ip_filter_enabled_change() {
        // M225 Step 3: ip_filter_enabled graduated to immediate. apply_settings
        // writes through Arc<RwLock<IpFilter>> with self.ip_filter.write().enabled
        // = enabled; future is_blocked calls observe the new value on the next
        // RwLock read.
        let old = Settings::default();
        let mut new = old.clone();
        new.ip_filter_enabled = !old.ip_filter_enabled;
        assert_eq!(classify_immediate(&old, &new), vec!["ip_filter_enabled"]);
        assert_eq!(classify_restart_required(&old, &new), Vec::<&str>::new());
    }

    #[test]
    fn settings_delta_from_diff_includes_save_resume_interval() {
        // M225 Step 1: SettingsDelta carries save_resume_interval_secs so
        // apply_settings can dispatch the Notify on observed change.
        use crate::types::SettingsDelta;
        let old = Settings::default();
        let mut new = old.clone();
        new.save_resume_interval_secs = old.save_resume_interval_secs.saturating_add(30);
        let d = SettingsDelta::from_diff(&old, &new);
        assert_eq!(
            d.save_resume_interval_secs,
            Some(new.save_resume_interval_secs)
        );
        assert!(d.hashing_threads.is_none());
        assert!(d.ip_filter_enabled.is_none());
        assert!(!d.is_empty());
    }

    #[test]
    fn settings_delta_from_diff_includes_hashing_threads() {
        // M225 Step 2: SettingsDelta carries hashing_threads so the existing
        // TorrentCommand::UpdateSettings fan-out propagates per-torrent.
        use crate::types::SettingsDelta;
        let old = Settings::default();
        let mut new = old.clone();
        new.hashing_threads = old.hashing_threads.saturating_add(1);
        let d = SettingsDelta::from_diff(&old, &new);
        assert_eq!(d.hashing_threads, Some(new.hashing_threads));
        assert!(d.save_resume_interval_secs.is_none());
        assert!(d.ip_filter_enabled.is_none());
        assert!(!d.is_empty());
    }

    #[test]
    fn settings_delta_from_diff_includes_ip_filter_enabled() {
        // M225 Step 3: SettingsDelta carries ip_filter_enabled. apply_settings
        // applies it through the outer Arc<RwLock<IpFilter>> write-lock.
        use crate::types::SettingsDelta;
        let old = Settings::default();
        let mut new = old.clone();
        new.ip_filter_enabled = !old.ip_filter_enabled;
        let d = SettingsDelta::from_diff(&old, &new);
        assert_eq!(d.ip_filter_enabled, Some(new.ip_filter_enabled));
        assert!(d.save_resume_interval_secs.is_none());
        assert!(d.hashing_threads.is_none());
        assert!(!d.is_empty());
    }

    #[test]
    fn settings_delta_is_empty_honours_m225_fields() {
        // M225: is_empty must return false when any M225 field is set so the
        // fan-out path runs.
        use crate::types::SettingsDelta;
        let mut d = SettingsDelta::default();
        assert!(d.is_empty());
        d.save_resume_interval_secs = Some(120);
        assert!(!d.is_empty());
        d = SettingsDelta::default();
        d.hashing_threads = Some(8);
        assert!(!d.is_empty());
        d = SettingsDelta::default();
        d.ip_filter_enabled = Some(false);
        assert!(!d.is_empty());
    }

    // ── M226: SettingsDelta + classify_immediate coverage ──────────────────

    /// Helper for compact M226 delta+classify tests: toggle one field, verify
    /// the delta picks it up AND [`classify_immediate`] yields the expected
    /// alias AND [`classify_restart_required`] stays empty.
    fn m226_delta_and_classify_check<F>(mutate: F, alias: &'static str)
    where
        F: FnOnce(&mut Settings),
    {
        use crate::types::SettingsDelta;
        let old = Settings::default();
        let mut new = old.clone();
        mutate(&mut new);
        let d = SettingsDelta::from_diff(&old, &new);
        assert!(
            !d.is_empty(),
            "{alias}: delta must not be empty after toggle"
        );
        let imm = classify_immediate(&old, &new);
        assert!(
            imm.contains(&alias),
            "{alias}: classify_immediate must contain alias, got {imm:?}"
        );
        let rr = classify_restart_required(&old, &new);
        assert!(
            !rr.contains(&alias),
            "{alias}: must NOT appear in classify_restart_required"
        );
    }

    #[test]
    fn m226_notify_on_complete_immediate() {
        m226_delta_and_classify_check(|s| s.notify_on_complete = true, "notify_on_complete");
    }

    #[test]
    fn m226_notify_on_error_immediate() {
        m226_delta_and_classify_check(|s| s.notify_on_error = true, "notify_on_error");
    }

    #[test]
    fn m226_on_complete_program_immediate() {
        m226_delta_and_classify_check(
            |s| s.on_complete_program = Some(std::path::PathBuf::from("/usr/local/bin/finish")),
            "on_complete_program",
        );
    }

    #[test]
    fn m226_use_incomplete_dir_immediate() {
        m226_delta_and_classify_check(|s| s.use_incomplete_dir = true, "use_incomplete_dir");
    }

    #[test]
    fn m226_incomplete_dir_immediate() {
        m226_delta_and_classify_check(
            |s| s.incomplete_dir = Some(std::path::PathBuf::from("/tmp/inc")),
            "incomplete_dir",
        );
    }

    #[test]
    fn m226_default_skip_hash_check_immediate() {
        m226_delta_and_classify_check(
            |s| s.default_skip_hash_check = true,
            "default_skip_hash_check",
        );
    }

    #[test]
    fn m226_incomplete_extension_enabled_immediate() {
        // Default is TRUE so we toggle false to observe diff.
        m226_delta_and_classify_check(
            |s| s.incomplete_extension_enabled = false,
            "incomplete_extension_enabled",
        );
    }

    #[test]
    fn m226_watched_folder_immediate() {
        m226_delta_and_classify_check(
            |s| s.watched_folder = Some(std::path::PathBuf::from("/tmp/watched")),
            "watched_folder",
        );
    }

    #[test]
    fn m226_delete_torrent_after_add_immediate() {
        m226_delta_and_classify_check(
            |s| s.delete_torrent_after_add = true,
            "delete_torrent_after_add",
        );
    }

    #[test]
    fn m226_move_completed_enabled_immediate() {
        m226_delta_and_classify_check(
            |s| s.move_completed_enabled = true,
            "move_completed_enabled",
        );
    }

    #[test]
    fn m226_move_completed_to_immediate() {
        m226_delta_and_classify_check(
            |s| s.move_completed_to = Some(std::path::PathBuf::from("/tmp/done")),
            "move_completed_to",
        );
    }

    #[test]
    fn m226_ip_filter_auto_refresh_immediate() {
        m226_delta_and_classify_check(
            |s| s.ip_filter_auto_refresh = true,
            "ip_filter_auto_refresh",
        );
    }

    #[test]
    fn m226_web_ui_https_enabled_immediate() {
        m226_delta_and_classify_check(|s| s.web_ui_https_enabled = true, "web_ui_https_enabled");
    }

    #[test]
    fn m226_network_interface_immediate() {
        m226_delta_and_classify_check(
            |s| s.network_interface = Some("eth0".into()),
            "network_interface",
        );
    }

    #[test]
    fn m226_default_add_paused_immediate() {
        m226_delta_and_classify_check(|s| s.default_add_paused = true, "default_add_paused");
    }

    #[test]
    fn m226_delta_clears_optional_path_incomplete_dir() {
        // F4 — outer Some + inner None means "clear to None". Without nested
        // Option this case is indistinguishable from "no change".
        use crate::types::SettingsDelta;
        let old = Settings {
            incomplete_dir: Some(std::path::PathBuf::from("/foo")),
            ..Settings::default()
        };
        let new = Settings {
            incomplete_dir: None,
            ..old.clone()
        };
        let d = SettingsDelta::from_diff(&old, &new);
        assert_eq!(d.incomplete_dir, Some(None), "must signal clear to None");
        assert!(!d.is_empty());
    }

    #[test]
    fn m226_delta_clears_optional_path_watched_folder() {
        // F4 — same pattern for watched_folder.
        use crate::types::SettingsDelta;
        let old = Settings {
            watched_folder: Some(std::path::PathBuf::from("/tmp/watch")),
            ..Settings::default()
        };
        let new = Settings {
            watched_folder: None,
            ..old.clone()
        };
        let d = SettingsDelta::from_diff(&old, &new);
        assert_eq!(d.watched_folder, Some(None));
        assert!(!d.is_empty());
    }

    #[test]
    fn m226_delta_is_empty_honours_new_fields() {
        // is_empty must return false when ANY M226 field is set.
        use crate::types::SettingsDelta;
        let mut d = SettingsDelta::default();
        assert!(d.is_empty());
        d.notify_on_complete = Some(true);
        assert!(!d.is_empty());
        d = SettingsDelta::default();
        d.watched_folder = Some(None); // clear-to-None still counts
        assert!(!d.is_empty());
        d = SettingsDelta::default();
        d.default_add_paused = Some(true);
        assert!(!d.is_empty());
    }

    #[test]
    fn m226_no_fields_appear_in_restart_required() {
        // Negative coverage: toggling each of the 15 M226 fields one at a
        // time must NOT produce any classify_restart_required entries.
        type Mutation = fn(&mut Settings);
        let mutations: [Mutation; 15] = [
            |s| s.notify_on_complete = true,
            |s| s.notify_on_error = true,
            |s| s.on_complete_program = Some(std::path::PathBuf::from("/p")),
            |s| s.use_incomplete_dir = true,
            |s| s.incomplete_dir = Some(std::path::PathBuf::from("/i")),
            |s| s.default_skip_hash_check = true,
            |s| s.incomplete_extension_enabled = false,
            |s| s.watched_folder = Some(std::path::PathBuf::from("/w")),
            |s| s.delete_torrent_after_add = true,
            |s| s.move_completed_enabled = true,
            |s| s.move_completed_to = Some(std::path::PathBuf::from("/m")),
            |s| s.ip_filter_auto_refresh = true,
            |s| s.web_ui_https_enabled = true,
            |s| s.network_interface = Some("eth0".into()),
            |s| s.default_add_paused = true,
        ];
        let old = Settings::default();
        for (idx, m) in mutations.iter().enumerate() {
            let mut new = old.clone();
            m(&mut new);
            let rr = classify_restart_required(&old, &new);
            assert!(
                rr.is_empty(),
                "mutation #{idx}: M226 fields must not surface restart_required, got {rr:?}"
            );
        }
    }

    #[test]
    fn classify_immediate_seed_time_and_inactive_combined() {
        // Both seed-time limits flipped in one delta — both must surface
        // in `immediate`, none in `restart_required`.
        let old = Settings::default();
        let mut new = old.clone();
        new.seed_time_limit_secs = Some(7200);
        new.inactive_seed_time_limit_secs = Some(900);
        let imm = classify_immediate(&old, &new);
        let set: std::collections::HashSet<&str> = imm.iter().copied().collect();
        assert_eq!(
            set,
            ["max_seeding_time", "max_inactive_seeding_time"]
                .into_iter()
                .collect::<std::collections::HashSet<_>>()
        );
        assert_eq!(classify_restart_required(&old, &new), Vec::<&str>::new());
    }

    #[test]
    fn classify_combined_seed_time_and_hashing_both_immediate() {
        // M225: hashing_threads graduated from restart_required to immediate
        // (D-eng-2 revised). With seed_time_limit also immediate, both fields
        // must surface in immediate, none in restart_required.
        let old = Settings::default();
        let mut new = old.clone();
        new.seed_time_limit_secs = Some(1200);
        new.hashing_threads = old.hashing_threads.saturating_add(2);
        let imm = classify_immediate(&old, &new);
        let set: std::collections::HashSet<&str> = imm.iter().copied().collect();
        assert_eq!(
            set,
            ["max_seeding_time", "hashing_threads"]
                .into_iter()
                .collect::<std::collections::HashSet<_>>()
        );
        assert_eq!(classify_restart_required(&old, &new), Vec::<&str>::new());
    }

    #[test]
    fn classify_combined_hashing_and_save_resume_both_immediate() {
        // M225: hashing_threads and save_resume_interval both graduated from
        // restart_required to immediate. Mixed change must land both in
        // immediate, none in restart_required.
        let old = Settings::default();
        let mut new = old.clone();
        new.hashing_threads = old.hashing_threads.saturating_add(3);
        new.save_resume_interval_secs = old.save_resume_interval_secs.saturating_add(120);
        let imm = classify_immediate(&old, &new);
        let set: std::collections::HashSet<&str> = imm.iter().copied().collect();
        assert_eq!(
            set,
            ["hashing_threads", "save_resume_interval"]
                .into_iter()
                .collect::<std::collections::HashSet<_>>()
        );
        assert_eq!(classify_restart_required(&old, &new), Vec::<&str>::new());
    }

    // ── M226: AddTorrentParams.paused: Option<bool> resolution ──────────
    //
    // The constructor default `paused: None` means "honour the engine's
    // `default_add_paused`"; an explicit `.paused(v)` call wraps `Some(v)`
    // and wins over the engine setting. Tests exercise all 4 combinations
    // (3 here + 1 implicit default already covered by existing
    // `pause_resume_via_session` and `add_torrent_with_meta` tests).

    /// Re-bencode a single-piece v1 torrent so the bytes branch of
    /// `add_torrent` can ingest it. Helper avoids dragging
    /// `add_torrent_with_meta` into the M226 tests (that bypasses
    /// `AddTorrentParams` entirely).
    fn m226_make_torrent_bytes(data: &[u8], piece_length: u64) -> Vec<u8> {
        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;
        }

        irontide_bencode::to_bytes(&Torrent {
            info: Info {
                length: data.len() as u64,
                name: "m226-test",
                piece_length,
                pieces: &pieces,
            },
        })
        .unwrap()
    }

    /// M226 D1 acceptance: `default_add_paused = true` + caller passes no
    /// explicit `.paused(...)` → torrent must land paused.
    #[tokio::test]
    async fn add_torrent_with_default_add_paused_true_pauses_torrent() {
        let mut settings = test_settings();
        settings.default_add_paused = true;
        let session = SessionHandle::start(settings).await.unwrap();

        let data = vec![0xAB; 16384];
        let bytes = m226_make_torrent_bytes(&data, 16384);
        let info_hash = session
            .add_torrent(AddTorrentParams::bytes(bytes))
            .await
            .unwrap();

        // Pause is dispatched via `tokio::spawn(handle.pause())`; give the
        // dispatched task a tick to land before we read state.
        tokio::time::sleep(Duration::from_millis(100)).await;
        let stats = session.torrent_stats(info_hash).await.unwrap();
        assert_eq!(
            stats.state,
            TorrentState::Paused,
            "engine default_add_paused=true must pause the torrent when caller \
             passes AddTorrentParams::bytes() without an explicit .paused(...)"
        );

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

    /// M226 D1 acceptance: explicit `.paused(false)` must beat
    /// `default_add_paused = true` — the engine setting is the fallback,
    /// the per-call override is authoritative.
    #[tokio::test]
    async fn add_torrent_with_explicit_paused_false_resumes_despite_default() {
        let mut settings = test_settings();
        settings.default_add_paused = true;
        let session = SessionHandle::start(settings).await.unwrap();

        let data = vec![0xCD; 16384];
        let bytes = m226_make_torrent_bytes(&data, 16384);
        let info_hash = session
            .add_torrent(AddTorrentParams::bytes(bytes).paused(false))
            .await
            .unwrap();

        // Negative assertion: nothing should run a paused dispatch path —
        // a brief sleep guards against a phantom spawned pause.
        tokio::time::sleep(Duration::from_millis(100)).await;
        let stats = session.torrent_stats(info_hash).await.unwrap();
        assert_ne!(
            stats.state,
            TorrentState::Paused,
            "explicit .paused(false) must override default_add_paused=true; \
             got state={:?}",
            stats.state
        );

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

    /// M226 D1 acceptance: explicit `.paused(true)` must beat
    /// `default_add_paused = false` — mirror image of the previous test
    /// to cover the other direction of "explicit wins over default".
    #[tokio::test]
    async fn add_torrent_with_explicit_paused_true_pauses_despite_default_false() {
        let mut settings = test_settings();
        settings.default_add_paused = false;
        let session = SessionHandle::start(settings).await.unwrap();

        let data = vec![0xEF; 16384];
        let bytes = m226_make_torrent_bytes(&data, 16384);
        let info_hash = session
            .add_torrent(AddTorrentParams::bytes(bytes).paused(true))
            .await
            .unwrap();

        tokio::time::sleep(Duration::from_millis(100)).await;
        let stats = session.torrent_stats(info_hash).await.unwrap();
        assert_eq!(
            stats.state,
            TorrentState::Paused,
            "explicit .paused(true) must pause even when \
             default_add_paused=false"
        );

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