zc2 0.0.29

//! HTTP server for the broker API using tiny_http.
//! Request handling runs on separated threads (async_exec) so the server stays responsive.

use std::io::Read;
use std::net::SocketAddr;
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use std::sync::Arc;
use std::thread;
use std::time::Instant;

use crate::async_exec;

use chrono::Local;
use colored::Colorize;
use serde::{Deserialize, Serialize};
use tiny_http::{Header, Method};

use super::http_adapter::{BrokerRequest, BrokerResponse};
use super::{
    discovery::{detect_discovery_mode, Discovery, DiscoveryMode},
    flush::BufferedTransaction,
    ledger, node_identity,
    peer::{self, Authority},
    recovery,
    router::{ResourceRequirements, RoutingDecision},
    stats::{StatsResponse, TaskOfferRecord, TransactionRecord, TransactionStatus, WorkerStats},
    task_board,
    wal::{WalEntry, WalStatus},
    worker::{self, ModelResolveError, Worker, WorkerHeartbeat, WorkerRegistration, WorkerStatus},
    BrokerConfig, BrokerState,
};
use crate::model_uri::parse_model_uri;

/// Global request counter for transaction IDs
static REQUEST_COUNTER: AtomicU64 = AtomicU64::new(0);

/// TTL for a two-phase peer offer reserved but not yet committed/cancelled.
/// Past this, the background sweep releases the held worker slot.
const PENDING_OFFER_TTL_SECS: u64 = 10;

/// Build a `(name, value)` header pair, falling back to a safe marker header
/// when the name/value bytes would be rejected by HTTP header validation (e.g.
/// peer-supplied worker names containing CR/LF/NUL). Never panics on
/// attacker-controlled data — the returned pair is always safe to emit.
fn header_or(name: &str, value: &str) -> (String, String) {
    // Reuse tiny_http's validation: if it accepts the bytes, the pair is safe;
    // otherwise fall back to the inert marker header.
    if Header::from_bytes(name.as_bytes(), value.as_bytes()).is_ok() {
        (name.to_string(), value.to_string())
    } else {
        ("X-Zakuro-Invalid".to_string(), "1".to_string())
    }
}

/// Clamp a computed charge to [0, reserved]: a non-finite or negative computed
/// value charges nothing; an over-large value is capped at what was reserved,
/// so a timeout (charged on elapsed time) can never bill more than was held.
fn capped_charge(computed: f64, reserved: f64) -> f64 {
    if computed.is_finite() {
        computed.clamp(0.0, reserved.max(0.0))
    } else {
        0.0
    }
}

/// Format credits with color based on amount
fn format_credits(amount: f64) -> String {
    if amount >= 1.0 {
        format!("{:.4}", amount).green().to_string()
    } else if amount >= 0.01 {
        format!("{:.4}", amount).yellow().to_string()
    } else {
        format!("{:.6}", amount).cyan().to_string()
    }
}

/// Log a transaction in live mode and record to stats
#[allow(clippy::too_many_arguments)]
fn log_transaction(
    state: &Arc<BrokerState>,
    verbose: bool,
    tx_num: u64,
    user: &str,
    action: &str,
    cost: f64,
    balance: f64,
    worker: Option<&str>,
    duration_ms: f64,
    status: &str,
) {
    log_transaction_with_worker_info(
        state,
        verbose,
        tx_num,
        user,
        action,
        cost,
        balance,
        worker,
        duration_ms,
        status,
        None,
        None,
        None,
        None,
        None,
    );
}

/// Log a transaction with optional request_id (for trace), price, and worker identity
#[allow(clippy::too_many_arguments)]
fn log_transaction_with_worker_info(
    state: &Arc<BrokerState>,
    verbose: bool,
    tx_num: u64,
    user: &str,
    action: &str,
    cost: f64,
    balance: f64,
    worker: Option<&str>,
    duration_ms: f64,
    status: &str,
    price_per_hour: Option<f64>,
    owner_id: Option<&str>,
    worker_pid: Option<&str>,
    worker_ip: Option<&str>,
    request_id: Option<&str>,
) {
    let now = Local::now();

    let tx_status = match status {
        "OK" => TransactionStatus::Ok,
        "FAIL" => TransactionStatus::Fail,
        "PENDING" => TransactionStatus::Pending,
        _ => TransactionStatus::Pending,
    };

    let record = TransactionRecord {
        tx_num,
        timestamp: now,
        user_id: user.to_string(),
        action: action.to_string(),
        cost,
        balance,
        worker: worker.map(|s| s.to_string()),
        duration_ms,
        status: tx_status,
        price_per_hour,
        owner_id: owner_id.map(|s| s.to_string()),
        worker_pid: worker_pid.map(|s| s.to_string()),
        worker_ip: worker_ip.map(|s| s.to_string()),
        request_id: request_id.map(|s| s.to_string()),
    };
    state.stats.record_transaction(record);

    // Console logging (verbose mode only)
    if !verbose {
        return;
    }

    let time_str = now.format("%H:%M:%S").to_string();

    let status_icon = match status {
        "OK" => "✓".green(),
        "FAIL" => "✗".red(),
        "PENDING" => "⋯".yellow(),
        _ => "•".white(),
    };

    let worker_str = worker
        .map(|w| format!(" → {}", w.cyan()))
        .unwrap_or_default();

    println!(
        "  {} {} #{:<4} {:>12} {:>8}  cost:{} bal:{} {:>6.1}ms{}",
        time_str.dimmed(),
        status_icon,
        tx_num,
        user.blue(),
        action.bold(),
        format_credits(cost),
        format_credits(balance),
        duration_ms,
        worker_str,
    );
}

/// Worker list response
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct WorkerListResponse {
    pub workers: Vec<WorkerInfo>,
    pub total: usize,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct WorkerInfo {
    pub id: String,
    pub name: String,
    pub uri: String,
    pub worker_type: String,
    pub status: String,
    pub cpus_available: f64,
    pub cpus_total: f64,
    pub memory_available_gib: f64,
    pub memory_total_gib: f64,
    pub gpus_available: u32,
    pub gpus_total: u32,
    pub price_per_hour: f64,
    pub min_charge: f64,
    pub active_requests: u32,
    pub avg_latency_ms: f64,
    pub max_timeout_secs: f64,
    pub gpu_model: Option<String>,
    pub gpu_vram_gb: Option<u32>,
    pub cpu_model: Option<String>,
    pub storage_gb: Option<u32>,
    // Time-windowed request counts
    pub requests_5h: u64,
    pub requests_1w: u64,
    pub requests_1m: u64,
    // Quota limits (0 = unlimited)
    pub quota_5h: u64,
    pub quota_1w: u64,
    pub quota_1m: u64,
    pub wireguard_ip: Option<String>,
    pub is_docker: Option<bool>,
    /// Owning node's zc:// handle (`zc://node-…`). Present on client-facing responses.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub node: Option<String>,
    /// Whether this worker serves a fixed model catalog or any model. Carried
    /// on /peer/workers so a peer broker can rebuild its model index for this
    /// provider (zc#172: without these three fields the index stayed per-pod).
    #[serde(default)]
    pub provider_type: worker::ProviderType,
    /// Model uuids this worker serves (`["*"]` for a general provider).
    #[serde(default)]
    pub served_models: Vec<String>,
    /// Price per 1,000,000 tokens for model inference, in credits.
    #[serde(default)]
    pub price_per_mtok: f64,
    /// Display name, carried alongside the opaque key-derived `uri`/`node` handles.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub label: Option<String>,
}

/// Price estimate response
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PriceEstimateResponse {
    pub min_cost: f64,
    pub max_cost: f64,
    pub matching_workers: usize,
}

/// Credit balance response
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CreditBalanceResponse {
    pub user_id: String,
    pub balance: f64,
    pub total_spent: f64,
    pub rate_limit: u32,
    pub rate_limit_per_second: Option<u32>,
    pub rate_limit_per_day: Option<u32>,
    pub rate_limit_per_month: Option<u32>,
}

#[derive(Debug, Serialize)]
struct ErrorResponse {
    error: String,
    code: String,
}

#[derive(Debug, Deserialize)]
struct AddCreditsRequest {
    amount: f64,
    #[serde(default)]
    description: Option<String>,
}

fn json_response<T: Serialize>(data: &T, status: u16) -> BrokerResponse {
    let body = serde_json::to_vec(data).unwrap_or_default();
    BrokerResponse::json_bytes(body, status)
}

fn error_response(error: &str, code: &str, status: u16) -> BrokerResponse {
    json_response(
        &ErrorResponse {
            error: error.to_string(),
            code: code.to_string(),
        },
        status,
    )
}

/// Send a task offer to a peer over QUIC using its advertised QUIC port.
fn quic_offer(
    qt: &std::sync::Arc<super::quic::QuicTransport>,
    peer_http_url: &str,
    quic_port: u16,
    offer: &task_board::TaskOffer,
) -> Result<task_board::TaskResult, String> {
    let url_trimmed = peer_http_url
        .trim_start_matches("http://")
        .trim_start_matches("https://");
    let host = url_trimmed.split(':').next().unwrap_or("127.0.0.1");

    // On loopback, connect via 127.0.0.1 because Linux rewrites source IPs
    let connect_host = if host.starts_with("127.") {
        "127.0.0.1"
    } else {
        host
    };

    let addr: SocketAddr = format!("{}:{}", connect_host, quic_port)
        .parse()
        .map_err(|e| format!("bad quic addr: {}", e))?;
    qt.offer_task(addr, offer)
}

/// Maximum accepted request-body size for synchronous HTTP endpoints.
/// Shared with the transport adapters so an over-cap body produces the
/// identical 413 regardless of frontend.
use super::http_adapter::MAX_BODY_BYTES;

/// Body access with the `MAX_BODY_BYTES` cap. The body is pre-read into
/// `BrokerRequest` by the transport adapter; this enforces the size cap,
/// returning a ready-to-send 413 when the body exceeds it.
fn body_or_413(req: &BrokerRequest) -> Result<&[u8], BrokerResponse> {
    if req.body.len() > MAX_BODY_BYTES {
        Err(error_response(
            "Request body too large",
            "PAYLOAD_TOO_LARGE",
            413,
        ))
    } else {
        Ok(&req.body)
    }
}

/// Authenticate via Bearer token. Returns zakuro_user_id (or "admin" for master key).
fn authenticate_bearer(
    request: &BrokerRequest,
    state: &BrokerState,
) -> Result<String, BrokerResponse> {
    match request.header("Authorization") {
        Some(auth) => match auth.strip_prefix("Bearer ") {
            Some(token) => state
                .ledger
                .resolve_user_from_api_key(token)
                .map_err(|e| error_response(&e.to_string(), "UNAUTHORIZED", 401)),
            None => Err(error_response(
                "Invalid Authorization header",
                "UNAUTHORIZED",
                401,
            )),
        },
        None => Err(error_response(
            "Authorization required. Set Authorization: Bearer <key>",
            "UNAUTHORIZED",
            401,
        )),
    }
}

/// Verify worker key header. Returns true if no key is configured OR the key matches.
fn verify_worker_key(request: &BrokerRequest, state: &BrokerState) -> bool {
    match &state.config.worker_key {
        None => true, // No key configured — allow (local dev)
        Some(expected) => request
            .header("X-Worker-Key")
            .map(|k| k == *expected)
            .unwrap_or(false),
    }
}

/// Key-derived node handle for this broker's own node: `zc://node-{fingerprint}`.
/// The `label` (e.g. hostname) is display-only and never part of the identity.
fn node_handle_for(key: &super::node_identity::NodeKey, _label: Option<&str>) -> String {
    key.node_uri()
}

fn worker_to_info(
    w: &worker::Worker,
    registry: &worker::WorkerRegistry,
    node_key: &super::node_identity::NodeKey,
    client_facing: bool,
) -> WorkerInfo {
    use chrono::Duration as CDuration;
    let reqs_5h = registry.requests_in_window(&w.id, CDuration::hours(5));
    let reqs_1w = registry.requests_in_window(&w.id, CDuration::weeks(1));
    let reqs_1m = registry.requests_in_window(&w.id, CDuration::days(30));
    let quotas = registry.get_quotas(&w.id);
    // Node handle: a peer worker carries its source node; a local worker belongs
    // to this broker's node. Always a key-derived zc:// handle, never an IP or
    // hostname — the hostname (if any) only ever appears in `label`.
    let bare = |n: &str| n.strip_prefix("node-").unwrap_or(n).to_string();
    let node = Some(match &w.source_node {
        Some(n) => format!("zc://node-{}", bare(n)),
        None => node_handle_for(node_key, Some(&super::node_name_or_default())),
    });
    // Client-facing surfaces are IP-free: opaque zc:// uri, no wireguard_ip. The
    // peer channel keeps the real uri so peers can route.
    let (uri, wireguard_ip) = if client_facing {
        (w.zc_uri(), None)
    } else {
        (w.uri.clone(), w.wireguard_ip.clone())
    };
    WorkerInfo {
        id: w.id.clone(),
        name: w.name.clone(),
        uri,
        worker_type: w.worker_type.clone(),
        status: format!("{:?}", w.status).to_lowercase(),
        cpus_available: w.resources.cpus_available,
        cpus_total: w.resources.cpus_total,
        memory_available_gib: w.resources.memory_available as f64 / (1024.0 * 1024.0 * 1024.0),
        memory_total_gib: w.resources.memory_total as f64 / (1024.0 * 1024.0 * 1024.0),
        gpus_available: w.resources.gpus_available,
        gpus_total: w.resources.gpus_total,
        price_per_hour: w.pricing.price_per_hour,
        min_charge: w.pricing.min_charge,
        active_requests: w.active_requests,
        avg_latency_ms: w.avg_latency_ms,
        max_timeout_secs: w.max_timeout_secs,
        gpu_model: w.hardware.gpu_model.clone(),
        gpu_vram_gb: w.hardware.gpu_vram_gb,
        cpu_model: w.hardware.cpu_model.clone(),
        storage_gb: w.hardware.storage_gb,
        requests_5h: reqs_5h,
        requests_1w: reqs_1w,
        requests_1m: reqs_1m,
        quota_5h: quotas.per_5h,
        quota_1w: quotas.per_week,
        quota_1m: quotas.per_month,
        wireguard_ip,
        is_docker: w.is_docker,
        node,
        provider_type: w.provider_type,
        served_models: w.served_models.clone(),
        price_per_mtok: w.price_per_mtok,
        label: Some(w.name.clone()),
    }
}

/// Build this node's advertised endpoint from its mesh IP and bound port.
pub(crate) fn mesh_endpoint_for(mesh_ip: Option<String>, port: u16) -> Option<String> {
    mesh_ip.map(|ip| format!("{ip}:{port}"))
}

/// How often the node-sync tick's "no mesh endpoint" line may repeat while
/// the condition persists (it does not rate-limit the initial transition,
/// which always logs).
const NO_MESH_ENDPOINT_LOG_INTERVAL_SECS: u64 = 30 * 60;

/// What [`MeshEndpointLogGate::on_tick`] says to do this tick.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum MeshEndpointLogAction {
    /// Nothing changed worth logging.
    None,
    /// No mesh endpoint this tick, and it's either a fresh transition or the
    /// rate-limit interval has elapsed — log loudly (error-ish, `eprintln!`).
    NoEndpoint,
    /// A mesh endpoint just reappeared after an absence — log a recovery
    /// line (info-ish, `println!`).
    Recovered,
}

/// Rate-limits the node-sync tick's "no mesh endpoint" log line.
///
/// The tick this feeds runs every 12 ticks (5s default interval) = every
/// ~60s, so an unconditional log there — Fix 1's failure mode when a broker
/// never gets a tunnel — fires forever, unrate-limited, straight to stderr:
/// a paging hazard if stderr is scraped. This keeps it loud on the
/// transition into/out of the no-endpoint state, then at most once every
/// [`NO_MESH_ENDPOINT_LOG_INTERVAL_SECS`] while it persists.
///
/// `/health`'s `mesh_tunnel` field is unaffected — it re-probes the mesh IP
/// on every request and stays the machine-readable signal regardless of this
/// gate's log suppression.
pub(crate) struct MeshEndpointLogGate {
    had_endpoint: AtomicBool,
    last_no_endpoint_log_secs: AtomicU64,
}

impl MeshEndpointLogGate {
    pub(crate) const fn new() -> Self {
        Self {
            // Optimistic default: a broker that has a tunnel from its very
            // first tick must not log a bogus "Recovered" line, so the
            // "previous" state is "had one".
            had_endpoint: AtomicBool::new(true),
            last_no_endpoint_log_secs: AtomicU64::new(0),
        }
    }

    /// Call once per node-sync tick with whether this tick has a mesh
    /// endpoint and the current unix time (injectable so tests don't depend
    /// on wall-clock timing).
    pub(crate) fn on_tick(&self, has_endpoint: bool, now_secs: u64) -> MeshEndpointLogAction {
        let had_before = self.had_endpoint.swap(has_endpoint, Ordering::SeqCst);
        if has_endpoint {
            return if had_before {
                MeshEndpointLogAction::None
            } else {
                MeshEndpointLogAction::Recovered
            };
        }
        if had_before {
            // Fresh transition into the no-endpoint state: always loud.
            self.last_no_endpoint_log_secs
                .store(now_secs, Ordering::SeqCst);
            return MeshEndpointLogAction::NoEndpoint;
        }
        let last = self.last_no_endpoint_log_secs.load(Ordering::SeqCst);
        if now_secs.saturating_sub(last) >= NO_MESH_ENDPOINT_LOG_INTERVAL_SECS {
            self.last_no_endpoint_log_secs
                .store(now_secs, Ordering::SeqCst);
            MeshEndpointLogAction::NoEndpoint
        } else {
            MeshEndpointLogAction::None
        }
    }
}

static MESH_ENDPOINT_LOG_GATE: MeshEndpointLogGate = MeshEndpointLogGate::new();

/// One peer the roster says this broker should dial: its key-derived
/// fingerprint plus the `http://`-prefixed base URL to reach it at.
///
/// The fingerprint travels WITH the URL because identity, not address, is
/// what the caller must reason about: the same physical broker is spelled
/// `http://zc-broker-1.zc-broker...:9000` by `ZAKURO_PEERS` and
/// `http://10.13.13.7:9000` by the roster, and only the fingerprint reveals
/// that those are one broker rather than two.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct RosterPeer {
    /// Bare 16-hex-char fingerprint of the node's public key.
    pub fp: String,
    /// `http://ip:port` base URL, the spelling `PeerManager` registers under.
    pub url: String,
}

/// Turn a roster snapshot into the peers the node-sync tick loop should dial.
///
/// Non-revoked entries only, resolved to their advertised endpoint via
/// `endpoint_for_fingerprint` (which itself already excludes revoked nodes —
/// the `!revoked` filter here is a harmless, deliberately-kept double guard),
/// and empty/whitespace-only endpoints dropped so a malformed roster entry
/// never turns into a garbage `"http://"` peer.
///
/// # Excluding self
///
/// The primary self-filter is on IDENTITY: any roster row whose pubkey — or
/// whose pubkey's fingerprint — is this node's own is dropped, via
/// `self_pubkey`.
///
/// It must be identity-based, because the address-based filter fails in
/// precisely the case that matters. `self_endpoint` is derived from
/// `mesh_ip()`, so it is `None` exactly when this node's tunnel is down; but
/// registration deliberately treats an omitted endpoint as "unchanged", so
/// this node's own STALE endpoint is still sitting on the roster during that
/// flap. The address filter therefore switched itself off at the one moment
/// it had something to filter, and the broker registered itself as its own
/// peer: a self-dialing PeerClient, self health-checks, and a `zc brokers`
/// listing containing itself.
///
/// `self_endpoint` is still honoured as a second, belt-and-braces guard — it
/// costs nothing and covers a node whose roster row is somehow keyed by a
/// pubkey this process does not recognise as its own.
pub(crate) fn roster_peer_entries(
    cache: &super::roster_cache::RosterCache,
    self_pubkey: Option<&str>,
    self_endpoint: Option<&str>,
) -> Vec<RosterPeer> {
    let self_fp = self_pubkey.and_then(super::node_identity::fingerprint_of_pubkey_b64);
    cache
        .entries()
        .iter()
        .filter(|(_, revoked)| !revoked)
        // Identity self-filter (primary), on both the pubkey and its
        // fingerprint, independent of tunnel state.
        .filter(|(pk, _)| Some(pk.as_str()) != self_pubkey)
        .filter_map(|(pk, _)| {
            let fp = super::node_identity::fingerprint_of_pubkey_b64(pk)?;
            if self_fp.as_deref() == Some(fp.as_str()) {
                return None;
            }
            let addr = cache.endpoint_for_fingerprint(&fp)?;
            Some((fp, addr))
        })
        // Address self-filter (secondary), on the bare "ip:port" form that
        // `mesh_endpoint_for` produced for `self_endpoint`.
        .filter(|(_, addr)| Some(addr.as_str()) != self_endpoint)
        .filter(|(_, addr)| !addr.trim().is_empty())
        .map(|(fp, addr)| {
            let url = if addr.contains("://") {
                addr
            } else {
                format!("http://{addr}")
            };
            RosterPeer { fp, url }
        })
        .collect()
}

pub fn handle(state: Arc<BrokerState>, req: &BrokerRequest, verbose: bool) -> BrokerResponse {
    // Reconstruct the full request target (path + query) so the existing
    // string-based route matching (e.g. `/stats?user=`, `/peer/balance?...`)
    // behaves exactly as it did against tiny_http's `request.url()`.
    let path = if req.query.is_empty() {
        req.path.clone()
    } else {
        format!("{}?{}", req.path, req.query)
    };
    let method = req.method.clone();

    let response = match (method, path.as_str()) {
        // Deployment-reconciler reverse proxy: ANY method, `/serve/:id/*path`.
        // Matched by prefix (not an exact path) since the tail is arbitrary —
        // see `deploy::serve::parse_serve_path`. Kept ahead of every other
        // arm below since none of them use this prefix, so ordering here is
        // just for readability, not correctness.
        (_, p) if p.starts_with("/serve/") => super::deploy::serve::handle_serve(&state, req),

        // Health check
        (Method::Get, "/health") => {
            // Re-probe the WireGuard mesh IP on every health check (the tunnel may
            // come up after startup). WireGuard is decommissioned; mesh = 10.13.13.0/24.
            //
            // Fix E: `wireguard_connected` and `mesh_tunnel` are two renderings
            // of THIS ONE value, never two independent probes. They used to be
            // computed from two different detectors -- `discovery::get_mesh_ip()`
            // here and `vpn::native::mesh_ip()` below -- which disagreed in
            // exactly the container this endpoint is scraped in, so /health
            // contradicted itself. Fix A made those detectors the same function;
            // sharing the resolved value here makes the contradiction
            // structurally impossible rather than merely unlikely, including via
            // the `own_wireguard_ip` fallback (which `mesh_tunnel` never saw).
            let live_ts_ip =
                super::discovery::get_mesh_ip().or_else(|| state.own_wireguard_ip.clone());
            let ts_connected = live_ts_ip
                .as_ref()
                .map(|ip| ip.starts_with("10.13.13."))
                .unwrap_or(false);
            // Client body is IP-free: report connectivity as a bool, never the
            // raw mesh IP. `node_name` may stay — display label only, never
            // used for resolution/routing.
            json_response(
                &serde_json::json!({
                    "status": "healthy",
                    "service": "zakuro-broker",
                    "wireguard_connected": ts_connected,
                    "node_name": state.config.node_name,
                    // Key-derived identity (not an address): lets `zc://node-<fp>`
                    // resolve against a local broker by id, and `zc brokers`
                    // recognise this machine's own broker in the directory.
                    "node_id": state.node_key.node_uri(),
                    "mesh_tunnel": if ts_connected { "up" } else { "down" },
                }),
                200,
            )
        }

        // Stats endpoint (supports ?user= filter)
        (Method::Get, path) if path == "/stats" || path.starts_with("/stats?") => {
            // Require Bearer auth
            match authenticate_bearer(req, &state) {
                Err(resp) => resp,
                Ok(caller) => {
                    let is_admin = caller == "admin";

                    // Parse ?user= query parameter
                    let mut user_filter: Option<String> = path.find('?').and_then(|qpos| {
                        let query = &path[qpos + 1..];
                        query
                            .split('&')
                            .find(|p| p.starts_with("user="))
                            .map(|p| p[5..].to_string())
                    });

                    // Non-admin callers can only see their own transactions
                    if !is_admin {
                        user_filter = Some(caller.clone());
                    }

                    let workers = state.workers.list();
                    let active = workers
                        .iter()
                        .filter(|w| w.status == WorkerStatus::Healthy)
                        .count();

                    let worker_stats: Vec<WorkerStats> = workers
                        .iter()
                        .map(|w| WorkerStats {
                            id: w.id.clone(),
                            name: w.name.clone(),
                            // Client-facing: key-derived zc:// uri, never the raw
                            // mesh uri (which leaks the 10.13.13.x IP).
                            uri: w.zc_uri(),
                            status: format!("{:?}", w.status).to_lowercase(),
                            cpus_available: w.resources.cpus_available,
                            memory_available_gib: w.resources.memory_available as f64
                                / (1024.0 * 1024.0 * 1024.0),
                            gpus_available: w.resources.gpus_available,
                            price_per_hour: w.pricing.price_per_hour,
                            active_requests: w.active_requests,
                            avg_latency_ms: w.avg_latency_ms,
                        })
                        .collect();

                    // Connectivity is reported as a bool only; the raw mesh IP
                    // (10.13.13.x) is never placed in the client-facing body.
                    let wireguard_connected = state.own_wireguard_ip.is_some();
                    let metrics = state.stats.metrics(
                        active,
                        workers.len(),
                        state.is_local_mode(),
                        state.is_billing_enabled(),
                        None,
                    );

                    let mut transactions = state.stats.recent_transactions(50);
                    if let Some(ref uid) = user_filter {
                        transactions.retain(|tx| tx.user_id == *uid);
                    }

                    let stats_resp = StatsResponse {
                        host: state.config.host.clone(),
                        port: state.config.port,
                        transactions,
                        task_offers: state.stats.recent_task_offers(30),
                        workers: worker_stats,
                        metrics,
                        rps_history: state.stats.rps_history(),
                        wireguard_ip: None,
                        wireguard_connected,
                    };

                    json_response(&stats_resp, 200)
                }
            }
        }

        // List workers
        (Method::Get, path) if path == "/workers" || path.starts_with("/workers?") => {
            // Optional `?node=zc://node-{fingerprint}` (or bare `node-{fingerprint}`)
            // filter. Resolved by fingerprint only (node_identity::fp_matches_node_arg) —
            // a hostname/label never matches, even if it happens to look like a handle.
            let node_filter = req.query.split('&').find_map(|kv| kv.strip_prefix("node="));
            // A reserved P2P offer counts as activity until its commit runs:
            // the local agent reads this count before stopping a draining worker.
            let reserved = pending_reservations(&state);
            let infos: Vec<WorkerInfo> = state
                .workers
                .list()
                .iter()
                .map(|w| {
                    let mut info = worker_to_info(w, &state.workers, &state.node_key, true);
                    info.active_requests += reserved.get(&w.id).copied().unwrap_or(0);
                    info
                })
                .filter(|wi| {
                    node_filter.is_none_or(|nf| {
                        wi.node.as_deref().is_some_and(|n| {
                            node_identity::fp_matches_node_arg(node_identity::strip_node_arg(n), nf)
                        })
                    })
                })
                .collect();

            json_response(
                &WorkerListResponse {
                    total: infos.len(),
                    workers: infos,
                },
                200,
            )
        }

        // Register worker (requires worker key when configured)
        (Method::Post, "/workers") => {
            if !verify_worker_key(req, &state) {
                error_response(
                    "Worker key required. Set X-Worker-Key header",
                    "UNAUTHORIZED",
                    401,
                )
            } else {
                match body_or_413(req) {
                    Err(resp) => resp,
                    Ok(body) => match serde_json::from_slice::<WorkerRegistration>(body) {
                        Ok(registration) => {
                            if registration.pricing.price_per_hour < 0.0 {
                                error_response("price_per_hour must be >= 0", "BAD_REQUEST", 400)
                            } else {
                                println!(
                                    "  [BROKER] Registering worker: {} at {}",
                                    registration.name, registration.uri
                                );
                                let mut worker = state.workers.register(registration);
                                // Locally-registered workers (no source_node) belong to
                                // this broker's node: stamp its key-derived fingerprint
                                // so worker.zc_uri() is `zc://worker-{node_fp}-{slot}`.
                                if worker.source_node.is_none() {
                                    if let Some(updated) = state
                                        .workers
                                        .set_node_fp(&worker.id, &state.node_key.fingerprint())
                                    {
                                        worker = updated;
                                    }
                                }

                                // Sync worker immediately (don't wait for periodic sync)
                                if let Some(ref owner_id) = state.config.owner_user_id {
                                    let node_name = state.config.node_name.as_deref();
                                    let node_pubkey = state.node_key.public_b64();

                                    // Prefer API sync if configured
                                    if let (Some(ref api_url), Some(ref api_key)) =
                                        (&state.config.api_url, &state.config.api_key)
                                    {
                                        match super::ledger::Ledger::sync_workers_via_api(
                                            owner_id,
                                            std::slice::from_ref(&worker),
                                            api_url,
                                            api_key,
                                            node_name,
                                            state.own_wireguard_ip.as_deref(),
                                            Some(node_pubkey.as_str()),
                                        ) {
                                            Ok(outcome) => {
                                                state.workers.apply_hub_prices(&outcome.prices);
                                                println!("  [WORKER_SYNC] Worker {} synced to dashboard via API", worker.name)
                                            }
                                            Err(e) => {
                                                eprintln!(
                                                    "  [WORKER_SYNC] API sync failed for {}: {}",
                                                    worker.name, e
                                                );
                                            }
                                        }
                                    }
                                }
                                json_response(&worker, 201)
                            } // else
                        }
                        Err(e) => {
                            error_response(&format!("Invalid request: {}", e), "BAD_REQUEST", 400)
                        }
                    },
                }
            }
        }

        // Worker heartbeat (requires worker key when configured)
        (Method::Post, "/workers/heartbeat") => {
            if !verify_worker_key(req, &state) {
                error_response(
                    "Worker key required. Set X-Worker-Key header",
                    "UNAUTHORIZED",
                    401,
                )
            } else {
                match body_or_413(req) {
                    Err(resp) => resp,
                    Ok(body) => match serde_json::from_slice::<WorkerHeartbeat>(body) {
                        Ok(heartbeat) => match state.workers.heartbeat(heartbeat) {
                            Some(worker) => json_response(
                                &serde_json::json!({"status": "ok", "worker_id": worker.id}),
                                200,
                            ),
                            None => error_response("Worker not found", "NOT_FOUND", 404),
                        },
                        Err(e) => {
                            error_response(&format!("Invalid request: {}", e), "BAD_REQUEST", 400)
                        }
                    },
                }
            }
        }

        // Price estimation
        (Method::Post, "/price") => match body_or_413(req) {
            Err(resp) => resp,
            Ok(body) => match serde_json::from_slice::<ResourceRequirements>(body) {
                Ok(requirements) => {
                    match state.router.estimate_cost(&state.workers, &requirements) {
                        Some((min_cost, max_cost)) => {
                            let matching =
                                state.router.list_matching(&state.workers, &requirements);
                            json_response(
                                &PriceEstimateResponse {
                                    min_cost,
                                    max_cost,
                                    matching_workers: matching.len(),
                                },
                                200,
                            )
                        }
                        None => error_response("No workers available", "NO_CAPACITY", 503),
                    }
                }
                Err(e) => error_response(&format!("Invalid request: {}", e), "BAD_REQUEST", 400),
            },
        },

        // Peer list — this node's known peers, for transitive network discovery.
        // Unauthenticated (topology only, no secrets): crawl a node, get its
        // peers, recurse to map the whole mesh.
        (Method::Get, "/peers") => {
            // Topology is sensitive: gate with the same handshake auth as
            // /peer/health|identity — a configured peer key is required;
            // keyless brokers still answer from loopback for local discovery
            // (audit M4: was unauthenticated reconnaissance).
            //
            // IP-free: like /brokers, this must never expose peer_url/IP or
            // this node's hostname to a client-facing caller — the auth gate
            // here (peer_handshake_auth) is a shared-secret/loopback check,
            // not true peer identity auth, so this endpoint is effectively
            // client-reachable. Peer entries and self are both reduced to
            // key-derived `zc://node-<fp>` ids via the same PeerManager
            // fingerprint cache that handle_brokers uses.
            match peer_handshake_auth(&state, req) {
                Some(resp) => resp,
                None => {
                    state.peer_manager.ensure_fingerprints_cached();

                    let mut peer_urls = state.peer_manager.peer_urls();
                    peer_urls.sort();

                    let peers: Vec<String> = peer_urls
                        .into_iter()
                        .filter_map(|url| state.peer_manager.peer_fingerprint(&url))
                        .collect();

                    json_response(
                        &serde_json::json!({
                            "node": state.node_key.node_uri(),
                            "p2p_enabled": state.peer_manager.is_enabled(),
                            "peers": peers,
                            "total": peers.len(),
                        }),
                        200,
                    )
                }
            }
        }

        // Brokers list — client-facing, IP-free primitive: "which brokers
        // does this node talk to". Unauthenticated (identity only, no
        // secrets, no IPs — same threat model as /peers' topology, but with
        // the peer_url/IP redacted down to a key-derived id).
        (Method::Get, "/brokers") => handle_brokers(&state),

        // Broker-advertised price `P` (credits/hour). GET is client-facing
        // (IP-free, no secrets). Note: `POST /price` is already taken by the
        // pre-existing cost-estimation endpoint below (takes
        // `ResourceRequirements`, unrelated to this broker's own price), so
        // the setter lives at `POST /price/set` to avoid colliding with it.
        // Gated loopback-only so a remote peer can never set this broker's
        // price for it.
        (Method::Get, "/price") => handle_get_price(&state),

        (Method::Post, "/price/set") => handle_set_price(&state, req),

        // --- Peer-to-peer broker endpoints (authenticated via X-Peer-Key) ---
        (Method::Get, "/peer/health") => handle_peer_health(&state, req),

        (Method::Get, "/peer/workers") => handle_peer_workers(&state, req),

        // Signed full-set peer gossip — roster-gated (see handle_peer_peers).
        (Method::Get, "/peer/peers") => handle_peer_peers(&state, req),

        // Signed price+resources advertisement — roster-gated (see handle_peer_advert).
        (Method::Get, "/peer/advert") => handle_peer_advert(&state, req),

        (Method::Post, "/peer/reserve") => handle_peer_reserve(state.clone(), req),

        (Method::Post, "/peer/commit") => handle_peer_commit(state.clone(), req),

        (Method::Post, "/peer/cancel") => handle_peer_cancel(state.clone(), req),

        (Method::Get, p) if p.starts_with("/peer/balance") => handle_peer_balance(&state, req),

        (Method::Post, "/peer/earn") => handle_peer_earn(state.clone(), req),

        // Peer identity — handshake endpoint
        (Method::Get, "/peer/identity") => handle_peer_identity(&state, req),

        // Peer task offer — publish-lock execution
        (Method::Post, "/peer/tasks/offer") => handle_peer_task_offer(state.clone(), req),
        (Method::Post, "/peer/tasks/commit") => handle_peer_task_commit(state.clone(), req),
        (Method::Post, "/peer/tasks/cancel") => handle_peer_task_cancel(state.clone(), req),

        // Model inference - forward a one-shot OpenAI chat completion to a resolved provider
        (Method::Post, "/infer") => handle_infer(&state, req),

        // Execute - main entry point
        (Method::Post, "/execute") => handle_execute(state, req, verbose),

        // List active instances (admin only)
        (Method::Get, "/instances") => match authenticate_bearer(req, &state) {
            Err(resp) => resp,
            Ok(caller) if caller != "admin" => {
                error_response("Forbidden: admin only", "FORBIDDEN", 403)
            }
            Ok(_) => {
                let instances: Vec<serde_json::Value> = state
                    .instance_registry
                    .iter()
                    .map(|entry| {
                        serde_json::json!({
                            "instance_id": entry.key().clone(),
                            "worker_id": entry.value().clone(),
                        })
                    })
                    .collect();
                json_response(
                    &serde_json::json!({
                        "instances": instances,
                        "total": instances.len(),
                    }),
                    200,
                )
            }
        },

        // Delete an instance binding (admin only)
        (Method::Delete, path) if path.starts_with("/instances/") => {
            match authenticate_bearer(req, &state) {
                Err(resp) => resp,
                Ok(caller) if caller != "admin" => {
                    error_response("Forbidden: admin only", "FORBIDDEN", 403)
                }
                Ok(_) => {
                    let instance_id = path.trim_start_matches("/instances/");
                    match state.instance_registry.remove(instance_id) {
                        Some(_) => json_response(
                            &serde_json::json!({"status": "ok", "instance_id": instance_id}),
                            200,
                        ),
                        None => error_response("Instance not found", "NOT_FOUND", 404),
                    }
                }
            }
        }

        // Get credits (uses ledger) — requires Bearer, scoped to own user or admin
        (Method::Get, path) if path.starts_with("/credits/") && !path.contains("/add") => {
            match authenticate_bearer(req, &state) {
                Err(resp) => resp,
                Ok(caller) => {
                    let user_id = path.trim_start_matches("/credits/");
                    if caller != "admin" && caller != user_id {
                        error_response("Forbidden: can only view own balance", "FORBIDDEN", 403)
                    } else {
                        let info = state.ledger.get_user_info(user_id);
                        let credits = state.credits.get(info.user_id.as_str());
                        // Use live in-memory balance when available (reflects in-flight deductions)
                        let live_balance =
                            credits.as_ref().map(|c| c.balance).unwrap_or(info.balance);
                        json_response(
                            &serde_json::json!({
                                "user_id": info.user_id,
                                "balance": live_balance,
                                "balance_status": credits.as_ref().map(|c| c.balance_status.as_str()).unwrap_or("authoritative"),
                                "last_prefetched": credits.as_ref().and_then(|c| c.last_prefetched).map(|t| t.to_rfc3339()),
                            }),
                            200,
                        )
                    }
                }
            }
        }

        // Add credits (REQUIRES API KEY - uses ledger)
        (Method::Post, path) if path.starts_with("/credits/") && path.ends_with("/add") => {
            let user_id = path
                .trim_start_matches("/credits/")
                .trim_end_matches("/add");

            // Require API key for adding credits
            if let Some(api_key) = req.header("X-Api-Key") {
                match body_or_413(req) {
                    Err(resp) => resp,
                    Ok(body) => match serde_json::from_slice::<AddCreditsRequest>(body) {
                        Ok(req) => {
                            // In standalone mode (no dashboard API), allow seeding local credits
                            // with the ZAKURO_MASTER_KEY. This enables test environments and
                            // standalone deployments without a dashboard.
                            if state.ledger.is_api_mode() {
                                error_response("Adding credits directly via broker is not supported in API mode. Use the dashboard API.", "NOT_SUPPORTED", 501)
                            } else {
                                // In standalone mode: verify master key from env, or allow any
                                // key when no master key is configured (test/dev environments).
                                let master_key =
                                    std::env::var("ZAKURO_MASTER_KEY").unwrap_or_default();
                                let authorized = master_key.is_empty() || api_key == master_key;
                                if !authorized {
                                    error_response("Invalid master key", "UNAUTHORIZED", 401)
                                } else {
                                    let new_balance = {
                                        let mut entry = state
                                            .ledger
                                            .local_credits
                                            .entry(user_id.to_string())
                                            .or_insert(0.0);
                                        *entry += req.amount;
                                        *entry
                                    };
                                    // Keep authoritative_balances in sync so /me and P2P path
                                    // see the correct balance immediately after adding credits.
                                    state
                                        .ledger
                                        .authoritative_balances
                                        .entry(user_id.to_string())
                                        .and_modify(|b| *b += req.amount)
                                        .or_insert(new_balance);
                                    state.ledger.publish_transaction(
                                        &uuid::Uuid::new_v4().to_string(),
                                        user_id,
                                        "credit",
                                        req.amount,
                                        new_balance,
                                        "",
                                        0.0,
                                        state.config.node_name.as_deref(),
                                    );
                                    json_response(
                                        &serde_json::json!({
                                            "status": "ok",
                                            "new_balance": new_balance,
                                            "ledger": "local"
                                        }),
                                        200,
                                    )
                                }
                            }
                        }
                        Err(e) => {
                            error_response(&format!("Invalid request: {}", e), "BAD_REQUEST", 400)
                        }
                    },
                }
            } else {
                error_response(
                    "API key required. Set X-Api-Key header with ZAKURO_MASTER_KEY",
                    "UNAUTHORIZED",
                    401,
                )
            }
        }

        // Ledger status — requires master key (Bearer or X-Api-Key), redacts password
        (Method::Get, "/ledger/status") => match authenticate_bearer(req, &state) {
            Err(resp) => resp,
            Ok(caller) if caller != "admin" => {
                error_response("Forbidden: admin only", "FORBIDDEN", 403)
            }
            Ok(_) => json_response(
                &serde_json::json!({
                    "api_mode": state.ledger.is_api_mode(),
                }),
                200,
            ),
        },

        // Drain a worker (loopback-only): stop routing new work to it.
        (Method::Post, path) if path.starts_with("/workers/") && path.ends_with("/drain") => {
            let worker_id = path
                .trim_start_matches("/workers/")
                .trim_end_matches("/drain");
            handle_drain_worker(&state, req, worker_id)
        }

        // Delete worker (requires worker key when configured)
        (Method::Delete, path) if path.starts_with("/workers/") => {
            if !verify_worker_key(req, &state) {
                error_response(
                    "Worker key required. Set X-Worker-Key header",
                    "UNAUTHORIZED",
                    401,
                )
            } else {
                let worker_id = path.trim_start_matches("/workers/");
                match state.workers.remove(worker_id) {
                    Some(worker) => {
                        println!("  [BROKER] Worker unregistered: {}", worker_id);
                        json_response(
                            &serde_json::json!({"status": "ok", "worker_id": worker.id}),
                            200,
                        )
                    }
                    None => error_response("Worker not found", "NOT_FOUND", 404),
                }
            }
        }

        // Quota usage (authenticated) — returns current rate limit counters
        (Method::Get, "/quotas") => {
            match authenticate_bearer(req, &state) {
                Err(resp) => resp,
                Ok(caller) => {
                    let user_credits = state.credits.get(&caller);
                    let now = chrono::Utc::now();
                    match user_credits {
                        Some(uc) => {
                            // Calculate seconds until each window resets
                            let sec_reset = 1.0_f64
                                - now
                                    .signed_duration_since(uc.second_window_start)
                                    .num_milliseconds() as f64
                                    / 1000.0;
                            let day_reset = 86400.0
                                - now.signed_duration_since(uc.day_window_start).num_seconds()
                                    as f64;
                            let month_reset = 2_592_000.0
                                - now
                                    .signed_duration_since(uc.month_window_start)
                                    .num_seconds() as f64;

                            json_response(
                                &serde_json::json!({
                                    "user_id": caller,
                                    "rate_limit_per_second": uc.rate_limit_per_second,
                                    "rate_limit_per_day": uc.rate_limit_per_day,
                                    "rate_limit_per_month": uc.rate_limit_per_month,
                                    "requests_this_second": uc.requests_this_second,
                                    "requests_this_day": uc.requests_this_day,
                                    "requests_this_month": uc.requests_this_month,
                                    "seconds_until_second_reset": sec_reset.max(0.0),
                                    "seconds_until_day_reset": day_reset.max(0.0),
                                    "seconds_until_month_reset": month_reset.max(0.0),
                                }),
                                200,
                            )
                        }
                        None => json_response(
                            &serde_json::json!({
                                "user_id": caller,
                                "rate_limit_per_second": serde_json::Value::Null,
                                "rate_limit_per_day": serde_json::Value::Null,
                                "rate_limit_per_month": serde_json::Value::Null,
                                "requests_this_second": 0,
                                "requests_this_day": 0,
                                "requests_this_month": 0,
                                "seconds_until_second_reset": 0,
                                "seconds_until_day_reset": 0,
                                "seconds_until_month_reset": 0,
                            }),
                            200,
                        ),
                    }
                }
            }
        }

        // User info (authenticated)
        (Method::Get, "/me") => {
            if let Some(auth) = req.header("Authorization") {
                match auth.strip_prefix("Bearer ") {
                    Some(token) => match state.ledger.resolve_user_from_api_key(token) {
                        Ok(uid) => {
                            let balance = state.ledger.load_balance_if_needed(&uid);
                            json_response(
                                &serde_json::json!({
                                    "user_id": uid,
                                    "balance": balance,
                                    "local_mode": state.is_local_mode(),
                                }),
                                200,
                            )
                        }
                        Err(e) => error_response(&e.to_string(), "UNAUTHORIZED", 401),
                    },
                    None => error_response("Invalid Authorization header", "UNAUTHORIZED", 401),
                }
            } else {
                error_response(
                    "API key required. Set Authorization: Bearer <key>",
                    "UNAUTHORIZED",
                    401,
                )
            }
        }

        // Not found
        _ => error_response("Not found", "NOT_FOUND", 404),
    };

    response
}

// --- Peer endpoint handlers ---

/// Fail-closed auth for the P2P **credit surface** (reserve/commit/cancel/
/// earn/balance/workers/tasks-offer). A valid X-Peer-Key is ALWAYS required;
/// `verify_peer_key` denies when no key is configured, so a keyless broker
/// refuses to serve these endpoints entirely. Returns `Some(401)` to reject,
/// `None` when authorized.
fn peer_credit_auth(state: &Arc<BrokerState>, request: &BrokerRequest) -> Option<BrokerResponse> {
    // Zero-trust per-node signature gate. Permissive by default (logs and allows)
    // so a mixed/upgrading mesh keeps working; enforced when ZAKURO_ENFORCE_NODE_SIG
    // is set. Retires ZAKURO_PEER_KEY as the identity gate once enforced.
    if let Some(reject) = node_sig_gate(state, request) {
        return Some(reject);
    }
    if peer::verify_peer_key(
        request.header("X-Peer-Key").as_deref(),
        state.peer_manager.peer_key(),
    ) {
        None
    } else {
        Some(error_response(
            "Peer authentication required (set ZAKURO_PEER_KEY and send X-Peer-Key)",
            "UNAUTHORIZED",
            401,
        ))
    }
}

/// Testable core of the node-signature gate. Returns `Ok(signer_pubkey)` when the
/// request carries a valid signature from a rostered node; `Err(reason)` otherwise.
/// Pure — no env, no I/O — so it can be unit-tested with a hand-built request.
fn check_node_sig(
    roster: &dashmap::DashMap<String, bool>,
    guard: &node_identity::ReplayGuard,
    request: &BrokerRequest,
    now: u64,
) -> Result<String, String> {
    // `revoked == false` → authorized; absent → not rostered.
    let is_rostered = |id: &str| roster.get(id).map(|r| !*r.value()).unwrap_or(false);
    let header = |name: &str| request.header(name);
    let method = format!("{:?}", request.method).to_uppercase(); // "GET"/"POST"
    node_identity::verify_request(
        &is_rostered,
        guard,
        &method,
        &request.path,
        &request.body,
        &header,
        now,
    )
}

/// Whether dashboard-signed job vouchers are required (issued on dispatch and
/// verified on receipt). Off by default — zero added latency and no behavior change.
/// Are dashboard vouchers required for remote/foreign jobs on this broker?
/// `ZAKURO_REQUIRE_VOUCHER=1|true`. The fleet sets it explicitly; brokers
/// started from the CLI get it defaulted on whenever billing credentials are
/// present (`broker::apply_user_broker_defaults`), so a user broker mints
/// when it dispatches to the fleet, which rejects unvouched offers with 402.
fn voucher_required() -> bool {
    std::env::var("ZAKURO_REQUIRE_VOUCHER")
        .map(|v| v == "1" || v == "true")
        .unwrap_or(false)
}

/// After a successful execution, redeem the offer's voucher nonce at the
/// dashboard (double-spend guard). No-op unless vouchers are required and a
/// voucher is present; best-effort (logs and continues on failure).
fn redeem_offer_voucher(state: &BrokerState, offer: &task_board::TaskOffer, actual_cost: f64) {
    if !voucher_required() || offer.voucher_signed_json.is_empty() {
        return;
    }
    let nonce = match serde_json::from_str::<serde_json::Value>(&offer.voucher_signed_json) {
        Ok(v) => v
            .get("task_nonce")
            .and_then(|n| n.as_str())
            .map(|s| s.to_string()),
        Err(_) => None,
    };
    if let (Some(nonce), Some(api_url), Some(api_key)) =
        (nonce, &state.config.api_url, &state.config.api_key)
    {
        match super::node_sync::redeem_voucher(api_url, api_key, &nonce, actual_cost) {
            Ok(true) => {}
            Ok(false) => {
                eprintln!("  [VOUCHER] nonce already spent (double-spend attempt?): {nonce}")
            }
            Err(e) => eprintln!("  [VOUCHER] redeem failed: {e}"),
        }
    }
}

/// Verify the voucher carried on an incoming `TaskOffer` against the cached
/// dashboard pubkey and the offer's estimated price. Returns `Err(reason)` on a
/// verification failure; `Ok(())` when valid or when vouchers are not required.
fn verify_offer_voucher(
    state: &Arc<BrokerState>,
    offer: &task_board::TaskOffer,
) -> Result<(), String> {
    if !voucher_required() {
        return Ok(());
    }
    let pubkey = state
        .dash_voucher_pubkey
        .read()
        .ok()
        .and_then(|g| g.clone())
        .ok_or("no dashboard voucher pubkey cached yet")?;
    if offer.voucher_signed_json.is_empty() {
        return Err("voucher required but none supplied".into());
    }
    // Estimated spend for this offer: price/hr × duration(hrs), bounded by the offer.
    let price_estimate =
        offer.max_price_per_hour * (offer.estimated_duration_secs / 3600.0).max(0.0);
    super::voucher::verify_voucher_now(
        &pubkey,
        &offer.voucher_signed_json,
        &offer.voucher_sig,
        price_estimate,
    )
    .map(|_| ())
}

/// Env-driven wrapper: enforce when `ZAKURO_ENFORCE_NODE_SIG` is set, else log and
/// allow (permissive rollout). Returns `Some(401)` only when enforcing a failure.
fn node_sig_gate(state: &Arc<BrokerState>, request: &BrokerRequest) -> Option<BrokerResponse> {
    let enforce = std::env::var("ZAKURO_ENFORCE_NODE_SIG")
        .map(|v| v == "1" || v == "true")
        .unwrap_or(false);
    match check_node_sig(
        &state.node_roster,
        &state.node_sig_guard,
        request,
        node_identity::now_secs(),
    ) {
        Ok(_) => None,
        Err(e) => {
            if enforce {
                Some(error_response(
                    &format!("node signature check failed: {e}"),
                    "UNAUTHORIZED",
                    401,
                ))
            } else {
                // Permissive rollout: stay silent for entirely-unsigned peers (expected
                // while the mesh upgrades); only flag a *present but invalid* signature.
                if request.header("X-Node-Id").is_some() {
                    eprintln!(
                        "  [NODE_SIG] permissive: {} {} — {}",
                        format!("{:?}", request.method).to_uppercase(),
                        request.path,
                        e
                    );
                }
                None
            }
        }
    }
}

/// Auth for the P2P **handshake surface** (health/identity). When a peer key
/// is configured it is required (same as the credit surface). When no key is
/// configured these stay reachable from loopback only, so localhost broker
/// auto-discovery (`discover_broker_peers_on_localhost`) keeps working without
/// exposing handshake info to the network. Returns `Some(401)` to reject,
/// `None` when authorized.
fn peer_handshake_auth(
    state: &Arc<BrokerState>,
    request: &BrokerRequest,
) -> Option<BrokerResponse> {
    let key = state.peer_manager.peer_key();
    if key.is_empty() {
        if request.is_loopback() {
            None
        } else {
            Some(error_response(
                "Peer authentication required (set ZAKURO_PEER_KEY)",
                "UNAUTHORIZED",
                401,
            ))
        }
    } else if peer::verify_peer_key(request.header("X-Peer-Key").as_deref(), key) {
        None
    } else {
        Some(error_response("Invalid peer key", "UNAUTHORIZED", 401))
    }
}

/// A single entry in the `/brokers` listing: a key-derived, IP-free peer id.
#[derive(serde::Serialize)]
struct BrokerEntry {
    id: String,
    reachable: bool,
}

/// A single entry in the `/brokers` listing: a key-derived, IP-free peer id.
#[derive(serde::Serialize)]
struct BrokersResponse {
    #[serde(rename = "self")]
    self_id: String,
    brokers: Vec<BrokerEntry>,
}

/// `GET /brokers` — the IP-free "list the brokers to communicate with"
/// primitive. Design model: a broker owns and manages only its own local
/// workers; the mesh is a set of BROKERS talking P2P. This is the client
/// surface for that mesh topology, scrubbed of every IP/peer_url — only
/// key-derived `zc://node-<fp>` ids are returned.
///
/// Peer ids come from `PeerManager`'s cached fingerprints, learned from each
/// peer's own `/peer/health` response (`broker_id`, now key-derived — see
/// `handle_peer_health`) during QUIC/health discovery and cached on the
/// `PeerClient`. A peer whose fingerprint hasn't been learned yet is
/// probed on demand (`ensure_fingerprints_cached`) so a cold-started broker
/// still answers usefully; if it's still unknown after that (peer
/// unreachable / predates key-derived identity), it is OMITTED from the
/// list rather than leaking its `peer_url` as a stand-in id.
fn handle_brokers(state: &Arc<BrokerState>) -> BrokerResponse {
    state.peer_manager.ensure_fingerprints_cached();

    let mut peer_urls = state.peer_manager.peer_urls();
    peer_urls.sort();

    // One broker, one row — keyed on identity, because one broker can be
    // registered under two spellings (its `ZAKURO_PEERS` DNS name and its
    // roster mesh address). The tick loop reconciles those away, but it runs
    // only every ~60s and cannot dedup a peer whose fingerprint was still
    // unresolved when it last ran; listing the same `zc://node-<fp>` twice
    // would falsify this feature's acceptance criterion in that window. A
    // peer is reachable if ANY of its spellings is.
    let mut seen: std::collections::HashSet<String> = std::collections::HashSet::new();
    let brokers: Vec<BrokerEntry> = peer_urls
        .into_iter()
        .filter_map(|url| {
            let fp_id = state.peer_manager.peer_fingerprint(&url)?;
            let reachable = state
                .peer_manager
                .get_client(&url)
                .map(|c| c.is_reachable())
                .unwrap_or(false);
            Some((fp_id, reachable))
        })
        .fold(Vec::<BrokerEntry>::new(), |mut acc, (fp_id, reachable)| {
            if seen.insert(fp_id.clone()) {
                acc.push(BrokerEntry {
                    id: fp_id,
                    reachable,
                });
            } else if reachable {
                if let Some(e) = acc.iter_mut().find(|e| e.id == fp_id) {
                    e.reachable = true;
                }
            }
            acc
        });

    json_response(
        &BrokersResponse {
            self_id: state.node_key.node_uri(),
            brokers,
        },
        200,
    )
}

/// Body for `POST /price`.
#[derive(Debug, Deserialize)]
struct SetPriceRequest {
    price_per_hour: f64,
}

/// `GET /price` — this broker's currently advertised price (credits/hour).
/// Client-facing, IP-free: only the numeric price is ever returned.
fn handle_get_price(state: &Arc<BrokerState>) -> BrokerResponse {
    json_response(
        &serde_json::json!({ "price_per_hour": state.price.get() }),
        200,
    )
}

/// `POST /price` — set this broker's advertised price. Loopback-only: a
/// broker's price is its own operator's decision, never settable by a
/// remote peer or client over the network.
fn handle_set_price(state: &Arc<BrokerState>, request: &BrokerRequest) -> BrokerResponse {
    if !request.is_loopback() {
        return error_response("Setting price is local-only (loopback)", "FORBIDDEN", 403);
    }
    match body_or_413(request) {
        Err(resp) => resp,
        Ok(body) => match serde_json::from_slice::<SetPriceRequest>(body) {
            Ok(req) => {
                state.price.set(req.price_per_hour);
                json_response(
                    &serde_json::json!({ "price_per_hour": state.price.get() }),
                    200,
                )
            }
            Err(e) => error_response(&format!("Invalid request body: {e}"), "BAD_REQUEST", 400),
        },
    }
}

/// `POST /workers/{id}/drain` — stop routing new work to one of this broker's
/// workers so the local `zc agent` can stop it without killing a job
/// (spec 2026-09-13-macos-widget §6.6). Loopback-only, like `/price/set`:
/// only the agent supervising the worker on this machine may drain it.
fn handle_drain_worker(
    state: &Arc<BrokerState>,
    request: &BrokerRequest,
    worker_id: &str,
) -> BrokerResponse {
    if !request.is_loopback() {
        return error_response("Draining is local-only (loopback)", "FORBIDDEN", 403);
    }
    match state.workers.drain(worker_id) {
        Some(w) => json_response(
            &serde_json::json!({
                "status": "draining",
                "worker_id": w.id,
                "active_requests": w.active_requests,
            }),
            200,
        ),
        None => error_response("Worker not found", "NOT_FOUND", 404),
    }
}

// --- Model inference (/infer) ---

/// Inbound `POST /infer` body: an OpenAI-shaped chat request addressed to a
/// `zc://` model uuid (or bare uuid) instead of a model name.
#[derive(Debug, Deserialize)]
struct InferRequest {
    model: String,
    /// Passed through to the provider as-is (messages + any extra OpenAI fields).
    #[serde(flatten)]
    rest: serde_json::Value,
}

/// The subset of an OpenAI chat-completions response this route cares about.
#[derive(Debug, Deserialize)]
struct OpenAiChatResponse {
    choices: Vec<OpenAiChoice>,
    #[serde(default)]
    usage: OpenAiUsage,
}

#[derive(Debug, Deserialize)]
struct OpenAiChoice {
    message: OpenAiMessage,
}

#[derive(Debug, Deserialize)]
struct OpenAiMessage {
    #[serde(default)]
    content: String,
}

#[derive(Debug, Default, Deserialize)]
struct OpenAiUsage {
    #[serde(default)]
    prompt_tokens: u64,
    #[serde(default)]
    completion_tokens: u64,
    #[serde(default)]
    total_tokens: u64,
}

/// Errors from [`forward_chat`], sanitized so the handler never has to worry
/// about leaking transport internals (connection strings, TLS details, etc.)
/// into a client-facing response.
#[derive(Debug)]
enum ForwardError {
    /// Transport-level failure (connection refused, timeout, DNS, ...).
    Transport(String),
    /// Provider responded but not with a parseable OpenAI chat completion.
    BadResponse(String),
}

impl std::fmt::Display for ForwardError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Transport(_) => write!(f, "provider unreachable"),
            Self::BadResponse(_) => write!(f, "provider returned an invalid response"),
        }
    }
}

/// Real HTTP forward of an OpenAI chat body to `{worker_uri}/v1/chat/completions`,
/// using the same outbound client (`ureq`) as `ledger::sync_workers_via_api`.
///
/// Factored out from [`handle_infer`] so tests can substitute a stub closure
/// in place of a live network call.
fn forward_chat_live(
    worker_uri: &str,
    body: &serde_json::Value,
) -> Result<OpenAiChatResponse, ForwardError> {
    let endpoint = format!("{}/v1/chat/completions", worker_uri.trim_end_matches('/'));
    let payload = serde_json::to_string(body)
        .map_err(|e| ForwardError::BadResponse(format!("failed to serialize request: {e}")))?;

    // A hung/unresponsive provider must not hang the broker's own /infer
    // handler indefinitely — ureq's defaults have no timeout. 120s read covers
    // slow generations without leaving the request open forever; connect gets
    // a much tighter bound since a live provider should accept fast.
    let agent = ureq::Agent::new_with_config(
        ureq::Agent::config_builder()
            .timeout_connect(Some(std::time::Duration::from_secs(10)))
            .timeout_recv_response(Some(std::time::Duration::from_secs(120)))
            .build(),
    );

    let response = agent
        .post(&endpoint)
        .config()
        .http_status_as_error(false)
        .build()
        .header("Content-Type", "application/json")
        .send(payload.as_str())
        .map_err(|e| ForwardError::Transport(e.to_string()))?;

    let status = response.status().as_u16();
    let text = response
        .into_body()
        .read_to_string()
        .map_err(|e| ForwardError::Transport(e.to_string()))?;

    if status != 200 {
        return Err(ForwardError::BadResponse(format!(
            "provider returned status {status}"
        )));
    }

    serde_json::from_str::<OpenAiChatResponse>(&text)
        .map_err(|e| ForwardError::BadResponse(format!("failed to parse provider response: {e}")))
}

/// Auth gate for `/infer`, mirroring `execute_prepare`'s bearer resolution
/// exactly: a non-empty Bearer token must resolve to a user via the same
/// `resolve_user_from_api_key` path `/execute` uses; in local mode a missing
/// token is allowed (single-node, free demo path); in remote mode a missing
/// or invalid token is rejected with the same 401 shape `/execute` returns.
/// Returns the resolved user id (`None` on the keyless local-mode path) so
/// the billing step downstream charges the same identity auth admitted.
fn infer_authenticate(
    state: &Arc<BrokerState>,
    request: &BrokerRequest,
) -> Result<Option<String>, BrokerResponse> {
    let bearer = request
        .header("Authorization")
        .and_then(|a| a.strip_prefix("Bearer ").map(|t| t.trim().to_string()))
        .filter(|t| !t.is_empty());

    if let Some(token) = bearer {
        state
            .ledger
            .resolve_user_from_api_key(&token)
            .map(Some)
            .map_err(|e| error_response(&e.to_string(), "UNAUTHORIZED", 401))
    } else if state.is_local_mode() {
        // No Bearer token: allowed only in local mode, where execution is
        // single-node and free — same rule `execute_prepare` applies.
        Ok(None)
    } else {
        // Remote mode: require an API key whether or not billing is enabled.
        Err(error_response(
            "API key required. Set Authorization: Bearer <key>",
            "UNAUTHORIZED",
            401,
        ))
    }
}

/// Fallback generation budget when the caller sends no `max_tokens`: the
/// reservation must cover the worst the provider might generate, and
/// llama-server's own no-limit default is effectively "until context runs
/// out", so this is deliberately generous rather than typical.
const INFER_DEFAULT_MAX_TOKENS: u64 = 4096;

/// Upper bound on what a request could cost, reserved before forwarding.
///
/// Prompt tokens are unknown until the provider reports usage, so they are
/// over-estimated at one token per 3 bytes of request body (English text
/// runs ~4 bytes/token; 3 keeps the ceiling above the actual for tokenizers
/// that split tighter). Generation is bounded by the caller's `max_tokens`
/// (or `INFER_DEFAULT_MAX_TOKENS`). The commit is capped by this ceiling
/// (`capped_charge`), so over-estimating can only over-RESERVE, never
/// over-CHARGE — the difference is refunded at commit.
fn infer_cost_ceiling(price_per_mtok: f64, body_bytes: usize, max_tokens: Option<u64>) -> f64 {
    let prompt_est = (body_bytes as f64 / 3.0).ceil();
    let gen_budget = max_tokens.unwrap_or(INFER_DEFAULT_MAX_TOKENS) as f64;
    (prompt_est + gen_budget) * price_per_mtok / 1_000_000.0
}

/// Settle a billed inference whose provider is registered on THIS broker:
/// credit the broker's configured owner the payout (WAL-backed, exactly as
/// `handle_peer_earn` does for a mesh-delivered earn), mirror the platform
/// commission into the local cache, and redeem the voucher so the dashboard
/// credits the platform-house authoritatively. With no owner configured the
/// payout leg has no payee — the payout is REFUNDED to the requester (who
/// then nets only the commission), exactly the rule `settle_executor_payout`
/// applies when the earn RPC fails: money is never destroyed to nobody.
#[allow(clippy::too_many_arguments)]
fn settle_own_provider_payout(
    state: &Arc<BrokerState>,
    requester_uid: &str,
    worker: &Worker,
    actual_cost: f64,
    commission_c: f64,
    voucher_nonce: &str,
    request_id: &str,
    duration_ms: f64,
) {
    let (payout, commission) = split_commission(actual_cost, commission_c);
    if commission > 0.0 && state.is_billing_enabled() {
        let platform_uid =
            std::env::var("ZAKURO_PLATFORM_UID").unwrap_or_else(|_| "platform-house".into());
        state
            .ledger
            .local_credits
            .entry(platform_uid.clone())
            .and_modify(|b| *b += commission)
            .or_insert(commission);
        state
            .ledger
            .authoritative_balances
            .entry(platform_uid)
            .and_modify(|b| *b += commission)
            .or_insert(commission);
    }
    match state.config.owner_user_id.as_deref() {
        Some(owner) if payout > 0.0 => {
            let earn_request_id = format!("earn-{request_id}");
            let dashboard_configured =
                state.config.api_url.is_some() && state.config.api_key.is_some();
            if dashboard_configured {
                let _ = state.wal.append(&WalEntry {
                    request_id: earn_request_id.clone(),
                    user_id: owner.to_string(),
                    reservation_id: String::new(),
                    estimated_cost: payout,
                    actual_cost: Some(payout),
                    worker_id: worker.id.clone(),
                    duration_ms: Some(duration_ms),
                    timestamp: chrono::Utc::now(),
                    status: WalStatus::Earned,
                });
            }
            let balance_after = state.ledger.local_add_credits(owner, payout);
            state.tx_buffer.push_transaction(BufferedTransaction {
                request_id: earn_request_id,
                user_id: owner.to_string(),
                tx_type: "credit".to_string(),
                amount: payout,
                balance_after,
                worker_id: worker.id.clone(),
                duration_ms,
                source_node: state.config.node_name.clone(),
                worker_name: Some(worker.name.clone()),
                worker_uri: Some(worker.uri.clone()),
                price_per_hour: worker.pricing.price_per_hour,
            });
        }
        Some(_) => {}
        None => {
            // No payee: refund the payout to the requester (nets −commission)
            // — the settle_executor_payout earn-failure rule; money is never
            // destroyed to nobody.
            eprintln!(
                "  [INFER] no owner configured on this broker: refunding provider payout \
                 {payout:.6} for request {request_id} to the requester"
            );
            if payout > 0.0 && state.is_billing_enabled() {
                state
                    .ledger
                    .local_credits
                    .entry(requester_uid.to_string())
                    .and_modify(|b| *b += payout)
                    .or_insert(payout);
                state
                    .ledger
                    .authoritative_balances
                    .entry(requester_uid.to_string())
                    .and_modify(|b| *b += payout)
                    .or_insert(payout);
                state.tx_buffer.push_transaction(BufferedTransaction {
                    request_id: format!("{request_id}-earn-refund"),
                    user_id: requester_uid.to_string(),
                    tx_type: "refund".to_string(),
                    amount: payout,
                    balance_after: 0.0,
                    worker_id: worker.id.clone(),
                    duration_ms,
                    source_node: state.config.node_name.clone(),
                    worker_name: Some(worker.name.clone()),
                    worker_uri: Some(worker.uri.clone()),
                    price_per_hour: worker.pricing.price_per_hour,
                });
            }
        }
    }
    if !voucher_nonce.is_empty() {
        if let (Some(api_url), Some(api_key)) = (&state.config.api_url, &state.config.api_key) {
            match super::node_sync::redeem_voucher(api_url, api_key, voucher_nonce, actual_cost) {
                Ok(true) => {}
                Ok(false) => {
                    eprintln!("  [VOUCHER] infer nonce already spent: {voucher_nonce}")
                }
                Err(e) => eprintln!("  [VOUCHER] infer redeem failed: {e}"),
            }
        }
    }
}

/// Billing context carried from the pre-forward reserve to settlement.
struct InferBilling {
    res_id: String,
    ceiling: f64,
    request_id: String,
    uid: String,
    /// The ONE dashboard-verified commission rate for this request, captured
    /// at mint (0.0 when vouchers are not required) — settlement never
    /// re-derives it, mirroring `dispatch_to_peers`.
    commission_c: f64,
    /// Dashboard voucher nonce to redeem at settlement ("" when vouchers off).
    voucher_nonce: String,
}

/// What the request actually cost: total tokens at the provider's price.
fn infer_actual_cost(price_per_mtok: f64, total_tokens: u64) -> f64 {
    total_tokens as f64 * price_per_mtok / 1_000_000.0
}

/// `POST /infer` — resolve `model` (a `zc://` model uuid) to a serving worker
/// and forward a one-shot OpenAI chat completion to it. Charges the caller
/// `total_tokens × price_per_mtok / 1e6` (reserve-ceiling → forward →
/// capped commit; full refund when the provider call fails). Free when the
/// provider is unpriced, billing is disabled, or the caller is the keyless
/// local-mode path. Provider payout is NOT settled here — it rides on the
/// published transaction (`worker_id` + tokens) for the voucher/receipt
/// settlement to pay out, mirroring where /execute's payout lives.
fn handle_infer(state: &Arc<BrokerState>, request: &BrokerRequest) -> BrokerResponse {
    handle_infer_with(state, request, forward_chat_live)
}

/// Testable core of `/infer`: auth -> parse -> resolve -> forward -> map, with
/// the actual provider call injected as `forward`. Production wires
/// [`forward_chat_live`]; tests substitute a canned stub.
fn handle_infer_with(
    state: &Arc<BrokerState>,
    request: &BrokerRequest,
    forward: impl FnOnce(&str, &serde_json::Value) -> Result<OpenAiChatResponse, ForwardError>,
) -> BrokerResponse {
    let user_id = match infer_authenticate(state, request) {
        Ok(uid) => uid,
        Err(resp) => return resp,
    };

    let body = match body_or_413(request) {
        Ok(b) => b,
        Err(resp) => return resp,
    };
    let body_len = body.len();

    let parsed: InferRequest = match serde_json::from_slice(body) {
        Ok(v) => v,
        Err(_) => return error_response("invalid model uri", "BAD_REQUEST", 400),
    };

    let model_uuid = match parse_model_uri(&parsed.model) {
        Some(uuid) => uuid,
        None => return error_response("invalid model uri", "BAD_REQUEST", 400),
    };

    let worker = match state.workers.resolve_model(&model_uuid) {
        Ok(w) => w,
        Err(ModelResolveError::NoProvider { model_uuid }) => {
            return error_response(
                &format!("no provider serving zc://{model_uuid}"),
                "NOT_FOUND",
                404,
            );
        }
    };

    // Forward the caller's body as-is (messages, max_tokens, etc.). The
    // `model` field is what the provider keys on, and the two provider kinds
    // need different things: a SPECIALIZED provider is one llama-server that
    // ignores the name (any value works; the worker name reads best in its
    // logs), but a GENERAL provider serves many models and must be told
    // WHICH one — its on-demand loader (`serve_general`) parses this field
    // as the model uuid. Sending it the worker name would 400 every request.
    let mut forward_body = parsed.rest;
    if let serde_json::Value::Object(ref mut map) = forward_body {
        let model_field = match worker.provider_type {
            crate::broker::worker::ProviderType::General => model_uuid.clone(),
            crate::broker::worker::ProviderType::Specialized => worker.name.clone(),
        };
        map.insert("model".to_string(), serde_json::Value::String(model_field));
    }

    // ── Billing: reserve the ceiling before spending provider compute ──
    // Billable only when all three hold: billing is on, the provider set a
    // price, and auth resolved a user (the keyless local-mode path stays
    // free). An unpriced provider (price_per_mtok == 0, today's default)
    // bills nothing, so rolling this out changes nothing until providers
    // opt in with `zc serve --price`.
    let max_tokens = forward_body.get("max_tokens").and_then(|v| v.as_u64());
    let billable = state.is_billing_enabled() && worker.price_per_mtok > 0.0;
    let reservation = match (&user_id, billable) {
        (Some(uid), true) => {
            let ceiling = infer_cost_ceiling(worker.price_per_mtok, body_len, max_tokens);
            // Commission rides on a dashboard-signed voucher exactly as it
            // does for direct-forward /execute: minted fail-closed BEFORE
            // any credits are reserved or provider compute is spent, so a
            // billed inference can never run uncommissioned when vouchers
            // are required. Vouchers off (the default) → commission 0 and
            // no dashboard round-trip.
            let (commission_c, voucher_nonce) = if voucher_required() {
                match mint_and_verify_remote_voucher(state, ceiling, None) {
                    Ok(v) => v,
                    Err(resp) => return resp,
                }
            } else {
                (0.0, String::new())
            };
            let request_id = uuid::Uuid::new_v4().to_string();
            match state.ledger.local_reserve(uid, ceiling, &request_id) {
                Ok((res_id, _balance)) => Some(InferBilling {
                    res_id,
                    ceiling,
                    request_id,
                    uid: uid.clone(),
                    commission_c,
                    voucher_nonce,
                }),
                Err(ledger::LedgerError::InsufficientCredits {
                    required,
                    available,
                }) => {
                    return error_response(
                        &format!("Insufficient credits: need {required:.6}, have {available:.6}"),
                        "INSUFFICIENT_CREDITS",
                        402,
                    );
                }
                Err(e) => return error_response(&e.to_string(), "LEDGER_ERROR", 503),
            }
        }
        _ => None,
    };

    let started = Instant::now();
    match forward(&worker.uri, &forward_body) {
        Ok(resp) => {
            let content = resp
                .choices
                .first()
                .map(|c| c.message.content.clone())
                .unwrap_or_default();
            // Commit the actual cost, capped by the reservation so an
            // over-reporting provider can never charge past the ceiling the
            // caller's balance was checked against. The uncharged remainder
            // is released by the commit.
            let charged = match &reservation {
                Some(bill) => {
                    let InferBilling {
                        res_id,
                        ceiling,
                        request_id,
                        uid,
                        commission_c,
                        voucher_nonce,
                    } = bill;
                    let actual = capped_charge(
                        infer_actual_cost(worker.price_per_mtok, resp.usage.total_tokens),
                        *ceiling,
                    );
                    let balance_after = match state.ledger.local_commit(res_id, actual) {
                        Ok(b) => b,
                        Err(e) => {
                            // The forward already succeeded and the tokens are
                            // spent; a commit failure must not un-serve the
                            // response. Log and report the charge we attempted.
                            eprintln!("  [INFER] commit error for {request_id}: {e}");
                            state.ledger.load_balance_if_needed(uid)
                        }
                    };
                    // Audit trail: same buffered-transaction stream the
                    // dashboard ingests for /execute. duration_ms carries the
                    // forward latency; tokens are recoverable from amount /
                    // price_per_mtok. Provider payout settles downstream off
                    // this record — never minted here.
                    state.tx_buffer.push_transaction(BufferedTransaction {
                        request_id: request_id.clone(),
                        user_id: uid.clone(),
                        tx_type: "infer".to_string(),
                        amount: actual,
                        balance_after,
                        worker_id: worker.id.clone(),
                        duration_ms: started.elapsed().as_millis() as f64,
                        source_node: state.config.node_name.clone(),
                        worker_name: Some(worker.name.clone()),
                        worker_uri: Some(worker.uri.clone()),
                        price_per_hour: worker.pricing.price_per_hour,
                    });
                    // ── Provider payout + commission, /execute's direct-path
                    // semantics verbatim: settle to the provider's broker by
                    // its key-derived node identity, redeem the voucher for
                    // the authoritative platform-house credit, and if the
                    // provider's broker cannot be resolved, refund the FULL
                    // charge — pay nobody, redeem nothing, requester nets 0.
                    let own_fp = state.node_key.fingerprint();
                    let exec_fp = executor_fp(&worker);
                    if exec_fp == Some(own_fp.as_str()) {
                        // Provider registered directly on THIS broker (zc
                        // serve --advertise against the fleet): its payout
                        // goes to this broker's configured owner — the same
                        // payee handle_peer_earn would credit if the earn
                        // arrived over the mesh. No RPC to fail, so no
                        // refund leg; conservation is payout+commission ==
                        // actual by construction.
                        settle_own_provider_payout(
                            state,
                            uid,
                            &worker,
                            actual,
                            *commission_c,
                            voucher_nonce,
                            request_id,
                            started.elapsed().as_millis() as f64,
                        );
                        actual
                    } else {
                        match exec_fp.and_then(|fp| state.peer_manager.get_url_for_fingerprint(fp))
                        {
                            Some(peer_url) => {
                                settle_executor_payout(
                                    state,
                                    uid,
                                    actual,
                                    *commission_c,
                                    &peer_url,
                                    &worker.id,
                                    request_id,
                                    started.elapsed().as_millis() as f64,
                                );
                                if !voucher_nonce.is_empty() {
                                    if let (Some(api_url), Some(api_key)) =
                                        (&state.config.api_url, &state.config.api_key)
                                    {
                                        match super::node_sync::redeem_voucher(
                                            api_url,
                                            api_key,
                                            voucher_nonce,
                                            actual,
                                        ) {
                                            Ok(true) => {}
                                            Ok(false) => eprintln!(
                                            "  [VOUCHER] infer nonce already spent: {voucher_nonce}"
                                        ),
                                            Err(e) => {
                                                eprintln!("  [VOUCHER] infer redeem failed: {e}")
                                            }
                                        }
                                    }
                                }
                                actual
                            }
                            None => {
                                eprintln!(
                                "  [INFER] provider's broker unresolved for worker {}                                  (request {request_id}): refunding {actual:.6} in full",
                                worker.name
                            );
                                state
                                    .ledger
                                    .local_credits
                                    .entry(uid.to_string())
                                    .and_modify(|b| *b += actual)
                                    .or_insert(actual);
                                state
                                    .ledger
                                    .authoritative_balances
                                    .entry(uid.to_string())
                                    .and_modify(|b| *b += actual)
                                    .or_insert(actual);
                                state.tx_buffer.push_transaction(BufferedTransaction {
                                    request_id: format!("{request_id}-unresolved-refund"),
                                    user_id: uid.to_string(),
                                    tx_type: "refund".to_string(),
                                    amount: actual,
                                    balance_after: 0.0,
                                    worker_id: worker.id.clone(),
                                    duration_ms: started.elapsed().as_millis() as f64,
                                    source_node: state.config.node_name.clone(),
                                    worker_name: Some(worker.name.clone()),
                                    worker_uri: Some(worker.uri.clone()),
                                    price_per_hour: worker.pricing.price_per_hour,
                                });
                                0.0
                            }
                        }
                    }
                }
                None => 0.0,
            };
            json_response(
                &serde_json::json!({
                    "content": content,
                    "usage": {
                        "prompt_tokens": resp.usage.prompt_tokens,
                        "completion_tokens": resp.usage.completion_tokens,
                        "total_tokens": resp.usage.total_tokens,
                    },
                    "provider": worker.name,
                    "charged_zkcr": charged,
                }),
                200,
            )
        }
        Err(e) => {
            // Failed forward: the caller pays nothing — release the full
            // reservation before surfacing the error.
            if let Some(bill) = &reservation {
                if let Err(cancel_err) = state.ledger.local_cancel(&bill.res_id) {
                    eprintln!(
                        "  [INFER] cancel error for {}: {cancel_err}",
                        bill.request_id
                    );
                }
            }
            error_response(&format!("provider request failed: {e}"), "BAD_GATEWAY", 502)
        }
    }
}

#[cfg(test)]
mod infer_tests {
    use super::*;
    use crate::broker::worker::{
        HardwareInfo, ProviderType, WorkerPricing, WorkerRegistration, WorkerResources,
    };
    use crate::broker::BrokerState;
    use std::sync::Arc;
    use tiny_http::Method;

    const UUID: &str = "ae5f3db4-437a-40d1-93ec-c8258315d69a";

    fn state_with_provider(uuid: &str, name: &str) -> Arc<BrokerState> {
        let state = BrokerState::new();
        state.workers.register(WorkerRegistration {
            name: name.to_string(),
            uri: "http://10.0.0.5:9000".to_string(),
            worker_type: "zakuro".to_string(),
            resources: WorkerResources::default(),
            pricing: WorkerPricing::default(),
            tags: vec![],
            max_timeout_secs: 0.0,
            hardware: HardwareInfo::default(),
            wireguard_ip: None,
            is_docker: None,
            source_node: None,
            explicit_local: false,
            provider_type: ProviderType::Specialized,
            served_models: vec![uuid.to_string()],
            price_per_mtok: 1.0,
        });
        // These tests exercise parse/resolve/forward, not auth — run them in
        // local mode (keyless, single-node) so a missing Bearer token doesn't
        // trip the auth gate added for the /infer 401 fix.
        state.set_local_mode(true);
        Arc::new(state)
    }

    fn infer_req(body: &str) -> BrokerRequest {
        infer_req_with_headers(body, vec![])
    }

    fn infer_req_with_headers(body: &str, headers: Vec<(String, String)>) -> BrokerRequest {
        BrokerRequest {
            method: Method::Post,
            path: "/infer".to_string(),
            query: String::new(),
            headers,
            body: body.as_bytes().to_vec(),
            peer_addr: None,
        }
    }

    fn canned_ok(
        _worker_uri: &str,
        _body: &serde_json::Value,
    ) -> Result<OpenAiChatResponse, ForwardError> {
        Ok(OpenAiChatResponse {
            choices: vec![OpenAiChoice {
                message: OpenAiMessage {
                    content: "hello there".to_string(),
                },
            }],
            usage: OpenAiUsage {
                prompt_tokens: 10,
                completion_tokens: 5,
                total_tokens: 15,
            },
        })
    }

    fn canned_err(
        _worker_uri: &str,
        _body: &serde_json::Value,
    ) -> Result<OpenAiChatResponse, ForwardError> {
        Err(ForwardError::Transport(
            "connection refused to 10.0.0.5:9000 secret-token".to_string(),
        ))
    }

    #[test]
    fn served_uuid_forwards_and_maps_response() {
        let state = state_with_provider(UUID, "gpu-worker-1");
        let req = infer_req(&format!(
            r#"{{"model":"zc://{UUID}","messages":[{{"role":"user","content":"hi"}}]}}"#
        ));

        let resp = handle_infer_with(&state, &req, canned_ok);
        assert_eq!(resp.status, 200);
        let v: serde_json::Value = serde_json::from_slice(&resp.body).unwrap();
        assert_eq!(v["content"], "hello there");
        assert_eq!(v["usage"]["prompt_tokens"], 10);
        assert_eq!(v["usage"]["completion_tokens"], 5);
        assert_eq!(v["usage"]["total_tokens"], 15);
        assert_eq!(v["provider"], "gpu-worker-1");
        assert_eq!(v["charged_zkcr"], 0.0);
    }

    #[test]
    fn general_provider_receives_the_model_uuid_not_the_worker_name() {
        let state = BrokerState::new();
        state.set_local_mode(true);
        state.workers.register(WorkerRegistration {
            name: "general-1".to_string(),
            uri: "http://10.0.0.6:8600".to_string(),
            worker_type: "llm".to_string(),
            resources: WorkerResources::default(),
            pricing: WorkerPricing::default(),
            tags: vec![],
            max_timeout_secs: 0.0,
            hardware: HardwareInfo::default(),
            wireguard_ip: None,
            is_docker: None,
            source_node: None,
            explicit_local: false,
            provider_type: ProviderType::General,
            served_models: vec![crate::broker::worker::MODEL_WILDCARD.to_string()],
            price_per_mtok: 0.0,
        });
        let state = Arc::new(state);
        let req = infer_req(&format!(r#"{{"model":"zc://{UUID}","messages":[]}}"#));

        let seen = std::sync::Mutex::new(String::new());
        let resp = handle_infer_with(&state, &req, |_, body| {
            *seen.lock().unwrap() = body["model"].as_str().unwrap_or("").to_string();
            canned_ok("", body)
        });
        assert_eq!(resp.status, 200);
        assert_eq!(
            *seen.lock().unwrap(),
            UUID,
            "a general provider must be told WHICH model to load"
        );
    }

    #[test]
    fn unserved_uuid_returns_404() {
        let state = BrokerState::new();
        state.set_local_mode(true);
        let state = Arc::new(state);
        let req = infer_req(&format!(r#"{{"model":"zc://{UUID}","messages":[]}}"#));

        let resp = handle_infer_with(&state, &req, canned_ok);
        assert_eq!(resp.status, 404);
        let v: serde_json::Value = serde_json::from_slice(&resp.body).unwrap();
        assert_eq!(v["error"], format!("no provider serving zc://{UUID}"));
    }

    #[test]
    fn invalid_model_uri_returns_400() {
        let state = BrokerState::new();
        state.set_local_mode(true);
        let state = Arc::new(state);
        let req = infer_req(r#"{"model":"zc://node-abc","messages":[]}"#);

        let resp = handle_infer_with(&state, &req, canned_ok);
        assert_eq!(resp.status, 400);
        let v: serde_json::Value = serde_json::from_slice(&resp.body).unwrap();
        assert_eq!(v["error"], "invalid model uri");
    }

    #[test]
    fn provider_forward_error_returns_502_without_leaking_internals() {
        let state = state_with_provider(UUID, "gpu-worker-1");
        let req = infer_req(&format!(
            r#"{{"model":"{UUID}","messages":[{{"role":"user","content":"hi"}}]}}"#
        ));

        let resp = handle_infer_with(&state, &req, canned_err);
        assert_eq!(resp.status, 502);
        let body = String::from_utf8(resp.body.clone()).unwrap();
        assert!(
            !body.contains("10.0.0.5") && !body.contains("secret-token"),
            "502 body must not leak transport internals: {body}"
        );
        let v: serde_json::Value = serde_json::from_slice(&resp.body).unwrap();
        assert!(v["error"]
            .as_str()
            .unwrap()
            .starts_with("provider request failed"));
    }

    /// A state where billing is genuinely on (dashboard api configured) and
    /// the caller identity `uid` holds `balance` in the local ledger.
    fn billing_state_with_priced_provider(
        uuid: &str,
        price_per_mtok: f64,
        uid: &str,
        balance: f64,
    ) -> Arc<BrokerState> {
        let mut state = BrokerState::new();
        state.config.api_url = Some("http://dashboard.test".to_string());
        state.config.api_key = Some("svc-key".to_string());
        state.config.owner_user_id = Some("provider-owner".to_string());
        let w = state.workers.register(WorkerRegistration {
            name: "priced-worker".to_string(),
            uri: "http://10.0.0.5:9000".to_string(),
            worker_type: "llm".to_string(),
            resources: WorkerResources::default(),
            pricing: WorkerPricing::default(),
            tags: vec![],
            max_timeout_secs: 0.0,
            hardware: HardwareInfo::default(),
            wireguard_ip: None,
            is_docker: None,
            source_node: None,
            explicit_local: false,
            provider_type: ProviderType::Specialized,
            served_models: vec![uuid.to_string()],
            price_per_mtok,
        });
        // Directly-registered provider: stamped with this broker's own node
        // fp, exactly as the POST /workers route does — settlement takes the
        // own-provider (owner payout) branch.
        let fp = state.node_key.fingerprint();
        state.workers.set_node_fp(&w.id, &fp);
        state.set_local_mode(true); // keyless allowed; billing still applies to Bearer callers
        state
            .ledger
            .authoritative_balances
            .insert(uid.to_string(), balance);
        Arc::new(state)
    }

    fn bearer(uid: &str) -> Vec<(String, String)> {
        vec![(
            "Authorization".to_string(),
            format!("Bearer zk_{uid}_deadbeef"),
        )]
    }

    #[test]
    fn cost_ceiling_and_actual_cost_math() {
        // 300-byte body -> 100 prompt-token estimate; +200 max_tokens = 300
        // tokens at 1000 zkcr/mtok = 0.3.
        assert!((infer_cost_ceiling(1000.0, 300, Some(200)) - 0.3).abs() < 1e-9);
        // No max_tokens: the generous default budget applies.
        let c = infer_cost_ceiling(1000.0, 300, None);
        assert!((c - (100.0 + INFER_DEFAULT_MAX_TOKENS as f64) * 1000.0 / 1e6).abs() < 1e-9);
        assert!((infer_actual_cost(1000.0, 15) - 0.015).abs() < 1e-12);
        // Unpriced provider: everything is zero.
        assert_eq!(infer_cost_ceiling(0.0, 300, Some(200)), 0.0);
        assert_eq!(infer_actual_cost(0.0, 15), 0.0);
    }

    #[test]
    fn billed_infer_charges_actual_tokens_and_reports_it() {
        let state = billing_state_with_priced_provider(UUID, 1000.0, "u1", 10.0);
        let body = format!(
            r#"{{"model":"zc://{UUID}","messages":[{{"role":"user","content":"hi"}}],"max_tokens":100}}"#
        );
        let req = infer_req_with_headers(&body, bearer("u1"));

        let resp = handle_infer_with(&state, &req, canned_ok);
        assert_eq!(resp.status, 200);
        let v: serde_json::Value = serde_json::from_slice(&resp.body).unwrap();
        // canned_ok reports 15 total tokens at 1000 zkcr/mtok = 0.015.
        assert!((v["charged_zkcr"].as_f64().unwrap() - 0.015).abs() < 1e-9);
        // The balance dropped by exactly the charge — the reservation
        // remainder was released, not kept.
        let bal = *state.ledger.authoritative_balances.get("u1").unwrap();
        assert!((bal - (10.0 - 0.015)).abs() < 1e-9, "balance {bal}");
        // Vouchers off → commission 0 → the provider's owner earns the full
        // charge; the three legs conserve: requester −0.015, owner +0.015.
        let owner = *state
            .ledger
            .authoritative_balances
            .get("provider-owner")
            .expect("owner credited");
        assert!((owner - 0.015).abs() < 1e-9, "owner payout {owner}");
    }

    #[test]
    fn no_owner_refunds_payout_to_requester() {
        // Own-provider settlement with no owner configured must refund the
        // payout leg — the requester nets only the commission (0 with
        // vouchers off), never a charge that pays nobody.
        let state = billing_state_with_priced_provider(UUID, 1000.0, "u7", 10.0);
        // billing helper sets an owner; strip it via a fresh state clone is
        // not possible (Arc) — rebuild without owner instead.
        let mut raw = BrokerState::new();
        raw.config.api_url = Some("http://dashboard.test".to_string());
        raw.config.api_key = Some("svc-key".to_string());
        raw.config.owner_user_id = None;
        let w = raw.workers.register(WorkerRegistration {
            name: "priced-worker".to_string(),
            uri: "http://10.0.0.5:9000".to_string(),
            worker_type: "llm".to_string(),
            resources: WorkerResources::default(),
            pricing: WorkerPricing::default(),
            tags: vec![],
            max_timeout_secs: 0.0,
            hardware: HardwareInfo::default(),
            wireguard_ip: None,
            is_docker: None,
            source_node: None,
            explicit_local: false,
            provider_type: ProviderType::Specialized,
            served_models: vec![UUID.to_string()],
            price_per_mtok: 1000.0,
        });
        let fp = raw.node_key.fingerprint();
        raw.workers.set_node_fp(&w.id, &fp);
        raw.set_local_mode(true);
        raw.ledger
            .authoritative_balances
            .insert("u7".to_string(), 10.0);
        let state2 = Arc::new(raw);
        drop(state);

        let body = format!(
            r#"{{"model":"zc://{UUID}","messages":[{{"role":"user","content":"hi"}}],"max_tokens":100}}"#
        );
        let req = infer_req_with_headers(&body, bearer("u7"));
        let resp = handle_infer_with(&state2, &req, canned_ok);
        assert_eq!(resp.status, 200);
        // Vouchers off => commission 0 => full payout refunded => net 0.
        let bal = *state2.ledger.authoritative_balances.get("u7").unwrap();
        assert!(
            (bal - 10.0).abs() < 1e-9,
            "requester must net 0, balance {bal}"
        );
    }

    #[test]
    fn unstamped_provider_settlement_refunds_in_full() {
        // A provider with no node identity has no payee; the requester must
        // be made whole (pay nobody, charge nobody — conserving), exactly
        // like /execute's unresolved-peer arm.
        let state = billing_state_with_priced_provider(UUID, 1000.0, "u6", 10.0);
        // Strip the fp the helper stamped.
        let wid = state.workers.list()[0].id.clone();
        state.workers.set_node_fp(&wid, "");
        let body = format!(
            r#"{{"model":"zc://{UUID}","messages":[{{"role":"user","content":"hi"}}],"max_tokens":100}}"#
        );
        let req = infer_req_with_headers(&body, bearer("u6"));

        let resp = handle_infer_with(&state, &req, canned_ok);
        assert_eq!(resp.status, 200);
        let v: serde_json::Value = serde_json::from_slice(&resp.body).unwrap();
        assert_eq!(
            v["charged_zkcr"], 0.0,
            "refunded charge must be reported as 0"
        );
        let bal = *state.ledger.authoritative_balances.get("u6").unwrap();
        assert!(
            (bal - 10.0).abs() < 1e-9,
            "requester made whole, balance {bal}"
        );
        assert!(
            state
                .ledger
                .authoritative_balances
                .get("provider-owner")
                .map(|b| *b == 0.0)
                .unwrap_or(true),
            "nobody may be paid when the charge was refunded"
        );
    }

    #[test]
    fn insufficient_credits_rejects_before_forwarding() {
        // Ceiling for this request is ~0.13 zkcr; the caller has less.
        let state = billing_state_with_priced_provider(UUID, 1000.0, "u2", 0.0001);
        let body = format!(
            r#"{{"model":"zc://{UUID}","messages":[{{"role":"user","content":"hi"}}],"max_tokens":100}}"#
        );
        let req = infer_req_with_headers(&body, bearer("u2"));

        let forwarded = std::sync::atomic::AtomicBool::new(false);
        let resp = handle_infer_with(&state, &req, |_, _| {
            forwarded.store(true, std::sync::atomic::Ordering::SeqCst);
            canned_ok("", &serde_json::Value::Null)
        });
        assert_eq!(resp.status, 402);
        assert!(
            !forwarded.load(std::sync::atomic::Ordering::SeqCst),
            "provider compute must not be spent for a caller who cannot pay"
        );
        // Balance untouched.
        let bal = *state.ledger.authoritative_balances.get("u2").unwrap();
        assert!((bal - 0.0001).abs() < 1e-12);
    }

    #[test]
    fn failed_forward_refunds_the_full_reservation() {
        let state = billing_state_with_priced_provider(UUID, 1000.0, "u3", 5.0);
        let body = format!(
            r#"{{"model":"zc://{UUID}","messages":[{{"role":"user","content":"hi"}}],"max_tokens":100}}"#
        );
        let req = infer_req_with_headers(&body, bearer("u3"));

        let resp = handle_infer_with(&state, &req, canned_err);
        assert_eq!(resp.status, 502);
        let bal = *state.ledger.authoritative_balances.get("u3").unwrap();
        assert!(
            (bal - 5.0).abs() < 1e-9,
            "failed call must cost nothing, balance {bal}"
        );
    }

    #[test]
    fn unpriced_provider_stays_free_for_authed_caller() {
        let state = billing_state_with_priced_provider(UUID, 0.0, "u4", 5.0);
        let body = format!(r#"{{"model":"zc://{UUID}","messages":[]}}"#);
        let req = infer_req_with_headers(&body, bearer("u4"));

        let resp = handle_infer_with(&state, &req, canned_ok);
        assert_eq!(resp.status, 200);
        let v: serde_json::Value = serde_json::from_slice(&resp.body).unwrap();
        assert_eq!(v["charged_zkcr"], 0.0);
        let bal = *state.ledger.authoritative_balances.get("u4").unwrap();
        assert!((bal - 5.0).abs() < 1e-12);
    }

    #[test]
    fn keyless_local_caller_stays_free_even_on_priced_provider() {
        let state = billing_state_with_priced_provider(UUID, 1000.0, "unused", 5.0);
        let body = format!(r#"{{"model":"zc://{UUID}","messages":[]}}"#);
        let req = infer_req(&body);

        let resp = handle_infer_with(&state, &req, canned_ok);
        assert_eq!(resp.status, 200);
        let v: serde_json::Value = serde_json::from_slice(&resp.body).unwrap();
        assert_eq!(v["charged_zkcr"], 0.0);
    }

    #[test]
    fn over_reporting_provider_cannot_charge_past_the_ceiling() {
        let state = billing_state_with_priced_provider(UUID, 1000.0, "u5", 10.0);
        let body = format!(
            r#"{{"model":"zc://{UUID}","messages":[{{"role":"user","content":"hi"}}],"max_tokens":10}}"#
        );
        let req = infer_req_with_headers(&body, bearer("u5"));

        let resp = handle_infer_with(&state, &req, |_, _| {
            Ok(OpenAiChatResponse {
                choices: vec![OpenAiChoice {
                    message: OpenAiMessage {
                        content: "x".to_string(),
                    },
                }],
                usage: OpenAiUsage {
                    prompt_tokens: 1_000_000,
                    completion_tokens: 1_000_000,
                    total_tokens: 2_000_000,
                },
            })
        });
        assert_eq!(resp.status, 200);
        let v: serde_json::Value = serde_json::from_slice(&resp.body).unwrap();
        let charged = v["charged_zkcr"].as_f64().unwrap();
        let ceiling = infer_cost_ceiling(1000.0, req.body.len(), Some(10));
        assert!(
            charged <= ceiling + 1e-12,
            "charged {charged} must not exceed reserved ceiling {ceiling}"
        );
    }

    fn canned_panics(
        _worker_uri: &str,
        _body: &serde_json::Value,
    ) -> Result<OpenAiChatResponse, ForwardError> {
        panic!("forward must not run when the auth gate rejects the request");
    }

    #[test]
    fn remote_mode_without_bearer_returns_401_before_forward() {
        let state = state_with_provider(UUID, "gpu-worker-1");
        state.set_local_mode(false); // remote mode: auth required, like /execute
        let req = infer_req(&format!(
            r#"{{"model":"zc://{UUID}","messages":[{{"role":"user","content":"hi"}}]}}"#
        ));

        let resp = handle_infer_with(&state, &req, canned_panics);
        assert_eq!(resp.status, 401);
        let v: serde_json::Value = serde_json::from_slice(&resp.body).unwrap();
        assert_eq!(
            v["error"],
            "API key required. Set Authorization: Bearer <key>"
        );
    }

    #[test]
    fn remote_mode_with_valid_bearer_proceeds() {
        let state = state_with_provider(UUID, "gpu-worker-1");
        state.set_local_mode(false); // remote mode: auth required, like /execute
        let req = infer_req_with_headers(
            &format!(r#"{{"model":"zc://{UUID}","messages":[{{"role":"user","content":"hi"}}]}}"#),
            vec![(
                "Authorization".to_string(),
                "Bearer zk_user123_abcdef".to_string(),
            )],
        );

        let resp = handle_infer_with(&state, &req, canned_ok);
        assert_eq!(resp.status, 200);
        let v: serde_json::Value = serde_json::from_slice(&resp.body).unwrap();
        assert_eq!(v["content"], "hello there");
        assert_eq!(v["charged_zkcr"], 0.0);
    }

    #[test]
    fn local_mode_without_bearer_is_allowed() {
        // Demo/single-host path: local mode stays keyless, mirroring /execute.
        let state = state_with_provider(UUID, "gpu-worker-1"); // already local_mode(true)
        let req = infer_req(&format!(
            r#"{{"model":"zc://{UUID}","messages":[{{"role":"user","content":"hi"}}]}}"#
        ));

        let resp = handle_infer_with(&state, &req, canned_ok);
        assert_eq!(resp.status, 200);
        let v: serde_json::Value = serde_json::from_slice(&resp.body).unwrap();
        assert_eq!(v["content"], "hello there");
    }
}

fn handle_peer_health(state: &Arc<BrokerState>, request: &BrokerRequest) -> BrokerResponse {
    if let Some(resp) = peer_handshake_auth(state, request) {
        return resp;
    }
    // broker_id is this node's key-derived identity (`zc://node-<fp>`), never
    // an IP — peers cache this from a successful probe (PeerClient::
    // check_health) to answer the IP-free `/brokers` listing without ever
    // touching the peer's base_url/IP.
    //
    // The response body is signed too (`X-Node-Id`/`X-Node-Sig`, same
    // convention as `/peer/peers`) so `discovery::accept_peer` can bind a
    // gossiped/scanned `(fp, url)` hint to the key that actually answers at
    // `url`, rejecting an address-spoofed peer whose health is signed by a
    // different key than the fp it claims.
    let body = serde_json::to_vec(&peer::PeerHealthResponse {
        status: "healthy".to_string(),
        broker_id: state.node_key.node_uri(),
    })
    .unwrap_or_default();
    let sig = state.node_key.sign(&body);
    BrokerResponse::json_bytes(body, 200)
        .with_header("X-Node-Id", &state.node_key.public_b64())
        .with_header("X-Node-Sig", &sig)
}

fn handle_peer_workers(state: &Arc<BrokerState>, request: &BrokerRequest) -> BrokerResponse {
    if let Some(resp) = peer_credit_auth(state, request) {
        return resp;
    }
    // Return only this broker's OWN workers — never re-forward peer-discovered
    // ones (they carry Some(source_node), stamped at peer-sync ingest). The old
    // predicate was "uri is loopback", which silently excluded any own worker
    // registered with a reachable address — exactly what `zc serve --advertise`
    // now produces — so an advertised provider was never visible to the rest
    // of the fleet (zc#172).
    let worker_infos: Vec<WorkerInfo> = state
        .workers
        .list()
        .iter()
        .filter(|w| w.source_node.is_none())
        .map(|w| worker_to_info(w, &state.workers, &state.node_key, false))
        .collect();

    json_response(
        &WorkerListResponse {
            total: worker_infos.len(),
            workers: worker_infos,
        },
        200,
    )
}

/// `GET /peer/peers` — signed full-set peer gossip (roster-gated), the
/// forward-compat primitive that feeds spec #2's delta merge. Unlike the
/// permissive `node_sig_gate` used elsewhere during a mixed-version mesh
/// rollout, gossip must ALWAYS pass a strict node-signature check to be
/// served at all — the request itself is peer-authenticated (`verify_request`
/// via `check_node_sig`).
///
/// The response body is signed too: `X-Node-Id` (this node's pubkey) and
/// `X-Node-Sig` (raw Ed25519 signature over the exact JSON body bytes, per
/// `node_identity::verify_sig`), so `discovery::fetch_gossip` can verify the
/// signer and gate on roster membership before trusting any entry.
fn handle_peer_peers(state: &Arc<BrokerState>, request: &BrokerRequest) -> BrokerResponse {
    if let Err(e) = check_node_sig(
        &state.node_roster,
        &state.node_sig_guard,
        request,
        node_identity::now_secs(),
    ) {
        return error_response(
            &format!("node signature check failed: {e}"),
            "UNAUTHORIZED",
            401,
        );
    }

    let entries: Vec<serde_json::Value> = state
        .peer_manager
        .gossip_entries()
        .into_iter()
        .map(|p| serde_json::json!({"fp": p.fp, "url": p.url, "epoch": p.last_seen}))
        .collect();

    let body = serde_json::to_vec(&serde_json::json!({ "peers": entries })).unwrap_or_default();
    let sig = state.node_key.sign(&body);

    BrokerResponse::json_bytes(body, 200)
        .with_header("X-Node-Id", &state.node_key.public_b64())
        .with_header("X-Node-Sig", &sig)
}

/// `GET /peer/advert` — signed advertisement of this broker's price and
/// aggregated available resources, feeding spec #2's executor selection
/// (task 5). Mirrors `handle_peer_peers` exactly: strict node-signature gate
/// on the inbound request (peer-authenticated, never permissive), and the
/// response body is signed (`X-Node-Id`/`X-Node-Sig`, raw Ed25519 over the
/// exact JSON body bytes) so `discovery::fetch_advert` can verify the signer
/// and roster-gate before trusting it.
///
/// SECURITY: the body carries only fp + price + aggregated resources +
/// epoch — never per-worker IPs/addresses.
fn handle_peer_advert(state: &Arc<BrokerState>, request: &BrokerRequest) -> BrokerResponse {
    if let Err(e) = check_node_sig(
        &state.node_roster,
        &state.node_sig_guard,
        request,
        node_identity::now_secs(),
    ) {
        return error_response(
            &format!("node signature check failed: {e}"),
            "UNAUTHORIZED",
            401,
        );
    }

    let advert = crate::broker::discovery::Advert {
        fp: state.node_key.fingerprint(),
        price_per_hour: state.price.get(),
        resources: state.workers.aggregate_available(),
        epoch: node_identity::now_secs(),
    };

    let body = serde_json::to_vec(&advert).unwrap_or_default();
    let sig = state.node_key.sign(&body);

    BrokerResponse::json_bytes(body, 200)
        .with_header("X-Node-Id", &state.node_key.public_b64())
        .with_header("X-Node-Sig", &sig)
}

fn handle_peer_reserve(state: Arc<BrokerState>, request: &BrokerRequest) -> BrokerResponse {
    if let Some(resp) = peer_credit_auth(&state, request) {
        return resp;
    }

    let body = match body_or_413(request) {
        Ok(b) => b,
        Err(resp) => return resp,
    };
    let req: peer::PeerReserveRequest = match serde_json::from_slice(body) {
        Ok(r) => r,
        Err(e) => return error_response(&format!("Invalid request: {}", e), "BAD_REQUEST", 400),
    };

    match state
        .ledger
        .local_reserve(&req.user_id, req.amount, &req.request_id)
    {
        Ok((reservation_id, balance_before)) => json_response(
            &peer::PeerReserveResponse {
                reservation_id,
                balance_before,
            },
            200,
        ),
        Err(ledger::LedgerError::InsufficientCredits {
            required,
            available,
        }) => json_response(
            &peer::PeerErrorResponse {
                error: format!(
                    "Insufficient credits: need {:.4}, have {:.4}",
                    required, available
                ),
                code: "INSUFFICIENT_CREDITS".to_string(),
            },
            402,
        ),
        // 503, not 402: we could not determine the balance, so this is our
        // failure to authorize rather than the caller being out of credits.
        // Clients switch on `code`, so it gets its own rather than being
        // flattened into LEDGER_ERROR.
        Err(e @ ledger::LedgerError::BalanceUnavailable { .. }) => json_response(
            &peer::PeerErrorResponse {
                error: e.to_string(),
                code: "BALANCE_UNAVAILABLE".to_string(),
            },
            503,
        ),
        Err(e) => error_response(&e.to_string(), "LEDGER_ERROR", 500),
    }
}

fn handle_peer_commit(state: Arc<BrokerState>, request: &BrokerRequest) -> BrokerResponse {
    if let Some(resp) = peer_credit_auth(&state, request) {
        return resp;
    }

    let body = match body_or_413(request) {
        Ok(b) => b,
        Err(resp) => return resp,
    };
    let req: peer::PeerCommitRequest = match serde_json::from_slice(body) {
        Ok(r) => r,
        Err(e) => return error_response(&format!("Invalid request: {}", e), "BAD_REQUEST", 400),
    };

    match state
        .ledger
        .local_commit(&req.reservation_id, req.actual_cost)
    {
        Ok(balance_after) => json_response(&peer::PeerCommitResponse { balance_after }, 200),
        Err(e) => error_response(&e.to_string(), "LEDGER_ERROR", 500),
    }
}

fn handle_peer_cancel(state: Arc<BrokerState>, request: &BrokerRequest) -> BrokerResponse {
    if let Some(resp) = peer_credit_auth(&state, request) {
        return resp;
    }

    let body = match body_or_413(request) {
        Ok(b) => b,
        Err(resp) => return resp,
    };
    let req: peer::PeerCancelRequest = match serde_json::from_slice(body) {
        Ok(r) => r,
        Err(e) => return error_response(&format!("Invalid request: {}", e), "BAD_REQUEST", 400),
    };

    if let Err(e) = state.ledger.local_cancel(&req.reservation_id) {
        eprintln!(
            "  [BILLING] local_cancel failed for {}: {}",
            req.reservation_id, e
        );
    }
    json_response(&serde_json::json!({"status": "ok"}), 200)
}

fn handle_peer_balance(state: &Arc<BrokerState>, request: &BrokerRequest) -> BrokerResponse {
    if let Some(resp) = peer_credit_auth(state, request) {
        return resp;
    }

    let user_id = request
        .query
        .split('&')
        .find(|p| p.starts_with("user_id="))
        .map(|p| p[8..].to_string())
        .unwrap_or_default();

    if user_id.is_empty() {
        return error_response("Missing user_id parameter", "BAD_REQUEST", 400);
    }

    let balance = state.ledger.load_balance_if_needed(&user_id);
    json_response(&peer::PeerBalanceResponse { user_id, balance }, 200)
}

fn handle_peer_earn(state: Arc<BrokerState>, request: &BrokerRequest) -> BrokerResponse {
    if let Some(resp) = peer_credit_auth(&state, request) {
        return resp;
    }

    let body = match body_or_413(request) {
        Ok(b) => b,
        Err(resp) => return resp,
    };
    let req: peer::PeerEarnRequest = match serde_json::from_slice(body) {
        Ok(r) => r,
        Err(e) => return error_response(&format!("Invalid request: {}", e), "BAD_REQUEST", 400),
    };

    let owner_user_id = match state.config.owner_user_id.as_deref() {
        Some(uid) => uid.to_string(),
        None => {
            return error_response("No owner configured on this broker", "NOT_CONFIGURED", 503);
        }
    };

    let earn_request_id = format!("earn-{}", req.request_id);

    // No dashboard configured (standalone/local-only P2P) — there's nothing to
    // deliver, so mirror `Ledger::publish_transaction`'s existing no-op-when-
    // no-api-configured behavior: skip the WAL entirely rather than append an
    // `Earned` row that could NEVER be marked `Committed` (flush_to_api is
    // only reachable when api_url/api_key are set). Without this guard, a
    // standalone broker would re-replay and re-mint the same earn on every
    // restart forever.
    let dashboard_configured = state.config.api_url.is_some() && state.config.api_key.is_some();

    if dashboard_configured {
        // WAL the earn BEFORE crediting in-memory: if we crash between here and
        // the dashboard flush, replay re-applies it. Left as `Earned` (non-terminal)
        // — it's only marked `Committed` once the periodic tx_buffer flush has
        // actually delivered it to the dashboard (see flush::flush_to_api), so a
        // crash before delivery always leaves it replay-eligible.
        let _ = state.wal.append(&WalEntry {
            request_id: earn_request_id.clone(),
            user_id: owner_user_id.clone(),
            reservation_id: String::new(),
            estimated_cost: req.amount,
            actual_cost: Some(req.amount),
            worker_id: req.worker_id.clone(),
            duration_ms: Some(req.duration_ms),
            timestamp: chrono::Utc::now(),
            status: WalStatus::Earned,
        });
    }

    // Credit in-memory balance
    let balance_after = state.ledger.local_add_credits(&owner_user_id, req.amount);

    // Queue earn transaction for dashboard sync (type "credit" maps to "credit_purchase")
    state.tx_buffer.push_transaction(BufferedTransaction {
        request_id: earn_request_id,
        user_id: owner_user_id.clone(),
        tx_type: "credit".to_string(),
        amount: req.amount,
        balance_after,
        worker_id: req.worker_id.clone(),
        duration_ms: req.duration_ms,
        source_node: state.config.node_name.clone(),
        worker_name: Some(req.worker_id.clone()),
        worker_uri: None,
        price_per_hour: 0.0,
    });
    state
        .tx_buffer
        .snapshot_balance(&owner_user_id, balance_after);

    eprintln!(
        "  [EARN] Worker {} earned {:.6} credits from user {} → owner {} (balance now {:.6})",
        req.worker_id, req.amount, req.requesting_user, owner_user_id, balance_after
    );

    json_response(
        &serde_json::json!({"status": "ok", "balance_after": balance_after}),
        200,
    )
}

fn handle_peer_identity(state: &Arc<BrokerState>, request: &BrokerRequest) -> BrokerResponse {
    if let Some(resp) = peer_handshake_auth(state, request) {
        return resp;
    }

    let workers: Vec<task_board::WorkerSummary> = state
        .workers
        .list()
        .iter()
        .filter(|w| state.is_local_worker(&w.uri))
        .map(|w| task_board::WorkerSummary {
            name: w.name.clone(),
            price_per_hour: w.pricing.price_per_hour,
            status: format!("{:?}", w.status),
            cpus: w.resources.cpus_total,
            memory_bytes: w.resources.memory_total,
            gpus: w.resources.gpus_total,
        })
        .collect();

    let identity = task_board::PeerIdentity {
        owner_user_id: state.config.owner_user_id.clone().unwrap_or_default(),
        node_name: state.config.node_name.clone().unwrap_or_default(),
        verified: state.is_billing_enabled(),
        workers,
        quic_port: state.quic_port.load(Ordering::Relaxed),
        // This build supports the two-phase reserve→commit/cancel offer protocol.
        supports_two_phase: true,
    };

    json_response(&identity, 200)
}

/// Select a matching local worker for an offer (same filters as one-phase
/// execution), round-robin. None when no local worker matches.
fn select_local_worker_for_offer(
    state: &BrokerState,
    offer: &task_board::TaskOffer,
) -> Option<Worker> {
    // NOTE: `offer.target_worker` is intentionally NOT consulted here. Worker
    // selection is this broker's private authority — a client (or a peer
    // relaying a client's request) never names a worker directly. See
    // docs/superpowers/specs/2026-07-11-zc-key-derived-identity-amendment.md
    // "Routing addendum".
    let local_workers: Vec<Worker> = state
        .workers
        .healthy()
        .into_iter()
        .filter(|w| state.is_local_worker(&w.uri))
        .filter(|w| w.pricing.price_per_hour <= offer.max_price_per_hour)
        .filter(|w| {
            offer
                .worker_type
                .as_ref()
                .is_none_or(|wt| w.worker_type.as_str() == wt.as_str())
        })
        .collect();
    if local_workers.is_empty() {
        return None;
    }
    let idx = (REQUEST_COUNTER.fetch_add(1, Ordering::SeqCst) as usize) % local_workers.len();
    Some(local_workers[idx].clone())
}

/// Two-phase RESERVE: pick + quota-reserve a local worker and stash the offer
/// (NOT executed), awaiting a commit/cancel. Returns TaskAccept or TaskReject.
pub fn reserve_offer(
    state: &BrokerState,
    offer: &task_board::TaskOffer,
) -> Result<task_board::TaskAccept, task_board::TaskReject> {
    let worker =
        select_local_worker_for_offer(state, offer).ok_or_else(|| task_board::TaskReject {
            task_id: offer.task_id.clone(),
            reason: "No matching local worker".to_string(),
        })?;
    if !state.workers.try_reserve_quota(&worker.id) {
        return Err(task_board::TaskReject {
            task_id: offer.task_id.clone(),
            reason: "Worker quota exhausted".to_string(),
        });
    }
    let estimated_cost = worker.pricing.estimate_cost(offer.estimated_duration_secs);
    state.pending_offers.insert(
        offer.task_id.clone(),
        super::PendingOffer {
            offer: offer.clone(),
            worker_id: worker.id.clone(),
            created: Instant::now(),
        },
    );
    Ok(task_board::TaskAccept {
        task_id: offer.task_id.clone(),
        estimated_cost,
        worker_name: worker.name.clone(),
        executor_owner: state.config.owner_user_id.clone().unwrap_or_default(),
        price_per_hour: worker.pricing.price_per_hour,
    })
}

/// How many reserved-but-uncommitted offers each worker holds (worker id →
/// count). `GET /workers` adds these to `active_requests`: a reservation pins
/// its worker until the commit runs on it, so a drain must not read that
/// worker as idle in the meantime.
pub fn pending_reservations(state: &BrokerState) -> std::collections::HashMap<String, u32> {
    let mut counts = std::collections::HashMap::new();
    for entry in state.pending_offers.iter() {
        *counts.entry(entry.value().worker_id.clone()).or_insert(0) += 1;
    }
    counts
}

/// Two-phase CANCEL: release a reserved offer's quota slot. Idempotent.
pub fn cancel_offer(state: &BrokerState, task_id: &str) {
    if let Some((_, pending)) = state.pending_offers.remove(task_id) {
        state.workers.cancel_quota_reservation(&pending.worker_id);
    }
}

/// Two-phase COMMIT: remove and return the reserved offer for execution.
/// None when the task is unknown or already committed/cancelled/expired.
pub fn take_committed(state: &BrokerState, task_id: &str) -> Option<super::PendingOffer> {
    state.pending_offers.remove(task_id).map(|(_, p)| p)
}

/// Release reserved offers older than `ttl` (a lost commit/cancel) so worker
/// slots don't leak. Called periodically by the broker background loop.
pub fn sweep_expired_offers(state: &BrokerState, ttl: std::time::Duration) {
    let stale: Vec<String> = state
        .pending_offers
        .iter()
        .filter(|e| e.value().created.elapsed() > ttl)
        .map(|e| e.key().clone())
        .collect();
    for task_id in stale {
        cancel_offer(state, &task_id);
    }
}

/// Execute a task offer on a local worker. Used by HTTP peer offer and by subscription client.
pub fn execute_offer_locally(
    state: &BrokerState,
    offer: &task_board::TaskOffer,
) -> Result<task_board::TaskResult, task_board::TaskReject> {
    let worker =
        select_local_worker_for_offer(state, offer).ok_or_else(|| task_board::TaskReject {
            task_id: offer.task_id.clone(),
            reason: "No matching local worker".to_string(),
        })?;
    run_offer_on(state, offer, &worker)
}

/// Run an offer on a specific (already-selected, possibly pre-reserved) worker:
/// decode the payload, forward to the worker, build the TaskResult. Used by the
/// one-phase path (execute_offer_locally) and by the two-phase commit (which
/// runs on the worker it reserved).
fn run_offer_on(
    state: &BrokerState,
    offer: &task_board::TaskOffer,
    worker: &Worker,
) -> Result<task_board::TaskResult, task_board::TaskReject> {
    // A P2P offer must count toward active_requests for the whole forward
    // (through the response read), exactly like /execute — otherwise a
    // draining worker mid-P2P-job reports 0 active requests and the agent
    // sends SIGTERM before the job completes (spec §6.5). Held for the entire
    // function body; dropped (decrementing) on every return path, including
    // the early payload-decode error below.
    let _active_guard = state.workers.active_guard(&worker.id);

    let payload = base64::Engine::decode(
        &base64::engine::general_purpose::STANDARD,
        &offer.payload_b64,
    )
    .map_err(|e| task_board::TaskReject {
        task_id: offer.task_id.clone(),
        reason: format!("Invalid payload encoding: {}", e),
    })?;

    let worker_uri = format!("{}/execute", worker.uri.trim_end_matches('/'));
    let start = Instant::now();
    let timeout = if offer.timeout_secs > 0.0 {
        offer.timeout_secs
    } else {
        300.0
    };
    let agent = ureq::Agent::new_with_config(
        ureq::Agent::config_builder()
            .timeout_global(Some(std::time::Duration::from_secs_f64(timeout + 5.0)))
            .build(),
    );

    let forward_result = agent
        .post(&worker_uri)
        .header("Content-Type", "application/octet-stream")
        .header("X-Zakuro-Request-Id", &offer.task_id)
        .header("X-Zakuro-Timeout-Secs", &format!("{:.1}", timeout))
        .send(&payload);

    let duration_ms = start.elapsed().as_secs_f64() * 1000.0;

    match forward_result {
        Ok(response) => {
            let actual_cost = worker.pricing.estimate_cost(duration_ms / 1000.0);
            let worker_pid = response
                .headers()
                .get("X-Zakuro-Pid")
                .and_then(|v| v.to_str().ok())
                .map(|s| s.to_string());
            let mut response_body = Vec::new();
            let _ = response
                .into_body()
                .into_reader()
                .read_to_end(&mut response_body);
            let result_b64 =
                base64::Engine::encode(&base64::engine::general_purpose::STANDARD, &response_body);
            let executor_owner = state.config.owner_user_id.clone().unwrap_or_default();
            // Redeem the voucher nonce (double-spend guard). Best-effort and only
            // when vouchers are in use; settlement still rides the existing path.
            redeem_offer_voucher(state, offer, actual_cost);
            let mut result = task_board::TaskResult {
                task_id: offer.task_id.clone(),
                payload_b64: result_b64,
                duration_ms,
                actual_cost,
                worker_name: worker.name.clone(),
                worker_uri: worker.zc_uri(),
                price_per_hour: worker.pricing.price_per_hour,
                executor_owner,
                worker_pid,
                executor_node_uri: state.node_key.node_uri(),
                executor_node_id: None,
                executor_sig: None,
            };
            result.executor_node_id = Some(state.node_key.public_b64());
            result.executor_sig = Some(state.node_key.sign(&task_board::receipt_bytes(&result)));
            Ok(result)
        }
        Err(e) => Err(task_board::TaskReject {
            task_id: offer.task_id.clone(),
            reason: format!("Worker execution failed: {}", e),
        }),
    }
}

fn handle_peer_task_offer(state: Arc<BrokerState>, request: &BrokerRequest) -> BrokerResponse {
    if let Some(resp) = peer_credit_auth(&state, request) {
        return resp;
    }

    let body = match body_or_413(request) {
        Ok(b) => b,
        Err(resp) => return resp,
    };
    let offer: task_board::TaskOffer = match serde_json::from_slice(body) {
        Ok(o) => o,
        Err(e) => return error_response(&format!("Invalid task offer: {}", e), "BAD_REQUEST", 400),
    };

    // NOTE: `offer.target_worker` is intentionally NOT consulted here — a
    // client-supplied worker target is not a valid reason to accept/reject a
    // task offer. Worker selection remains the accepting broker's private
    // authority (see select_local_worker_for_offer).

    // Zero-trust authorization: the dashboard-signed voucher must cover this spend
    // (no-op unless ZAKURO_REQUIRE_VOUCHER is set). Reject before reserving/executing.
    if let Err(reason) = verify_offer_voucher(&state, &offer) {
        return error_response(
            &format!("voucher check failed: {reason}"),
            "VOUCHER_INVALID",
            402,
        );
    }

    if offer.two_phase {
        // Two-phase: RESERVE a worker slot and return an accept; do NOT execute
        // until a commit arrives. A cancel (or TTL sweep) releases the slot.
        match reserve_offer(&state, &offer) {
            Ok(accept) => json_response(&accept, 200),
            Err(reject) => json_response(&reject, 404),
        }
    } else {
        // One-phase (legacy / non-capable peers): execute immediately.
        match execute_offer_locally(&state, &offer) {
            Ok(result) => json_response(&result, 200),
            Err(reject) => json_response(&reject, 404),
        }
    }
}

/// Two-phase COMMIT: execute the previously-reserved offer on its reserved
/// worker and return the result. Unknown/expired task → reject.
fn handle_peer_task_commit(state: Arc<BrokerState>, request: &BrokerRequest) -> BrokerResponse {
    if let Some(resp) = peer_credit_auth(&state, request) {
        return resp;
    }
    let body = match body_or_413(request) {
        Ok(b) => b,
        Err(resp) => return resp,
    };
    let commit: task_board::TaskCommit = match serde_json::from_slice(body) {
        Ok(c) => c,
        Err(e) => return error_response(&format!("Invalid commit: {}", e), "BAD_REQUEST", 400),
    };
    match take_committed(&state, &commit.task_id) {
        Some(pending) => match state.workers.get(&pending.worker_id) {
            Some(worker) => match run_offer_on(&state, &pending.offer, &worker) {
                Ok(result) => json_response(&result, 200),
                Err(reject) => json_response(&reject, 404),
            },
            None => json_response(
                &task_board::TaskReject {
                    task_id: commit.task_id.clone(),
                    reason: "Reserved worker no longer available".to_string(),
                },
                404,
            ),
        },
        None => json_response(
            &task_board::TaskReject {
                task_id: commit.task_id.clone(),
                reason: "Unknown or expired reservation".to_string(),
            },
            404,
        ),
    }
}

/// Two-phase CANCEL: release a previously-reserved offer (no execution).
fn handle_peer_task_cancel(state: Arc<BrokerState>, request: &BrokerRequest) -> BrokerResponse {
    if let Some(resp) = peer_credit_auth(&state, request) {
        return resp;
    }
    let body = match body_or_413(request) {
        Ok(b) => b,
        Err(resp) => return resp,
    };
    let cancel: task_board::TaskCancel = match serde_json::from_slice(body) {
        Ok(c) => c,
        Err(e) => return error_response(&format!("Invalid cancel: {}", e), "BAD_REQUEST", 400),
    };
    cancel_offer(&state, &cancel.task_id);
    json_response(
        &serde_json::json!({ "status": "cancelled", "task_id": cancel.task_id }),
        200,
    )
}

// ── execute helpers ──────────────────────────────────────────────────────────

/// Forward a request body to a worker, with an optional hard timeout, reusing
/// the broker's shared connection-pooled agent (no fresh TCP+TLS per call).
/// The per-request timeout is set on the request builder so a single agent
/// serves every worker call (async-phase-2: connection pooling).
fn forward_to_worker(
    agent: &ureq::Agent,
    worker_uri: &str,
    body: &[u8],
    request_id: &str,
    effective_timeout: f64,
) -> Result<ureq::http::Response<ureq::Body>, ureq::Error> {
    if effective_timeout > 0.0 {
        agent
            .post(worker_uri)
            .config()
            .timeout_global(Some(std::time::Duration::from_secs_f64(
                effective_timeout + 5.0,
            )))
            .build()
            .header("Content-Type", "application/octet-stream")
            .header("X-Zakuro-Request-Id", request_id)
            .header(
                "X-Zakuro-Timeout-Secs",
                &format!("{:.1}", effective_timeout),
            )
            .send(body)
    } else {
        agent
            .post(worker_uri)
            .header("Content-Type", "application/octet-stream")
            .header("X-Zakuro-Request-Id", request_id)
            .send(body)
    }
}

struct WorkerReply {
    status: u16,
    headers: Vec<(String, String)>,
    body: Vec<u8>,
}

async fn forward_to_worker_async(
    client: &reqwest::Client,
    worker_uri: &str,
    body: Vec<u8>,
    request_id: &str,
    effective_timeout: f64,
) -> Result<WorkerReply, String> {
    let mut req = client
        .post(worker_uri)
        .header("Content-Type", "application/octet-stream")
        .header("X-Zakuro-Request-Id", request_id)
        .body(body);
    if effective_timeout > 0.0 {
        req = req
            .header("X-Zakuro-Timeout-Secs", format!("{:.1}", effective_timeout))
            .timeout(std::time::Duration::from_secs_f64(effective_timeout + 5.0));
    }
    let resp = req.send().await.map_err(|e| e.to_string())?;
    let status = resp.status().as_u16();
    let headers = resp
        .headers()
        .iter()
        .map(|(k, v)| {
            (
                k.as_str().to_lowercase(),
                v.to_str().unwrap_or("").to_string(),
            )
        })
        .collect();
    let body = resp.bytes().await.map_err(|e| e.to_string())?.to_vec();
    Ok(WorkerReply {
        status,
        headers,
        body,
    })
}

/// Convert a ureq HTTP response into a `WorkerReply`.
///
/// Header names are lowercased so that downstream code can do
/// case-insensitive lookups by comparing against lowercase literals.
fn into_worker_reply(resp: ureq::http::Response<ureq::Body>) -> WorkerReply {
    use std::io::Read as _;
    let status = resp.status().as_u16();
    let headers = resp
        .headers()
        .iter()
        .map(|(k, v)| {
            (
                k.as_str().to_lowercase(),
                v.to_str().unwrap_or("").to_string(),
            )
        })
        .collect();
    let mut body = Vec::new();
    let _ = resp.into_body().into_reader().read_to_end(&mut body);
    WorkerReply {
        status,
        headers,
        body,
    }
}

/// Look up a header value from a `WorkerReply` by name, case-insensitively.
///
/// Because `into_worker_reply` lowercases all names, passing a lowercase
/// literal is sufficient.  Mixed-case callers work too since we normalise
/// the needle as well.
fn reply_header<'a>(reply: &'a WorkerReply, name: &str) -> Option<&'a str> {
    let needle = name.to_lowercase();
    reply
        .headers
        .iter()
        .find(|(k, _)| *k == needle)
        .map(|(_, v)| v.as_str())
}

/// Post-forward half of execute: WAL EXECUTED, commit/refund, WAL COMMITTED,
/// ledger/buffer updates, response building, and the synchronous retry path.
///
/// `forward` is the outcome of calling `forward_to_worker` (converted to a
/// `WorkerReply` via `into_worker_reply`) or an error string.
///
/// NOTE: Callers must call `state.workers.increment_active(&p.worker.id)` before
/// forwarding. `execute_finish` is responsible for decrementing `p.worker.id`
/// exactly once on every exit path (success via `record_request`, and
/// timeout/no-worker/retry-exhausted via `decrement_active`).
///
/// NOTE: The one-shot retry inside this function is still synchronous
/// (`forward_to_worker` + `into_worker_reply`). The primary /execute forward
/// runs async via `forward_to_worker_async`; this sync path serves the retry
/// and non-axum callers (bench).
fn execute_finish(
    state: &Arc<BrokerState>,
    verbose: bool,
    p: PreparedForward,
    forward: Result<WorkerReply, String>,
) -> BrokerResponse {
    let worker_name = p.worker.name.clone();
    let duration_ms = p.start.elapsed().as_secs_f64() * 1000.0;

    match forward {
        Ok(reply) => {
            // Calculate actual cost (free for local worker)
            let actual_cost = if p.is_local {
                0.0
            } else {
                let actual_duration_secs = duration_ms / 1000.0;
                p.worker.pricing.estimate_cost(actual_duration_secs)
            };

            // WAL: mark as executed (critical — if we crash here, recovery will commit)
            if !p.is_local {
                let _ = state.wal.update_status(
                    &p.request_id,
                    WalStatus::Executed,
                    Some(actual_cost),
                    Some(duration_ms),
                );
            }

            // Commit reservation + publish transaction — authority-aware
            let credits_remaining = commit_credits(
                state,
                &p.authority,
                p.is_local,
                &p.reservation_id,
                actual_cost,
                p.balance_before,
                &p.request_id,
                &p.user_id,
                &p.worker,
                duration_ms,
                p.commission_c,
                &p.voucher_task_nonce,
            );

            // WAL: mark as committed
            if !p.is_local {
                let _ = state.wal.update_status(
                    &p.request_id,
                    WalStatus::Committed,
                    Some(actual_cost),
                    Some(duration_ms),
                );
            }

            // Update worker stats — record_request also decrements the in-flight
            // counter (via WorkerRegistry::decrement_active internally).
            state
                .workers
                .record_request(&p.worker.id, duration_ms, true);
            state.active_requests.remove(&p.request_id);

            // Header lookups use lowercase names (into_worker_reply lowercases).
            let worker_pid = reply_header(&reply, "x-zakuro-pid").map(|s| s.to_string());
            let worker_ip = reply_header(&reply, "x-zakuro-ip")
                .map(|s| s.to_string())
                .or_else(|| {
                    let u = p
                        .worker
                        .uri
                        .strip_prefix("http://")
                        .unwrap_or(&p.worker.uri);
                    u.split(':').next().map(|s| s.to_string())
                });

            let response_body = reply.body;

            // Register instance affinity: pin instance_id → worker_id
            if p.instance_action.as_deref() == Some("create_instance") {
                if let Some(ref iid) = p.instance_id {
                    state
                        .instance_registry
                        .insert(iid.clone(), p.worker.id.clone());
                }
            }

            // Log transaction with agreed price and worker identity (owner_id, pid, ip)
            let action_label = match p.instance_action.as_deref() {
                Some("create_instance") => "CREATE_INST",
                Some("call_method") => "CALL_METHOD",
                _ => "EXECUTE",
            };
            log_transaction_with_worker_info(
                state,
                verbose,
                p.tx_num,
                &p.user_id,
                action_label,
                actual_cost,
                credits_remaining,
                Some(&worker_name),
                duration_ms,
                "OK",
                Some(p.worker.pricing.price_per_hour),
                state.config.owner_user_id.as_deref(),
                worker_pid.as_deref(),
                worker_ip.as_deref(),
                Some(&p.request_id),
            );

            let headers = [
                header_or("Content-Type", "application/octet-stream"),
                header_or("X-Zakuro-Request-Id", &p.request_id),
                header_or("X-Zakuro-Worker", worker_name.as_str()),
                header_or("X-Zakuro-Cost", &format!("{:.6}", actual_cost)),
                header_or(
                    "X-Zakuro-Credits-Remaining",
                    &format!("{:.6}", credits_remaining),
                ),
                header_or("X-Zakuro-Duration-Ms", &format!("{:.2}", duration_ms)),
                header_or("X-Zakuro-Transport", "local"),
            ];
            let mut resp = BrokerResponse {
                status: 200,
                headers: Vec::new(),
                body: response_body,
            };
            resp.headers.extend(headers);
            resp
        }
        Err(e) => {
            // When a timeout fires, the worker may still be running. Charge for
            // the wall-clock time the request was in flight so a malicious user
            // can't abuse a long-running function for free.
            let is_timeout = e.contains("timed out") || e.contains("Timeout");

            let timeout_cost = if is_timeout && !p.is_local {
                let elapsed_secs = duration_ms / 1000.0;
                // Never charge more than was reserved (the reservation is itself
                // capped at the user's balance): elapsed-time billing on a slow
                // worker could otherwise exceed the hold (audit M2).
                capped_charge(
                    p.worker.pricing.estimate_cost(elapsed_secs),
                    p.reservation_amount,
                )
            } else {
                0.0
            };

            if is_timeout {
                // ── Timeout: partial charge, no retry ────────────────────────
                if !p.is_local && timeout_cost > 0.0 {
                    match &p.authority {
                        Authority::Local => {
                            if let Err(e) =
                                state.ledger.local_commit(&p.reservation_id, timeout_cost)
                            {
                                eprintln!(
                                    "  [BILLING] local_commit failed for {}: {}",
                                    p.request_id, e
                                );
                            }
                            state.tx_buffer.push_transaction(BufferedTransaction {
                                request_id: p.request_id.clone(),
                                user_id: p.user_id.clone(),
                                tx_type: "commit".to_string(),
                                amount: timeout_cost,
                                balance_after: p.balance_before - timeout_cost,
                                worker_id: p.worker.id.clone(),
                                duration_ms,
                                source_node: state.config.node_name.clone(),
                                worker_name: Some(p.worker.name.clone()),
                                worker_uri: Some(p.worker.uri.clone()),
                                price_per_hour: p.worker.pricing.price_per_hour,
                            });
                        }
                        Authority::Peer(url) => {
                            if let Some(client) = state.peer_manager.get_client(url) {
                                let _ = client.commit(&p.reservation_id, timeout_cost);
                            } else {
                                let _ = state.ledger.commit(&p.reservation_id, timeout_cost);
                            }
                            state.ledger.publish_transaction(
                                &p.request_id,
                                &p.user_id,
                                "commit",
                                timeout_cost,
                                p.balance_before - timeout_cost,
                                &p.worker.id,
                                duration_ms,
                                state.config.node_name.as_deref(),
                            );
                        }
                        Authority::Standalone => {
                            let _ = state.ledger.commit(&p.reservation_id, timeout_cost);
                            state.ledger.publish_transaction(
                                &p.request_id,
                                &p.user_id,
                                "commit",
                                timeout_cost,
                                p.balance_before - timeout_cost,
                                &p.worker.id,
                                duration_ms,
                                state.config.node_name.as_deref(),
                            );
                        }
                    }
                    let _ = state.wal.update_status(
                        &p.request_id,
                        WalStatus::Committed,
                        Some(timeout_cost),
                        Some(duration_ms),
                    );
                }
                state.active_requests.remove(&p.request_id);
                log_transaction(
                    state,
                    verbose,
                    p.tx_num,
                    &p.user_id,
                    "EXECUTE",
                    timeout_cost,
                    p.balance_before - timeout_cost,
                    Some(&worker_name),
                    duration_ms,
                    "FAIL",
                );
                // Don't mark as unhealthy — the worker is fine, just slow
                // Decrement the outer worker's in-flight counter (no RAII guard in this path).
                state.workers.decrement_active(&p.worker.id);
                return error_response(
                    &format!(
                        "Request timed out after {:.1}s (charged {:.6} credits)",
                        duration_ms / 1000.0,
                        timeout_cost
                    ),
                    "TIMEOUT",
                    504,
                );
            }

            // ── Non-timeout failure: cancel reservation + retry on another worker ─
            // Mark the failed worker unhealthy so it won't be selected again.
            state.workers.mark_unhealthy(&p.worker.id);
            // Return the pre-committed quota slot so it doesn't count against the worker.
            state.workers.cancel_quota_reservation(&p.worker.id);

            // Cancel reservation (full refund) for the failed attempt.
            if !p.is_local {
                cancel_credits(
                    state,
                    &p.authority,
                    &p.reservation_id,
                    &p.request_id,
                    &p.user_id,
                    &p.worker.id,
                    p.balance_before,
                    duration_ms,
                );
            }
            state.active_requests.remove(&p.request_id);
            // Decrement the outer worker's in-flight counter (no RAII guard in this path).
            state.workers.decrement_active(&p.worker.id);

            // Try remaining healthy workers (up to MAX_RETRIES attempts).
            const MAX_RETRIES: usize = 2;
            let mut tried_ids: Vec<String> = vec![p.worker.id.clone()];

            for attempt in 1..=MAX_RETRIES {
                // Find next healthy worker not yet attempted
                let next_worker = {
                    let healthy = state.workers.healthy();
                    healthy.into_iter().find(|w| !tried_ids.contains(&w.id))
                };

                let next = match next_worker {
                    Some(w) => w,
                    None => {
                        log_transaction(
                            state,
                            verbose,
                            p.tx_num,
                            &p.user_id,
                            "EXECUTE",
                            0.0,
                            p.balance_before,
                            Some(&worker_name),
                            duration_ms,
                            "FAIL",
                        );
                        return error_response(
                            &format!(
                                "Worker unreachable and no fallback available (tried {} worker(s))",
                                tried_ids.len()
                            ),
                            "NO_WORKERS",
                            503,
                        );
                    }
                };

                let retry_uri = format!("{}/execute", next.uri.trim_end_matches('/'));
                let retry_name = next.name.clone();
                tried_ids.push(next.id.clone());

                // Atomically reserve a quota slot on the retry worker.
                // Skip it if its quota is already full.
                if !state.workers.try_reserve_quota(&next.id) {
                    continue;
                }

                eprintln!(
                    "  [RETRY] attempt {}/{} → {} ({})",
                    attempt, MAX_RETRIES, retry_name, retry_uri
                );

                // Per-attempt in-flight guard: decrements on a failed attempt
                // (loop continues → drop) or is disarmed on success below.
                let mut retry_guard = state.workers.active_guard(&next.id);
                state
                    .active_requests
                    .insert(p.request_id.clone(), next.id.clone());

                let retry_start = Instant::now();
                // Retry is still synchronous in this phase; the async path covers only
                // the first forward (see task-6).
                let retry_result = forward_to_worker(
                    &state.http_client,
                    &retry_uri,
                    &p.body,
                    &p.request_id,
                    p.effective_timeout,
                )
                .map(into_worker_reply)
                .map_err(|e| e.to_string());

                let retry_duration_ms = retry_start.elapsed().as_secs_f64() * 1000.0;

                match retry_result {
                    Ok(retry_reply) => {
                        let actual_cost = if p.is_local {
                            0.0
                        } else {
                            next.pricing.estimate_cost(retry_duration_ms / 1000.0)
                        };

                        // Billing for the retry: reserve then immediately commit (execution already done).
                        let retry_reservation_id = if !p.is_local {
                            let res_id = format!("{}-retry{}", p.request_id, attempt);
                            match &p.authority {
                                Authority::Local => {
                                    let _ = state.ledger.local_reserve(
                                        &p.user_id,
                                        actual_cost,
                                        &res_id,
                                    );
                                    let _ = state.ledger.local_commit(&res_id, actual_cost);
                                }
                                Authority::Peer(url) => {
                                    // Forward reserve + immediate commit to authoritative peer.
                                    if let Some(client) = state.peer_manager.get_client(url) {
                                        if client.reserve(&p.user_id, actual_cost, &res_id).is_ok()
                                        {
                                            let _ = client.commit(&res_id, actual_cost);
                                        }
                                    }
                                }
                                Authority::Standalone => {
                                    // Standalone: reserve from local_credits (already loaded) + commit.
                                    if state
                                        .ledger
                                        .reserve(&p.user_id, actual_cost, &res_id)
                                        .is_ok()
                                    {
                                        let _ = state.ledger.commit(&res_id, actual_cost);
                                    }
                                }
                            }
                            res_id
                        } else {
                            String::new()
                        };

                        if !p.is_local {
                            let _ = state.wal.update_status(
                                &p.request_id,
                                WalStatus::Executed,
                                Some(actual_cost),
                                Some(retry_duration_ms),
                            );
                            let _ = state.wal.update_status(
                                &p.request_id,
                                WalStatus::Committed,
                                Some(actual_cost),
                                Some(retry_duration_ms),
                            );
                        }

                        state
                            .workers
                            .record_request(&next.id, retry_duration_ms, true);
                        retry_guard.disarm();
                        state.active_requests.remove(&p.request_id);

                        let credits_remaining = if p.is_local {
                            p.balance_before
                        } else {
                            p.balance_before - actual_cost
                        };

                        // Queue retry transaction to tx_buffer (flushed periodically to dashboard)
                        state.tx_buffer.push_transaction(BufferedTransaction {
                            request_id: format!("{}-retry{}", p.request_id, attempt),
                            user_id: p.user_id.clone(),
                            tx_type: "commit".to_string(),
                            amount: actual_cost,
                            balance_after: credits_remaining,
                            worker_id: next.id.clone(),
                            duration_ms: retry_duration_ms,
                            source_node: state.config.node_name.clone(),
                            worker_name: Some(next.name.clone()),
                            worker_uri: Some(next.uri.clone()),
                            price_per_hour: next.pricing.price_per_hour,
                        });

                        let action_label = match p.instance_action.as_deref() {
                            Some("create_instance") => "CREATE_INST",
                            Some("call_method") => "CALL_METHOD",
                            _ => "EXECUTE",
                        };
                        log_transaction(
                            state,
                            verbose,
                            p.tx_num,
                            &p.user_id,
                            action_label,
                            actual_cost,
                            credits_remaining,
                            Some(&retry_name),
                            retry_duration_ms,
                            "OK",
                        );

                        let response_body = retry_reply.body;

                        let _ = retry_reservation_id; // suppress unused warning
                        let headers = [
                            header_or("Content-Type", "application/octet-stream"),
                            header_or("X-Zakuro-Request-Id", &p.request_id),
                            header_or("X-Zakuro-Cost", &format!("{:.6}", actual_cost)),
                            header_or(
                                "X-Zakuro-Credits-Remaining",
                                &format!("{:.6}", credits_remaining),
                            ),
                            header_or("X-Zakuro-Duration-Ms", &format!("{:.2}", retry_duration_ms)),
                            header_or("X-Zakuro-Retries", &format!("{}", attempt)),
                        ];
                        let mut resp = BrokerResponse {
                            status: 200,
                            headers: Vec::new(),
                            body: response_body,
                        };
                        resp.headers.extend(headers);
                        return resp;
                    }
                    Err(_retry_err) => {
                        // This retry also failed — mark unhealthy, cancel quota slot, continue
                        state.workers.mark_unhealthy(&next.id);
                        state.workers.cancel_quota_reservation(&next.id);
                        state.active_requests.remove(&p.request_id);
                    }
                }
            }

            // All retries exhausted
            log_transaction(
                state,
                verbose,
                p.tx_num,
                &p.user_id,
                "EXECUTE",
                0.0,
                p.balance_before,
                Some(&worker_name),
                duration_ms,
                "FAIL",
            );
            error_response(
                &format!(
                    "All workers unreachable after {} retries (tried: {})",
                    MAX_RETRIES,
                    tried_ids.join(", ")
                ),
                "NO_WORKERS",
                503,
            )
        }
    }
}

/// Reserve credits — authority-aware.
/// Returns `Ok(reservation_id)` or `Err(error_response)` for early exit.
#[allow(clippy::too_many_arguments)]
fn reserve_credits(
    state: &Arc<BrokerState>,
    authority: &peer::Authority,
    user_id: &str,
    amount: f64,
    request_id: &str,
    verbose: bool,
    tx_num: u64,
    balance_before: f64,
) -> Result<String, BrokerResponse> {
    let fail = |msg: &str, code: &str, status: u16| -> Result<String, _> {
        log_transaction(
            state,
            verbose,
            tx_num,
            user_id,
            "EXECUTE",
            0.0,
            balance_before,
            None,
            0.0,
            "FAIL",
        );
        Err(error_response(msg, code, status))
    };

    match authority {
        peer::Authority::Local => match state.ledger.local_reserve(user_id, amount, request_id) {
            Ok((id, _)) => Ok(id),
            Err(ledger::LedgerError::InsufficientCredits {
                required,
                available,
            }) => fail(
                &format!(
                    "Insufficient credits: need {:.4}, have {:.4}",
                    required, available
                ),
                "INSUFFICIENT_CREDITS",
                402,
            ),
            Err(e @ ledger::LedgerError::BalanceUnavailable { .. }) => {
                fail(&e.to_string(), "BALANCE_UNAVAILABLE", 503)
            }
            Err(e) => fail(&e.to_string(), "LEDGER_ERROR", 503),
        },
        peer::Authority::Peer(url) => {
            let peer_result = state
                .peer_manager
                .get_client(url)
                .and_then(|c| c.reserve(user_id, amount, request_id).ok())
                .map(|r| r.reservation_id);
            if let Some(id) = peer_result {
                return Ok(id);
            }
            eprintln!(
                "  [P2P] Peer reserve failed ({}), falling back to local",
                url
            );
            reserve_via_ledger(
                state,
                user_id,
                amount,
                request_id,
                verbose,
                tx_num,
                balance_before,
            )
        }
        peer::Authority::Standalone => reserve_via_ledger(
            state,
            user_id,
            amount,
            request_id,
            verbose,
            tx_num,
            balance_before,
        ),
    }
}

fn reserve_via_ledger(
    state: &Arc<BrokerState>,
    user_id: &str,
    amount: f64,
    request_id: &str,
    verbose: bool,
    tx_num: u64,
    balance_before: f64,
) -> Result<String, BrokerResponse> {
    let fail = |msg: &str, code: &str, status: u16| -> Result<String, _> {
        log_transaction(
            state,
            verbose,
            tx_num,
            user_id,
            "EXECUTE",
            0.0,
            balance_before,
            None,
            0.0,
            "FAIL",
        );
        Err(error_response(msg, code, status))
    };
    match state.ledger.reserve(user_id, amount, request_id) {
        Ok(id) => Ok(id),
        Err(ledger::LedgerError::InsufficientCredits {
            required,
            available,
        }) => fail(
            &format!(
                "Insufficient credits: need {:.4}, have {:.4}",
                required, available
            ),
            "INSUFFICIENT_CREDITS",
            402,
        ),
        Err(e @ ledger::LedgerError::BalanceUnavailable { .. }) => {
            fail(&e.to_string(), "BALANCE_UNAVAILABLE", 503)
        }
        Err(e) => fail(&e.to_string(), "LEDGER_ERROR", 503),
    }
}

/// Cancel a credit reservation — authority-aware.
/// Also publishes a "cancel" transaction and updates the WAL.
/// Only call when `!is_local`.
#[allow(clippy::too_many_arguments)]
fn cancel_credits(
    state: &Arc<BrokerState>,
    authority: &peer::Authority,
    reservation_id: &str,
    request_id: &str,
    user_id: &str,
    worker_id: &str,
    balance_before: f64,
    duration_ms: f64,
) {
    match authority {
        peer::Authority::Local => {
            if let Err(e) = state.ledger.local_cancel(reservation_id) {
                eprintln!("  [BILLING] local_cancel failed for {}: {}", request_id, e);
            }
        }
        peer::Authority::Peer(url) => {
            if let Some(client) = state.peer_manager.get_client(url) {
                if let Err(e) = client.cancel(reservation_id) {
                    eprintln!("  [BILLING] peer cancel failed for {}: {}", request_id, e);
                }
            } else if let Err(e) = state.ledger.cancel(reservation_id) {
                eprintln!("  [BILLING] cancel failed for {}: {}", request_id, e);
            }
        }
        peer::Authority::Standalone => {
            if let Err(e) = state.ledger.cancel(reservation_id) {
                eprintln!("  [BILLING] cancel failed for {}: {}", request_id, e);
            }
        }
    }
    // Queue cancel to tx_buffer — flushed periodically to dashboard.
    // For Peer authority the peer itself records the cancel; we still log it here for auditing.
    state.tx_buffer.push_transaction(BufferedTransaction {
        request_id: request_id.to_string(),
        user_id: user_id.to_string(),
        tx_type: "cancel".to_string(),
        amount: 0.0,
        balance_after: balance_before,
        worker_id: worker_id.to_string(),
        duration_ms,
        source_node: state.config.node_name.clone(),
        worker_name: None,
        worker_uri: None,
        price_per_hour: 0.0,
    });
    let _ = state.wal.update_status(
        request_id,
        super::wal::WalStatus::Failed,
        None,
        Some(duration_ms),
    );
}

/// Commit a credit reservation and return the new balance.
/// Handles all authority paths, queues tx_buffer entries, and (for `Local`)
/// triggers the earn notification to the worker's broker.
/// Pay the executor's broker `cost*(1-commission_c)` and — when
/// `commission_c > 0` and billing is enabled — credit the platform-house
/// account (both ledger caches) with `cost*commission_c`. `payout+commission
/// == cost` always (see `split_commission`), so this single call is the ONE
/// place executor earn is computed for a remote settlement — every remote
/// money path (the offer path and the direct-forward path) must route
/// through here so commission is universal and the conservation invariant
/// (requester −cost == executor +payout + platform +commission) can't drift
/// between call sites. `commission_c == 0.0` degrades to the legacy
/// uncommissioned payout (`payout == cost`) — callers on a `voucher_required`
/// path must never reach here with `commission_c == 0.0` for a remote job
/// (see the fail-closed minting in `execute_prepare` / `dispatch_to_peers`).
#[allow(clippy::too_many_arguments)]
fn settle_executor_payout(
    state: &Arc<BrokerState>,
    user_id: &str,
    cost: f64,
    commission_c: f64,
    executor_peer_url: &str,
    executor_worker_name: &str,
    request_id: &str,
    duration_ms: f64,
) {
    let (payout, commission) = split_commission(cost, commission_c);
    if commission > 0.0 && state.is_billing_enabled() {
        let platform_uid =
            std::env::var("ZAKURO_PLATFORM_UID").unwrap_or_else(|_| "platform-house".into());
        state
            .ledger
            .local_credits
            .entry(platform_uid.clone())
            .and_modify(|b| *b += commission)
            .or_insert(commission);
        state
            .ledger
            .authoritative_balances
            .entry(platform_uid)
            .and_modify(|b| *b += commission)
            .or_insert(commission);
    }
    // Resolve the executor to a REGISTERED peer before paying it. The executor
    // identifies itself by the address it believes it has
    // (`http://<own_ip>:<port>`, see `our_url` in `start_server`), but it is
    // registered under whatever `ZAKURO_PEERS` spelled -- possibly a DNS name.
    // Same host, different spelling: the exact-string lookup missed and every
    // remote job fell into the refund arm below, so the executor was never paid
    // for work it really did. IP-configured deployments are unaffected either
    // way (the spellings coincide, and the exact match is tried first).
    let settle_url = state
        .peer_manager
        .get_url_for_endpoint(executor_peer_url)
        .unwrap_or_else(|| executor_peer_url.to_string());
    let earn_ok = match state.peer_manager.get_client(&settle_url) {
        Some(client) => match client.earn(
            payout,
            duration_ms,
            executor_worker_name,
            user_id,
            request_id,
        ) {
            Ok(_) => true,
            Err(e) => {
                eprintln!(
                    "  [EARN] Failed to notify peer {}: {}",
                    executor_peer_url, e
                );
                false
            }
        },
        None => {
            // Print what was looked up AND what it resolved to: when these
            // differ, the peer is registered under another spelling and the
            // real fault is a registry mismatch, not an unreachable executor.
            eprintln!(
                "  [EARN] No client for peer {} (resolved to {}, request {}): executor unreachable, refunding payout to requester",
                executor_peer_url, settle_url, request_id
            );
            false
        }
    };

    // The executor's broker could not be paid (unreachable, or the earn RPC
    // failed — e.g. it restarted between returning the job result and
    // receiving this earn call). The requester was already debited `cost`
    // by the caller; refund `payout` back so the requester nets only
    // `-commission` (platform keeps its cut, executor got nothing, and the
    // three legs sum to zero: requester -commission, executor +0, platform
    // +commission). Only valid on the path where the requester was actually
    // debited `cost` for this job — see the callers of
    // `settle_executor_payout`.
    let refund = earn_refund_amount(payout, earn_ok);
    if refund > 0.0 && state.is_billing_enabled() {
        state
            .ledger
            .local_credits
            .entry(user_id.to_string())
            .and_modify(|b| *b += refund)
            .or_insert(refund);
        state
            .ledger
            .authoritative_balances
            .entry(user_id.to_string())
            .and_modify(|b| *b += refund)
            .or_insert(refund);
        state.tx_buffer.push_transaction(BufferedTransaction {
            request_id: format!("{request_id}-earn-refund"),
            user_id: user_id.to_string(),
            tx_type: "refund".to_string(),
            amount: refund,
            balance_after: 0.0,
            worker_id: executor_worker_name.to_string(),
            duration_ms,
            source_node: state.config.node_name.clone(),
            worker_name: Some(executor_worker_name.to_string()),
            worker_uri: None,
            price_per_hour: 0.0,
        });
    }
}

/// The executing node's fingerprint for settlement routing. `Worker::node_fp`
/// is stamped for peer-synced workers by `discovery::peer_node_fp` and for
/// local workers from this node's own key. Deliberately has NO address
/// fallback: an unstamped worker routes to the full-refund arm rather than to
/// a lucky exact host match (which never fired behind a proxy/NAT anyway).
fn executor_fp(worker: &Worker) -> Option<&str> {
    if worker.node_fp.is_empty() {
        None
    } else {
        Some(worker.node_fp.as_str())
    }
}

/// The executing worker is one of THIS broker's own: stamped with our node
/// fingerprint when it registered (`discovery` / `POST /workers`). Keyed on
/// identity, never on address — the same rule as every other settlement
/// site: an address match would call a NAT'd or proxied peer "ours" and pay
/// nobody. An unstamped worker is NOT ours here; it takes the existing
/// unresolved-executor refund arm.
fn executor_is_self(state: &BrokerState, worker: &Worker) -> bool {
    executor_fp(worker).is_some_and(|fp| fp == state.node_key.fingerprint())
}

#[allow(clippy::too_many_arguments)]
fn commit_credits(
    state: &Arc<BrokerState>,
    authority: &peer::Authority,
    is_local: bool,
    reservation_id: &str,
    actual_cost: f64,
    balance_before: f64,
    request_id: &str,
    user_id: &str,
    worker: &worker::Worker,
    duration_ms: f64,
    commission_c: f64,
    voucher_task_nonce: &str,
) -> f64 {
    if is_local {
        state.ledger.publish_transaction(
            request_id,
            user_id,
            "commit",
            0.0,
            balance_before,
            &worker.id,
            duration_ms,
            state.config.node_name.as_deref(),
        );
        if state.is_billing_enabled() {
            state.tx_buffer.push_transaction(BufferedTransaction {
                request_id: request_id.to_string(),
                user_id: user_id.to_string(),
                tx_type: "commit".to_string(),
                amount: 0.0,
                balance_after: balance_before,
                worker_id: worker.id.clone(),
                duration_ms,
                source_node: state.config.node_name.clone(),
                worker_name: Some(worker.name.clone()),
                worker_uri: Some(worker.uri.clone()),
                price_per_hour: worker.pricing.price_per_hour,
            });
        }
        return balance_before;
    }

    match authority {
        peer::Authority::Local => {
            let balance = match state.ledger.local_commit(reservation_id, actual_cost) {
                Ok(b) => b,
                Err(e) => {
                    eprintln!("  [P2P] Local commit error for {}: {}", request_id, e);
                    balance_before - actual_cost
                }
            };
            state.tx_buffer.push_transaction(BufferedTransaction {
                request_id: request_id.to_string(),
                user_id: user_id.to_string(),
                tx_type: "commit".to_string(),
                amount: actual_cost,
                balance_after: balance,
                worker_id: worker.id.clone(),
                duration_ms,
                source_node: state.config.node_name.clone(),
                worker_name: Some(worker.name.clone()),
                worker_uri: Some(worker.uri.clone()),
                price_per_hour: worker.pricing.price_per_hour,
            });
            state.tx_buffer.snapshot_balance(user_id, balance);
            // Notify provider's broker that their worker earned credits, net of
            // platform commission (`commission_c`, stamped in the dashboard
            // voucher minted in `execute_prepare` for this remote job — see
            // `settle_executor_payout`). Gross basis is `actual_cost` — the SAME
            // amount the requester was debited above — so payout+commission ==
            // actual_cost and the legs net to zero. Deriving earn from
            // wall-clock `duration_ms` diverges from the committed charge under
            // concurrency (queue latency inflates it), minting credits — the
            // conservation bug a stress test surfaced. `duration_ms` stays as
            // transaction metadata only.
            // ALL THREE money legs (executor earn, platform-house cache credit,
            // and the dashboard voucher redeem that authoritatively credits
            // platform commission) must happen together or not at all. Keeping
            // the redeem OUTSIDE this guard could credit the platform its
            // commission while the executor earn never fires (unresolvable
            // peer) — requester −cost, executor +0, platform +commission →
            // credits unaccounted, requester overcharged. Bind them atomically.
            // Settlement is keyed by the executor's key-derived node identity
            // (`zc://node-<fp>`), never by an address: a peer reached via the
            // sidecar CONNECT proxy or behind NAT has a base-URL host that is
            // not its worker's IP, so the old exact-host match silently paid
            // nobody for real work.
            // Self-executed for a foreign requester: the executor is this very
            // broker, so pay the owner here and redeem — no peer hop to resolve.
            if executor_is_self(state, worker) {
                settle_self_payout(
                    state,
                    user_id,
                    actual_cost,
                    commission_c,
                    worker,
                    request_id,
                    duration_ms,
                );
                redeem_task_nonce(state, voucher_task_nonce, actual_cost);
                return balance;
            }
            let exec_fp = executor_fp(worker);
            match exec_fp.and_then(|fp| state.peer_manager.get_url_for_fingerprint(fp)) {
                Some(peer_url) => {
                    settle_executor_payout(
                        state,
                        user_id,
                        actual_cost,
                        commission_c,
                        &peer_url,
                        &worker.id,
                        request_id,
                        duration_ms,
                    );
                    // Redeem the voucher this broker minted for this remote job
                    // (fail-closed minting happens in `execute_prepare` — this is
                    // the authoritative dashboard credit for the platform-house
                    // commission, mirroring `redeem_offer_voucher` on the offer
                    // path). Best-effort: logs and continues on failure — the
                    // executor earn + platform cache credit already happened just
                    // above via `settle_executor_payout`.
                    if !voucher_task_nonce.is_empty() {
                        if let (Some(api_url), Some(api_key)) =
                            (&state.config.api_url, &state.config.api_key)
                        {
                            match super::node_sync::redeem_voucher(
                                api_url,
                                api_key,
                                voucher_task_nonce,
                                actual_cost,
                            ) {
                                Ok(true) => {}
                                Ok(false) => eprintln!(
                                    "  [VOUCHER] nonce already spent (double-spend attempt?): {voucher_task_nonce}"
                                ),
                                Err(e) => eprintln!("  [VOUCHER] redeem failed: {e}"),
                            }
                        }
                    }
                }
                None => {
                    // Executor peer could not be resolved from the executing
                    // node's identity — either the worker carries no stamped
                    // `node_fp`, or no peer's cached fingerprint matches it
                    // (happens under chaos when the peer is temporarily evicted
                    // from the registry mid-restart): pay nobody and redeem
                    // nothing (redeeming here would credit the platform
                    // commission with no offsetting executor earn). The whole
                    // settlement failed — no executor earn, no platform-house
                    // credit, no voucher redeem — so the requester, already
                    // debited `actual_cost` via `local_commit` above, must be
                    // made whole for the FULL charge (not just `payout`).
                    // Net: requester -actual_cost +actual_cost = 0, executor 0,
                    // platform 0 → the job effectively didn't bill, conserving.
                    eprintln!(
                        "  [EARN] UNRESOLVED executor peer for node={} \
                         (request {request_id}): no executor payout/redeem — refunding \
                         requester {actual_cost:.6} in full to conserve",
                        exec_fp
                            .map(|f| format!("zc://node-{f}"))
                            .unwrap_or_else(|| "<unstamped>".into())
                    );
                    if state.is_billing_enabled() {
                        state
                            .ledger
                            .local_credits
                            .entry(user_id.to_string())
                            .and_modify(|b| *b += actual_cost)
                            .or_insert(actual_cost);
                        state
                            .ledger
                            .authoritative_balances
                            .entry(user_id.to_string())
                            .and_modify(|b| *b += actual_cost)
                            .or_insert(actual_cost);
                        state.tx_buffer.push_transaction(BufferedTransaction {
                            request_id: format!("{request_id}-unresolved-refund"),
                            user_id: user_id.to_string(),
                            tx_type: "refund".to_string(),
                            amount: actual_cost,
                            balance_after: balance + actual_cost,
                            worker_id: worker.id.clone(),
                            duration_ms,
                            source_node: state.config.node_name.clone(),
                            worker_name: Some(worker.name.clone()),
                            worker_uri: Some(worker.uri.clone()),
                            price_per_hour: worker.pricing.price_per_hour,
                        });
                    }
                }
            }
            balance
        }
        peer::Authority::Peer(url) => {
            let peer_balance = if let Some(client) = state.peer_manager.get_client(url) {
                match client.commit(reservation_id, actual_cost) {
                    Ok(resp) => {
                        state.tx_buffer.push_transaction(BufferedTransaction {
                            request_id: request_id.to_string(),
                            user_id: user_id.to_string(),
                            tx_type: "commit".to_string(),
                            amount: actual_cost,
                            balance_after: resp.balance_after,
                            worker_id: worker.id.clone(),
                            duration_ms,
                            source_node: state.config.node_name.clone(),
                            worker_name: Some(worker.name.clone()),
                            worker_uri: Some(worker.uri.clone()),
                            price_per_hour: worker.pricing.price_per_hour,
                        });
                        Some(resp.balance_after)
                    }
                    Err(e) => {
                        eprintln!(
                            "  [P2P] Peer commit failed ({}), falling back to local: {}",
                            url, e
                        );
                        None
                    }
                }
            } else {
                None
            };
            match peer_balance {
                Some(b) => b,
                None => {
                    state.ledger.publish_transaction(
                        request_id,
                        user_id,
                        "commit",
                        actual_cost,
                        balance_before - actual_cost,
                        &worker.id,
                        duration_ms,
                        state.config.node_name.as_deref(),
                    );
                    match state.ledger.commit(reservation_id, actual_cost) {
                        Ok(b) => b,
                        Err(e) => {
                            eprintln!("  [LEDGER] Commit error for {}: {}", request_id, e);
                            balance_before - actual_cost
                        }
                    }
                }
            }
        }
        peer::Authority::Standalone => {
            let balance = match state.ledger.commit(reservation_id, actual_cost) {
                Ok(b) => b,
                Err(e) => {
                    eprintln!(
                        "  [LEDGER] Commit error for {}: {} (WAL has record)",
                        request_id, e
                    );
                    balance_before - actual_cost
                }
            };
            // Queue to tx_buffer (flushed periodically) instead of synchronous API call
            state.tx_buffer.push_transaction(BufferedTransaction {
                request_id: request_id.to_string(),
                user_id: user_id.to_string(),
                tx_type: "commit".to_string(),
                amount: actual_cost,
                balance_after: balance,
                worker_id: worker.id.clone(),
                duration_ms,
                source_node: state.config.node_name.clone(),
                worker_name: Some(worker.name.clone()),
                worker_uri: Some(worker.uri.clone()),
                price_per_hour: worker.pricing.price_per_hour,
            });
            // P2P off (single broker, billing on): a foreign requester's job on
            // this node's worker still pays the owner and the platform.
            if executor_is_self(state, worker) {
                settle_self_payout(
                    state,
                    user_id,
                    actual_cost,
                    commission_c,
                    worker,
                    request_id,
                    duration_ms,
                );
                redeem_task_nonce(state, voucher_task_nonce, actual_cost);
            }
            balance
        }
    }
}

/// Redeem a minted voucher's nonce at the dashboard (double-spend guard +
/// authoritative platform commission). No-op without a nonce or api creds;
/// best-effort, logs and continues — settlement on this ledger already stands.
fn redeem_task_nonce(state: &Arc<BrokerState>, voucher_task_nonce: &str, actual_cost: f64) {
    if voucher_task_nonce.is_empty() {
        return;
    }
    if let (Some(api_url), Some(api_key)) = (&state.config.api_url, &state.config.api_key) {
        match super::node_sync::redeem_voucher(api_url, api_key, voucher_task_nonce, actual_cost) {
            Ok(true) => {}
            Ok(false) => eprintln!(
                "  [VOUCHER] nonce already spent (double-spend attempt?): {voucher_task_nonce}"
            ),
            Err(e) => eprintln!("  [VOUCHER] redeem failed: {e}"),
        }
    }
}

/// Settlement for a job this broker ran on its OWN worker for a requester who
/// is not the owner. Same split as `settle_executor_payout` — `cost*(1-c)` to
/// the executor's owner, `cost*c` to platform-house — minus the network hop:
/// the executor IS this broker, so the owner is credited on this ledger
/// directly (exactly what `handle_peer_earn` does when we are the remote
/// side). Conservation: requester −cost == owner +payout + platform +commission.
/// Without an owner configured there is nobody to pay, so the payout is
/// refunded to the requester rather than vanishing.
fn settle_self_payout(
    state: &Arc<BrokerState>,
    user_id: &str,
    cost: f64,
    commission_c: f64,
    worker: &worker::Worker,
    request_id: &str,
    duration_ms: f64,
) {
    if !state.is_billing_enabled() || cost <= 0.0 {
        return;
    }
    let (payout, commission) = split_commission(cost, commission_c);
    if commission > 0.0 {
        let platform_uid =
            std::env::var("ZAKURO_PLATFORM_UID").unwrap_or_else(|_| "platform-house".into());
        state
            .ledger
            .local_credits
            .entry(platform_uid.clone())
            .and_modify(|b| *b += commission)
            .or_insert(commission);
        state
            .ledger
            .authoritative_balances
            .entry(platform_uid)
            .and_modify(|b| *b += commission)
            .or_insert(commission);
    }
    let Some(owner) = state.config.owner_user_id.clone() else {
        eprintln!(
            "  [EARN] self-executed job {request_id} but no owner configured on this broker; \
             refunding payout {payout:.6} to requester {user_id}"
        );
        state
            .ledger
            .local_credits
            .entry(user_id.to_string())
            .and_modify(|b| *b += payout)
            .or_insert(payout);
        state
            .ledger
            .authoritative_balances
            .entry(user_id.to_string())
            .and_modify(|b| *b += payout)
            .or_insert(payout);
        state.tx_buffer.push_transaction(BufferedTransaction {
            request_id: format!("{request_id}-earn-refund"),
            user_id: user_id.to_string(),
            tx_type: "refund".to_string(),
            amount: payout,
            balance_after: 0.0,
            worker_id: worker.id.clone(),
            duration_ms,
            source_node: state.config.node_name.clone(),
            worker_name: Some(worker.name.clone()),
            worker_uri: None,
            price_per_hour: worker.pricing.price_per_hour,
        });
        return;
    };
    let earn_request_id = format!("earn-{request_id}");
    let _ = state.wal.append(&WalEntry {
        request_id: earn_request_id.clone(),
        user_id: owner.clone(),
        reservation_id: String::new(),
        estimated_cost: payout,
        actual_cost: Some(payout),
        worker_id: worker.id.clone(),
        duration_ms: Some(duration_ms),
        timestamp: chrono::Utc::now(),
        status: WalStatus::Earned,
    });
    let balance_after = state.ledger.local_add_credits(&owner, payout);
    state.tx_buffer.push_transaction(BufferedTransaction {
        request_id: earn_request_id,
        user_id: owner.clone(),
        tx_type: "credit".to_string(),
        amount: payout,
        balance_after,
        worker_id: worker.id.clone(),
        duration_ms,
        source_node: state.config.node_name.clone(),
        worker_name: Some(worker.name.clone()),
        worker_uri: None,
        price_per_hour: worker.pricing.price_per_hour,
    });
    state.tx_buffer.snapshot_balance(&owner, balance_after);
    println!(
        "  [EARN] Worker {} earned {:.6} credits from user {} → owner {} (self-executed; commission {:.6}; balance now {:.6})",
        worker.name, payout, user_id, owner, commission, balance_after
    );
}

/// Dispatch a task offer to peer brokers via QUIC subscribers then parallel HTTP/QUIC.
/// Returns the first successful response, or a 503 if no peer accepted.
/// Always returns a complete `Response` — the caller should `return` it immediately.
/// Overall deadline for waiting on peer offer responses in `dispatch_to_peers`.
///
/// `PeerClient::offer_task` falls back to a 310s global timeout when the offer
/// carries no `timeout_secs`, and the fan-out loop's `recv` had no deadline of
/// its own — so a single slow or unresponsive peer could hang the request for
/// over five minutes, far past any client timeout. This caps the wait: an
/// explicit task budget is honored (plus slack for transport/queueing), and an
/// unset budget falls back to 30s rather than 310s.
fn peer_dispatch_deadline(timeout_secs: f64) -> std::time::Duration {
    if timeout_secs > 0.0 {
        std::time::Duration::from_secs_f64(timeout_secs + 12.0)
    } else {
        std::time::Duration::from_secs(30)
    }
}

/// Builds the set of peer URLs to broadcast a task offer to in step 2 of
/// `dispatch_to_peers`, excluding `abandoned_preferred_peer` when present.
///
/// `abandoned_preferred_peer` is `Some(url)` only when step 1.5's direct
/// pre-selected offer to that peer timed out or errored — since offers are
/// one-phase (`PeerClient::offer_task` returns only once the peer finishes
/// executing), that peer may still be executing the same `task_id`.
/// Re-offering the same task to it in the broadcast race could cause it to
/// execute the job a second time, so it is excluded from this dispatch's
/// broadcast set. This is narrow, per-dispatch scoping: it does not affect
/// which peers are considered for other requests, and it does not change
/// step 2's broadcast semantics for the remaining peers (parallel offer,
/// first-accept-wins).
fn broadcast_targets(peer_urls: &[String], abandoned_preferred_peer: Option<&str>) -> Vec<String> {
    match abandoned_preferred_peer {
        Some(abandoned) => peer_urls
            .iter()
            .filter(|url| url.as_str() != abandoned)
            .cloned()
            .collect(),
        None => peer_urls.to_vec(),
    }
}

/// Env escape hatch for marketplace policy pre-selection (task 5). Default
/// ON — any value other than exactly `"0"` (including unset) leaves
/// pre-selection active. Set `ZAKURO_MARKETPLACE_SELECT=0` to disable it and
/// fall back to the legacy broadcast-only race for safe rollout.
fn marketplace_select_enabled() -> bool {
    std::env::var("ZAKURO_MARKETPLACE_SELECT")
        .map(|v| v != "0")
        .unwrap_or(true)
}

/// Marketplace policy pre-selection (task 5): pick the single best-admitted
/// peer broker for `req` from cached adverts, ranked by lowest observed
/// latency (resource admission + freshness first) — see
/// `selection::select_executor_broker`. Returns the peer's base URL, or
/// `None` when no peer is admitted (caller falls back to the broadcast
/// race unchanged).
///
/// Latency source: `PeerManager::peer_latency_ms` (the most recent
/// `/peer/health` probe RTT). A peer that hasn't been probed yet has no
/// latency signal — it is still included (so a single freshly-registered
/// peer can be pre-selected) but ranked behind any peer with a measured
/// RTT, via an `f64::MAX` sentinel latency.
fn preselect_executor_peer(state: &Arc<BrokerState>, req: &ResourceRequirements) -> Option<String> {
    let now = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0);
    let peers: Vec<(String, Option<super::discovery::Advert>, f64)> = state
        .peer_manager
        .peer_urls()
        .into_iter()
        .map(|url| {
            let advert = state.peer_manager.peer_advert(&url);
            let latency_ms = state.peer_manager.peer_latency_ms(&url).unwrap_or(f64::MAX);
            (url, advert, latency_ms)
        })
        .collect();
    // Staleness window: generous relative to the discovery tick (default
    // 15s, see DiscoveryConfig::interval_secs) so a couple of missed ticks
    // don't spuriously disable pre-selection.
    const MAX_ADVERT_AGE_SECS: u64 = 120;
    super::selection::select_executor_broker(&peers, req, MAX_ADVERT_AGE_SECS, now).map(|b| b.url)
}

#[allow(clippy::too_many_arguments)]
/// Split a gross charge `gross` into `(payout, commission)` for commission rate
/// `c` in `[0.0, 1.0)`. The commission is computed first and the payout is the
/// exact remainder (`gross - commission`) — never an independently rounded
/// piece — so `payout + commission == gross` holds to the last bit. `c == 0.0`
/// yields `(gross, 0.0)`.
fn split_commission(gross: f64, c: f64) -> (f64, f64) {
    let commission = gross * c;
    let payout = gross - commission;
    (payout, commission)
}

/// Pure decision: given the executor's earn outcome, how much (if any) should
/// be refunded to the requester by `settle_executor_payout`?
///
/// The requester was already debited `cost` by the caller before settlement.
/// - `earn_ok == true`: the executor was paid `payout`; nothing to refund.
/// - `earn_ok == false`: the executor's broker could not be reached/paid (it
///   restarted between returning the job result and receiving the earn RPC,
///   or the peer was already unresolvable) — refund `payout` to the
///   requester so they net only `-commission`, matching the platform's cut.
///   Conservation holds either way: requester_net + executor_delta +
///   platform_delta == 0, where platform_delta == commission in both cases.
fn earn_refund_amount(payout: f64, earn_ok: bool) -> f64 {
    if earn_ok {
        0.0
    } else {
        payout
    }
}

/// Extract the stamped `commission_c` from an offer's dashboard-signed voucher.
///
/// This runs on the REQUESTER's settlement broker — a party with an obvious
/// incentive to strip or zero `commission_c` before it ever reaches this
/// point, since that broker's own operator controls the code path. We must
/// not trust the JSON contents until the dashboard's Ed25519 signature over
/// the *exact bytes* has been verified against `dash_pubkey` (mirroring
/// `verify_offer_voucher`'s signature-first discipline). `price_estimate` is
/// passed as `0.0` because this call only extracts `commission_c` — it does
/// not re-check budget (already enforced by the executor broker's earlier
/// `verify_offer_voucher` call) — so a generous/zero estimate never spuriously
/// rejects a valid voucher on budget grounds here.
///
/// Returns `0.0` (no local platform-mirror commission) whenever: there is no
/// voucher, no cached dashboard pubkey, or signature/verification fails. This
/// is safe and non-regressive — the dashboard remains the authoritative
/// commission enforcer via its own voucher-nonce lookup at settlement, so a
/// `0.0` here only skips the broker-local platform-house cache mirror, never
/// dashboard-side enforcement. A parse or verification failure must never
/// throw money, so we always fall back to no commission rather than guess.
fn offer_commission_c(offer: &task_board::TaskOffer, dash_pubkey: Option<&str>) -> f64 {
    if offer.voucher_signed_json.is_empty() || offer.voucher_sig.is_empty() {
        return 0.0;
    }
    let Some(pubkey) = dash_pubkey else {
        return 0.0;
    };
    match super::voucher::verify_voucher_now(
        pubkey,
        &offer.voucher_signed_json,
        &offer.voucher_sig,
        0.0,
    ) {
        Ok(v) if (0.0..1.0).contains(&v.commission_c) => v.commission_c,
        _ => 0.0,
    }
}

#[allow(clippy::too_many_arguments)]
fn dispatch_to_peers(
    state: &Arc<BrokerState>,
    offer: task_board::TaskOffer,
    start: Instant,
    user_id: &str,
    _is_self_owned: bool,
    request_id: &str,
    tx_num: u64,
    verbose: bool,
    balance_before: f64,
    preferred_peer: Option<String>,
    // The ONE dashboard-verified commission rate for this job, captured at mint
    // time in `execute_prepare` (0.0 when vouchers are not required). Used
    // directly for the executor payout — settlement never re-derives it
    // (re-derivation returned 0.0 on a rotated/missing pubkey and minted
    // credits, since the executor-side redeem still charged commission).
    verified_commission_c: f64,
) -> BrokerResponse {
    let peer_urls: Vec<String> = state.peer_manager.peer_urls();

    // ── Pre-dispatch credit gate (audit C2) ──────────────────────────
    // Mirror the local select_worker credit check: reject the request with
    // 402 INSUFFICIENT_CREDITS *before* offering the task to any peer when the
    // requester cannot cover the maximum cost the offer permits. Without this,
    // remote jobs were dispatched with no balance check and overspend was
    // silently clamped to zero after the fact.
    if state.is_billing_enabled() {
        // Maximum the requester can be charged: the offer's price ceiling
        // (max_price_per_hour) over its estimated duration. When no budget was
        // supplied, max_price_per_hour is f64::MAX — the cost cannot be bounded
        // ahead of the offer (the executing peer's real price is unknown until it
        // accepts), so we require only a strictly positive balance and settle the
        // actual cost after execution. (Previously this reserved f64::MAX, making
        // any un-budgeted remote dispatch impossible — a money-path bug.)
        // The no-budget sentinel is f64::MAX (a FINITE value — is_finite() is true
        // for it), so detect "unbounded" as >= f64::MAX (also catches infinity).
        let unbounded = offer.max_price_per_hour >= f64::MAX;
        let max_cost = if unbounded {
            0.0
        } else {
            offer.max_price_per_hour / 3600.0 * offer.estimated_duration_secs
        };
        let insufficient = if unbounded {
            balance_before <= 0.0
        } else {
            balance_before < max_cost
        };
        if insufficient {
            log_transaction(
                state,
                verbose,
                tx_num,
                user_id,
                "EXECUTE",
                0.0,
                balance_before,
                None,
                0.0,
                "FAIL",
            );
            let detail = if unbounded {
                format!(
                    "Insufficient credits: a positive balance is required, have {:.4}",
                    balance_before
                )
            } else {
                format!(
                    "Insufficient credits: need {:.4}, have {:.4}",
                    max_cost, balance_before
                )
            };
            return error_response(&detail, "INSUFFICIENT_CREDITS", 402);
        }
    }

    let quic_transport = state.quic.get().cloned();
    let mut winning_peer: Option<String> = None;
    let mut winning_result: Option<task_board::TaskResult> = None;
    let mut winning_transport: Option<String> = None;

    // 1) Push to already-connected QUIC subscribers first (zero extra latency).
    if let Some(ref qt) = quic_transport {
        if let Some((url, res)) = qt.broadcast_offer_to_subscribers(&offer) {
            winning_peer = Some(url);
            winning_result = Some(res);
            winning_transport = Some("subscribed".to_string());
        }
    }

    // 1.5) Marketplace policy pre-selection (task 5): try the single
    // best-admitted peer directly, via the SAME per-peer offer mechanism
    // (`PeerClient::offer_task`, normal accept/timeout semantics) used by
    // the broadcast race below. On accept, this IS the winner — the
    // broadcast race (step 2) never runs. On decline/timeout/unreachable,
    // fall through unchanged to step 2, which may re-offer to the same
    // peer — that's fine (matches the legacy path's own retry-by-broadcast
    // behavior).
    // Bounded to the SAME deadline the broadcast race (step 2) uses via
    // `peer_dispatch_deadline` — `PeerClient::offer_task`'s own internal
    // timeout defaults to ~310s (offer.timeout_secs + 10, or 310 when
    // unset), which would otherwise let a reachable-but-hung pre-selected
    // peer stall the whole request far longer than the broadcast race's
    // ~12s-slack/30s-fallback bound. The offer itself runs on a worker
    // thread (mirroring step 2's pattern, including looking up the client
    // fresh inside the thread to avoid holding the dashmap `Ref` across
    // threads) and we only ever *wait* up to the deadline here — we never
    // race it against the broadcast loop. On timeout/decline/error we
    // fall straight through to step 2 below, strictly sequentially, so at
    // most one of {pre-selected peer, broadcast winner} can ever produce
    // a `winning_result`; a still-running abandoned offer thread cannot
    // cause a double-charge because the local dispatch logic only acts on
    // whichever single `TaskResult` this function returns.
    // Tracks the preferred peer's URL when step 1.5 times out or errors
    // (i.e. the offer thread may still be running the job on that peer,
    // since offers are one-phase and only return on completion). Set only
    // on the timeout/err path, never on the success path — used to exclude
    // that peer from step 2's broadcast below.
    let mut abandoned_preferred_peer: Option<String> = None;
    if winning_peer.is_none() {
        if let Some(ref peer_url) = preferred_peer {
            if state.peer_manager.get_client(peer_url).is_some() {
                let (tx, rx) = std::sync::mpsc::channel::<Result<task_board::TaskResult, String>>();
                let state_c = state.clone();
                let offer_c = offer.clone();
                let peer_url_c = peer_url.clone();
                std::thread::spawn(move || {
                    let result = match state_c.peer_manager.get_client(&peer_url_c) {
                        Some(client) => client.offer_task(&offer_c),
                        None => Err("peer unreachable".to_string()),
                    };
                    let _ = tx.send(result);
                });
                let deadline = peer_dispatch_deadline(offer.timeout_secs);
                if let Ok(Ok(result)) = rx.recv_timeout(deadline) {
                    winning_peer = Some(peer_url.clone());
                    winning_result = Some(result);
                    winning_transport = Some("http".to_string());
                } else {
                    // Timed out (RecvTimeoutError) or the peer
                    // declined/errored (Ok(Err(_))). Because offers are
                    // one-phase (`PeerClient::offer_task` only returns
                    // once the peer FINISHES executing), a timeout here
                    // means the preferred peer may still be executing
                    // this same task_id. Record it so step 2 excludes it
                    // from the broadcast — otherwise the same task_id
                    // would be re-offered to a peer that could still be
                    // running it, duplicating execution (worst case: the
                    // same peer runs the same job twice). Cross-peer
                    // redundant execution across *different* peers in the
                    // step-2 broadcast race (offer-to-all, first-accept-
                    // wins) is pre-existing, intentionally out of scope
                    // here — exactly-once execution is deferred to the
                    // proof-of-execution/settlement work (spec #3).
                    abandoned_preferred_peer = Some(peer_url.clone());
                }
            }
        }
    }

    // Peers to broadcast to in step 2: all known peers minus the abandoned
    // preferred peer (if any).
    let broadcast_peer_urls = broadcast_targets(&peer_urls, abandoned_preferred_peer.as_deref());

    // 2) If no subscriber took it, offer to all peers in parallel; first to accept wins.
    if winning_peer.is_none() && !broadcast_peer_urls.is_empty() {
        let (tx, rx) =
            std::sync::mpsc::channel::<Option<(String, task_board::TaskResult, String)>>();
        for peer_url in &broadcast_peer_urls {
            let tx = tx.clone();
            let state_c = state.clone();
            let offer_c = offer.clone();
            let quic_c = quic_transport.clone();
            let peer_url = peer_url.clone();
            std::thread::spawn(move || {
                let peer_quic_port = state_c.peer_manager.get_quic_port(&peer_url);
                let (offer_result, transport_used) =
                    if let (Some(ref qt), p) = (&quic_c, peer_quic_port) {
                        if p > 0 {
                            (quic_offer(qt, &peer_url, p, &offer_c), "quic".to_string())
                        } else if let Some(client) = state_c.peer_manager.get_client(&peer_url) {
                            (client.offer_task(&offer_c), "http".to_string())
                        } else {
                            (Err("peer unreachable".into()), String::new())
                        }
                    } else if let Some(client) = state_c.peer_manager.get_client(&peer_url) {
                        (client.offer_task(&offer_c), "http".to_string())
                    } else {
                        (Err("peer unreachable".into()), String::new())
                    };
                let _ = tx.send(offer_result.ok().map(|r| (peer_url, r, transport_used)));
            });
        }
        drop(tx);
        // Bounded wait: the first peer to accept wins. A declining/unreachable
        // peer sends `None` and we keep waiting for the others, but the total
        // wait is capped (peer_dispatch_deadline) so one slow/unresponsive peer
        // can't hang the request for up to offer_task's 310s fallback. On
        // timeout we stop waiting and fall through to the 503 below; any
        // still-running offer threads send into the dropped receiver harmlessly.
        let deadline = peer_dispatch_deadline(offer.timeout_secs);
        let dispatch_start = Instant::now();
        for _ in 0..broadcast_peer_urls.len() {
            let remaining = deadline.saturating_sub(dispatch_start.elapsed());
            match rx.recv_timeout(remaining) {
                Ok(Some((url, res, trans))) => {
                    winning_peer = Some(url);
                    winning_result = Some(res);
                    winning_transport = Some(trans);
                    break;
                }
                Ok(None) => continue, // peer declined/unreachable; wait for others
                Err(_) => break,      // deadline reached or all senders gone
            }
        }
    }

    if let (Some(peer_url), Some(result), Some(transport_used)) =
        (winning_peer, winning_result, winning_transport)
    {
        let duration_ms = start.elapsed().as_secs_f64() * 1000.0;
        // Dispatch to peers = always alien compute; owner is not exempt from billing here.
        let cost = result.actual_cost;
        let balance_after = balance_before - cost;

        log_transaction_with_worker_info(
            state,
            verbose,
            tx_num,
            user_id,
            "EXECUTE",
            cost,
            balance_after,
            Some(&result.worker_name),
            duration_ms,
            "OK",
            Some(result.price_per_hour),
            Some(&result.executor_owner),
            result.worker_pid.as_deref(),
            // A peer's address is never disclosed over the mesh, so a
            // dispatched (alien-compute) transaction has no worker IP to log.
            // Locally-executed transactions still record theirs (see the
            // `x-zakuro-ip` path in the local execute arm).
            None,
            Some(request_id),
        );

        if state.is_billing_enabled() && cost > 0.0 {
            state.credits.set_balance(user_id, balance_after);
            // Surface overspend instead of silently clamping to zero: if the peer
            // charged more than the requester could cover, the post-balance is
            // negative. Record the true value and warn so the overspend is visible
            // (reconciliation / dashboard flush) rather than hidden (audit C2).
            if balance_after < 0.0 {
                eprintln!(
                    "  [BILLING] OVERSPEND user={} cost={:.4} balance_before={:.4} balance_after={:.4} request_id={}",
                    user_id, cost, balance_before, balance_after, request_id
                );
            }
            // Update ledger caches so /me reflects the deduction immediately.
            state
                .ledger
                .local_credits
                .entry(user_id.to_string())
                .and_modify(|b| *b -= cost);
            state
                .ledger
                .authoritative_balances
                .entry(user_id.to_string())
                .and_modify(|b| *b -= cost);
            state.tx_buffer.push_transaction(BufferedTransaction {
                request_id: request_id.to_string(),
                user_id: user_id.to_string(),
                tx_type: "commit".to_string(),
                amount: cost,
                balance_after,
                worker_id: result.worker_name.clone(),
                duration_ms,
                source_node: state.config.node_name.clone(),
                worker_name: Some(result.worker_name.clone()),
                worker_uri: Some(result.worker_uri.clone()),
                price_per_hour: result.price_per_hour,
            });
        }

        if cost > 0.0 {
            // Commission is the ONE rate `verified_commission_c` that
            // `execute_prepare` already verified at mint time (dashboard
            // signature + `voucher_commission_valid`) before this offer was ever
            // dispatched — 0.0 only when vouchers are not required (legacy free/
            // uncommissioned payout). We do NOT re-derive it here via
            // `offer_commission_c`: that returned 0.0 whenever this broker's
            // cached pubkey was missing/rotated, paying the executor the FULL
            // cost while the executor-side `redeem_offer_voucher` still charged
            // the voucher's own commission at the dashboard → net minting of
            // `commission` credits. Threading the mint-verified c means the
            // earn(payout) leg and the dashboard redeem always agree.
            //
            // Gross basis is `cost` (= result.actual_cost) — the SAME amount the
            // requester was debited above — so the legs net to zero: requester
            // −cost, executor +payout, platform +commission, payout+commission==cost.
            // `settle_executor_payout` gates the platform-house credit on
            // `state.is_billing_enabled()`, matching the requester debit's gate
            // above so both legs stay symmetric; commission is credited to
            // platform-house authoritatively by the dashboard at
            // `/voucher/redeem` (executor-side, see `redeem_offer_voucher`) — the
            // local credit here is a cache mirror only, no separate batch-sync
            // delta is emitted for it.
            settle_executor_payout(
                state,
                user_id,
                cost,
                verified_commission_c,
                &peer_url,
                &result.worker_name,
                request_id,
                duration_ms,
            );
        }

        let response_body = base64::Engine::decode(
            &base64::engine::general_purpose::STANDARD,
            &result.payload_b64,
        )
        .unwrap_or_default();

        let headers = [
            header_or("Content-Type", "application/octet-stream"),
            header_or("X-Zakuro-Request-Id", request_id),
            header_or("X-Zakuro-Worker", result.worker_name.as_str()),
            header_or("X-Zakuro-Cost", &format!("{:.6}", cost)),
            header_or(
                "X-Zakuro-Credits-Remaining",
                &format!("{:.6}", balance_after),
            ),
            header_or("X-Zakuro-Duration-Ms", &format!("{:.2}", duration_ms)),
            header_or("X-Zakuro-Transport", transport_used.as_str()),
        ];
        let mut resp = BrokerResponse {
            status: 200,
            headers: Vec::new(),
            body: response_body,
        };
        resp.headers.extend(headers);
        return resp;
    }

    log_transaction(
        state,
        verbose,
        tx_num,
        user_id,
        "EXECUTE",
        0.0,
        balance_before,
        None,
        0.0,
        "FAIL",
    );
    error_response("No worker available (local or peer)", "NO_WORKERS", 503)
}

/// Values produced by the prepare phase and consumed by the forward+finish phase.
/// Carries every field that `handle_execute`'s forward+finish half needs so that
/// `execute_prepare` can return them in one bundle.
struct PreparedForward {
    worker_uri: String,
    body: Vec<u8>,
    request_id: String,
    tx_num: u64,
    effective_timeout: f64,
    user_id: String,
    authority: Authority,
    reservation_id: String,
    balance_before: f64,
    /// Full worker snapshot — needed by `commit_credits` and the retry/timeout
    /// billing paths which access worker.id, worker.uri, worker.name, and
    /// worker.pricing. Carrying the struct rather than individual fields avoids
    /// partial duplication and lets us pass `&p.worker` directly to helpers.
    worker: Worker,
    /// Whether this execution is free (local worker or self-owned).
    is_local: bool,
    /// Credits reserved for the request (used to cap timeout charges).
    reservation_amount: f64,
    /// Instance-affinity action header ("create_instance" / "call_method" / None).
    instance_action: Option<String>,
    /// Instance ID from the affinity header.
    instance_id: Option<String>,
    /// Monotonic clock captured at the start of the request.
    start: Instant,
    /// Platform commission rate stamped in the dashboard voucher minted for
    /// this remote job (0.0 for local jobs / no voucher required). Consumed by
    /// `commit_credits` → `settle_executor_payout`.
    commission_c: f64,
    /// The minted voucher's `task_nonce`, redeemed at settlement in
    /// `commit_credits` (empty when no voucher was minted for this job).
    voucher_task_nonce: String,
}

/// Fail-closed voucher mint for the direct-forward remote path (a remote
/// worker selected outside `dispatch_to_peers` — non-P2P billing routing, or
/// instance-affinity pinning to a remote worker). Mirrors the offer path's
/// mint-or-reject, but also verifies the returned voucher's signature and
/// extracts `commission_c` + `task_nonce` here since there is no separate
/// executor-side `verify_offer_voucher` step for this path: settlement
/// happens entirely on the requester's own broker in `commit_credits`.
/// Returns `Err(response)` — the caller must reject the job with it rather
/// than falling back to an uncommissioned / unvouchered dispatch.
fn mint_and_verify_remote_voucher(
    state: &Arc<BrokerState>,
    budget: f64,
    mint_key: Option<&str>,
) -> Result<(f64, String), BrokerResponse> {
    let (_json, _sig, v) = mint_and_verify_voucher(state, budget, mint_key)?;
    Ok((v.commission_c, v.task_nonce))
}

/// Shared fail-closed mint+verify used by BOTH remote paths. Obtains a
/// dashboard-signed voucher for `budget`, REQUIRES a cached dashboard pubkey,
/// verifies the Ed25519 signature over the exact bytes, and enforces
/// `voucher_commission_valid` on the stamped `commission_c`. Any failure — no
/// api creds, mint error, no cached pubkey, bad signature, invalid/zero
/// commission — returns `Err(response)` so the caller can REJECT the job at
/// mint time (pre-dispatch), never running it uncommissioned. Returns the
/// verbatim `(signed_json, sig)` (to attach to a peer offer) plus the parsed
/// `Voucher` so a single verified `commission_c` drives BOTH the executor
/// payout and the dashboard redeem — they can never disagree.
///
/// `mint_key`: the credential the voucher is minted under. The dashboard
/// records the voucher's requester and resolves the commission tier from this
/// key, so for a job a *foreign* user submits with `Authorization: Bearer`, it
/// is THEIR key; `None` falls back to this broker's own key (the owner's jobs,
/// and paths that have no requester credential in hand).
fn mint_and_verify_voucher(
    state: &Arc<BrokerState>,
    budget: f64,
    mint_key: Option<&str>,
) -> Result<(String, String, super::voucher::Voucher), BrokerResponse> {
    let (api_url, own_key) = match (&state.config.api_url, &state.config.api_key) {
        (Some(u), Some(k)) => (u, k),
        _ => {
            return Err(error_response(
                "Voucher required for remote dispatch but broker is not configured for \
                 dashboard vouchers (missing api_url/api_key)",
                "VOUCHER_UNAVAILABLE",
                503,
            ));
        }
    };
    let api_key = mint_key.filter(|k| !k.trim().is_empty()).unwrap_or(own_key);
    let (signed_json, sig) =
        super::node_sync::obtain_voucher(api_url, api_key, budget.max(0.000_001)).map_err(|e| {
            eprintln!("  [VOUCHER] issue failed: {e}");
            error_response(
                &format!("Voucher required for remote dispatch but mint failed: {e}"),
                "VOUCHER_MINT_FAILED",
                503,
            )
        })?;
    let dash_pubkey = state
        .dash_voucher_pubkey
        .read()
        .ok()
        .and_then(|g| g.clone())
        .ok_or_else(|| {
            error_response(
                "Voucher required for remote dispatch but no dashboard voucher pubkey cached yet",
                "VOUCHER_UNAVAILABLE",
                503,
            )
        })?;
    let v =
        super::voucher::verify_voucher_now(&dash_pubkey, &signed_json, &sig, 0.0).map_err(|e| {
            eprintln!("  [VOUCHER] minted voucher failed verification: {e}");
            error_response(
                &format!("Voucher verification failed: {e}"),
                "VOUCHER_VERIFY_FAILED",
                503,
            )
        })?;
    if !voucher_commission_valid(v.commission_c) {
        eprintln!(
            "  [VOUCHER] minted voucher has invalid/zero commission_c={}, rejecting (fail-closed)",
            v.commission_c
        );
        return Err(error_response(
            "Voucher minted but commission_c invalid; refusing to dispatch uncommissioned",
            "VOUCHER_COMMISSION_INVALID",
            503,
        ));
    }
    Ok((signed_json, sig, v))
}

/// Pure fail-closed gate: a voucher's `commission_c` is only usable to settle
/// a `voucher_required` remote job when it is a real, in-range, positive rate.
/// `0.0` (no commission — e.g. a legacy/tampered/unverifiable voucher) and any
/// out-of-`[0.0, 1.0)` or non-finite value (NaN from a malformed payload) must
/// reject rather than silently settle uncommissioned. Factored out as a pure
/// function so the fail-closed decision is directly unit-testable without
/// standing up the mint/verify network round-trip.
fn voucher_commission_valid(c: f64) -> bool {
    c.is_finite() && c > 0.0 && c < 1.0
}

/// Result of the prepare phase.
#[allow(clippy::large_enum_variant)]
enum Prepared {
    /// Ready to forward to a local worker — all pre-forward work is done.
    Forward(PreparedForward),
    /// Short-circuit: prepare already produced a final response
    /// (auth failure, 402, 413, local-mode no-worker 503, or the entire
    /// P2P dispatch_to_peers path which returns its own BrokerResponse).
    Done(BrokerResponse),
}

/// Pre-forward half of execute: authenticate, balance, route, reserve credits,
/// WAL RESERVED, read body. Returns either `Prepared::Forward` (ready to call
/// `forward_to_worker`) or `Prepared::Done` (early response).
///
/// Zero behavior change vs the original `handle_execute` up to the forward call.
fn execute_prepare(state: &Arc<BrokerState>, request: &BrokerRequest, verbose: bool) -> Prepared {
    let start = Instant::now();
    let request_id = uuid::Uuid::new_v4().to_string();
    let tx_num = REQUEST_COUNTER.fetch_add(1, Ordering::SeqCst) + 1;

    // Instance affinity headers (set by RemoteProxy for stateful class instances)
    let instance_action = request.header("X-Zakuro-Instance-Action");
    let instance_id = request.header("X-Zakuro-Instance-Id");

    // Resolve user ID: prefer a Bearer token, else fall back to X-Zakuro-User.
    // A non-empty Bearer token must validate; an empty/whitespace token (e.g. a
    // client that built `Authorization: Bearer ` from an empty env var) is
    // treated as no token and falls through to the keyless path below.
    let bearer = request
        .header("Authorization")
        .and_then(|a| a.strip_prefix("Bearer ").map(|t| t.trim().to_string()))
        .filter(|t| !t.is_empty());

    // Kept for voucher minting: a foreign requester's voucher is minted under
    // THEIR credential (see `mint_and_verify_voucher`).
    let requester_key: Option<String> = bearer.clone();
    let user_id = if let Some(token) = bearer {
        match state.ledger.resolve_user_from_api_key(&token) {
            Ok(uid) => uid,
            Err(e) => return Prepared::Done(error_response(&e.to_string(), "UNAUTHORIZED", 401)),
        }
    } else if state.is_local_mode() {
        // No Bearer token: trust the X-Zakuro-User header only in local mode,
        // where execution is single-node and free. Remote mode ALWAYS requires a
        // Bearer token, independent of whether billing is enabled — auth must not
        // be coupled to billing state (audit M2). An authenticated user on a
        // billing-disabled remote broker still executes free: the credit-check
        // gate below is separately skipped when billing is off.
        request
            .header("X-Zakuro-User")
            .unwrap_or_else(|| "anonymous".to_string())
    } else {
        // Remote mode: require an API key whether or not billing is enabled.
        return Prepared::Done(error_response(
            "API key required. Set Authorization: Bearer <key>",
            "UNAUTHORIZED",
            401,
        ));
    };

    // Parse requirements from header
    let requirements: ResourceRequirements = request
        .header("X-Zakuro-Requirements")
        .and_then(|s| serde_json::from_str(&s).ok())
        .unwrap_or_default();

    // Reject invalid budget_credits early — must be positive if present
    if let Some(b) = requirements.budget_credits {
        if b <= 0.0 {
            return Prepared::Done(error_response(
                "budget_credits must be positive",
                "BAD_REQUEST",
                400,
            ));
        }
    }

    // Determine P2P authority for this user
    let authority = state.peer_manager.determine_authority(&user_id);

    // Get user balance — P2P-aware
    let balance_before = match &authority {
        Authority::Local => {
            // Authoritative: read from DashMap (loads from PG on first access)
            state.ledger.load_balance_if_needed(&user_id)
        }
        Authority::Peer(url) => {
            // Non-authoritative: ask peer, fall back to local
            if let Some(client) = state.peer_manager.get_client(url) {
                client
                    .get_balance(&user_id)
                    .unwrap_or_else(|_| state.ledger.get_balance(&user_id))
            } else {
                state.ledger.get_balance(&user_id)
            }
        }
        Authority::Standalone => state.ledger.load_balance_if_needed(&user_id),
    };

    // Sync in-memory credit manager with ledger balance (for router credit checks + rate limiting)
    let _ = state.credits.get_or_create(&user_id, balance_before);
    if matches!(authority, Authority::Peer(_)) {
        // Non-authoritative: mark balance as prefetched from peer
        state
            .credits
            .set_prefetched_balance(&user_id, balance_before);
    } else {
        state.credits.set_balance(&user_id, balance_before);
    }

    // --- Instance affinity: route call_method to the pinned worker ---
    let pinned_worker = if instance_action.as_deref() == Some("call_method") {
        if let Some(ref iid) = instance_id {
            if let Some(worker_id) = state.instance_registry.get(iid) {
                state.workers.get(worker_id.value())
            } else {
                // Instance not in registry — return clear error
                log_transaction(
                    state,
                    verbose,
                    tx_num,
                    &user_id,
                    "CALL_METHOD",
                    0.0,
                    balance_before,
                    None,
                    0.0,
                    "FAIL",
                );
                return Prepared::Done(error_response(
                    &format!("Instance not found in broker registry: {}", iid),
                    "INSTANCE_NOT_FOUND",
                    404,
                ));
            }
        } else {
            None
        }
    } else {
        None
    };

    // Select worker: use pinned worker for call_method, otherwise normal routing
    let routing = if let Some(worker) = pinned_worker {
        // Pinned worker for instance affinity — skip router
        if worker.status != WorkerStatus::Healthy {
            log_transaction(
                state,
                verbose,
                tx_num,
                &user_id,
                "CALL_METHOD",
                0.0,
                balance_before,
                Some(&worker.name),
                0.0,
                "FAIL",
            );
            // Clean up stale instance binding
            if let Some(ref iid) = instance_id {
                state.instance_registry.remove(iid.as_str());
            }
            return Prepared::Done(error_response(
                "Pinned worker is unhealthy, instance binding removed",
                "WORKER_UNHEALTHY",
                503,
            ));
        }
        RoutingDecision {
            estimated_cost: worker
                .pricing
                .estimate_cost(requirements.estimated_duration_secs),
            reason: format!("Instance affinity: pinned to {}", worker.name),
            alternatives_count: 0,
            worker,
        }
    } else if state.is_local_mode() || !state.is_billing_enabled() {
        // No billing → skip credit checks, use any worker
        match state
            .router
            .select_worker_no_checks(&state.workers, &requirements)
        {
            Ok(r) => r,
            Err(e) => {
                log_transaction(
                    state,
                    verbose,
                    tx_num,
                    &user_id,
                    "EXECUTE",
                    0.0,
                    balance_before,
                    None,
                    0.0,
                    "FAIL",
                );
                let status = if e.code == "QUOTA_EXCEEDED" { 429 } else { 503 };
                return Prepared::Done(error_response(&e.message, &e.code, status));
            }
        }
    } else if state.peer_manager.is_enabled() {
        // ── Publish-lock model (P2P + billing) ────────────────────────
        // 1) Try LOCAL workers first (self-execution = free), unless remote_only
        // 2) If no local worker (or remote_only) → publish task to peers
        let is_self_owned = state.config.owner_user_id.as_deref() == Some(user_id.as_str());
        // Targeted addressing: clients pin to a BROKER (target_node), never a
        // worker — the broker managing a set of workers has sole authority
        // over which worker runs a job. `target_worker` is a client-facing
        // no-op for routing (kept in the request schema for
        // backward-compat/observability only); see
        // docs/superpowers/specs/2026-07-11-zc-key-derived-identity-amendment.md
        // "Routing addendum".
        //
        // Resolved by fingerprint only (node_identity::node_filter_matches) — a
        // hostname/label target never resolves to "local", even if it happens to
        // look like a handle.
        let target_node = requirements.target_node.as_deref();
        let force_remote = requirements.remote_only
            || target_node
                .is_some_and(|tn| !node_identity::node_filter_matches(&state.node_key, tn));
        let try_local: Option<RoutingDecision> = if force_remote {
            None
        } else {
            let live_ts_ip =
                super::discovery::get_mesh_ip().or_else(|| state.own_wireguard_ip.clone());
            state
                .router
                .select_local_worker(&state.workers, live_ts_ip.as_deref(), &requirements)
                .ok()
        };
        if let Some(local_decision) = try_local {
            local_decision
        } else {
            // No local worker (or remote_only=true) → build offer and dispatch to peer brokers.
            {
                let body = match body_or_413(request) {
                    Ok(b) => b,
                    Err(resp) => return Prepared::Done(resp),
                };
                // When vouchers are required, obtain AND VERIFY a dashboard-signed
                // voucher authorizing this spend, then attach it to the offer.
                // Off by default (no added latency).
                //
                // Fail-closed AT MINT — same verify-at-mint discipline as the
                // direct path's `mint_and_verify_voucher`: require the cached
                // dashboard pubkey, verify the signature, and enforce
                // `voucher_commission_valid`. Any failure REJECTS the job here,
                // pre-dispatch. Crucially, the ONE verified `commission_c` is
                // captured now and threaded into `dispatch_to_peers` for the
                // executor payout — settlement no longer re-derives commission
                // via `offer_commission_c` (which returned 0.0 on a missing/
                // rotated pubkey and paid the executor the FULL cost while the
                // executor-side redeem still credited platform commission →
                // MINTED credits). Mint-time verify + threaded c means the
                // earn(payout) leg and the dashboard redeem always agree.
                let (voucher_signed_json, voucher_sig, offer_commission_c_verified) =
                    if voucher_required() {
                        let budget = requirements.budget_credits.unwrap_or(0.0);
                        if budget <= 0.0 {
                            return Prepared::Done(error_response(
                                "Voucher required for remote dispatch but no positive \
                                 budget_credits supplied",
                                "VOUCHER_UNAVAILABLE",
                                503,
                            ));
                        }
                        match mint_and_verify_voucher(state, budget, requester_key.as_deref()) {
                            Ok((j, s, v)) => (j, s, v.commission_c),
                            Err(resp) => return Prepared::Done(resp),
                        }
                    } else {
                        (String::new(), String::new(), 0.0)
                    };
                let offer = task_board::TaskOffer {
                    task_id: request_id.clone(),
                    payload_b64: base64::Engine::encode(
                        &base64::engine::general_purpose::STANDARD,
                        body,
                    ),
                    max_price_per_hour: if let Some(budget) = requirements.budget_credits {
                        let hours = requirements.estimated_duration_secs / 3600.0;
                        if hours > 0.0 {
                            budget / hours
                        } else {
                            f64::MAX
                        }
                    } else {
                        f64::MAX
                    },
                    estimated_duration_secs: requirements.estimated_duration_secs,
                    timeout_secs: requirements.timeout_secs,
                    cpus: requirements.cpus,
                    memory_bytes: requirements.memory_bytes,
                    gpus: requirements.gpus,
                    worker_type: requirements.worker_type.clone(),
                    tags: requirements.tags.clone(),
                    requester_user_id: user_id.clone(),
                    source_broker: state.config.node_name.clone().unwrap_or_default(),
                    peer_key: state.peer_manager.peer_key().to_string(),
                    // One-phase by default; the dispatcher sets this per-peer in
                    // two-phase mode (Task 4). Keeps current behavior until then.
                    two_phase: false,
                    voucher_signed_json,
                    voucher_sig,
                    // A client-supplied target_worker is never forwarded into the
                    // offer — worker selection is the accepting broker's private
                    // authority, not something a client (or a relaying peer) can
                    // steer. `target_worker` stays reserved on TaskOffer for
                    // internal/observability use only.
                    target_worker: String::new(),
                };
                state.stats.record_task_offer(TaskOfferRecord {
                    task_id: request_id.clone(),
                    timestamp: Local::now(),
                    requester_user_id: user_id.clone(),
                    max_price_per_hour: offer.max_price_per_hour,
                    source_broker: offer.source_broker.clone(),
                });

                // ── Marketplace policy pre-selection (task 5) ─────────────
                // Pick the single best-admitted peer (resource-sufficient,
                // fresh advert, lowest observed latency) and hand it to
                // `dispatch_to_peers` to try FIRST, directly, ahead of the
                // broadcast race. `ZAKURO_MARKETPLACE_SELECT=0` disables this
                // (preferred_peer stays None) for safe rollout — behavior is
                // then byte-for-byte identical to the legacy path.
                let preferred_peer = if marketplace_select_enabled() {
                    preselect_executor_peer(state, &requirements)
                } else {
                    None
                };

                return Prepared::Done(dispatch_to_peers(
                    state,
                    offer,
                    start,
                    &user_id,
                    is_self_owned,
                    &request_id,
                    tx_num,
                    verbose,
                    balance_before,
                    preferred_peer,
                    offer_commission_c_verified,
                ));
            }
        }
    } else {
        // Non-P2P billing mode: use standard routing with credit checks
        match state.router.select_worker(
            &state.workers,
            &state.credits,
            &user_id,
            balance_before,
            &requirements,
        ) {
            Ok(r) => r,
            Err(ref e) if e.code == "INSUFFICIENT_CREDITS" || e.code == "TIMEOUT_INCOMPATIBLE" => {
                if requirements.remote_only {
                    log_transaction(
                        state,
                        verbose,
                        tx_num,
                        &user_id,
                        "EXECUTE",
                        0.0,
                        balance_before,
                        None,
                        0.0,
                        "FAIL",
                    );
                    let status = if e.code == "INSUFFICIENT_CREDITS" {
                        402
                    } else {
                        503
                    };
                    return Prepared::Done(error_response(&e.message, &e.code, status));
                }
                // The free local fallback is for the OWNER's own jobs. A foreign
                // requester who cannot afford the job gets the 402 below — running
                // it free on this node's worker was an unbilled compute leak.
                let owner_here = state.config.owner_user_id.as_deref() == Some(user_id.as_str());
                let healthy = if owner_here {
                    state.workers.healthy()
                } else {
                    Vec::new()
                };
                match healthy.into_iter().find(|w| state.is_local_worker(&w.uri)) {
                    Some(local_worker) => RoutingDecision {
                        worker: local_worker,
                        estimated_cost: 0.0,
                        reason: "Local fallback - free execution".to_string(),
                        alternatives_count: 0,
                    },
                    None => {
                        log_transaction(
                            state,
                            verbose,
                            tx_num,
                            &user_id,
                            "EXECUTE",
                            0.0,
                            balance_before,
                            None,
                            0.0,
                            "FAIL",
                        );
                        let status = if e.code == "INSUFFICIENT_CREDITS" {
                            402
                        } else {
                            503
                        };
                        return Prepared::Done(error_response(&e.message, &e.code, status));
                    }
                }
            }
            Err(e) => {
                let status = match e.code.as_str() {
                    "INSUFFICIENT_CREDITS" => 402,
                    "RATE_LIMITED" | "QUOTA_EXCEEDED" => 429,
                    "NO_WORKERS" | "NO_CAPACITY" | "TIMEOUT_INCOMPATIBLE" => 503,
                    _ => 400,
                };
                log_transaction(
                    state,
                    verbose,
                    tx_num,
                    &user_id,
                    "EXECUTE",
                    0.0,
                    balance_before,
                    None,
                    0.0,
                    "FAIL",
                );
                return Prepared::Done(error_response(&e.message, &e.code, status));
            }
        }
    };

    // At this point, routing selected a local worker → execute directly.
    // (Remote execution in P2P mode already returned above via the publish-lock path.)
    let is_self_owned = state.config.owner_user_id.as_deref() == Some(&user_id);
    // "Free" means: no billing authority at all, or the owner running their
    // own jobs. Landing on THIS node's own worker is NOT what makes a job
    // free — a foreign requester who addresses this broker directly pays the
    // worker's price like anyone else, and the owner earns it (see the
    // self-executed branch in `commit_credits`). Before this, every direct
    // request to a fleet broker that its own worker could serve ran at
    // cost 0 while the same job forwarded to a peer was billed.
    let is_local = !state.is_billing_enabled() || is_self_owned;
    let self_executed =
        executor_is_self(state, &routing.worker) || state.is_local_worker(&routing.worker.uri);

    // Derive effective timeout from budget_credits if provided.
    // budget_credits / (price_per_hour / 3600) = max seconds the budget covers.
    let effective_timeout = if let Some(budget) = requirements.budget_credits {
        let price_per_sec = routing.worker.pricing.price_per_hour / 3600.0;
        let max_secs = if price_per_sec > 0.0 {
            budget / price_per_sec
        } else {
            86_400.0
        };
        if requirements.timeout_secs > 0.0 {
            max_secs.min(requirements.timeout_secs)
        } else {
            max_secs
        }
    } else {
        requirements.timeout_secs
    };

    // Calculate reservation amount: if a timeout is specified, reserve based on
    // effective_timeout * price_per_hour so a malicious user can at most lose credits
    // equal to their balance (capped by timeout). Otherwise use estimated cost.
    let reservation_amount = if !is_local && effective_timeout > 0.0 {
        // Reserve for the full timeout duration — this is the max the user can lose.
        let timeout_cost = routing.worker.pricing.estimate_cost(effective_timeout);
        // Cap reservation at user's balance — the user can at most lose what they have.
        timeout_cost.min(balance_before)
    } else {
        routing.estimated_cost
    };

    // ── Fail-closed voucher minting for the direct-forward remote path ──
    // Covers every route to a remote worker OTHER than `dispatch_to_peers`
    // (which mints its own voucher above, before building the offer): the
    // non-P2P billing path (`state.router.select_worker`) and
    // instance-affinity pinning to a remote worker. `is_local` is already
    // final at this point, so `!is_local` here always means "remote worker,
    // billing enabled" (the no-billing/local-mode branch forces `is_local`).
    //
    // Only `Authority::Local` settles commission here (`commit_credits`'s
    // `Authority::Local` branch is the sole redeem/settle site). For
    // `Authority::Peer`/`Standalone` this broker is NOT the settlement
    // authority, so minting a voucher would consume a dashboard nonce that is
    // never redeemed and the job would run uncommissioned. Fail-closed: reject
    // such a remote job under `voucher_required()` rather than mint-and-waste
    // or run for free. A mint or verification failure likewise REJECTS.
    //
    // A SELF-EXECUTED job (this broker's own worker) is settled right here on
    // every authority path — there is no remote executor to pay, the owner is
    // credited on this ledger — so it is minted (under the requester's own
    // credential) and redeemed here regardless of `authority`.
    let (commission_c, voucher_task_nonce): (f64, String) = if !is_local && voucher_required() {
        if self_executed || matches!(authority, Authority::Local) {
            match mint_and_verify_remote_voucher(
                state,
                reservation_amount.max(routing.estimated_cost),
                requester_key.as_deref(),
            ) {
                Ok(v) => v,
                Err(resp) => return Prepared::Done(resp),
            }
        } else {
            return Prepared::Done(error_response(
                "Voucher required for remote dispatch but this broker is not the \
                 settlement authority for the requester; refusing to run uncommissioned",
                "VOUCHER_NON_LOCAL_AUTHORITY",
                503,
            ));
        }
    } else {
        (0.0, String::new())
    };

    // Reserve credits — P2P-aware (skip for local worker - free execution)
    let reservation_id = if is_local {
        format!("local-{}", request_id)
    } else {
        match reserve_credits(
            state,
            &authority,
            &user_id,
            reservation_amount,
            &request_id,
            verbose,
            tx_num,
            balance_before,
        ) {
            Ok(id) => id,
            Err(resp) => return Prepared::Done(resp),
        }
    };

    // WAL: record reservation (skip for local worker)
    if !is_local {
        let _ = state.wal.append(&WalEntry {
            request_id: request_id.clone(),
            user_id: user_id.clone(),
            reservation_id: reservation_id.clone(),
            estimated_cost: reservation_amount,
            actual_cost: None,
            worker_id: routing.worker.id.clone(),
            duration_ms: None,
            timestamp: chrono::Utc::now(),
            status: WalStatus::Reserved,
        });
    }

    // Read request body BEFORE inserting into active_requests so a 413 early-return
    // does not leave a stale entry (matches original pre-split behavior where the
    // active_guard drop and the active_requests insert were both skipped on 413).
    let body = match body_or_413(request) {
        Ok(b) => b.to_vec(),
        Err(resp) => return Prepared::Done(resp),
    };

    // Track request (RAII in-flight guard is created in handle_execute just before
    // forward_to_worker so the guard's drop always pairs with the forward attempt).
    state
        .active_requests
        .insert(request_id.clone(), routing.worker.id.clone());

    let worker_uri = format!("{}/execute", routing.worker.uri.trim_end_matches('/'));

    Prepared::Forward(PreparedForward {
        worker_uri,
        body,
        request_id,
        tx_num,
        effective_timeout,
        user_id,
        authority,
        reservation_id,
        balance_before,
        worker: routing.worker,
        is_local,
        reservation_amount,
        instance_action,
        instance_id,
        start,
        commission_c,
        voucher_task_nonce,
    })
}

fn handle_execute(
    state: Arc<BrokerState>,
    request: &BrokerRequest,
    verbose: bool,
) -> BrokerResponse {
    let p = match execute_prepare(&state, request, verbose) {
        Prepared::Done(r) => return r,
        Prepared::Forward(p) => p,
    };

    // Manually increment in-flight counter (no RAII guard — execute_finish
    // is now responsible for decrementing on every exit path).
    state.workers.increment_active(&p.worker.id);

    let forward = forward_to_worker(
        &state.http_client,
        &p.worker_uri,
        &p.body,
        &p.request_id,
        p.effective_timeout,
    )
    .map(into_worker_reply)
    .map_err(|e| e.to_string());

    execute_finish(&state, verbose, p, forward)
}

/// Build the broker's async runtime.
///
/// `worker_threads` sizes tokio's async worker pool:
/// - `None` → multi-thread, one worker per CPU. Production default and the
///   configuration the async-migration benchmark was run against.
/// - `Some(n)` with `n >= 1` → multi-thread with exactly `n` workers.
/// - `Some(0)` → **current-thread** runtime: the async work runs on the
///   broker's own thread, so it spawns **no** persistent worker threads.
///
/// The `Some(0)` mode exists for the test suite. Tests start hundreds of
/// brokers in one process and never shut their runtimes down; a per-CPU (or
/// even 2-thread) worker pool *per leaked broker* accumulates ~350–1100 live
/// threads on a 20-core box, and that oversubscription starves latency-sensitive
/// tests like `test_p2p_mesh_fibonacci_500` into spurious global-timeout
/// failures. A current-thread runtime leaks ~0 persistent threads per broker,
/// so the cumulative count stays flat no matter how many brokers the suite
/// spawns. The blocking pool (capped at 64, created on demand and reaped when
/// idle) still offloads the synchronous `/execute` work in every mode.
fn build_broker_runtime(worker_threads: Option<usize>) -> std::io::Result<tokio::runtime::Runtime> {
    if matches!(worker_threads, Some(0)) {
        return tokio::runtime::Builder::new_current_thread()
            .enable_all()
            .max_blocking_threads(64)
            .build();
    }
    let mut builder = tokio::runtime::Builder::new_multi_thread();
    builder.enable_all().max_blocking_threads(64);
    if let Some(n) = worker_threads {
        builder.worker_threads(n.max(1));
    }
    builder.build()
}

/// Serve the broker HTTP API on an axum/tokio runtime bound to `host:port`.
///
/// A single catch-all fallback builds a transport-agnostic `BrokerRequest` and
/// runs the unchanged `handle()` on a bounded `spawn_blocking` pool (so the
/// long, blocking `/execute` path can never starve the async accept loop or
/// explode into an unbounded thread-per-request as the old tiny_http frontend
/// did). `handle()` itself does all routing — unknown routes fall through to
/// its own 404. Blocks the calling thread until the server stops.
/// Resolves on SIGTERM (`systemctl stop`/`restart`) or SIGINT (Ctrl-C), and
/// clears `running` as it resolves so the cleanup thread's loop (the one that
/// owns the graceful-shutdown flush block) stops waiting on its next tick
/// instead of sleeping through the shutdown. Without this, nothing ever
/// cleared `running`, so a SIGTERM killed the process before either the WAL
/// or the tx_buffer got flushed (crash-durability gap: ~2.9% payout loss
/// under chaos testing).
async fn shutdown_signal(running: Arc<AtomicBool>) {
    let ctrl_c = async {
        let _ = tokio::signal::ctrl_c().await;
    };

    #[cfg(unix)]
    let terminate = async {
        match tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) {
            Ok(mut sig) => {
                sig.recv().await;
            }
            Err(e) => {
                eprintln!("  [SHUTDOWN] failed to install SIGTERM handler: {}", e);
                std::future::pending::<()>().await;
            }
        }
    };
    #[cfg(not(unix))]
    let terminate = std::future::pending::<()>();

    tokio::select! {
        _ = ctrl_c => {}
        _ = terminate => {}
    }

    eprintln!("  [SHUTDOWN] signal received, starting graceful shutdown...");
    running.store(false, Ordering::Relaxed);
}

fn serve_axum(
    state: Arc<BrokerState>,
    host: String,
    port: u16,
    verbose: bool,
    running: Arc<AtomicBool>,
) -> std::io::Result<()> {
    use axum::extract::ConnectInfo;
    use axum::response::IntoResponse;

    let rt = build_broker_runtime(state.config.runtime_worker_threads)?;

    rt.block_on(async move {
        // /execute fast path: run execute_prepare / execute_finish directly on the
        // async runtime instead of bouncing each through a spawn_blocking handoff
        // (two thread handoffs per request). Only safe when the hot path can never
        // block:
        //   * standalone ledger (`!is_api_mode()`) — no synchronous dashboard-API
        //     auth/balance calls on the request path,
        //   * no P2P (`!peer_manager.is_enabled()`) — no synchronous peer
        //     reserve/commit calls,
        //   * WAL `fsync` is off the request thread (the dedicated flush worker).
        // Auto-enabled in that mode. `ZC_INLINE_EXECUTE` overrides either way:
        // `1`/`true` forces it on (operator asserts a non-blocking hot path),
        // any other value forces it off (keep the spawn_blocking path).
        let inline_safe = !state.ledger.is_api_mode() && !state.peer_manager.is_enabled();
        let inline_forced = std::env::var("ZC_INLINE_EXECUTE").ok();
        let inline_execute = match inline_forced.as_deref() {
            Some(v) => v == "1" || v.eq_ignore_ascii_case("true"),
            None => inline_safe,
        };
        if inline_execute {
            eprintln!(
                "[PERF] /execute inline fast path ENABLED ({})",
                if inline_forced.is_some() {
                    "forced via ZC_INLINE_EXECUTE"
                } else {
                    "auto: standalone ledger, no P2P"
                }
            );
        }
        let app = axum::Router::new()
            // ── Async /execute route: worker round-trip runs on the tokio
            // runtime instead of holding a blocking-pool thread.
            .route(
                "/execute",
                axum::routing::post({
                    let state = state.clone();
                    move |ConnectInfo(peer): ConnectInfo<SocketAddr>,
                          req: axum::extract::Request| {
                        let state = state.clone();
                        async move {
                            let breq = BrokerRequest::from_axum(req, Some(peer)).await;
                            // Phase 1: auth, routing, WAL reserve — synchronous/blocking.
                            let prepared =
                                if inline_execute {
                                    execute_prepare(&state, &breq, verbose)
                                } else {
                                    let st = state.clone();
                                    match tokio::task::spawn_blocking(move || {
                                        execute_prepare(&st, &breq, verbose)
                                    })
                                    .await
                                    {
                                        Ok(p) => p,
                                        Err(_) => return BrokerResponse::json_bytes(
                                            br#"{"error":"handler panicked","code":"INTERNAL"}"#
                                                .to_vec(),
                                            500,
                                        )
                                        .into_response(),
                                    }
                                };
                            let p = match prepared {
                                Prepared::Done(r) => return r.into_response(),
                                Prepared::Forward(p) => p,
                            };
                            // Phase 2: async worker forward (does not hold a blocking thread).
                            state.workers.increment_active(&p.worker.id);
                            let forward = forward_to_worker_async(
                                &state.async_http,
                                &p.worker_uri,
                                p.body.clone(),
                                &p.request_id,
                                p.effective_timeout,
                            )
                            .await;
                            // Phase 3: billing, WAL commit, response — synchronous/blocking.
                            // Capture worker_id before `p` is moved into the closure so we can
                            // decrement the in-flight counter if execute_finish panics.
                            let worker_id = p.worker.id.clone();
                            if inline_execute {
                                // Inline path mirrors the spawn_blocking branch's panic
                                // safety: catch_unwind so a panicking execute_finish still
                                // balances the increment_active above (otherwise the worker
                                // would leak an in-flight slot and skew routing).
                                match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
                                    execute_finish(&state, verbose, p, forward)
                                })) {
                                    Ok(r) => r.into_response(),
                                    Err(_) => {
                                        state.workers.decrement_active(&worker_id);
                                        BrokerResponse::json_bytes(
                                            br#"{"error":"handler panicked","code":"INTERNAL"}"#
                                                .to_vec(),
                                            500,
                                        )
                                        .into_response()
                                    }
                                }
                            } else {
                                let st = state.clone();
                                match tokio::task::spawn_blocking(move || {
                                    execute_finish(&st, verbose, p, forward)
                                })
                                .await
                                {
                                    Ok(r) => r.into_response(),
                                    Err(_) => {
                                        // execute_finish panicked: it never decremented the counter,
                                        // so we must balance the increment_active call above.
                                        state.workers.decrement_active(&worker_id);
                                        BrokerResponse::json_bytes(
                                            br#"{"error":"handler panicked","code":"INTERNAL"}"#
                                                .to_vec(),
                                            500,
                                        )
                                        .into_response()
                                    }
                                }
                            }
                        }
                    }
                }),
            )
            .fallback(
                move |ConnectInfo(peer): ConnectInfo<SocketAddr>, req: axum::extract::Request| {
                    let state = state.clone();
                    async move {
                        let breq = BrokerRequest::from_axum(req, Some(peer)).await;
                        match tokio::task::spawn_blocking(move || handle(state, &breq, verbose))
                            .await
                        {
                            Ok(resp) => resp.into_response(),
                            Err(_join_err) => {
                                // Handler panicked: mirror an internal error.
                                BrokerResponse::json_bytes(
                                    br#"{"error":"handler panicked","code":"INTERNAL"}"#.to_vec(),
                                    500,
                                )
                                .into_response()
                            }
                        }
                    }
                },
            );

        let listener = tokio::net::TcpListener::bind((host.as_str(), port)).await?;
        axum::serve(
            listener,
            app.into_make_service_with_connect_info::<SocketAddr>(),
        )
        .with_graceful_shutdown(shutdown_signal(running))
        .await
    })
}

/// Start the broker server
pub fn start_server(config: BrokerConfig) -> std::io::Result<()> {
    let addr = format!("{}:{}", config.host, config.port);
    let bind_host = config.host.clone();
    let bind_port = config.port;

    let verbose = config.verbose;
    let daemon = config.daemon;
    let mut broker_state = BrokerState::with_config(config.clone());

    // Startup handshake: verify broker identity with the dashboard.
    // This resolves the real owner_user_id from the API key and ensures
    // the broker only operates with a verified identity.
    if broker_state.is_billing_enabled() {
        match broker_state.verify_owner_with_dashboard() {
            Some(uid) => {
                eprintln!(
                    "  [HANDSHAKE] Verified owner: {} (dashboard confirmed)",
                    uid
                );
            }
            None => {
                eprintln!("  [HANDSHAKE] WARNING: Could not verify owner with dashboard — billing continues with configured credentials");
            }
        }
    }

    let state = Arc::new(broker_state);

    // Offline-first roster warm start: seed `node_roster` from the last
    // dashboard fetch cached to `~/.zakuro/roster.json`, so a broker that
    // restarts with the dashboard unreachable still has an authorized-node
    // roster (for both inbound `check_node_sig` and outbound discovery's
    // `RosterCache::fingerprint_authorized`) instead of starting empty and
    // rejecting every peer until the next live fetch succeeds.
    for (pk, revoked) in super::roster_cache::RosterCache::load().entries() {
        state.node_roster.insert(pk, revoked);
    }

    // Warm start: restore the peer set persisted at the end of the previous
    // run's discovery round (`peers.json`), so a restarted broker has known
    // peers immediately instead of waiting on gossip/mesh-scan/dashboard to
    // rebuild the set from scratch.
    if state.peer_manager.is_enabled() {
        state.peer_manager.load_persisted();
    }

    // Start QUIC transport for peer-to-peer task offers. Can be disabled
    // (ZAKURO_DISABLE_QUIC=1) to force the HTTP offer path in environments where
    // UDP/QUIC between nodes is blocked or unreliable.
    let quic_disabled = std::env::var("ZAKURO_DISABLE_QUIC")
        .map(|v| v == "1" || v == "true")
        .unwrap_or(false);
    if state.peer_manager.is_enabled() && !quic_disabled {
        let quic_port = config.quic_port.unwrap_or(config.port + 1);
        let quic_addr = SocketAddr::from(([0, 0, 0, 0], quic_port));

        match super::quic::QuicTransport::new(quic_addr, state.clone()) {
            Ok(qt) => {
                let actual_port = qt.local_addr().map(|a| a.port()).unwrap_or(quic_port);
                state.quic_port.store(actual_port, Ordering::Relaxed);
                let local = qt.local_addr().map(|a| a.to_string()).unwrap_or_default();
                let _ = state.quic.set(qt);
                eprintln!("  [QUIC] Listening on {} (peer task transport)", local);

                // Subscribe to peers' task feeds so we get offers pushed immediately (ultra reactive).
                let our_url = format!(
                    "http://{}:{}",
                    state.own_wireguard_ip.as_deref().unwrap_or("127.0.0.1"),
                    config.port
                );
                super::quic::run_subscription_client(
                    state.clone(),
                    our_url,
                    std::sync::Arc::new(execute_offer_locally),
                );
            }
            Err(e) => {
                eprintln!("  [QUIC] Failed to start: {} (falling back to HTTP)", e);
            }
        }

        // Spawn a delayed QUIC port discovery (peers may not be up yet)
        let state_for_discovery = state.clone();
        async_exec::spawn_detached(move || {
            thread::sleep(std::time::Duration::from_millis(500));
            state_for_discovery.peer_manager.discover_quic_ports();
        });
    }

    // Replay WAL before accepting requests
    recovery::replay_wal(
        &state.wal,
        &state.ledger,
        &state.tx_buffer,
        state.config.node_name.as_deref(),
    );

    // Running flag for graceful shutdown
    let running = Arc::new(AtomicBool::new(true));

    // Dedicated WAL flush worker: owns every fsync so no request thread blocks on
    // durable I/O (group commit, age-bounded). `append` only pushes to the
    // lock-free buffer; this worker drains + fsyncs on the age bound / size
    // threshold and does a final drain when `running` clears.
    let state_wal = state.clone();
    let running_wal = running.clone();
    async_exec::spawn_detached(move || {
        state_wal.wal.run_flush_worker(&running_wal);
    });

    // Start background cleanup thread (includes WAL compaction every 5 min).
    // Its JoinHandle is kept (not detached) so `start_server` can block on it
    // after the HTTP server stops accepting connections — that's what
    // guarantees the graceful-shutdown flush below actually runs to
    // completion before the process exits on SIGTERM/SIGINT (see
    // `shutdown_signal` in `serve_axum`).
    let state_clone = state.clone();
    let running_cleanup = running.clone();
    let cleanup_handle = std::thread::Builder::new()
        .name("zc-cleanup".into())
        .spawn(move || {
            let mut compaction_counter: u64 = 0;
            while running_cleanup.load(Ordering::Relaxed) {
                thread::sleep(std::time::Duration::from_secs(
                    state_clone.config.health_check_interval,
                ));

                state_clone
                    .workers
                    .mark_stale(state_clone.config.worker_timeout as i64);
                // Remove workers stale for >2× the timeout (well beyond recoverable)
                let removed = state_clone
                    .workers
                    .remove_stale(state_clone.config.worker_timeout as i64 * 2);
                if !removed.is_empty() {
                    eprintln!("  [HEALTH] Removed {} stale worker(s)", removed.len());
                }
                // Release two-phase offers reserved but never committed/cancelled
                // (lost commit/cancel) so worker slots don't leak.
                sweep_expired_offers(
                    &state_clone,
                    std::time::Duration::from_secs(PENDING_OFFER_TTL_SECS),
                );
                state_clone.stats.tick_rps();

                // Deployment reconciler: fetch desired state from the hub and
                // drive local docker containers toward it (every 3 ticks ≈
                // 15s at default 5s interval — see `deploy::tick`, which is
                // itself a no-op when api_url/api_key aren't configured, same
                // precondition WORKER_SYNC below has). Reuses this thread
                // rather than spawning a dedicated one: the reconciler's own
                // work (docker CLI calls, HTTP polling for health) is no more
                // blocking than the worker-sync/roster-refresh calls already
                // sharing this loop.
                if compaction_counter.is_multiple_of(3) {
                    super::deploy::tick(&state_clone);
                }

                // Periodic worker sync (every 12 ticks ≈ 60s at default 5s interval)
                if compaction_counter.is_multiple_of(12) {
                    if let Some(ref owner_id) = state_clone.config.owner_user_id {
                        // Only sync workers that belong to this node (local or matching
                        // local WireGuard IP). P2P-discovered remote workers are synced
                        // by their own brokers with the correct source_node.
                        let local_ip = super::discovery::get_effective_node_ip();
                        let workers: Vec<_> = state_clone
                            .workers
                            .list()
                            .into_iter()
                            .filter(|w| match w.wireguard_ip.as_deref() {
                                Some("127.0.0.1") | Some("::1") | Some("localhost") | None => true,
                                Some(ip) => local_ip.as_deref() == Some(ip),
                            })
                            .collect();
                        let node_name = state_clone.config.node_name.as_deref();
                        // Same key this node registers on the roster below, so the
                        // dashboard can join worker rows to a live broker.
                        let node_pubkey = state_clone.node_key.public_b64();

                        if let (Some(ref api_url), Some(ref api_key)) =
                            (&state_clone.config.api_url, &state_clone.config.api_key)
                        {
                            match super::ledger::Ledger::sync_workers_via_api(
                                owner_id,
                                &workers,
                                api_url,
                                api_key,
                                node_name,
                                local_ip.as_deref(),
                                Some(node_pubkey.as_str()),
                            ) {
                                Ok(outcome) => {
                                    let repriced =
                                        state_clone.workers.apply_hub_prices(&outcome.prices);
                                    println!(
                                        "  [WORKER_SYNC] Synced {} worker(s) to {} via API ({} repriced by the hub)",
                                        workers.len(),
                                        api_url,
                                        repriced
                                    );
                                }
                                Err(e) => {
                                    eprintln!("  [WORKER_SYNC] API sync failed: {}", e);
                                }
                            }
                        }
                    }
                }

                // Zero-trust mesh: register this node's signing key and refresh the
                // authorized-node roster + dashboard voucher pubkey (every 12 ticks).
                if compaction_counter.is_multiple_of(12) {
                    if let (Some(ref api_url), Some(ref api_key)) =
                        (&state_clone.config.api_url, &state_clone.config.api_key)
                    {
                        let pubkey = state_clone.node_key.public_b64();
                        // Task 9 consumes `self_endpoint` to filter this broker's own
                        // address out of the peer list it derives from the roster.
                        let endpoint =
                            mesh_endpoint_for(crate::vpn::native::mesh_ip(), state_clone.config.port);
                        let self_endpoint = endpoint.clone();
                        // Loud on purpose: with ZAKURO_PEERS still set the broker
                        // works cluster-native, and a silent fallback is how the
                        // mesh path stays unused. Rate-limited so a broker stuck
                        // without a tunnel (Fix 1's failure mode) doesn't page an
                        // stderr scraper every ~60s forever.
                        match MESH_ENDPOINT_LOG_GATE
                            .on_tick(endpoint.is_some(), super::node_identity::now_secs())
                        {
                            MeshEndpointLogAction::NoEndpoint => eprintln!(
                                "  [NODE_SYNC] no zakuro0 address - registering without a mesh endpoint"
                            ),
                            MeshEndpointLogAction::Recovered => println!(
                                "  [NODE_SYNC] mesh endpoint present again - registering as reachable"
                            ),
                            MeshEndpointLogAction::None => {}
                        }
                        // Whether this host can run a deployment at all. The
                        // hub judges deploy-host eligibility on it; without
                        // it a live broker with no docker is offered in the
                        // hosts list and whatever lands there sits `pending`
                        // forever. One `docker info` per node-sync round
                        // (~60s), alongside the HTTP calls already here.
                        let deploy_runtime = super::deploy::runtime_available();
                        if let Err(e) = super::node_sync::register_node(
                            api_url,
                            api_key,
                            &pubkey,
                            endpoint.as_deref(),
                            Some(deploy_runtime),
                        ) {
                            eprintln!("  [NODE_SYNC] register failed: {e}");
                        }
                        match super::node_sync::fetch_roster_full(api_url, api_key) {
                            Ok((pairs, endpoints)) => {
                                let fresh: std::collections::HashSet<String> =
                                    pairs.iter().map(|(k, _)| k.clone()).collect();
                                for (pk, revoked) in pairs.clone() {
                                    state_clone.node_roster.insert(pk, revoked);
                                }
                                // Drop nodes no longer in the roster (no empty-window race).
                                state_clone.node_roster.retain(|k, _| fresh.contains(k));
                                // Cache the live roster to disk so a restarted broker (or
                                // a discovery round while the dashboard is down) has an
                                // offline fallback (finding 2 — T1 roster cache wiring).
                                let mut cache =
                                    super::roster_cache::RosterCache::from_entries(pairs);
                                cache.set_endpoints(endpoints);
                                cache.persist();

                                // Close the loop: dial peers discovered through the
                                // roster, not just the ones named in ZAKURO_PEERS.
                                // Roster endpoints are bare "ip:port" (see
                                // `RosterCache`'s doc comment); `peer_manager`
                                // registers and compares peers as full
                                // "http://ip:port" base URLs, so
                                // `roster_peer_entries` translates before merging.
                                // Self-filtering is by identity, not address —
                                // see that function's doc comment.
                                let roster_peers = roster_peer_entries(
                                    &cache,
                                    Some(pubkey.as_str()),
                                    self_endpoint.as_deref(),
                                );

                                // Resolve identities BEFORE deduping. A
                                // ZAKURO_PEERS entry and a roster entry for the
                                // same broker are two spellings of one node
                                // (`http://zc-broker-1.zc-broker...:9000` vs
                                // `http://10.13.13.7:9000`); comparing URL
                                // strings — as the previous merge did — sees two
                                // peers and registers both, giving one broker two
                                // PeerClients, two health probes, two task-feed
                                // subscriptions, and two identical `zc://node-<fp>`
                                // rows in `zc brokers`.
                                state_clone.peer_manager.ensure_fingerprints_cached();

                                let mut keep: std::collections::HashSet<String> =
                                    std::collections::HashSet::new();
                                for rp in &roster_peers {
                                    // Same broker already registered under its
                                    // configured spelling: keep that one and add
                                    // nothing. Omitting the roster spelling from
                                    // `keep` also evicts a duplicate that an
                                    // earlier tick registered while this peer was
                                    // still unreachable (below).
                                    if state_clone
                                        .peer_manager
                                        .configured_url_for_fingerprint(&rp.fp)
                                        .is_some()
                                    {
                                        continue;
                                    }
                                    // Either a genuinely new broker, or a configured
                                    // peer whose fingerprint is not resolved yet
                                    // (never successfully probed). Register the
                                    // roster spelling: an unresolved fingerprint is a
                                    // REACHABILITY failure, and treating it as
                                    // "different broker" is the safe direction —
                                    // the alternative is refusing to dial a peer we
                                    // cannot yet identify. Any duplicate this creates
                                    // is bounded by the roster size (registration is
                                    // idempotent, so this cannot loop) and is
                                    // reconciled away on the first tick after the
                                    // configured peer answers a probe.
                                    state_clone
                                        .peer_manager
                                        .register_roster_peer(rp.url.clone());
                                    keep.insert(rp.url.clone());
                                }

                                // Peers are now removable, not just addable: a
                                // roster-derived peer that has left the roster is
                                // dropped instead of being health-checked forever.
                                // ZAKURO_PEERS-configured peers are never evicted
                                // (enforced inside `remove_roster_peer`), so a
                                // roster carrying no endpoints leaves the
                                // cluster-native fallback exactly as it was.
                                let evicted =
                                    state_clone.peer_manager.retain_roster_peers(&keep);
                                if !evicted.is_empty() {
                                    println!(
                                        "  [NODE_SYNC] Evicted {} roster-derived peer(s) no longer on the roster",
                                        evicted.len()
                                    );
                                }
                            }
                            Err(e) => eprintln!("  [NODE_SYNC] roster fetch failed: {e}"),
                        }
                        match super::node_sync::fetch_voucher_pubkey(api_url) {
                            Ok(pk) => {
                                if let Ok(mut w) = state_clone.dash_voucher_pubkey.write() {
                                    *w = Some(pk);
                                }
                            }
                            Err(e) => eprintln!("  [NODE_SYNC] voucher pubkey fetch failed: {e}"),
                        }
                    }
                }

                // Purge instance bindings for unhealthy workers
                let unhealthy_ids: Vec<String> = state_clone
                    .workers
                    .list()
                    .iter()
                    .filter(|w| w.status == WorkerStatus::Unhealthy)
                    .map(|w| w.id.clone())
                    .collect();
                if !unhealthy_ids.is_empty() {
                    state_clone
                        .instance_registry
                        .retain(|_, worker_id| !unhealthy_ids.contains(worker_id));
                }

                // Flush transaction buffer every tick — regardless of P2P mode.
                // Both P2P (local_reserve path) and Standalone (reserve path) queue to tx_buffer;
                // without this flush non-P2P billing transactions would be silently lost.
                if let (Some(ref api_url), Some(ref api_key)) =
                    (&state_clone.config.api_url, &state_clone.config.api_key)
                {
                    state_clone
                        .tx_buffer
                        .flush_to_api(api_url, api_key, &state_clone.wal);
                }
                // Also flush WAL write buffer
                if let Err(e) = state_clone.wal.flush_buffer() {
                    eprintln!("  [WAL] flush_buffer failed: {}", e);
                }

                // P2P: peer health check (every 12 ticks ≈ 60s)
                if compaction_counter.is_multiple_of(12) && state_clone.peer_manager.is_enabled() {
                    state_clone.peer_manager.health_check_all();
                }

                // P2P: roster-gated peer discovery round — merge signed gossip from
                // known peers (re-probing each hint via `discovery::accept_peer`) and
                // backfill via mesh scan when the peer set is empty (every 6 ticks
                // ≈ 30s). Gated on P2P being enabled and this node already having a
                // mesh IP (no mesh, no subnet to scan).
                if compaction_counter.is_multiple_of(6)
                    && state_clone.peer_manager.is_enabled()
                    && super::discovery::get_mesh_ip().is_some()
                {
                    // Prefer the live in-memory roster; fall back to the on-disk
                    // cache when it's empty (dashboard has never been reached
                    // this run, or `node_roster` was cleared) so discovery still
                    // has an authorized-node set to gate against offline
                    // (finding 2 — T1 roster cache wiring).
                    let roster = if state_clone.node_roster.is_empty() {
                        super::roster_cache::RosterCache::load()
                    } else {
                        super::roster_cache::RosterCache::from_entries(
                            state_clone
                                .node_roster
                                .iter()
                                .map(|e| (e.key().clone(), *e.value()))
                                .collect(),
                        )
                    };
                    super::discovery::run_discovery_round(&state_clone, &roster);
                }

                // QUIC: discover peer QUIC ports (on first tick and then periodically)
                if (compaction_counter <= 1 || compaction_counter.is_multiple_of(12))
                    && state_clone.peer_manager.is_enabled()
                    && state_clone.quic.get().is_some()
                {
                    state_clone.peer_manager.discover_quic_ports();
                }

                // P2P: reconcile stale prefetched balances (every 6 ticks ≈ 30s)
                if compaction_counter.is_multiple_of(6) && state_clone.peer_manager.is_enabled() {
                    let user_ids = state_clone.credits.get_all_user_ids();
                    for uid in user_ids {
                        if state_clone.credits.needs_reconciliation(&uid, 30) {
                            state_clone.credits.set_reconciling(&uid);
                            let authority = state_clone.peer_manager.determine_authority(&uid);
                            if let Authority::Peer(ref url) = authority {
                                if let Some(client) = state_clone.peer_manager.get_client(url) {
                                    match client.get_balance(&uid) {
                                        Ok(balance) => {
                                            state_clone
                                                .credits
                                                .set_prefetched_balance(&uid, balance);
                                        }
                                        Err(_) => {
                                            // Leave as reconciling until next attempt
                                        }
                                    }
                                }
                            }
                        }
                    }
                }

                // WAL compaction every ~5 minutes (60 ticks at 5s interval)
                compaction_counter += 1;
                if compaction_counter.is_multiple_of(60) {
                    if let Err(e) = state_clone.wal.compact() {
                        eprintln!("  [WAL] Compaction failed: {}", e);
                    }
                }
            }

            // Graceful shutdown: flush remaining transactions (always, not just in P2P mode)
            if let (Some(ref api_url), Some(ref api_key)) =
                (&state_clone.config.api_url, &state_clone.config.api_key)
            {
                eprintln!("  [FLUSH] Shutdown: flushing remaining transactions...");
                state_clone
                    .tx_buffer
                    .flush_to_api(api_url, api_key, &state_clone.wal);
            }
            if let Err(e) = state_clone.wal.flush_buffer() {
                eprintln!("  [WAL] flush_buffer failed: {}", e);
            }
        })
        .expect("failed to spawn zc-cleanup thread");

    // Start worker discovery (WireGuard or local fallback)
    if config.enable_discovery {
        let state_for_discovery = state.clone();
        let discovery_config = config.discovery.clone();
        let discovery_verbose = verbose;

        // Detect mode before spawning thread so we can log it
        let mode = detect_discovery_mode(&discovery_config.subnet);

        // Set local mode flag (free execution when not on WireGuard)
        let is_local = matches!(mode, DiscoveryMode::Local);
        state.set_local_mode(is_local);

        if verbose && !daemon {
            match &mode {
                DiscoveryMode::WireGuard { subnet } => {
                    println!(
                        "  {} WireGuard network detected (subnet: {}.0/24)",
                        "[DISCOVERY]".cyan(),
                        subnet
                    );
                }
                DiscoveryMode::Local => {
                    println!(
                        "  {} Local mode - free execution, scanning localhost:3960-3962",
                        "[DISCOVERY]".yellow()
                    );
                }
            }
        }

        async_exec::spawn_detached(move || {
            let discovery = Discovery::new(discovery_config, state_for_discovery);
            discovery.run(discovery_verbose);
        });
    }

    // Console output
    if !daemon {
        // Log ledger status
        if state.ledger.is_api_mode() {
            println!("  {} API mode - using dashboard API", "[LEDGER]".cyan());
        } else {
            println!(
                "  {} Standalone mode - using local in-memory operations",
                "[LEDGER]".yellow()
            );
        }

        // Log billing status
        if state.is_billing_enabled() {
            println!(
                "  {} Billing enabled (dashboard API authority)",
                "[BILLING]".cyan()
            );
        } else {
            println!(
                "  {} Billing disabled — all executions are free (no API credentials)",
                "[BILLING]".yellow()
            );
        }

        // Log P2P status
        if state.peer_manager.is_enabled() {
            println!(
                "  {} P2P credit operations enabled ({} peers)",
                "[P2P]".cyan(),
                state.peer_manager.peer_count(),
            );
        }

        println!("  {} Listening on {}", "[BROKER]".green().bold(), addr);

        if verbose {
            println!();
            println!("  {}", "Live Transactions:".bold().underline());
            println!("  {}", "─".repeat(80));
            println!(
                "  {}    {:>4}  {:>12} {:>8}  {:>10} {:>10} {:>8}  {}",
                "TIME".dimmed(),
                "#".dimmed(),
                "USER".dimmed(),
                "ACTION".dimmed(),
                "COST".dimmed(),
                "BALANCE".dimmed(),
                "LATENCY".dimmed(),
                "WORKER".dimmed(),
            );
            println!("  {}", "─".repeat(80));
        }
    }

    // Serve on the axum/tokio runtime. Each request runs the unchanged
    // handle() on a bounded spawn_blocking pool, so long /execute calls never
    // block the accept loop or explode into unbounded threads.
    //
    // `serve_axum` returns once `shutdown_signal` observes SIGTERM/SIGINT and
    // axum finishes draining in-flight connections. At that point `running`
    // is already false, but the cleanup thread may still be mid-sleep before
    // it notices and runs the graceful-shutdown flush block — so join it
    // here rather than letting `main()` exit out from under it and lose
    // buffered transactions.
    let serve_result = serve_axum(state, bind_host, bind_port, verbose, running);
    let _ = cleanup_handle.join();
    serve_result
}

#[cfg(test)]
mod dispatch_deadline_tests {
    use super::peer_dispatch_deadline;
    use std::time::Duration;

    #[test]
    fn unset_timeout_caps_at_30s_not_the_peer_clients_310s_default() {
        // offer.timeout_secs == 0 must NOT inherit PeerClient::offer_task's 310s
        // fallback — a slow/unresponsive peer would otherwise hang the request
        // for >5 minutes (rx.recv had no deadline).
        assert_eq!(peer_dispatch_deadline(0.0), Duration::from_secs(30));
    }

    #[test]
    fn explicit_timeout_is_honored_with_slack() {
        // A real long task keeps its budget plus slack for transport overhead.
        assert_eq!(peer_dispatch_deadline(5.0), Duration::from_secs_f64(17.0));
    }

    /// Regression test for the step-1.5 pre-selected-peer bug: a reachable
    /// but hung peer must not be able to stall the request out to
    /// `PeerClient::offer_task`'s own ~310s internal timeout (unset
    /// `timeout_secs` -> 310s fallback). The fix bounds the wait on the
    /// worker-thread channel with `peer_dispatch_deadline`, exactly
    /// mirroring the pattern this test exercises directly against a stub
    /// peer that accepts the TCP connection and then never responds.
    #[test]
    fn preselected_offer_wait_is_bounded_by_dispatch_deadline_not_offer_tasks_310s() {
        use crate::broker::peer::PeerClient;
        use crate::broker::task_board;
        use std::io::Read;
        use std::net::TcpListener;

        // A raw TCP stub: accept the connection (so PeerClient's fast
        // connect-timeout doesn't fire) but never write a response, so
        // PeerClient::offer_task would otherwise block on its own
        // timeout_global (310s for an unset offer.timeout_secs).
        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
        let addr = listener.local_addr().unwrap();
        std::thread::spawn(move || {
            if let Ok((mut stream, _)) = listener.accept() {
                let mut buf = [0u8; 1024];
                // Read the request but send nothing back; hold the
                // connection open until the test process exits.
                let _ = stream.read(&mut buf);
                std::thread::sleep(Duration::from_secs(600));
            }
        });

        let client = PeerClient::new(format!("http://{addr}"), "test-key".to_string());
        let offer: task_board::TaskOffer = serde_json::from_str(
            r#"{"task_id":"t-bound","payload_b64":"","max_price_per_hour":100.0,"estimated_duration_secs":1.0,"timeout_secs":0.0,"requester_user_id":"u","source_broker":"n"}"#,
        )
        .unwrap();

        // Mirror the exact step-1.5 pattern: offer on a worker thread,
        // recv_timeout bounded by peer_dispatch_deadline.
        let (tx, rx) = std::sync::mpsc::channel::<Result<task_board::TaskResult, String>>();
        let offer_c = offer.clone();
        std::thread::spawn(move || {
            let _ = tx.send(client.offer_task(&offer_c));
        });

        let deadline = peer_dispatch_deadline(offer.timeout_secs);
        assert_eq!(
            deadline,
            Duration::from_secs(30),
            "sanity: unset timeout_secs -> 30s bound"
        );

        let start = std::time::Instant::now();
        let outcome = rx.recv_timeout(deadline);
        let elapsed = start.elapsed();

        assert!(
            outcome.is_err(),
            "stub peer never responds, so the channel recv must itself time out"
        );
        // The wait must fall through at ~peer_dispatch_deadline (30s), with
        // generous scheduling slack — and, critically, nowhere close to
        // offer_task's own ~310s internal timeout, which was the bug.
        assert!(
            elapsed < Duration::from_secs(60),
            "pre-selected offer wait was not bounded by peer_dispatch_deadline: took {elapsed:?}"
        );
    }

    /// Regression test for the step-1.5-timeout-then-step-2-rebroadcast bug
    /// (task 5, Critical finding): when the pre-selected peer's direct offer
    /// times out or errors, it may STILL be executing the task (offers are
    /// one-phase — `PeerClient::offer_task` only returns on completion). The
    /// fix excludes that abandoned peer from step 2's broadcast set so the
    /// same task_id is never re-offered to a peer that may still be running
    /// it.
    #[test]
    fn broadcast_targets_excludes_abandoned_preferred_peer() {
        use super::broadcast_targets;

        let peers = vec![
            "http://peer-a".to_string(),
            "http://peer-b".to_string(),
            "http://peer-c".to_string(),
        ];

        // No abandoned peer (step 1.5 succeeded, or preferred_peer was
        // None) -> broadcast set is unchanged.
        assert_eq!(broadcast_targets(&peers, None), peers);

        // Step 1.5 timed out/errored on peer-b -> it must be excluded from
        // the fallback broadcast, but the other peers are untouched.
        let targets = broadcast_targets(&peers, Some("http://peer-b"));
        assert_eq!(
            targets,
            vec!["http://peer-a".to_string(), "http://peer-c".to_string()]
        );
        assert!(
            !targets.contains(&"http://peer-b".to_string()),
            "abandoned preferred peer must not be re-offered the same task_id"
        );

        // Excluding a peer not in the set is a no-op (defensive).
        assert_eq!(broadcast_targets(&peers, Some("http://peer-z")), peers);
    }
}

#[cfg(test)]
mod runtime_tests {
    use super::build_broker_runtime;

    #[test]
    fn runtime_honors_explicit_worker_thread_count() {
        let rt = build_broker_runtime(Some(2)).unwrap();
        assert_eq!(rt.metrics().num_workers(), 2);
    }

    #[test]
    fn runtime_defaults_to_multi_thread_when_unset() {
        // Production passes None → tokio's default (num_cpus) multi-thread pool,
        // unchanged from the benchmarked configuration.
        let rt = build_broker_runtime(None).unwrap();
        assert!(rt.metrics().num_workers() >= 1);
    }

    #[test]
    fn runtime_zero_workers_is_current_thread() {
        // Some(0) → current-thread runtime: no persistent worker threads, so the
        // many brokers a parallel `cargo test` leaks don't oversubscribe the CPU.
        // A current-thread runtime reports exactly one "worker" (itself).
        let rt = build_broker_runtime(Some(0)).unwrap();
        assert_eq!(rt.metrics().num_workers(), 1);
    }
}

#[cfg(test)]
mod panic_fix_tests {
    use super::header_or;
    use super::{check_node_sig, worker_to_info, BrokerRequest};

    #[test]
    fn worker_to_info_client_hides_ip_peer_keeps_it() {
        use crate::broker::node_identity::NodeKey;
        use crate::broker::worker::{Worker, WorkerRegistry};
        let reg = WorkerRegistry::new();
        let key = NodeKey::generate();
        let mut w = Worker::new(
            "id1".into(),
            "worker-xyz".into(),
            "http://10.13.13.21:3960".into(),
            "zakuro".into(),
        );
        w.source_node = Some("node-i9".into());
        w.node_fp = "abc123".into();
        w.slot = "3960".into();
        // client-facing: key-derived zc:// uri, node handle, label, no IP anywhere in the JSON
        let ci = worker_to_info(&w, &reg, &key, true);
        assert_eq!(ci.uri, "zc://worker-abc123-3960");
        assert_eq!(ci.node.as_deref(), Some("zc://node-i9"));
        assert_eq!(ci.label.as_deref(), Some("worker-xyz"));
        let cj = serde_json::to_string(&ci).unwrap();
        assert!(!cj.contains("10.13.13.") && !cj.contains(":3960") && !cj.contains("http://"));
        // peer-facing: real uri retained
        let pi = worker_to_info(&w, &reg, &key, false);
        assert_eq!(pi.uri, "http://10.13.13.21:3960");
    }

    #[test]
    fn worker_to_info_carries_provider_fields_for_peers() {
        // zc#172: /peer/workers must carry the provider fields, or a peer
        // broker rebuilds this worker without them and its model index never
        // learns about the provider.
        use crate::broker::node_identity::NodeKey;
        use crate::broker::worker::{ProviderType, Worker, WorkerRegistry};
        let reg = WorkerRegistry::new();
        let key = NodeKey::generate();
        let mut w = Worker::new(
            "id3".into(),
            "zc-serve-116c1f8b".into(),
            "http://192.168.0.167:8600".into(),
            "llm".into(),
        );
        w.provider_type = ProviderType::Specialized;
        w.served_models = vec!["116c1f8b-7a22-452a-867c-f8b20afdb355".into()];
        w.price_per_mtok = 1.5;
        let pi = worker_to_info(&w, &reg, &key, false);
        assert_eq!(pi.provider_type, ProviderType::Specialized);
        assert_eq!(pi.served_models, w.served_models);
        assert_eq!(pi.price_per_mtok, 1.5);
        // and they survive serialization in the lowercase wire form
        let j = serde_json::to_value(&pi).unwrap();
        assert_eq!(j["provider_type"], "specialized");
        assert_eq!(
            j["served_models"][0],
            "116c1f8b-7a22-452a-867c-f8b20afdb355"
        );
    }

    #[test]
    fn no_client_surface_emits_ip() {
        // Render a full /workers client payload (WorkerListResponse, the actual
        // GET /workers response body) for a worker whose internal uri carries a
        // mesh IP, and confirm the IP never crosses the client boundary.
        use crate::broker::node_identity::NodeKey;
        use crate::broker::worker::{Worker, WorkerRegistry};
        let reg = WorkerRegistry::new();
        let key = NodeKey::generate();
        let mut w = Worker::new(
            "id2".into(),
            "worker-abc".into(),
            "http://10.13.13.5:3960".into(),
            "zakuro".into(),
        );
        w.node_fp = key.fingerprint();
        w.slot = "3960".into();
        let ci = worker_to_info(&w, &reg, &key, true);
        let body = serde_json::to_string(&super::WorkerListResponse {
            total: 1,
            workers: vec![ci],
        })
        .unwrap();
        assert!(!body.contains("10.13.13."));
        assert!(body.contains("zc://worker-"));
    }

    #[test]
    fn client_response_uses_key_derived_node_uri() {
        use crate::broker::node_identity::NodeKey;
        use crate::broker::worker::{Worker, WorkerRegistry};
        let key = NodeKey::generate();
        let handle = super::node_handle_for(&key, Some("lxd"));
        assert_eq!(handle, key.node_uri());
        assert!(handle.starts_with("zc://node-"));
        assert!(!handle.contains("lxd")); // hostname is not the identity

        // Also verify it flows through worker_to_info for a local worker (no source_node).
        let reg = WorkerRegistry::new();
        let w = Worker::new(
            "id2".into(),
            "local-worker".into(),
            "http://127.0.0.1:3960".into(),
            "zakuro".into(),
        );
        let ci = worker_to_info(&w, &reg, &key, true);
        assert_eq!(ci.node.as_deref(), Some(key.node_uri().as_str()));
    }

    #[test]
    fn capped_charge_never_exceeds_reserved() {
        use super::capped_charge;
        assert!((capped_charge(0.05, 0.02) - 0.02).abs() < 1e-9); // over → capped
        assert!((capped_charge(0.01, 0.02) - 0.01).abs() < 1e-9); // under → unchanged
        assert_eq!(capped_charge(f64::NAN, 0.02), 0.0); // non-finite → 0
        assert_eq!(capped_charge(-1.0, 0.02), 0.0); // negative → 0
    }

    #[test]
    fn header_or_accepts_valid_value() {
        let (k, v) = header_or("X-Zakuro-Worker", "node-01");
        assert_eq!(k, "X-Zakuro-Worker");
        assert_eq!(v, "node-01");
    }

    #[test]
    fn check_node_sig_accepts_rostered_signer_rejects_others() {
        use crate::broker::node_identity::{NodeKey, ReplayGuard};
        use dashmap::DashMap;
        use tiny_http::Method;

        let key = NodeKey::generate();
        let path = "/peer/tasks/offer";
        let body = br#"{"fn":"greet"}"#.to_vec();
        let hdrs = key.sign_headers("POST", path, &body);

        let build = |headers: Vec<(String, String)>, body: Vec<u8>| BrokerRequest {
            method: Method::Post,
            path: path.to_string(),
            query: String::new(),
            headers,
            body,
            peer_addr: None,
        };

        let roster = DashMap::new();
        roster.insert(key.public_b64(), false); // authorized
        let guard = ReplayGuard::new();
        let now = crate::broker::node_identity::now_secs();

        // valid, rostered → Ok(signer)
        let req = build(hdrs.clone(), body.clone());
        assert_eq!(
            check_node_sig(&roster, &guard, &req, now).unwrap(),
            key.public_b64()
        );

        // revoked → rejected
        roster.insert(key.public_b64(), true);
        let g2 = ReplayGuard::new();
        let req2 = build(hdrs.clone(), body.clone());
        assert!(check_node_sig(&roster, &g2, &req2, now).is_err());
        roster.insert(key.public_b64(), false);

        // tampered body → bad signature
        let g3 = ReplayGuard::new();
        let req3 = build(hdrs.clone(), b"{}".to_vec());
        assert!(check_node_sig(&roster, &g3, &req3, now).is_err());

        // unsigned → rejected
        let g4 = ReplayGuard::new();
        let req4 = build(vec![], body);
        assert!(check_node_sig(&roster, &g4, &req4, now).is_err());
    }

    #[test]
    fn peer_peers_requires_valid_node_signature_and_signs_response() {
        use crate::broker::node_identity::{verify_sig, NodeKey};
        use crate::broker::BrokerState;
        use std::sync::Arc;
        use tiny_http::Method;

        let state = BrokerState::new();
        let signer = NodeKey::generate();
        state.node_roster.insert(signer.public_b64(), false); // authorized
        let state = Arc::new(state);

        // Unsigned request → 401, never served.
        let unsigned = BrokerRequest {
            method: Method::Get,
            path: "/peer/peers".to_string(),
            query: String::new(),
            headers: vec![],
            body: vec![],
            peer_addr: None,
        };
        let resp = super::handle(Arc::clone(&state), &unsigned, false);
        assert_eq!(resp.status, 401);

        // Signed by a rostered node → 200, and the response itself carries a
        // valid X-Node-Id/X-Node-Sig over the exact body bytes.
        let hdrs = signer.sign_headers("GET", "/peer/peers", b"");
        let signed = BrokerRequest {
            method: Method::Get,
            path: "/peer/peers".to_string(),
            query: String::new(),
            headers: hdrs,
            body: vec![],
            peer_addr: None,
        };
        let resp = super::handle(Arc::clone(&state), &signed, false);
        assert_eq!(resp.status, 200);

        let get = |name: &str| -> Option<String> {
            resp.headers
                .iter()
                .find(|(k, _)| k.eq_ignore_ascii_case(name))
                .map(|(_, v)| v.clone())
        };
        let node_id = get("X-Node-Id").expect("response signed with X-Node-Id");
        let sig = get("X-Node-Sig").expect("response signed with X-Node-Sig");
        assert_eq!(node_id, state.node_key.public_b64());
        assert!(verify_sig(&node_id, &resp.body, &sig));

        let parsed: serde_json::Value = serde_json::from_slice(&resp.body).unwrap();
        assert!(parsed["peers"].as_array().is_some());
    }

    #[test]
    fn header_or_does_not_panic_on_peer_supplied_garbage() {
        // A peer could return a worker name with non-ASCII bytes (>127), which
        // HTTP header validation rejects — the old `.unwrap()` panicked here.
        // header_or must NOT panic; it falls back to a marker header.
        let (k, v) = header_or("X-Zakuro-Worker", "wörker\u{00ff}");
        assert_eq!(k, "X-Zakuro-Invalid");
        assert_eq!(v, "1");
    }

    #[test]
    fn health_endpoint_body_has_no_mesh_ip() {
        // GET /health end-to-end: the client body must report connectivity as
        // a bool only — never the raw mesh IP (10.13.13.x) or a loopback
        // address masquerading as an identity.
        use crate::broker::BrokerState;
        use std::sync::Arc;
        use tiny_http::Method;

        let mut state = BrokerState::new();
        state.own_wireguard_ip = Some("10.13.13.42".to_string());
        let state = Arc::new(state);

        let req = BrokerRequest {
            method: Method::Get,
            path: "/health".to_string(),
            query: String::new(),
            headers: vec![],
            body: vec![],
            peer_addr: None,
        };
        let resp = super::handle(state, &req, false);
        let body = String::from_utf8(resp.body).unwrap();
        assert!(
            !body.contains("10.13.13."),
            "health body leaked mesh IP: {body}"
        );
        assert!(
            !body.contains("127.0.0.1"),
            "health body leaked loopback: {body}"
        );
        assert!(body.contains("wireguard_connected"));
        assert!(!body.contains("\"wireguard_ip\""));
    }

    /// Fix E: `/health` must never contradict itself. `wireguard_connected`
    /// and `mesh_tunnel` describe the same fact, so "connected but tunnel
    /// down" is an impossible pair. Before the fix the two were computed from
    /// two different detectors and this state was reachable both in-container
    /// (no `ip` binary) and here (a cached `own_wireguard_ip` that
    /// `mesh_tunnel` never consulted).
    #[test]
    fn health_wireguard_connected_and_mesh_tunnel_never_disagree() {
        use crate::broker::BrokerState;
        use std::sync::Arc;
        use tiny_http::Method;

        let mut state = BrokerState::new();
        state.own_wireguard_ip = Some("10.13.13.42".to_string());
        let state = Arc::new(state);

        let req = BrokerRequest {
            method: Method::Get,
            path: "/health".to_string(),
            query: String::new(),
            headers: vec![],
            body: vec![],
            peer_addr: None,
        };
        let resp = super::handle(state, &req, false);
        let body: serde_json::Value =
            serde_json::from_slice(&resp.body).expect("/health returns JSON");

        let connected = body["wireguard_connected"]
            .as_bool()
            .expect("wireguard_connected is a bool");
        let tunnel = body["mesh_tunnel"]
            .as_str()
            .expect("mesh_tunnel is a string");

        // Shapes are unchanged: bool, and the "up"/"down" enum.
        assert!(tunnel == "up" || tunnel == "down", "mesh_tunnel={tunnel}");
        assert_eq!(
            connected,
            tunnel == "up",
            "/health contradicts itself: wireguard_connected={connected} mesh_tunnel={tunnel}"
        );
    }

    #[test]
    fn stats_worker_and_response_serialization_has_no_mesh_ip() {
        // WorkerStats.uri and StatsResponse.wireguard_ip are the two
        // /stats fields that used to carry the raw mesh IP straight to the
        // client. Assert both are IP-free once redacted the way the /stats
        // handler builds them (key-derived uri; wireguard_ip: None).
        use crate::broker::stats::{StatsCollector, StatsResponse, WorkerStats};

        let ws = WorkerStats {
            id: "id1".into(),
            name: "worker-abc".into(),
            uri: "zc://worker-abc123-3960".into(), // as built via w.zc_uri()
            status: "healthy".into(),
            cpus_available: 1.0,
            memory_available_gib: 1.0,
            gpus_available: 0,
            price_per_hour: 0.0,
            active_requests: 0,
            avg_latency_ms: 0.0,
        };
        let ws_json = serde_json::to_string(&ws).unwrap();
        assert!(!ws_json.contains("10.13.13."));
        assert!(!ws_json.contains("127.0.0.1"));
        assert!(ws_json.contains("zc://worker-"));

        let resp = StatsResponse {
            host: "0.0.0.0".into(),
            port: 8080,
            transactions: vec![],
            task_offers: vec![],
            workers: vec![ws],
            metrics: StatsCollector::new().metrics(0, 0, true, false, None),
            rps_history: vec![],
            wireguard_ip: None,
            wireguard_connected: true,
        };
        let resp_json = serde_json::to_string(&resp).unwrap();
        assert!(
            !resp_json.contains("10.13.13."),
            "stats body leaked mesh IP: {resp_json}"
        );
        assert!(
            !resp_json.contains("127.0.0.1"),
            "stats body leaked loopback: {resp_json}"
        );
    }

    #[test]
    fn mesh_endpoint_is_ip_plus_bound_port() {
        // The advertised port is whatever this broker actually bound, not a
        // hardcoded 9000 -- a user may run a broker anywhere.
        assert_eq!(
            super::mesh_endpoint_for(Some("10.13.13.6".to_string()), 9100).as_deref(),
            Some("10.13.13.6:9100")
        );
        assert_eq!(super::mesh_endpoint_for(None, 9000), None);
    }

    // --- Fix 2: rate-limited "no mesh endpoint" logging ---

    #[test]
    fn mesh_endpoint_log_gate_logs_on_first_absence() {
        let gate = super::MeshEndpointLogGate::new();
        assert_eq!(
            gate.on_tick(false, 1_000),
            super::MeshEndpointLogAction::NoEndpoint
        );
    }

    #[test]
    fn mesh_endpoint_log_gate_suppresses_repeat_within_interval() {
        let gate = super::MeshEndpointLogGate::new();
        assert_eq!(
            gate.on_tick(false, 1_000),
            super::MeshEndpointLogAction::NoEndpoint
        );
        // Still absent 60s later (one more tick) -- must not log again yet.
        assert_eq!(
            gate.on_tick(false, 1_060),
            super::MeshEndpointLogAction::None
        );
    }

    #[test]
    fn mesh_endpoint_log_gate_logs_again_after_interval_elapses() {
        let gate = super::MeshEndpointLogGate::new();
        assert_eq!(
            gate.on_tick(false, 1_000),
            super::MeshEndpointLogAction::NoEndpoint
        );
        // ~30 minutes later, still absent -- loud again.
        assert_eq!(
            gate.on_tick(false, 1_000 + 30 * 60),
            super::MeshEndpointLogAction::NoEndpoint
        );
    }

    #[test]
    fn mesh_endpoint_log_gate_logs_recovery_on_transition_back() {
        let gate = super::MeshEndpointLogGate::new();
        assert_eq!(
            gate.on_tick(false, 1_000),
            super::MeshEndpointLogAction::NoEndpoint
        );
        assert_eq!(
            gate.on_tick(true, 1_005),
            super::MeshEndpointLogAction::Recovered
        );
    }

    #[test]
    fn mesh_endpoint_log_gate_stays_silent_while_connected() {
        // A broker that has always had a mesh endpoint (the common case)
        // must never log anything -- no transition, no periodic reminder.
        let gate = super::MeshEndpointLogGate::new();
        assert_eq!(
            gate.on_tick(true, 1_000),
            super::MeshEndpointLogAction::None
        );
        assert_eq!(
            gate.on_tick(true, 1_000 + 30 * 60),
            super::MeshEndpointLogAction::None
        );
    }

    // --- Fix 4: roster -> peer URL derivation (self-filter + http:// prefix) ---

    /// Project `roster_peer_entries` down to just its URLs, the shape the
    /// pre-Fix-D assertions were written against.
    fn urls_of(entries: Vec<super::RosterPeer>) -> Vec<String> {
        entries.into_iter().map(|e| e.url).collect()
    }

    /// Fix D: the self-filter must key on IDENTITY, so it still works when
    /// this node's tunnel is down.
    ///
    /// This is the flap case and it is the whole point: `self_endpoint` is
    /// derived from `mesh_ip()`, so it is `None` exactly when the tunnel is
    /// down — while this node's own STALE endpoint is still on the roster,
    /// because registration treats an omitted endpoint as "unchanged". The
    /// address filter is therefore disabled precisely when it has something
    /// to filter, and the broker dials itself.
    #[test]
    fn roster_peer_entries_excludes_self_by_pubkey_when_tunnel_is_down() {
        use crate::broker::node_identity::NodeKey;
        use crate::broker::roster_cache::RosterCache;

        let self_key = NodeKey::generate();
        let peer_key = NodeKey::generate();
        let mut cache = RosterCache::from_entries(vec![
            (self_key.public_b64(), false),
            (peer_key.public_b64(), false),
        ]);
        // This node's own stale endpoint is still advertised on the roster.
        cache.set_endpoints(vec![
            (self_key.public_b64(), "10.13.13.5:9000".to_string()),
            (peer_key.public_b64(), "10.13.13.6:9000".to_string()),
        ]);

        // Tunnel down => self_endpoint is None, so ONLY identity can filter.
        let urls = urls_of(super::roster_peer_entries(
            &cache,
            Some(&self_key.public_b64()),
            None,
        ));

        assert_eq!(
            urls,
            vec!["http://10.13.13.6:9000".to_string()],
            "broker registered itself as a peer while its tunnel was down"
        );
    }

    /// The identity filter must not depend on the roster row's address at all:
    /// even if this node's roster endpoint has been reassigned to a different
    /// address than it last advertised, the row is still self.
    #[test]
    fn roster_peer_entries_excludes_self_even_when_its_address_changed() {
        use crate::broker::node_identity::NodeKey;
        use crate::broker::roster_cache::RosterCache;

        let self_key = NodeKey::generate();
        let mut cache = RosterCache::from_entries(vec![(self_key.public_b64(), false)]);
        cache.set_endpoints(vec![(
            self_key.public_b64(),
            "10.13.13.99:9000".to_string(),
        )]);

        let urls = urls_of(super::roster_peer_entries(
            &cache,
            Some(&self_key.public_b64()),
            Some("10.13.13.5:9000"),
        ));
        assert!(
            urls.is_empty(),
            "self row survived the identity filter: {urls:?}"
        );
    }

    /// A revoked node must stay unaddressable even if it is somehow also this
    /// node's own key — revocation and reachability are the same row.
    #[test]
    fn roster_peer_entries_still_drops_revoked_rows_with_identity_filter_on() {
        use crate::broker::node_identity::NodeKey;
        use crate::broker::roster_cache::RosterCache;

        let self_key = NodeKey::generate();
        let revoked = NodeKey::generate();
        let mut cache = RosterCache::from_entries(vec![
            (self_key.public_b64(), false),
            (revoked.public_b64(), true),
        ]);
        cache.set_endpoints(vec![(revoked.public_b64(), "10.13.13.7:9000".to_string())]);

        assert!(super::roster_peer_entries(&cache, Some(&self_key.public_b64()), None).is_empty());
    }

    /// The fingerprint travelling with the URL is the one Fix C dedups on, so
    /// it must actually match the node's key-derived identity.
    #[test]
    fn roster_peer_entries_carry_the_nodes_fingerprint() {
        use crate::broker::node_identity::NodeKey;
        use crate::broker::roster_cache::RosterCache;

        let peer_key = NodeKey::generate();
        let mut cache = RosterCache::from_entries(vec![(peer_key.public_b64(), false)]);
        cache.set_endpoints(vec![(peer_key.public_b64(), "10.13.13.6:9000".to_string())]);

        let entries = super::roster_peer_entries(&cache, None, None);
        assert_eq!(entries.len(), 1);
        assert_eq!(entries[0].fp, peer_key.fingerprint());
        assert_eq!(entries[0].url, "http://10.13.13.6:9000");
    }

    #[test]
    fn roster_peer_urls_skips_revoked_entries() {
        use crate::broker::node_identity::NodeKey;
        use crate::broker::roster_cache::RosterCache;

        let key = NodeKey::generate();
        let mut cache = RosterCache::from_entries(vec![(key.public_b64(), true)]);
        cache.set_endpoints(vec![(key.public_b64(), "10.13.13.6:9000".to_string())]);

        assert!(super::roster_peer_entries(&cache, None, None).is_empty());
    }

    #[test]
    fn roster_peer_urls_excludes_self_endpoint() {
        use crate::broker::node_identity::NodeKey;
        use crate::broker::roster_cache::RosterCache;

        let self_key = NodeKey::generate();
        let peer_key = NodeKey::generate();
        let mut cache = RosterCache::from_entries(vec![
            (self_key.public_b64(), false),
            (peer_key.public_b64(), false),
        ]);
        cache.set_endpoints(vec![
            (self_key.public_b64(), "10.13.13.5:9000".to_string()),
            (peer_key.public_b64(), "10.13.13.6:9000".to_string()),
        ]);

        let urls = urls_of(super::roster_peer_entries(
            &cache,
            None,
            Some("10.13.13.5:9000"),
        ));
        assert_eq!(urls, vec!["http://10.13.13.6:9000".to_string()]);
    }

    #[test]
    fn roster_peer_urls_prefixes_bare_addresses_with_http() {
        use crate::broker::node_identity::NodeKey;
        use crate::broker::roster_cache::RosterCache;

        let key = NodeKey::generate();
        let mut cache = RosterCache::from_entries(vec![(key.public_b64(), false)]);
        cache.set_endpoints(vec![(key.public_b64(), "10.13.13.6:9000".to_string())]);

        assert_eq!(
            urls_of(super::roster_peer_entries(&cache, None, None)),
            vec!["http://10.13.13.6:9000".to_string()]
        );
    }

    #[test]
    fn roster_peer_urls_empty_roster_yields_empty_vec() {
        use crate::broker::roster_cache::RosterCache;

        let cache = RosterCache::from_entries(vec![]);
        assert!(super::roster_peer_entries(&cache, None, None).is_empty());
    }

    #[test]
    fn roster_peer_urls_skips_empty_and_whitespace_only_endpoints() {
        use crate::broker::node_identity::NodeKey;
        use crate::broker::roster_cache::RosterCache;

        let blank_key = NodeKey::generate();
        let good_key = NodeKey::generate();
        let mut cache = RosterCache::from_entries(vec![
            (blank_key.public_b64(), false),
            (good_key.public_b64(), false),
        ]);
        cache.set_endpoints(vec![
            (blank_key.public_b64(), "   ".to_string()),
            (good_key.public_b64(), "10.13.13.6:9000".to_string()),
        ]);

        assert_eq!(
            urls_of(super::roster_peer_entries(&cache, None, None)),
            vec!["http://10.13.13.6:9000".to_string()]
        );
    }
}

#[cfg(test)]
mod two_phase_tests {
    use super::{
        cancel_offer, earn_refund_amount, offer_commission_c, reserve_offer, split_commission,
        sweep_expired_offers, take_committed, voucher_commission_valid,
    };
    use crate::broker::{task_board, BrokerState, PendingOffer};

    fn mk_offer(task_id: &str) -> task_board::TaskOffer {
        serde_json::from_str(&format!(
            r#"{{"task_id":"{}","payload_b64":"","max_price_per_hour":100.0,"estimated_duration_secs":1.0,"timeout_secs":10.0,"requester_user_id":"u","source_broker":"n"}}"#,
            task_id
        )).unwrap()
    }

    #[test]
    fn split_commission_ten_percent_exact() {
        let (payout, commission) = split_commission(100.0, 0.1);
        assert_eq!(commission, 10.0);
        assert_eq!(payout, 90.0);
        // No leak: the two legs sum back to gross exactly.
        assert_eq!(payout + commission, 100.0);
    }

    #[test]
    fn split_commission_min_charge_no_leak() {
        let gross = 0.001;
        let (payout, commission) = split_commission(gross, 0.1);
        // The exact-subtraction split must reconstruct gross to the last bit,
        // even when gross*c is not representable.
        assert_eq!(payout + commission, gross);
    }

    #[test]
    fn split_commission_zero_is_identity() {
        let (payout, commission) = split_commission(42.5, 0.0);
        assert_eq!(payout, 42.5);
        assert_eq!(commission, 0.0);
    }

    /// Conservation invariant of remote-dispatch settlement: for ANY cost and
    /// commission rate, executor earn + platform commission == the requester's
    /// charge (`cost`). This models both settlement branches in
    /// `dispatch_to_peers`: commissioned (payout,commission)=split_commission,
    /// and non-commissioned (earn=cost, commission=0). Guards against the
    /// wall-clock-duration earn regression that minted credits under load.
    #[test]
    fn settlement_conserves_for_all_commission_rates() {
        for &cost in &[0.001_f64, 1.0, 0.036668, 100.0, 0.0] {
            for &c in &[0.0_f64, 0.1, 0.5, 0.9, 0.999] {
                let (earn, commission) = if c > 0.0 {
                    split_commission(cost, c)
                } else {
                    (cost, 0.0)
                };
                assert_eq!(
                    earn + commission,
                    cost,
                    "conservation broken: cost={cost} c={c} earn={earn} commission={commission}"
                );
            }
        }
    }

    /// `settle_executor_payout` (used by BOTH the offer path and the
    /// direct-forward path, universally) is a thin wrapper around
    /// `split_commission` — this is the payout+commission==cost invariant it
    /// relies on, exercised directly at the exact rates named in the fix spec.
    #[test]
    fn settle_payout_conserves_at_named_commission_rates() {
        for &cost in &[0.001_f64, 1.0, 100.0] {
            for &c in &[0.0_f64, 0.1, 0.5] {
                let (payout, commission) = split_commission(cost, c);
                assert_eq!(payout + commission, cost, "cost={cost} c={c}");
                if c == 0.0 {
                    assert_eq!(commission, 0.0);
                    assert_eq!(payout, cost);
                } else {
                    assert!(commission > 0.0, "commission must be > 0 for c={c}");
                }
            }
        }
    }

    /// Money-critical chaos-found bug fix: when the executor's broker can't
    /// be paid (restarted between job completion and the earn RPC, or the
    /// peer is unresolvable), `settle_executor_payout` must refund the
    /// requester the `payout` leg instead of silently dropping it — otherwise
    /// requester -cost, executor +0, platform +commission leaks `payout`
    /// credits out of the system. This exercises the full conservation
    /// invariant, both on earn-success and earn-fail, at the named
    /// commission rates from the fix spec.
    #[test]
    fn earn_refund_conserves_on_success_and_failure() {
        for &cost in &[0.001_f64, 1.0, 0.036668, 100.0] {
            for &c in &[0.0_f64, 0.1, 0.5, 0.9] {
                let (payout, commission) = split_commission(cost, c);

                // earn succeeds: requester -cost, executor +payout, platform
                // +commission.
                let refund_ok = earn_refund_amount(payout, true);
                assert_eq!(refund_ok, 0.0);
                let requester_net_ok = -cost + refund_ok;
                let executor_delta_ok = payout;
                let platform_delta_ok = commission;
                let sum_ok = requester_net_ok + executor_delta_ok + platform_delta_ok;
                assert!(
                    sum_ok.abs() < 1e-9,
                    "earn-success conservation broken: cost={cost} c={c} sum={sum_ok}"
                );
                assert!(
                    (requester_net_ok - (-cost)).abs() < 1e-9,
                    "cost={cost} c={c}"
                );

                // earn fails: requester refunded `payout`, netting -commission;
                // executor gets nothing; platform still keeps its commission.
                let refund_fail = earn_refund_amount(payout, false);
                assert_eq!(refund_fail, payout);
                let requester_net_fail = -cost + refund_fail;
                let executor_delta_fail = 0.0;
                let platform_delta_fail = commission;
                let sum_fail = requester_net_fail + executor_delta_fail + platform_delta_fail;
                assert!(
                    sum_fail.abs() < 1e-9,
                    "earn-fail conservation broken: cost={cost} c={c} sum={sum_fail}"
                );
                assert!(
                    (requester_net_fail - (-commission)).abs() < 1e-9,
                    "requester should net exactly -commission when earn fails: cost={cost} c={c}"
                );
            }
        }
    }

    /// `commit_credits` `Authority::Local` None-arm (executor worker IP can't
    /// be resolved to a peer URL — the peer was temporarily evicted from the
    /// registry mid-restart under chaos): the requester was already debited
    /// `actual_cost` via `local_commit`, but NO executor earn, NO platform
    /// credit and NO voucher redeem happen. So the requester must be refunded
    /// the FULL `actual_cost` (not just payout), making them whole. This
    /// documents that net-zero conservation: requester -actual_cost
    /// +actual_cost == 0, executor 0, platform 0.
    #[test]
    fn unresolved_peer_full_refund_makes_requester_whole() {
        for &actual_cost in &[0.001_f64, 1.0, 0.036668, 100.0] {
            // Debit then full refund in the None arm.
            let requester_net = -actual_cost + actual_cost;
            let executor_delta = 0.0;
            let platform_delta = 0.0; // no earn, no commission, no redeem
            let sum = requester_net + executor_delta + platform_delta;
            assert!(
                sum.abs() < 1e-9,
                "unresolved-peer conservation broken: actual_cost={actual_cost} sum={sum}"
            );
            assert!(
                requester_net.abs() < 1e-9,
                "requester must be made whole (net 0): actual_cost={actual_cost}"
            );
        }
    }

    /// Fail-closed gate unit tests: `voucher_commission_valid` is the pure
    /// decision function both `mint_and_verify_remote_voucher` (direct-forward
    /// path) and the offer-path post-execution check consult. A `false` here
    /// must translate to a REJECT (mint-or-reject / logged commission-loss),
    /// never a silent fall-through to uncommissioned settlement.
    ///
    /// Integration gap: the full "mint fails at the network layer → the
    /// request is rejected with a 503" behavior is exercised by
    /// `mint_and_verify_remote_voucher`'s `Result<_, BrokerResponse>` return
    /// and consumed in `execute_prepare`/`dispatch_to_peers` via `return
    /// Prepared::Done(resp)` — that requires a running broker + mocked
    /// dashboard HTTP endpoint to test end-to-end, which the existing
    /// integration harness does not yet stand up for the voucher endpoints.
    /// This unit test covers the decision logic those call sites depend on.
    #[test]
    fn voucher_commission_valid_gate() {
        assert!(voucher_commission_valid(0.1));
        assert!(voucher_commission_valid(0.5));
        assert!(voucher_commission_valid(0.999));
        assert!(
            !voucher_commission_valid(0.0),
            "zero commission fails closed"
        );
        assert!(!voucher_commission_valid(1.0), "out of [0,1) fails closed");
        assert!(!voucher_commission_valid(1.5), "out of range fails closed");
        assert!(!voucher_commission_valid(-0.1), "negative fails closed");
        assert!(!voucher_commission_valid(f64::NAN), "NaN fails closed");
    }

    /// Offer-path (and direct-path) fail-closed reject at the config gate: a
    /// broker with no dashboard api creds configured MUST reject a
    /// voucher-required remote job with a 503 rather than dispatch it
    /// uncommissioned. This reaches the real `mint_and_verify_voucher` short of
    /// any network I/O (the api-creds check is the first gate), so it exercises
    /// the actual reject wiring both paths consume, not just the pure gate.
    #[test]
    fn mint_and_verify_voucher_rejects_without_api_creds() {
        let state = std::sync::Arc::new(BrokerState::new());
        let resp = super::mint_and_verify_voucher(&state, 5.0, None)
            .expect_err("no api creds → fail-closed reject");
        assert_eq!(resp.status, 503, "reject must be a 503");
    }

    /// A cached dashboard pubkey but no api creds still fails closed at the
    /// creds gate — verifies the fail-closed decision does not depend on the
    /// pubkey being absent.
    #[test]
    fn mint_and_verify_voucher_fails_closed_even_with_cached_pubkey() {
        let state = std::sync::Arc::new(BrokerState::new());
        if let Ok(mut g) = state.dash_voucher_pubkey.write() {
            *g = Some(crate::broker::node_identity::NodeKey::generate().public_b64());
        }
        assert!(
            super::mint_and_verify_voucher(&state, 5.0, None).is_err(),
            "missing api creds must reject regardless of cached pubkey"
        );
    }

    /// Build a validly dashboard-signed voucher with the given `commission_c`,
    /// returning `(signed_json, sig_b64, dash_pubkey_b64)`.
    fn mk_signed_voucher(
        commission_c: f64,
    ) -> (
        String,
        String,
        String,
        crate::broker::node_identity::NodeKey,
    ) {
        use crate::broker::node_identity::NodeKey;
        let dash = NodeKey::generate();
        let signed = format!(
            r#"{{"v":1,"requester_user":"u","budget_credits":1000000.0,"task_nonce":"n","exp":9999999999,"commission_c":{}}}"#,
            commission_c
        );
        let sig = dash.sign(signed.as_bytes());
        let pubkey = dash.public_b64();
        (signed, sig, pubkey, dash)
    }

    #[test]
    fn offer_commission_c_reads_validly_signed_voucher() {
        let (signed, sig, pubkey, _dash) = mk_signed_voucher(0.1);
        let mut offer = mk_offer("t-c");
        offer.voucher_signed_json = signed;
        offer.voucher_sig = sig;
        assert_eq!(offer_commission_c(&offer, Some(&pubkey)), 0.1);
    }

    #[test]
    fn offer_commission_c_defaults_zero_without_voucher() {
        let offer = mk_offer("t-nc");
        assert!(offer.voucher_signed_json.is_empty());
        assert_eq!(offer_commission_c(&offer, Some("irrelevant")), 0.0);
    }

    #[test]
    fn offer_commission_c_parse_failure_falls_back_to_zero() {
        let mut offer = mk_offer("t-bad");
        offer.voucher_signed_json = "{not valid json".to_string();
        offer.voucher_sig = "somesig".to_string();
        // A parse failure must never throw money — fall back to no commission.
        assert_eq!(offer_commission_c(&offer, Some("irrelevant")), 0.0);
    }

    #[test]
    fn offer_commission_c_out_of_range_falls_back_to_zero() {
        let (signed, sig, pubkey, _dash) = mk_signed_voucher(1.0);
        let mut offer = mk_offer("t-oob");
        // commission_c == 1.0 is out of the [0,1) range → treat as no commission,
        // even though the signature is otherwise valid.
        offer.voucher_signed_json = signed;
        offer.voucher_sig = sig;
        assert_eq!(offer_commission_c(&offer, Some(&pubkey)), 0.0);
    }

    // ── FINDING 1 regression coverage: unverified voucher must never be
    // trusted for commission_c ──────────────────────────────────────────

    #[test]
    fn offer_commission_c_zero_when_signature_missing() {
        // A requester-controlled voucher JSON with commission_c stamped high,
        // but NO signature at all — must not be trusted.
        let mut offer = mk_offer("t-nosig");
        offer.voucher_signed_json = r#"{"v":1,"requester_user":"u","budget_credits":5.0,"task_nonce":"n","exp":9999999999,"commission_c":0.5}"#.to_string();
        offer.voucher_sig = String::new();
        assert_eq!(offer_commission_c(&offer, Some("some-pubkey")), 0.0);
    }

    #[test]
    fn offer_commission_c_zero_when_signature_invalid() {
        // Valid JSON shape, but the signature does not verify against the
        // cached dashboard pubkey (e.g. requester forged/self-signed it, or
        // tampered with commission_c after signing) — must fall back to 0.0,
        // not trust the embedded commission_c: 0.5.
        let (signed, _sig, pubkey, _dash) = mk_signed_voucher(0.5);
        let mut offer = mk_offer("t-badsig");
        offer.voucher_signed_json = signed;
        offer.voucher_sig = "not-a-real-signature".to_string();
        assert_eq!(offer_commission_c(&offer, Some(&pubkey)), 0.0);
    }

    #[test]
    fn offer_commission_c_zero_when_signed_by_wrong_key() {
        // Signed correctly, but by a DIFFERENT keypair than the one cached on
        // broker state — e.g. a requester running their own broker with a
        // self-signed "dashboard" voucher. Must not be trusted.
        let (signed, sig, _their_pubkey, _their_dash) = mk_signed_voucher(0.5);
        let (_real_signed, _real_sig, real_pubkey, _real_dash) = mk_signed_voucher(0.1);
        let mut offer = mk_offer("t-wrongkey");
        offer.voucher_signed_json = signed;
        offer.voucher_sig = sig;
        assert_eq!(offer_commission_c(&offer, Some(&real_pubkey)), 0.0);
    }

    #[test]
    fn offer_commission_c_zero_when_no_pubkey_cached() {
        // Broker hasn't synced a dashboard pubkey yet — must not trust any
        // voucher content, even a validly-shaped one.
        let (signed, sig, _pubkey, _dash) = mk_signed_voucher(0.5);
        let mut offer = mk_offer("t-nopubkey");
        offer.voucher_signed_json = signed;
        offer.voucher_sig = sig;
        assert_eq!(offer_commission_c(&offer, None), 0.0);
    }

    #[test]
    fn offer_commission_c_zero_when_tampered_after_signing() {
        // Signature was valid over the ORIGINAL bytes, but the JSON string
        // carried on the wire was mutated afterwards (e.g. commission_c
        // stripped to near-zero) — verify_voucher checks the signature over
        // the *exact bytes supplied*, so a mismatched sig must fail closed.
        let (signed, sig, pubkey, _dash) = mk_signed_voucher(0.5);
        let tampered = signed.replace("0.5", "0.0000001");
        let mut offer = mk_offer("t-tampered");
        offer.voucher_signed_json = tampered;
        offer.voucher_sig = sig;
        assert_eq!(offer_commission_c(&offer, Some(&pubkey)), 0.0);
    }

    #[test]
    fn reserve_offer_rejects_when_no_local_worker() {
        let state = BrokerState::new();
        let r = reserve_offer(&state, &mk_offer("t1"));
        assert!(r.is_err(), "no local worker → TaskReject");
    }

    #[test]
    fn verify_offer_voucher_gate() {
        use crate::broker::node_identity::NodeKey;
        // Serialize test runs that toggle ZAKURO_REQUIRE_VOUCHER (process-global env).
        static LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
        let _g = LOCK.lock().unwrap();

        let state = std::sync::Arc::new(BrokerState::new());
        let dash = NodeKey::generate();
        *state.dash_voucher_pubkey.write().unwrap() = Some(dash.public_b64());

        // A dashboard-signed voucher with a generous budget, exp far in the future.
        let signed = r#"{"v":1,"requester_user":"u","budget_credits":1000000.0,"task_nonce":"n","exp":9999999999}"#;
        let sig = dash.sign(signed.as_bytes());
        let mut offer = task_board::TaskOffer {
            voucher_signed_json: signed.to_string(),
            voucher_sig: sig,
            ..mk_offer("t-v")
        };

        // required OFF → always Ok regardless of voucher
        std::env::remove_var("ZAKURO_REQUIRE_VOUCHER");
        assert!(super::verify_offer_voucher(&state, &offer).is_ok());

        // required ON → valid voucher passes
        std::env::set_var("ZAKURO_REQUIRE_VOUCHER", "1");
        assert!(super::verify_offer_voucher(&state, &offer).is_ok());

        // required ON, missing voucher → error
        let bare = mk_offer("t-bare");
        assert!(super::verify_offer_voucher(&state, &bare).is_err());

        // required ON, tampered budget → signature fails
        offer.voucher_signed_json = offer.voucher_signed_json.replace("1000000.0", "0.0000001");
        assert!(super::verify_offer_voucher(&state, &offer).is_err());

        std::env::remove_var("ZAKURO_REQUIRE_VOUCHER");
    }

    #[test]
    fn take_committed_removes_once() {
        let state = BrokerState::new();
        state.pending_offers.insert(
            "t1".into(),
            PendingOffer {
                offer: mk_offer("t1"),
                worker_id: "w1".into(),
                created: std::time::Instant::now(),
            },
        );
        assert!(take_committed(&state, "t1").is_some());
        assert!(
            take_committed(&state, "t1").is_none(),
            "second commit → None"
        );
    }

    #[test]
    fn cancel_is_idempotent() {
        let state = BrokerState::new();
        state.pending_offers.insert(
            "t1".into(),
            PendingOffer {
                offer: mk_offer("t1"),
                worker_id: "w1".into(),
                created: std::time::Instant::now(),
            },
        );
        cancel_offer(&state, "t1");
        assert!(!state.pending_offers.contains_key("t1"));
        cancel_offer(&state, "t1"); // absent → no panic
        cancel_offer(&state, "never"); // unknown → no panic
    }

    #[test]
    fn sweep_releases_stale_keeps_fresh() {
        let state = BrokerState::new();
        state.pending_offers.insert(
            "t2".into(),
            PendingOffer {
                offer: mk_offer("t2"),
                worker_id: "w".into(),
                created: std::time::Instant::now(),
            },
        );
        sweep_expired_offers(&state, std::time::Duration::from_secs(3600)); // fresh → kept
        assert!(state.pending_offers.contains_key("t2"));
        sweep_expired_offers(&state, std::time::Duration::ZERO); // any positive age → removed
        assert!(!state.pending_offers.contains_key("t2"));
    }
}

#[cfg(test)]
mod forward_async_tests {
    use super::forward_to_worker_async;

    #[tokio::test]
    async fn forward_async_round_trips_status_body_and_headers() {
        // Loopback mock: returns 200, a marker header, and a fixed body.
        let server = std::sync::Arc::new(tiny_http::Server::http("127.0.0.1:0").unwrap());
        let port = server.server_addr().to_ip().unwrap().port();
        std::thread::spawn(move || {
            for req in server.incoming_requests() {
                let r = tiny_http::Response::from_data(b"pong".to_vec())
                    .with_status_code(200)
                    .with_header(tiny_http::Header::from_bytes("X-Zakuro-Worker", "w1").unwrap())
                    .with_header(tiny_http::Header::from_bytes("Connection", "close").unwrap());
                let _ = req.respond(r);
            }
        });
        let client = reqwest::Client::new();
        let uri = format!("http://127.0.0.1:{}/execute", port);
        let reply = forward_to_worker_async(&client, &uri, b"ping".to_vec(), "rid-1", 0.0)
            .await
            .expect("forward ok");
        assert_eq!(reply.status, 200);
        assert_eq!(reply.body, b"pong");
        assert!(reply
            .headers
            .iter()
            .any(|(k, v)| k == "x-zakuro-worker" && v == "w1"));
    }
}

/// CHANGE 2 tests: `GET /brokers` — IP-free key-derived broker listing.
#[cfg(test)]
mod brokers_endpoint_tests {
    use super::handle_brokers;
    use crate::broker::node_identity::NodeKey;
    use crate::broker::{BrokerState, PeerManager};
    use std::sync::Arc;

    /// A fake peer broker that answers `/peer/health` with a fixed
    /// key-derived `broker_id`, exactly like a real broker's
    /// `handle_peer_health` now does.
    fn spawn_fake_peer_health(broker_id: &str) -> u16 {
        let server = Arc::new(tiny_http::Server::http("127.0.0.1:0").unwrap());
        let port = server.server_addr().to_ip().unwrap().port();
        let broker_id = broker_id.to_string();
        std::thread::spawn(move || {
            for req in server.incoming_requests() {
                let body = format!(r#"{{"status":"healthy","broker_id":"{}"}}"#, broker_id);
                let resp = tiny_http::Response::from_data(body.into_bytes())
                    .with_status_code(200)
                    .with_header(
                        tiny_http::Header::from_bytes("Content-Type", "application/json").unwrap(),
                    );
                let _ = req.respond(resp);
            }
        });
        port
    }

    fn state_with_peers(peer_urls: &[String]) -> Arc<BrokerState> {
        let mut state = BrokerState::new();
        let key = Arc::new(NodeKey::generate());
        // Use a distinct loopback address for "self" so the hash-ring
        // normalization (which collapses ip:broker_port) doesn't fold a
        // 127.0.0.1-hosted fake peer onto "self" and drop it from the peer set.
        state.peer_manager = PeerManager::new_with_node_key(
            Some("127.0.0.2"),
            peer_urls,
            state.config.port,
            String::new(), // no shared peer_key needed for loopback /peer/health
            true,
            Some(key.clone()),
        );
        state.node_key = key;
        Arc::new(state)
    }

    #[test]
    fn self_id_is_key_derived_and_matches_node_key() {
        let state = state_with_peers(&[]);
        let resp = handle_brokers(&state);
        let body: serde_json::Value = serde_json::from_slice(&resp.body).unwrap();
        assert_eq!(body["self"], state.node_key.node_uri());
        assert!(body["self"].as_str().unwrap().starts_with("zc://node-"));
        assert!(body["brokers"].as_array().unwrap().is_empty());
    }

    #[test]
    fn known_peer_fingerprint_appears_as_zc_id_no_ip_leaked() {
        let fp_id = "zc://node-deadbeefcafebabe";
        let port = spawn_fake_peer_health(fp_id);
        let peer_url = format!("http://127.0.0.1:{}", port);

        let state = state_with_peers(std::slice::from_ref(&peer_url));
        let resp = handle_brokers(&state);
        let raw = String::from_utf8(resp.body.clone()).unwrap();

        // No IP-shaped string, and no raw peer_url, anywhere in the body.
        assert!(!raw.contains("127.0.0.1"), "leaked loopback IP: {raw}");
        assert!(!raw.contains(&port.to_string()), "leaked peer port: {raw}");
        assert!(!raw.contains(&peer_url), "leaked raw peer_url: {raw}");
        assert!(!regex_ish_ip_shaped(&raw), "body looks IP-shaped: {raw}");

        let body: serde_json::Value = serde_json::from_str(&raw).unwrap();
        let brokers = body["brokers"].as_array().unwrap();
        assert_eq!(brokers.len(), 1);
        assert_eq!(brokers[0]["id"], fp_id);
        assert_eq!(brokers[0]["reachable"], true);
    }

    /// Fix C, at the display layer: one physical broker must produce exactly
    /// ONE row, even while it is registered under two spellings — its
    /// `ZAKURO_PEERS` name and its roster mesh address. Listing the same
    /// `zc://node-<fp>` twice is precisely what this feature's acceptance
    /// criterion forbids.
    #[test]
    fn one_broker_registered_under_two_spellings_is_listed_once() {
        let fp_id = "zc://node-deadbeefcafebabe";
        // Two live endpoints answering with the SAME key-derived broker_id:
        // the two spellings of one broker.
        let port_a = spawn_fake_peer_health(fp_id);
        let port_b = spawn_fake_peer_health(fp_id);
        let url_a = format!("http://127.0.0.1:{port_a}");
        let url_b = format!("http://127.0.0.1:{port_b}");

        // Register the second spelling directly, the way the node-sync tick
        // adds a roster-derived peer alongside a configured one.
        // (`PeerManager::new` normalizes its argument list onto `ip:broker_port`
        // for the hash ring, so two loopback ports passed there would collapse
        // into one entry and the test would model nothing.)
        let state = state_with_peers(std::slice::from_ref(&url_a));
        state.peer_manager.register_peer(url_b);
        assert_eq!(
            state.peer_manager.peer_count(),
            2,
            "test setup: two spellings"
        );

        let resp = handle_brokers(&state);
        let body: serde_json::Value = serde_json::from_slice(&resp.body).unwrap();
        let brokers = body["brokers"].as_array().unwrap();

        assert_eq!(
            brokers.len(),
            1,
            "one broker listed twice under two spellings: {body}"
        );
        assert_eq!(brokers[0]["id"], fp_id);
        assert_eq!(brokers[0]["reachable"], true);
    }

    /// Distinct brokers must still each get a row — the dedup keys on
    /// identity, and must not collapse genuinely different peers.
    #[test]
    fn distinct_brokers_are_each_listed() {
        let port_a = spawn_fake_peer_health("zc://node-aaaaaaaaaaaaaaaa");
        let port_b = spawn_fake_peer_health("zc://node-bbbbbbbbbbbbbbbb");
        let state = state_with_peers(&[format!("http://127.0.0.1:{port_a}")]);
        state
            .peer_manager
            .register_peer(format!("http://127.0.0.1:{port_b}"));
        assert_eq!(state.peer_manager.peer_count(), 2, "test setup: two peers");

        let resp = handle_brokers(&state);
        let body: serde_json::Value = serde_json::from_slice(&resp.body).unwrap();
        let mut ids: Vec<&str> = body["brokers"]
            .as_array()
            .unwrap()
            .iter()
            .map(|b| b["id"].as_str().unwrap())
            .collect();
        ids.sort();
        assert_eq!(
            ids,
            vec!["zc://node-aaaaaaaaaaaaaaaa", "zc://node-bbbbbbbbbbbbbbbb"]
        );
    }

    #[test]
    fn unknown_peer_fingerprint_is_omitted_not_leaked_as_ip() {
        // Peer that never answers /peer/health at all (nothing listening) —
        // its fingerprint can never be learned, so per the documented
        // "unknown → omitted" choice it must not appear in the list, and
        // its bare peer_url/IP must never leak as a stand-in id.
        let dead_peer = "http://127.0.0.1:1".to_string(); // port 1: nothing listens
        let state = state_with_peers(std::slice::from_ref(&dead_peer));
        let resp = handle_brokers(&state);
        let raw = String::from_utf8(resp.body.clone()).unwrap();

        assert!(!raw.contains(&dead_peer), "leaked raw peer_url: {raw}");
        let body: serde_json::Value = serde_json::from_str(&raw).unwrap();
        assert!(
            body["brokers"].as_array().unwrap().is_empty(),
            "unreachable/unknown peer must be omitted: {raw}"
        );
    }

    /// Crude IP-shaped detector for the negative assertion above: four
    /// dot-separated all-numeric octets.
    fn regex_ish_ip_shaped(s: &str) -> bool {
        for window in s.split(|c: char| !c.is_ascii_digit() && c != '.') {
            let parts: Vec<&str> = window.split('.').collect();
            if parts.len() == 4
                && parts
                    .iter()
                    .all(|p| !p.is_empty() && p.parse::<u8>().is_ok())
            {
                return true;
            }
        }
        false
    }

    /// `GET /peers` must be as IP-free as `/brokers` — its handshake auth
    /// (`peer_handshake_auth`) is a shared-secret/loopback check, not true
    /// peer identity, so it's effectively a client-facing surface. This
    /// drives it end-to-end through `super::handle`, the same way real
    /// clients hit it.
    #[test]
    fn peers_endpoint_is_ip_free_and_key_derived() {
        use tiny_http::Method;

        let fp_id = "zc://node-feedfacecafebabe";
        let port = spawn_fake_peer_health(fp_id);
        let peer_url = format!("http://127.0.0.1:{}", port);

        let state = state_with_peers(std::slice::from_ref(&peer_url));
        let self_uri = state.node_key.node_uri();

        let req = crate::broker::http_adapter::BrokerRequest {
            method: Method::Get,
            path: "/peers".to_string(),
            query: String::new(),
            headers: vec![],
            body: vec![],
            peer_addr: None, // in-process caller => treated as loopback
        };
        let resp = super::handle(state, &req, false);
        let raw = String::from_utf8(resp.body.clone()).unwrap();

        // No IP-shaped string, no raw peer_url, no hostname-as-identity.
        assert!(!raw.contains("10.13.13."), "leaked mesh IP: {raw}");
        assert!(!raw.contains("127.0.0.1"), "leaked loopback IP: {raw}");
        assert!(!raw.contains(&port.to_string()), "leaked peer port: {raw}");
        assert!(!raw.contains(&peer_url), "leaked raw peer_url: {raw}");
        assert!(!raw.starts_with("http://"), "leaked raw http url: {raw}");
        assert!(
            !raw.contains("http://"),
            "leaked raw http url anywhere: {raw}"
        );
        assert!(!regex_ish_ip_shaped(&raw), "body looks IP-shaped: {raw}");

        let body: serde_json::Value = serde_json::from_str(&raw).unwrap();
        assert_eq!(body["node"], self_uri);
        assert!(body["node"].as_str().unwrap().starts_with("zc://node-"));

        let peers = body["peers"].as_array().unwrap();
        assert_eq!(peers.len(), 1);
        assert_eq!(peers[0], fp_id);
        assert_eq!(body["total"], 1);
    }
}

#[cfg(test)]
mod marketplace_preselection_guard_tests {
    use super::marketplace_select_enabled;

    /// Serialize env-var mutation across this module's tests (std::env is
    /// process-global) — cargo test runs are already forced single-threaded
    /// for this crate (`--test-threads=1`), but keep the guard local and
    /// explicit in case that ever changes.
    static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());

    /// Guard test for the `ZAKURO_MARKETPLACE_SELECT=0` escape hatch (task 5):
    /// pre-selection must default ON (unset, or any value other than exactly
    /// "0") and must be disabled only by the literal "0".
    #[test]
    fn marketplace_select_escape_hatch() {
        let _g = ENV_LOCK.lock().unwrap();

        std::env::remove_var("ZAKURO_MARKETPLACE_SELECT");
        assert!(marketplace_select_enabled(), "default (unset) must be ON");

        std::env::set_var("ZAKURO_MARKETPLACE_SELECT", "0");
        assert!(
            !marketplace_select_enabled(),
            "\"0\" must disable pre-selection"
        );

        std::env::set_var("ZAKURO_MARKETPLACE_SELECT", "1");
        assert!(
            marketplace_select_enabled(),
            "any non-\"0\" value must be ON"
        );

        std::env::remove_var("ZAKURO_MARKETPLACE_SELECT");
    }
}

#[cfg(test)]
mod executor_identity_tests {
    use crate::broker::peer::PeerManager;
    use crate::broker::worker::Worker;

    #[test]
    fn executor_fp_prefers_node_identity_and_refuses_unstamped_workers() {
        let mut w = Worker::new(
            "w1".into(),
            "worker-a".into(),
            "http://10.13.13.7:3960".into(),
            "zakuro".into(),
        );
        // Unstamped (no source_node seen yet) → no identity → settlement must refund,
        // never fall back to parsing the address out of `uri`.
        assert_eq!(super::executor_fp(&w), None);

        w.node_fp = "aaaaaaaaaaaaaaaa".into();
        assert_eq!(super::executor_fp(&w), Some("aaaaaaaaaaaaaaaa"));
    }

    /// Direction 1 of the deliberate behaviour change: a PROXIED peer — its
    /// base-URL host is the sidecar, not the worker's mesh IP — now resolves
    /// and gets paid. `get_url_for_ip` on the worker IP misses entirely, which
    /// is the bug this task fixes (executor worked for free).
    #[test]
    fn proxied_executor_resolves_by_fingerprint_where_ip_match_fails() {
        let pm = PeerManager::new(
            Some("10.13.13.2"),
            &["127.0.0.1:19001".to_string()],
            9000,
            "k".to_string(),
            true,
        );
        pm.set_peer_fingerprint("http://127.0.0.1:19001", "cccccccccccccccc");

        let mut w = Worker::new(
            "w2".into(),
            "worker-proxied".into(),
            "http://10.13.13.7:3960".into(),
            "zakuro".into(),
        );
        w.node_fp = "cccccccccccccccc".into();

        // Old address-keyed resolution: the worker's IP is not any peer's host.
        assert_eq!(
            pm.get_url_for_ip("10.13.13.7"),
            None,
            "precondition: the old IP-keyed lookup must miss for a proxied peer"
        );
        // New identity-keyed resolution: pays the right peer.
        assert_eq!(
            super::executor_fp(&w)
                .and_then(|fp| pm.get_url_for_fingerprint(fp))
                .as_deref(),
            Some("http://127.0.0.1:19001")
        );
    }

    /// Direction 2, the accepted regression: a DIRECT peer whose worker carries
    /// no stamped `node_fp` used to be paid via the lucky exact-host match and
    /// now routes to the pay-nobody / full-refund arm. Asserted explicitly so
    /// the trade-off is visible and cannot regress silently.
    #[test]
    fn direct_but_unstamped_executor_now_routes_to_full_refund_arm() {
        let pm = PeerManager::new(
            Some("10.13.13.2"),
            &["10.13.13.7:9000".to_string()],
            9000,
            "k".to_string(),
            true,
        );
        pm.set_peer_fingerprint("http://10.13.13.7:9000", "dddddddddddddddd");

        let w = Worker::new(
            "w3".into(),
            "worker-direct".into(),
            "http://10.13.13.7:3960".into(),
            "zakuro".into(),
        );
        // Old behaviour would have resolved this peer from the worker's IP…
        assert_eq!(
            pm.get_url_for_ip("10.13.13.7").as_deref(),
            Some("http://10.13.13.7:9000")
        );
        // …but with no stamped identity the earn path now resolves to None,
        // i.e. no payout, no redeem, requester refunded in full.
        assert_eq!(super::executor_fp(&w), None);
        assert_eq!(
            super::executor_fp(&w).and_then(|fp| pm.get_url_for_fingerprint(fp)),
            None
        );
    }
}

/// Covering tests that drive the REAL settlement path (`commit_credits`) and
/// assert which `match` arm ran, rather than re-implementing the resolution
/// expression. The discriminator is network-free and needs no stub server:
/// only the `Some(peer_url)` arm credits the platform-house commission (via
/// `settle_executor_payout`), and it refunds the requester only `payout`; the
/// `None` arm credits nobody and refunds the FULL `actual_cost`.
/// Drives the REAL `TaskResult` producer (`run_offer_on`) against a stub worker
/// and asserts the privacy invariant over the value the producer actually
/// emitted — not over a hand-set field. Mutating `worker_uri: worker.zc_uri()`
/// back to `worker.uri.clone()` in `run_offer_on` makes these tests fail.
///
/// Also drives the REAL `PeerIdentity` producer (`handle_peer_identity`)
/// against a genuinely registered worker, covering the payload Task 4 did
/// not: `producer_emits_no_address_in_peer_identity` below.
#[cfg(test)]
mod task_result_producer_tests {
    use super::*;
    use crate::broker::worker::Worker;
    use crate::broker::{BrokerConfig, BrokerState};
    use std::io::{Read, Write};
    use std::net::TcpListener;
    use std::sync::atomic::{AtomicU16, Ordering};
    use std::sync::Arc;

    /// Bind a port and HOLD the reservation — the listener is handed straight to
    /// the serving thread and never released, so no TOCTOU re-bind race can
    /// flake this under parallel execution (same discipline as
    /// `discovery.rs::reserve_port`). Uses a range disjoint from that test's.
    fn reserve_port() -> TcpListener {
        static NEXT: AtomicU16 = AtomicU16::new(50100);
        loop {
            let port = NEXT.fetch_add(1, Ordering::Relaxed);
            assert!(port < 51000, "reserve_port exhausted the test port range");
            if let Ok(l) = TcpListener::bind(("127.0.0.1", port)) {
                return l;
            }
        }
    }

    /// Minimal worker that answers any POST with a 200 and an `X-Zakuro-IP`
    /// header. The header is deliberately present and deliberately a dotted
    /// quad: if the producer ever reinstates the IP-header capture, the payload
    /// assertions below catch it.
    fn spawn_stub_worker(listener: TcpListener) {
        std::thread::spawn(move || {
            for stream in listener.incoming() {
                let mut stream = match stream {
                    Ok(s) => s,
                    Err(_) => continue,
                };
                let mut buf = [0u8; 2048];
                let _ = stream.read(&mut buf);
                let body = "ok";
                let resp = format!(
                    "HTTP/1.1 200 OK\r\nContent-Length: {}\r\nContent-Type: application/octet-stream\r\nX-Zakuro-Pid: 4242\r\nX-Zakuro-IP: 10.13.13.7\r\n\r\n{}",
                    body.len(),
                    body
                );
                let _ = stream.write_all(resp.as_bytes());
                let _ = stream.flush();
            }
        });
    }

    fn mk_offer(task_id: &str) -> task_board::TaskOffer {
        serde_json::from_str(&format!(
            r#"{{"task_id":"{}","payload_b64":"","max_price_per_hour":100.0,"estimated_duration_secs":1.0,"timeout_secs":10.0,"requester_user_id":"u","source_broker":"n"}}"#,
            task_id
        ))
        .unwrap()
    }

    /// Produce a real `TaskResult` by running the real producer against a live
    /// stub worker whose URI is a genuine dialable `http://127.0.0.1:<port>`.
    fn produce_real_result() -> task_board::TaskResult {
        let listener = reserve_port();
        let port = listener.local_addr().unwrap().port();
        spawn_stub_worker(listener);

        let st = Arc::new(BrokerState::with_config(BrokerConfig::default()));
        let mut w = Worker::new(
            "wid".into(),
            "worker-exec".into(),
            format!("http://127.0.0.1:{}", port),
            "zakuro".into(),
        );
        w.node_fp = "aaaaaaaaaaaaaaaa".into();
        w.slot = "3960".into();

        super::run_offer_on(&st, &mk_offer("t-privacy"), &w)
            .expect("stub worker must answer so the producer builds a TaskResult")
    }

    #[test]
    fn producer_emits_no_address_in_task_result() {
        let r = produce_real_result();
        let json = serde_json::to_string(&r).unwrap();

        // Payload-level guards first: these are field-agnostic, so they hold
        // however a future regression smuggles an address in.
        assert!(
            !json.contains("http://"),
            "producer put a scheme+host on the wire: {json}"
        );
        assert!(
            !json.contains("worker_ip"),
            "worker_ip must be off the wire: {json}"
        );
        // Nothing matching a dotted quad may appear anywhere in the payload —
        // catches both `worker.uri` and a reinstated X-Zakuro-IP capture,
        // regardless of which field they land in.
        assert!(
            !contains_dotted_quad(&json),
            "producer put an IP address on the wire: {json}"
        );
        // The producer's own worker URI IS a dialable address; the emitted
        // handle must be the key-derived one instead.
        assert_eq!(
            r.worker_uri, "zc://worker-aaaaaaaaaaaaaaaa-3960",
            "producer must emit Worker::zc_uri(), not the dialable worker.uri"
        );
        // ...and the identity IS present.
        assert_eq!(r.executor_node_uri, st_node_uri(&r));
        assert!(
            r.executor_node_uri.starts_with("zc://node-"),
            "executor_node_uri must be the key-derived node identity: {:?}",
            r.executor_node_uri
        );
    }

    /// Produce a real `PeerIdentity` by driving the REAL producer
    /// (`handle_peer_identity`) against a `BrokerState` with a genuine
    /// registered worker whose `uri` is a dialable `http://127.0.0.1:<port>` —
    /// exactly the kind of value a regression could smuggle onto the wire.
    /// No stub server is needed: `handle_peer_identity` never dials the
    /// worker, it only reads registry state.
    fn produce_real_peer_identity() -> task_board::PeerIdentity {
        use crate::broker::http_adapter::BrokerRequest;
        use crate::broker::worker::WorkerRegistration;

        let config = BrokerConfig {
            owner_user_id: Some("1000000001".into()),
            node_name: Some("node-a".into()),
            ..Default::default()
        };
        let st = Arc::new(BrokerState::with_config(config));
        st.workers.register(WorkerRegistration {
            name: "worker-a".into(),
            uri: "http://127.0.0.1:39999".into(),
            worker_type: "zakuro".into(),
            resources: Default::default(),
            pricing: Default::default(),
            tags: vec![],
            max_timeout_secs: 0.0,
            hardware: Default::default(),
            wireguard_ip: None,
            is_docker: None,
            source_node: None,
            explicit_local: false,
            provider_type: Default::default(),
            served_models: vec![],
            price_per_mtok: 0.0,
        });

        let req = BrokerRequest {
            method: tiny_http::Method::Get,
            path: "/peer/identity".into(),
            query: "".into(),
            headers: vec![],
            body: vec![],
            peer_addr: None, // in-process caller -> is_loopback() == true, no peer key required
        };
        let resp = super::handle_peer_identity(&st, &req);
        assert_eq!(resp.status, 200, "handle_peer_identity must succeed");
        serde_json::from_slice(&resp.body).expect("handle_peer_identity must emit valid JSON")
    }

    #[test]
    fn producer_emits_no_address_in_peer_identity() {
        let id = produce_real_peer_identity();
        let json = serde_json::to_string(&id).unwrap();

        assert!(
            !json.contains("http://"),
            "producer put a scheme+host on the wire: {json}"
        );
        assert!(
            !contains_dotted_quad(&json),
            "producer put an IP address on the wire: {json}"
        );
        assert_eq!(id.workers.len(), 1, "the registered worker must be listed");
    }

    /// The `executor_node_uri` a well-formed result must carry: the executing
    /// node's own identity, derived from the same key that signed the receipt.
    fn st_node_uri(r: &task_board::TaskResult) -> String {
        let node_id = r
            .executor_node_id
            .as_ref()
            .expect("producer signs the receipt, so node_id is present");
        format!(
            "zc://node-{}",
            crate::broker::node_identity::fingerprint_of_pubkey_b64(node_id).unwrap()
        )
    }

    /// True if `s` contains something shaped like an IPv4 address.
    fn contains_dotted_quad(s: &str) -> bool {
        let b: Vec<char> = s.chars().collect();
        let mut i = 0;
        while i < b.len() {
            let mut j = i;
            let mut groups = 0;
            loop {
                let start = j;
                while j < b.len() && b[j].is_ascii_digit() {
                    j += 1;
                }
                if j == start {
                    break;
                }
                groups += 1;
                if groups == 4 {
                    return true;
                }
                if j < b.len() && b[j] == '.' {
                    j += 1;
                } else {
                    break;
                }
            }
            i = if j > i { j } else { i + 1 };
        }
        false
    }

    /// The SECOND producer (`quic.rs::handle_stream`) cannot be driven by a unit
    /// test: it is parameterized on concrete `quinn::SendStream`/`RecvStream`
    /// rather than a trait, so exercising it needs a live QUIC endpoint pair
    /// (TLS config, certs, connection handshake) that does not exist in this
    /// suite. This is a TEXTUAL guard, strictly weaker than the behavioural one
    /// above — it detects the specific reviewer-demonstrated regression
    /// (`worker.uri` back in the mesh-facing handle) but cannot prove the
    /// emitted value in general. Replace it with a real driving test if a QUIC
    /// harness ever lands.
    #[test]
    fn quic_producer_emits_identity_not_worker_uri() {
        let src = include_str!("quic.rs");
        assert!(
            src.contains("let wuri = worker.zc_uri();"),
            "quic.rs producer must derive its mesh-facing handle from Worker::zc_uri()"
        );
        assert!(
            !src.contains("let wuri = worker.uri"),
            "quic.rs producer must not put the dialable worker.uri on the wire"
        );
        assert!(
            !src.contains("X-Zakuro-IP"),
            "quic.rs must not capture the worker IP header for the mesh payload"
        );
    }

    #[test]
    fn dotted_quad_detector_is_sound() {
        // Guard the guard: a detector that never fires would silently defang
        // `producer_emits_no_address_in_task_result`.
        assert!(contains_dotted_quad("http://10.13.13.7:3960"));
        assert!(contains_dotted_quad("127.0.0.1"));
        assert!(contains_dotted_quad(r#"{"worker_ip":"192.168.0.23"}"#));
        assert!(!contains_dotted_quad("zc://worker-aaaaaaaaaaaaaaaa-3960"));
        assert!(!contains_dotted_quad("zc://node-13a9551e881f7f8c"));
        assert!(!contains_dotted_quad("1234.5")); // duration_ms
        assert!(!contains_dotted_quad("0.789")); // actual_cost
    }
}

#[cfg(test)]
mod commit_credits_arm_tests {
    use super::*;
    use crate::broker::peer::PeerManager;
    use crate::broker::worker::Worker;
    use crate::broker::{BrokerConfig, BrokerState};
    use std::sync::Arc;

    /// A peer registered at a closed loopback port: `get_client` returns `Some`
    /// so the `Some` arm is fully exercised, and the `earn` RPC fails fast with
    /// connection-refused (no network, no timeout).
    const PEER_ADDR: &str = "127.0.0.1:19099";
    const PEER_URL: &str = "http://127.0.0.1:19099";
    const PEER_FP: &str = "cccccccccccccccc";

    fn state_with_seeded_peer() -> Arc<BrokerState> {
        // Default: a closed port, so no redeem can ever succeed. Tests that care
        // about the redeem leg use `state_with_seeded_peer_api` instead.
        state_with_seeded_peer_api("http://127.0.0.1:1")
    }

    fn state_with_seeded_peer_api(api_url: &str) -> Arc<BrokerState> {
        // api_url/api_key make `is_billing_enabled()` true without touching the
        // process-global env (no ZAKURO_MASTER_KEY race). Pre-seeding
        // `authoritative_balances` makes `load_balance_if_needed` short-circuit
        // before any dashboard HTTP call, so the test never leaves the process.
        let config = BrokerConfig {
            api_url: Some(api_url.into()),
            api_key: Some("k".into()),
            ..Default::default()
        };
        let mut st = BrokerState::with_config(config);
        st.peer_manager = PeerManager::new(
            Some("10.13.13.2"),
            &[PEER_ADDR.to_string()],
            9000,
            "k".to_string(),
            true,
        );
        st.peer_manager.set_peer_fingerprint(PEER_URL, PEER_FP);
        let st = Arc::new(st);
        st.ledger
            .authoritative_balances
            .insert("u1".to_string(), 100.0);
        st.ledger.local_credits.insert("u1".to_string(), 100.0);
        assert!(st.is_billing_enabled());
        st
    }

    /// The worker's URI host is deliberately the SAME host as the peer's base
    /// URL, so a reinstated `get_url_for_ip` fallback in the production match
    /// head WOULD resolve it. That is what makes
    /// `unstamped_worker_takes_full_refund_arm_via_commit_credits` a real
    /// mutation detector rather than a tautology.
    fn worker(node_fp: Option<&str>) -> Worker {
        let mut w = Worker::new(
            "wid".into(),
            "worker-exec".into(),
            "http://127.0.0.1:3960".into(),
            "zakuro".into(),
        );
        if let Some(fp) = node_fp {
            w.node_fp = fp.into();
        }
        w
    }

    fn run_commit(st: &Arc<BrokerState>, w: &Worker) {
        run_commit_with_nonce(st, w, "");
    }

    fn run_commit_with_nonce(st: &Arc<BrokerState>, w: &Worker, nonce: &str) {
        let (reservation_id, _) = st
            .ledger
            .local_reserve("u1", 10.0, "ref")
            .expect("reserve must succeed against the seeded balance");
        // authoritative: 100 - 10 = 90 held.
        super::commit_credits(
            st,
            &Authority::Local,
            false, // is_local = false → the remote settlement path
            &reservation_id,
            4.0,   // actual_cost
            100.0, // balance_before
            "req-1",
            "u1",
            w,
            1000.0, // duration_ms
            0.10,   // commission_c → payout 3.6, commission 0.4
            nonce,  // empty = no dashboard redeem HTTP
        );
    }

    /// Bind a port and HOLD the reservation — the listener goes straight to the
    /// serving thread and is never released, so there is no bind-drop-rebind
    /// TOCTOU race under parallel execution. Range is disjoint from both
    /// `discovery.rs::reserve_port` (41000-50000) and
    /// `task_result_producer_tests::reserve_port` (50100-51000).
    fn reserve_port() -> std::net::TcpListener {
        use std::sync::atomic::{AtomicU16, Ordering};
        static NEXT: AtomicU16 = AtomicU16::new(51100);
        loop {
            let port = NEXT.fetch_add(1, Ordering::Relaxed);
            assert!(port < 52000, "reserve_port exhausted the test port range");
            if let Ok(l) = std::net::TcpListener::bind(("127.0.0.1", port)) {
                return l;
            }
        }
    }

    /// A stub dashboard that COUNTS `/api/broker/voucher/redeem` hits and answers
    /// `{"redeemed":true}`. Returns the shared counter and its base URL. This is
    /// what makes the third money leg (the authoritative dashboard commission
    /// credit) observable: without it the leg could be deleted wholesale and no
    /// test would notice.
    fn spawn_redeem_stub() -> (Arc<std::sync::atomic::AtomicUsize>, String) {
        use std::io::{Read, Write};
        use std::sync::atomic::{AtomicUsize, Ordering};
        let listener = reserve_port();
        let url = format!("http://127.0.0.1:{}", listener.local_addr().unwrap().port());
        let hits = Arc::new(AtomicUsize::new(0));
        let hits_srv = Arc::clone(&hits);
        std::thread::spawn(move || {
            for stream in listener.incoming() {
                let mut stream = match stream {
                    Ok(s) => s,
                    Err(_) => continue,
                };
                let mut buf = [0u8; 4096];
                let n = stream.read(&mut buf).unwrap_or(0);
                let req = String::from_utf8_lossy(&buf[..n]);
                // Count only the redeem endpoint, so an unrelated dashboard call
                // (e.g. a balance load) can never be mistaken for a redeem.
                if req.contains("/api/broker/voucher/redeem") {
                    hits_srv.fetch_add(1, Ordering::SeqCst);
                }
                let body = r#"{"redeemed":true}"#;
                let resp = format!(
                    "HTTP/1.1 200 OK\r\nContent-Length: {}\r\nContent-Type: application/json\r\nConnection: close\r\n\r\n{}",
                    body.len(),
                    body
                );
                let _ = stream.write_all(resp.as_bytes());
                let _ = stream.flush();
            }
        });
        (hits, url)
    }

    /// The `Some` arm must fire the dashboard voucher redeem — the THIRD money
    /// leg, which authoritatively credits the platform-house commission.
    /// Deleting the redeem block from the `Some` arm must fail this test.
    #[test]
    fn some_arm_redeems_the_voucher_exactly_once() {
        use std::sync::atomic::Ordering;
        let (hits, api_url) = spawn_redeem_stub();
        let st = state_with_seeded_peer_api(&api_url);
        run_commit_with_nonce(&st, &worker(Some(PEER_FP)), "nonce-abc");
        assert_eq!(
            hits.load(Ordering::SeqCst),
            1,
            "the resolvable-executor arm must redeem the voucher exactly once \
             (all three money legs fire together)"
        );
    }

    /// The `None` arm must redeem NOTHING: crediting the platform its commission
    /// with no offsetting executor earn would leave credits unaccounted and the
    /// requester overcharged.
    #[test]
    fn none_arm_redeems_nothing() {
        use std::sync::atomic::Ordering;
        let (hits, api_url) = spawn_redeem_stub();
        let st = state_with_seeded_peer_api(&api_url);
        // Unstamped worker → executor_fp returns None → the pay-nobody arm.
        run_commit_with_nonce(&st, &worker(None), "nonce-abc");
        assert_eq!(
            hits.load(Ordering::SeqCst),
            0,
            "the unresolvable-executor arm must redeem nothing"
        );
        // ...and the requester is still made whole for the FULL actual_cost.
        assert_eq!(bal(&st, "u1"), Some(100.0));
    }

    fn bal(st: &Arc<BrokerState>, uid: &str) -> Option<f64> {
        st.ledger.authoritative_balances.get(uid).map(|v| *v)
    }

    #[test]
    fn unstamped_worker_takes_full_refund_arm_via_commit_credits() {
        let st = state_with_seeded_peer();
        run_commit(&st, &worker(None));

        // None arm: local_commit refunded the 6.0 unspent hold (90 → 96), then
        // the arm refunded the FULL actual_cost 4.0 (96 → 100). Requester is
        // exactly whole.
        assert_eq!(
            bal(&st, "u1"),
            Some(100.0),
            "unstamped executor must leave the requester whole (full refund)"
        );
        // Pay-nobody: the platform-house commission leg must NOT have fired.
        assert_eq!(
            bal(&st, "platform-house"),
            None,
            "None arm credited the platform commission — a money leg escaped the Some arm"
        );
        assert_eq!(
            st.ledger.local_credits.get("platform-house").map(|v| *v),
            None
        );
    }

    #[test]
    fn stamped_resolvable_worker_takes_payout_arm_via_commit_credits() {
        let st = state_with_seeded_peer();
        run_commit(&st, &worker(Some(PEER_FP)));

        // Some arm: platform-house authoritatively credited its 0.4 commission.
        assert_eq!(
            bal(&st, "platform-house"),
            Some(0.4),
            "stamped, resolvable executor must credit the platform commission"
        );
        // The executor `earn` RPC cannot succeed (closed port), so `payout` 3.6
        // is refunded and the requester nets exactly -commission: 100 - 0.4.
        let got = bal(&st, "u1").unwrap();
        assert!(
            (got - 99.6).abs() < 1e-9,
            "requester should net -commission on the payout arm; got {got}"
        );
    }
}

/// Spec 2026-09-13-macos-widget §13: which price does billing read?
///
/// FINDING (confirmed by Step 2; rewrite for branch B if it fails): billing reads the per-worker
/// `worker.pricing.price_per_hour`; `BrokerPrice` (`state.price`) only feeds
/// `GET /price`, `/price/set` and the signed `/peer/advert`. Task 4 therefore
/// applies hub prices to `Worker.pricing` (branch A).
#[cfg(test)]
mod billing_price_pin_tests {
    use super::{execute_offer_locally, reserve_offer};
    use crate::broker::worker::test_registration;
    use crate::broker::{task_board, BrokerState};

    /// A worker that takes `delay_ms` to answer, so a job has a duration to bill.
    ///
    /// Built on `integration_tests::bind_loopback_http`, the shared bind-with-retry
    /// helper rather than another hand-rolled `tiny_http` server, so every test
    /// module reuses the one loopback-bind implementation.
    pub(super) fn slow_mock_worker(delay_ms: u64) -> u16 {
        let (server, port) = crate::integration_tests::integration::bind_loopback_http();
        std::thread::spawn(move || {
            for req in server.incoming_requests() {
                std::thread::sleep(std::time::Duration::from_millis(delay_ms));
                let _ = req.respond(tiny_http::Response::from_data(b"ok".to_vec()));
            }
        });
        port
    }

    pub(super) fn state_with_local_worker(name: &str, port: u16, price: f64) -> BrokerState {
        let state = BrokerState::new();
        state.workers.register(test_registration(
            name,
            format!("http://127.0.0.1:{port}"),
            price,
        ));
        state
    }

    /// No budget cap, so any worker price is selectable.
    pub(super) fn pin_offer(task_id: &str) -> task_board::TaskOffer {
        serde_json::from_str(&format!(
            r#"{{"task_id":"{task_id}","payload_b64":"","max_price_per_hour":1000000000.0,"estimated_duration_secs":10.0,"timeout_secs":10.0,"requester_user_id":"u","source_broker":"n"}}"#
        ))
        .unwrap()
    }

    #[test]
    fn billing_reads_the_worker_price_not_the_broker_price() {
        let port = slow_mock_worker(200);
        // 3600 credits/hour == 1 credit/second on the worker…
        let state = state_with_local_worker("pin-w0", port, 3600.0);
        // …and 0 on the broker. If billing read BrokerPrice, every cost would
        // collapse to min_charge (0.001).
        state.price.set(0.0);

        let accept = reserve_offer(&state, &pin_offer("pin-reserve")).unwrap();
        assert!(
            (accept.estimated_cost - 10.0).abs() < 1e-9,
            "estimate must use the worker price (10 s at 1 cr/s), got {}",
            accept.estimated_cost
        );
        assert_eq!(accept.price_per_hour, 3600.0);

        let result = execute_offer_locally(&state, &pin_offer("pin-exec")).unwrap();
        assert!(
            result.actual_cost >= 0.15,
            "a ~200 ms job at 1 cr/s must cost >= 0.15, got {} (BrokerPrice would give 0.001)",
            result.actual_cost
        );
        assert_eq!(result.price_per_hour, 3600.0);
    }

    /// A hub that answers every `sync-workers` call with `reply` and hands each
    /// request body to the test. Built on the shared `bind_loopback_http`
    /// rather than a new hand-rolled `tiny_http` server.
    fn mock_sync_hub(reply: &'static str) -> (String, std::sync::mpsc::Receiver<String>) {
        let (server, port) = crate::integration_tests::integration::bind_loopback_http();
        let (tx, rx) = std::sync::mpsc::channel();
        std::thread::spawn(move || {
            for mut req in server.incoming_requests() {
                let mut body = String::new();
                let _ = std::io::Read::read_to_string(req.as_reader(), &mut body);
                let _ = tx.send(body);
                let _ = req.respond(tiny_http::Response::from_string(reply).with_header(
                    tiny_http::Header::from_bytes("Content-Type", "application/json").unwrap(),
                ));
            }
        });
        (format!("http://127.0.0.1:{port}"), rx)
    }

    /// Spec §6.6 invariant: a job on worker X is billed at the hub's effective
    /// price for X once a sync has carried it, and sync keeps reporting X's own price.
    #[test]
    fn hub_price_from_sync_reply_is_what_a_job_is_billed() {
        use crate::broker::ledger::Ledger;
        let port = slow_mock_worker(200);
        let state = state_with_local_worker("pin-w1", port, 3600.0);
        let (hub, bodies) = mock_sync_hub(
            r#"{"success":true,"synced":1,"failed":0,"errors":[],"prices":{"pin-w1":7200.0}}"#,
        );

        let sync = || {
            Ledger::sync_workers_via_api(
                "u1",
                &state.workers.list(),
                &hub,
                "zk_u1_test",
                Some("n"),
                None,
                Some("pk"),
            )
            .unwrap()
        };

        let outcome = sync();
        assert_eq!(outcome.prices.get("pin-w1"), Some(&7200.0));
        assert_eq!(state.workers.apply_hub_prices(&outcome.prices), 1);
        let sent: serde_json::Value = serde_json::from_str(&bodies.recv().unwrap()).unwrap();
        assert_eq!(
            sent[0]["price_per_hour"], 3600.0,
            "first sync reports the worker's own price"
        );

        let result = execute_offer_locally(&state, &pin_offer("hub-exec")).unwrap();
        assert_eq!(result.price_per_hour, 7200.0);
        assert!(
            result.actual_cost >= 0.3,
            "~200 ms at 2 cr/s must cost >= 0.3, got {}",
            result.actual_cost
        );

        sync();
        let sent: serde_json::Value = serde_json::from_str(&bodies.recv().unwrap()).unwrap();
        assert_eq!(
            sent[0]["price_per_hour"], 3600.0,
            "sync keeps reporting the non-override price"
        );
    }
}

/// `POST /workers/{id}/drain` (spec 2026-09-13-macos-widget §6.6): loopback-only,
/// marks the worker `Draining`, 404 on an unknown id.
#[cfg(test)]
mod drain_route_tests {
    use super::*;
    use crate::broker::worker::test_registration;
    use tiny_http::Method;

    fn post(path: &str, peer: Option<std::net::SocketAddr>) -> BrokerRequest {
        BrokerRequest {
            method: Method::Post,
            path: path.to_string(),
            query: String::new(),
            headers: vec![],
            body: vec![],
            peer_addr: peer,
        }
    }

    #[test]
    fn drain_is_loopback_only_and_marks_the_worker_draining() {
        let state = Arc::new(BrokerState::new());
        let w = state.workers.register(test_registration(
            "fp-w0",
            "http://127.0.0.1:3960".to_string(),
            3.6,
        ));
        let path = format!("/workers/{}/drain", w.id);

        let remote: std::net::SocketAddr = "10.13.13.9:5555".parse().unwrap();
        assert_eq!(
            handle(state.clone(), &post(&path, Some(remote)), false).status,
            403
        );
        assert_eq!(
            state.workers.get(&w.id).unwrap().status,
            WorkerStatus::Healthy
        );

        let ok = handle(state.clone(), &post(&path, None), false);
        assert_eq!(ok.status, 200, "{}", String::from_utf8_lossy(&ok.body));
        let body: serde_json::Value = serde_json::from_slice(&ok.body).unwrap();
        assert_eq!(body["status"], "draining");
        assert_eq!(
            state.workers.get(&w.id).unwrap().status,
            WorkerStatus::Draining
        );

        let list = handle(
            state.clone(),
            &BrokerRequest {
                method: Method::Get,
                ..post("/workers", None)
            },
            false,
        );
        let list: serde_json::Value = serde_json::from_slice(&list.body).unwrap();
        assert_eq!(list["workers"][0]["status"], "draining");

        assert_eq!(
            handle(state, &post("/workers/nope/drain", None), false).status,
            404
        );
    }
}

/// A P2P task offer forwarded to a local worker must count toward
/// `active_requests` while it is in flight, exactly like `/execute` does —
/// otherwise a draining worker in the middle of a P2P job reports 0 active
/// requests and the agent sends SIGTERM before the job finishes (spec §6.5).
#[cfg(test)]
mod p2p_active_requests_tests {
    use super::billing_price_pin_tests::{pin_offer, slow_mock_worker, state_with_local_worker};
    use super::*;

    #[test]
    fn a_slow_p2p_offer_holds_active_requests_at_one_until_it_completes() {
        let port = slow_mock_worker(200);
        let state = Arc::new(state_with_local_worker("fp-w0", port, 3.6));
        let worker_id = state.workers.list()[0].id.clone();

        let state_for_thread = state.clone();
        let handle_thread = std::thread::spawn(move || {
            execute_offer_locally(&state_for_thread, &pin_offer("p2p-active"))
        });

        // Give the offer time to reach the worker (which sleeps 200ms) before
        // asserting the in-flight count.
        std::thread::sleep(std::time::Duration::from_millis(50));
        let mid = state.workers.get(&worker_id).unwrap();
        assert_eq!(
            mid.active_requests, 1,
            "a P2P offer in flight must be counted, exactly like /execute"
        );

        handle_thread.join().unwrap().unwrap();
        let after = state.workers.get(&worker_id).unwrap();
        assert_eq!(
            after.active_requests, 0,
            "released once the offer completes"
        );
    }
}

/// A reserved P2P offer pins its worker until the commit (which runs on that
/// exact worker), a cancel, or the reservation's expiry. `GET /workers`
/// counts it as activity for that whole window, so a drain can't read a
/// reserved-but-uncommitted worker as idle and have the agent stop it.
#[cfg(test)]
mod reservation_activity_tests {
    use super::billing_price_pin_tests::{pin_offer, slow_mock_worker, state_with_local_worker};
    use super::*;
    use tiny_http::Method;

    fn listed_active_requests(state: &Arc<BrokerState>) -> u64 {
        let resp = handle(
            state.clone(),
            &BrokerRequest {
                method: Method::Get,
                path: "/workers".to_string(),
                query: String::new(),
                headers: vec![],
                body: vec![],
                peer_addr: None,
            },
            false,
        );
        let list: serde_json::Value = serde_json::from_slice(&resp.body).unwrap();
        list["workers"][0]["active_requests"].as_u64().unwrap()
    }

    #[test]
    fn a_reserved_offer_counts_as_activity_until_commit_cancel_or_expiry() {
        let port = slow_mock_worker(0);
        let state = Arc::new(state_with_local_worker("fp-w0", port, 3.6));
        assert_eq!(listed_active_requests(&state), 0);

        reserve_offer(&state, &pin_offer("r-commit")).unwrap();
        assert_eq!(
            listed_active_requests(&state),
            1,
            "reserved, not yet committed"
        );
        let pending = take_committed(&state, "r-commit").unwrap();
        let worker = state.workers.get(&pending.worker_id).unwrap();
        run_offer_on(&state, &pending.offer, &worker).unwrap();
        assert_eq!(
            listed_active_requests(&state),
            0,
            "released once the commit ran"
        );

        reserve_offer(&state, &pin_offer("r-cancel")).unwrap();
        assert_eq!(listed_active_requests(&state), 1);
        cancel_offer(&state, "r-cancel");
        assert_eq!(listed_active_requests(&state), 0, "released by a cancel");

        reserve_offer(&state, &pin_offer("r-expire")).unwrap();
        assert_eq!(listed_active_requests(&state), 1);
        std::thread::sleep(std::time::Duration::from_millis(5));
        sweep_expired_offers(&state, std::time::Duration::ZERO);
        assert_eq!(
            listed_active_requests(&state),
            0,
            "released once the reservation expired"
        );
    }
}

/// The zc↔hub earnings contract (spec 2026-09-13-macos-widget §5.3/§6.6): a
/// provider's earnings are the rows booked as `earn-{request_id}` with
/// dashboard type `credit_purchase`. The hub's summary query depends on both.
///
/// These tests pin all three sites that book an earn row —
/// `settle_own_provider_payout`, `handle_peer_earn`, `settle_self_payout` —
/// plus the flush mapping (asserted at the payload level in
/// `flush::earn_credit_purchase_payload_tests`, and here as the pure
/// function). A refund's `{id}-earn-refund` id must NOT collide with the
/// `earn-` prefix the hub's summary query keys off of.
#[cfg(test)]
mod earn_prefix_contract_tests {
    use super::*;
    use crate::broker::flush::dashboard_type;
    use crate::broker::worker::test_registration;
    use tiny_http::Method;

    /// A broker state configured with `owner`, deterministic (no env
    /// dependence) and without a dashboard configured unless `api_configured`.
    fn owner_state(owner: Option<&str>, api_configured: bool) -> Arc<BrokerState> {
        Arc::new(BrokerState::with_config(crate::broker::BrokerConfig {
            owner_user_id: owner.map(|s| s.to_string()),
            api_url: api_configured.then(|| "http://127.0.0.1:1".to_string()),
            api_key: api_configured.then(|| "k".to_string()),
            peer_key: None,
            enable_p2p: false,
            ..crate::broker::BrokerConfig::default()
        }))
    }

    #[test]
    fn peer_earn_books_an_earn_prefixed_credit_purchase_for_the_owner() {
        let state = Arc::new(BrokerState::with_config(crate::broker::BrokerConfig {
            peer_key: Some("pk".to_string()),
            enable_p2p: true,
            owner_user_id: Some("owner".to_string()),
            api_url: None,
            api_key: None,
            // A non-empty peer list skips the localhost broker probe in with_config.
            discovery: crate::broker::DiscoveryConfig {
                peers: vec!["127.0.0.1:1".to_string()],
                ..crate::broker::DiscoveryConfig::default()
            },
            ..crate::broker::BrokerConfig::default()
        }));
        let body = serde_json::json!({
            "amount": 1.5,
            "duration_ms": 10.0,
            "worker_id": "a1b2c3d4-w0",
            "requesting_user": "someone",
            "request_id": "r-42"
        });
        let req = BrokerRequest {
            method: Method::Post,
            path: "/peer/earn".to_string(),
            query: String::new(),
            headers: vec![("X-Peer-Key".to_string(), "pk".to_string())],
            body: body.to_string().into_bytes(),
            peer_addr: None,
        };

        let resp = handle(state.clone(), &req, false);
        assert_eq!(resp.status, 200, "{}", String::from_utf8_lossy(&resp.body));

        let queued = state.tx_buffer.pending_snapshot();
        let tx = queued
            .iter()
            .find(|t| t.request_id == "earn-r-42")
            .expect("the earn row must be queued under the earn- prefix");
        assert_eq!(tx.user_id, "owner");
        assert_eq!(dashboard_type(&tx.tx_type), "credit_purchase");
    }

    #[test]
    fn dashboard_types_are_stable() {
        assert_eq!(dashboard_type("commit"), "job_execution");
        assert_eq!(dashboard_type("cancel"), "job_execution");
        assert_eq!(dashboard_type("credit"), "credit_purchase");
        assert_eq!(dashboard_type("serve"), "serve");
    }

    /// Site 1 (`server.rs::settle_own_provider_payout`): a job served on a
    /// worker registered directly on THIS broker pays its own configured
    /// owner via the same `earn-{request_id}` / `credit` shape as the peer
    /// path, driven directly at the function — the smallest real unit that
    /// builds this earning transaction.
    #[test]
    fn settle_own_provider_payout_books_an_earn_prefixed_credit_for_the_owner() {
        let state = owner_state(Some("owner"), false);
        let worker = state.workers.register(test_registration(
            "w-own",
            "http://127.0.0.1:1".to_string(),
            3600.0,
        ));

        settle_own_provider_payout(&state, "requester", &worker, 10.0, 0.0, "", "r-own-1", 5.0);

        let queued = state.tx_buffer.pending_snapshot();
        let tx = queued
            .iter()
            .find(|t| t.request_id == "earn-r-own-1")
            .expect("the own-provider payout must be queued under the earn- prefix");
        assert_eq!(tx.user_id, "owner");
        assert_eq!(tx.tx_type, "credit");
        assert_eq!(dashboard_type(&tx.tx_type), "credit_purchase");
    }

    /// Site 3 (`server.rs::settle_self_payout`): a self-executed job (no
    /// peer round trip) pays the owner the same way. Billing must be
    /// enabled (api_url + api_key configured) for this function to run at
    /// all — it early-returns otherwise.
    #[test]
    fn settle_self_payout_books_an_earn_prefixed_credit_for_the_owner() {
        let state = owner_state(Some("owner"), true);
        let worker = state.workers.register(test_registration(
            "w-self",
            "http://127.0.0.1:1".to_string(),
            3600.0,
        ));

        settle_self_payout(&state, "requester", 10.0, 0.0, &worker, "r-self-1", 5.0);

        let queued = state.tx_buffer.pending_snapshot();
        let tx = queued
            .iter()
            .find(|t| t.request_id == "earn-r-self-1")
            .expect("the self-executed payout must be queued under the earn- prefix");
        assert_eq!(tx.user_id, "owner");
        assert_eq!(tx.tx_type, "credit");
        assert_eq!(dashboard_type(&tx.tx_type), "credit_purchase");
    }

    /// When there's no payee (no owner configured), the payout is
    /// refunded to the requester as `{request_id}-earn-refund` — that id
    /// must NOT start with `earn-`, or the hub's `LIKE 'earn-%'` earnings
    /// query would count a refund as a provider's earnings.
    #[test]
    fn settle_own_provider_payout_refund_id_does_not_start_with_earn_prefix() {
        let state = owner_state(None, true);
        let worker = state.workers.register(test_registration(
            "w-refund",
            "http://127.0.0.1:1".to_string(),
            3600.0,
        ));

        settle_own_provider_payout(
            &state,
            "requester",
            &worker,
            10.0,
            0.0,
            "",
            "r-refund-1",
            5.0,
        );

        let queued = state.tx_buffer.pending_snapshot();
        let tx = queued
            .iter()
            .find(|t| t.user_id == "requester")
            .expect("the no-owner refund must be queued");
        assert_eq!(tx.request_id, "r-refund-1-earn-refund");
        assert!(
            !tx.request_id.starts_with("earn-"),
            "a refund id must never start with `earn-`: {}",
            tx.request_id
        );
        assert_eq!(tx.tx_type, "refund");
    }

    /// The second refund site (`settle_executor_payout`, the path `earn_refund_amount`
    /// feeds): when the executor's broker can't be resolved as a registered
    /// peer, the payout is refunded to the requester the same way — same
    /// non-collision requirement.
    #[test]
    fn settle_executor_payout_refund_id_does_not_start_with_earn_prefix() {
        let state = owner_state(None, true);

        settle_executor_payout(
            &state,
            "requester",
            10.0,
            0.0,
            "http://127.0.0.1:2",
            "unreachable-worker",
            "r-refund-2",
            5.0,
        );

        let queued = state.tx_buffer.pending_snapshot();
        let tx = queued
            .iter()
            .find(|t| t.user_id == "requester")
            .expect("the unreachable-executor refund must be queued");
        assert_eq!(tx.request_id, "r-refund-2-earn-refund");
        assert!(
            !tx.request_id.starts_with("earn-"),
            "a refund id must never start with `earn-`: {}",
            tx.request_id
        );
        assert_eq!(tx.tx_type, "refund");
    }

    /// The third refund site: `settle_self_payout`'s no-owner arm
    /// independently formats the same `{request_id}-earn-refund` id — a
    /// separate literal from the other two refund sites, so a mis-edit here
    /// specifically (e.g. `earn-{request_id}-refund`) is not caught by
    /// either of the other two refund tests above.
    #[test]
    fn settle_self_payout_refund_id_does_not_start_with_earn_prefix() {
        let state = owner_state(None, true);
        let worker = state.workers.register(test_registration(
            "w-self-refund",
            "http://127.0.0.1:1".to_string(),
            3600.0,
        ));

        settle_self_payout(&state, "requester", 10.0, 0.0, &worker, "r-refund-3", 5.0);

        let queued = state.tx_buffer.pending_snapshot();
        let tx = queued
            .iter()
            .find(|t| t.user_id == "requester")
            .expect("the self-executed no-owner refund must be queued");
        assert_eq!(tx.request_id, "r-refund-3-earn-refund");
        assert!(
            !tx.request_id.starts_with("earn-"),
            "a refund id must never start with `earn-`: {}",
            tx.request_id
        );
        assert_eq!(tx.tx_type, "refund");
    }
}