car-inference 0.47.0

//! # car-inference
//!
//! Local model inference for the Common Agent Runtime.
//!
//! Provides on-device inference using Candle with automatic hardware detection:
//! - **macOS**: Metal (Apple Silicon GPU)
//! - **Linux**: CUDA (NVIDIA GPU) or CPU fallback
//!
//! Ships with Qwen3 models downloaded on first use from HuggingFace.
//! Supports remote API models (OpenAI, Anthropic, Google) via the same schema.
//!
//! ## Architecture
//!
//! Models are first-class typed resources described by `ModelSchema` (analogous
//! to `ToolSchema`). The `UnifiedRegistry` holds local and remote models.
//! The `AdaptiveRouter` selects the best model using a three-phase strategy:
//! filter → score → explore. The `OutcomeTracker` learns from results to
//! improve routing over time.
//!
//! ## Dual purpose
//!
//! 1. **Internal** — powers skill learning/repair, semantic memory, policy evaluation
//! 2. **Service** — exposes `infer`, `embed`, `classify` as built-in CAR tools

pub mod action_ledger;
pub mod adaptive_router;
pub mod aws_sigv4;
pub mod backend;
pub mod backend_cache;
pub mod calibration;
pub mod catalog;
pub mod concierge;
pub mod discovery;
pub mod doctor;
pub mod download;
pub mod handle;
pub mod hardware;
pub mod intent;
pub mod key_pool;
pub mod lane_defaults;
pub mod media_tokens;
pub mod models;
pub mod nudge;
pub mod offload;
pub mod openrouter;
pub mod outcome;
pub mod protocol;
pub mod recommend;
pub mod registry;
pub mod remote;
pub mod router;
pub mod routing_ext;
pub mod runner;
pub mod schema;
pub mod scoreboard;
pub mod search;
pub mod service;
pub mod stream;
pub mod tasks;
/// Crate-private: reqwest client construction that degrades instead of
/// panicking when the OS trust store cannot be loaded. Not part of the public
/// API — see the module docs for the failure it exists to survive.
pub(crate) mod tls_client;
pub mod uninstall;
pub mod update_prefs;
pub mod upgrade;
pub mod usage_profile;
pub mod vllm_mlx;
pub mod vllm_pool;
pub mod vllm_runtime;

use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::time::Instant;
use std::time::{SystemTime, UNIX_EPOCH};

use reqwest::multipart::{Form, Part};
use serde::Serialize;
use thiserror::Error;
use tokio::process::Command;
use tokio::sync::Mutex;
use tokio::sync::RwLock;
use tracing::{debug, instrument};

// --- New types ---
pub use action_ledger::{ConciergeActionEntry, ConciergeActionKind};
pub use adaptive_router::{
    AdaptiveRouter, AdaptiveRoutingDecision, RoutingConfig, RoutingStrategy,
};
pub use concierge::{
    decide_concierge, evaluate_concierge, ConciergeDecision, ConciergeMode, ConciergeStatus,
    ConciergeSuggestion, DismissReason, DismissalRecord, ModelHealth,
    DEFAULT_CONCIERGE_THROTTLE_SECS, DEFAULT_WATCHED_USE_CASES,
};
pub use download::{DownloadEvent, DownloadProgress, ProgressSink};
pub use handle::InferenceHandle;
pub use intent::{IntentHint, Privacy, QualityTier, TaskHint, TierWeights, UseCase, UseCaseRole};
pub use key_pool::{KeyPool, KeyStats};
pub use lane_defaults::{LaneDefault, LaneDefaults};
pub use nudge::{NudgeDecision, NudgeState, UpgradeNudge};
pub use outcome::{
    prune_ledger, read_ledger, CodeOutcome, InferenceOutcome, InferenceTask, InferredOutcome,
    ModelProfile, OutcomeLedgerEntry, OutcomeTracker,
};
pub use recommend::{recommend, FitStatus, Recommendation, RecommendationSet};
pub use update_prefs::{UpdateChannel, UpdatePolicy, UpdatePreferences};
pub use upgrade::{HuggingFaceProbe, UpgradeFinding, UpgradeSource, UpstreamProbe};
pub use usage_profile::{use_case_for_task, LaneUsage, UsageProfile};

/// Current Unix time in seconds (concierge action timestamps).
fn now_unix() -> u64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0)
}
pub use offload::{
    current_local_offload, is_offload_worker, set_local_offload, LocalGenerationOffload,
};
pub use registry::{
    ModelFilter, ModelInfo, ModelRuntimeRequirement, ModelUpgrade, UnifiedRegistry,
};
pub use remote::RemoteBackend;
pub use routing_ext::{
    CircuitBreaker, CircuitBreakerRegistry, CircuitState, ImplicitSignal, ImplicitSignalType,
    RoutingMode, SpendControl, SpendLimitExceeded, SpendLimits, SpendStatus,
};
pub use runner::{
    current_inference_runner, set_inference_runner, EventEmitter, InferenceRunner, RunnerError,
    RunnerResult,
};
pub use schema::{
    ApiProtocol, ApproxCost, BenchmarkScore, CostModel, ModelCapability, ModelSchema, ModelSource,
    PerformanceEnvelope, ProprietaryAuth, TrustTier,
};

// --- Legacy re-exports (kept for backward compatibility) ---
pub use adaptive_router::TaskComplexity;
#[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
pub use backend::CandleBackend;
#[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
pub use backend::EmbeddingBackend;
#[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
pub use backend::MlxBackend;
pub use hardware::HardwareInfo;
pub use models::{ModelRegistry, ModelRole};
pub use router::{ModelRouter, RoutingDecision};
pub use stream::{StreamAccumulator, StreamEvent};
pub use tasks::{
    parse_boxes, BoundingBox, ClassifyRequest, ClassifyResult, ContentBlock, EmbedRequest,
    GenerateImageRequest, GenerateImageResult, GenerateParams, GenerateRequest,
    GenerateVideoRequest, GenerateVideoResult, GroundRequest, GroundResult, Message, Provenance,
    RerankRequest, RerankResult, RerankedDocument, ResponseFormat, RoutingWorkload,
    SynthesizeRequest, SynthesizeResult, ThinkingMode, ToolCall, TranscribeRequest,
    TranscribeResult, VideoMode,
};
// TokenUsage is defined in this module and already public

#[derive(Error, Debug)]
pub enum InferenceError {
    #[error("model not found: {0}")]
    ModelNotFound(String),

    #[error("model download failed: {0}")]
    DownloadFailed(String),

    #[error("inference failed: {0}")]
    InferenceFailed(String),

    /// A remote call that failed on a *retryable* class — 5xx / 429 / 529 /
    /// timeout / connection reset — after the bounded retry budget was
    /// exhausted. Distinct from [`InferenceError::InferenceFailed`] so a
    /// caller can tell "infra blip, safe to re-run" from "the request itself
    /// is wrong" (4xx / auth / validation). `status` carries the final HTTP
    /// status when the failure was an HTTP response; `None` for a transport
    /// or timeout error. Used by `car run-task` to classify a run as
    /// `infra_inference` (re-run) vs a non-retryable failure (alert).
    #[error("transient remote failure after retries (status={status:?}): {message}")]
    Transient {
        status: Option<u16>,
        message: String,
    },

    /// A request mode is accepted on the public surface but the
    /// selected backend hasn't wired it yet. Distinct from
    /// `InferenceFailed` so callers can distinguish "backend can't"
    /// from "backend tried and something went wrong".
    #[error("mode {mode} not implemented on backend {backend}: {reason}")]
    UnsupportedMode {
        mode: &'static str,
        backend: &'static str,
        reason: &'static str,
    },

    /// The provider **account** rejected the call — key absent or rejected
    /// (401/403), or out of credits/quota (402).
    ///
    /// Account-wide, so it says nothing about the model that happened to be
    /// selected. Booking it as a model failure benches healthy models over a
    /// billing problem, and — because the health EMA is a 30-day window and the
    /// circuit breaker has its own cooldown — the penalty outlives the fix: the
    /// user tops up their credits and the router still avoids the models
    /// (Parslee-ai/car#650). Distinct from `InferenceFailed` so the dispatch
    /// loop can resolve it as an unattributed receipt instead.
    ///
    /// `provider` is the schema's provider label, so the dispatch loop can drop
    /// every remaining candidate from the same account rather than replaying
    /// the identical rejection down the fallback chain.
    #[error("{provider} account rejected the request (HTTP {status}): {message}")]
    ProviderAccount {
        provider: String,
        status: u16,
        message: String,
    },

    /// No usable credential for a provider — and *why*, as data rather than
    /// prose.
    ///
    /// The message text already distinguished the cases (#803), but only in the
    /// text: a consumer wanting to branch on "token aged out mid-run" versus
    /// "never signed in" had to substring-match English that could be reworded
    /// at any time. #797 asked for the distinction to be matchable
    /// programmatically, which is what [`CredentialFailure`] is for.
    ///
    /// **The Display output opens with the historical prefix verbatim** —
    /// `no credential for proprietary provider '<provider>'`. That is load
    /// bearing, not cosmetic: `native_loop::is_auth_failure` (which drives the
    /// wait-for-sign-in path) and the coder-ab harness's `INFRA_MARKERS` (which
    /// keeps auth casualties out of a benchmark denominator) both classify on
    /// it as a substring. Rewording the opening would silently reclassify auth
    /// failures as ordinary errors in both.
    #[error("no credential for proprietary provider '{provider}' (model {model}): {detail}")]
    CredentialUnavailable {
        provider: String,
        model: String,
        /// Machine-readable classification — branch on this, not on `detail`.
        reason: CredentialFailure,
        /// Human-facing explanation and remedy. Wording is not a contract.
        detail: String,
    },

    /// The request was refused on **content** grounds by something in front of
    /// the model — a gateway safety filter, not the model's own judgement.
    ///
    /// Distinct from `InferenceFailed` because the three things a caller wants
    /// to do about it are all different from what they would do about a crash,
    /// and all three were impossible while it looked like one
    /// (Parslee-ai/car#796):
    ///
    /// - a **benchmark** can score it as a policy refusal instead of counting a
    ///   crash, or silently inflating a pass rate by dropping it;
    /// - a **retry loop** can stop, rather than burning its budget re-sending a
    ///   decision that will never change;
    /// - an **operator** can tell a content ruling from a misconfiguration.
    ///
    /// This says nothing about whether the refusal was *correct*. CAR is
    /// reporting that something upstream declined the content, not endorsing the
    /// call — an adversarial-safety suite is *supposed* to send input like this,
    /// and a gateway that drops a variable fraction of it cannot be a substrate
    /// for that measurement. Making the refusal legible is the part CAR owns.
    #[error("{provider} refused this request on content grounds{}{}: {message}",
        .kind.as_deref().map(|k| format!(" (type={k}")).unwrap_or_default(),
        .code.as_deref().map(|c| format!(", code={c})")).unwrap_or_default())]
    ContentRefused {
        provider: String,
        /// The gateway's own classification, when it sent one.
        kind: Option<String>,
        code: Option<String>,
        message: String,
    },

    /// A managed gateway has no upstream configured for an entire namespace of
    /// models it otherwise advertises.
    ///
    /// Environment-scoped, one level up from [`Self::ProviderAccount`]: the
    /// account is fine and the credential is fine — the *deployment* was never
    /// given an upstream to proxy to. Every model in the namespace fails it
    /// identically, so none of them deserves the health penalty, and retrying
    /// the next one down the fallback chain replays the same rejection.
    ///
    /// Kept distinct from `ProviderAccount` because the remedy is different and
    /// belongs to a different person: an account rejection is the user's to fix
    /// (top up credits, re-add a key), while this one is an operator
    /// provisioning gap the user cannot act on at all. Collapsing them would
    /// tell users to check a credential that is working.
    ///
    /// `namespace` is the model-id prefix the condition covers, so the dispatch
    /// loop can drop every remaining candidate under it (Parslee-ai/car#786).
    #[error("{provider} gateway has no upstream configured for '{namespace}' (HTTP {status}): {message}")]
    GatewayUnconfigured {
        provider: String,
        namespace: String,
        status: u16,
        message: String,
    },

    #[error("tokenization error: {0}")]
    TokenizationError(String),

    #[error("device error: {0}")]
    DeviceError(String),

    #[error("io error: {0}")]
    Io(#[from] std::io::Error),
}

/// Whether a dispatch error should count against the model's circuit breaker.
///
/// Two classes are excluded because neither is evidence about the model:
///
/// - [`InferenceError::UnsupportedMode`] is a **deterministic capability
///   mismatch** — a JsonSchema `response_format` on Anthropic, or a video/audio
///   block on a text-only provider — that will fail identically every time on
///   THIS model, while the model stays perfectly healthy for other traffic.
///   Feeding it to the breaker would trip a healthy model out of rotation for
///   ALL requests, not just the incompatible ones.
/// - [`InferenceError::ProviderAccount`] is an **account-wide** rejection —
///   a bad key, or no credits. Every model on that account fails it and no
///   model deserves the blame; benching them would outlive the billing fix
///   (Parslee-ai/car#650).
/// - [`InferenceError::GatewayUnconfigured`] is **environment-wide** — the
///   deployment has no upstream to proxy to, so every model in the namespace
///   fails identically and none of them was ever given a chance. Measured cost
///   of not excluding it: ten managed aliases sitting at 52 calls / 0 successes
///   in `car models stats`, a health record earned entirely by a
///   misconfiguration (Parslee-ai/car#786).
///
/// Every other error is a genuine availability/health signal and still counts.
fn error_counts_against_circuit_breaker(e: &InferenceError) -> bool {
    !matches!(
        e,
        InferenceError::UnsupportedMode { .. }
            | InferenceError::ProviderAccount { .. }
            | InferenceError::GatewayUnconfigured { .. }
            // A content refusal is a ruling about the REQUEST, not evidence
            // about the model — which handles the same payload correctly when
            // it gets through. Benching a model for what a filter in front of
            // it decided would make an adversarial-safety suite progressively
            // evict the models it is trying to measure (Parslee-ai/car#796).
            | InferenceError::ContentRefused { .. }
    )
}

/// Why a credential was unusable, as data — see
/// [`InferenceError::CredentialUnavailable`].
///
/// These need *different remedies*, which is the whole reason they are
/// separated: re-authenticating fixes `SignedOut` and `Expired`, does nothing
/// for `StoreUnreadable` (unlock the keychain), and is the wrong advice
/// entirely for `EnvVarMissing` (set the variable). A long job that dies on one
/// while being told to do the other is Parslee-ai/car#797.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CredentialFailure {
    /// A Parslee session existed and its access token aged out; refresh did not
    /// yield a new one. `expires_at` is unix seconds.
    ///
    /// The distinguishing case from #797: the account is *fine*, it is the run
    /// that outlived the token. Consumers that can checkpoint should treat this
    /// as resumable-after-reauth rather than as a hard configuration error.
    Expired { expires_at: u64 },
    /// A published tombstone: no account is active. The only state that
    /// genuinely means "log in".
    SignedOut,
    /// The credential store could not be read (locked keychain, helper
    /// timeout). Says nothing about whether credentials exist — notably NOT a
    /// sign-out, and re-authenticating is the wrong reflex.
    StoreUnreadable,
    /// A plain env/keychain-backed provider whose variable did not resolve.
    EnvVarMissing { env_var: String },
    /// The store reported an active session on the failure-path re-read — a
    /// race between the two reads, so the request is worth retrying.
    RaceRetryable,
}

/// Which device to run inference on.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Device {
    Cpu,
    Metal,
    Cuda(usize), // device ordinal
}

impl Device {
    /// Auto-detect the best available device for this platform.
    ///
    /// macOS uses MLX (Metal); x86_64 Linux and Windows are compiled with
    /// candle CUDA, so we prefer the GPU there and let `to_candle_device`'s
    /// `cuda_if_available` transparently fall back to CPU on a box with no
    /// NVIDIA GPU. aarch64 Linux and other targets run CPU candle. See
    /// `project_local_inference_gpu_only`.
    pub fn auto() -> Self {
        #[cfg(all(target_os = "macos", feature = "metal"))]
        {
            return Device::Metal;
        }
        #[cfg(all(
            any(target_os = "linux", target_os = "windows"),
            target_arch = "x86_64",
            not(car_skip_cuda)
        ))]
        {
            return Device::Cuda(0);
        }
        #[cfg(not(any(
            all(target_os = "macos", feature = "metal"),
            all(
                any(target_os = "linux", target_os = "windows"),
                target_arch = "x86_64",
                not(car_skip_cuda)
            )
        )))]
        {
            Device::Cpu
        }
    }
}

/// Configuration for the inference engine.
#[derive(Debug, Clone)]
pub struct InferenceConfig {
    /// Where to store downloaded models. Defaults to ~/.car/models/
    pub models_dir: std::path::PathBuf,
    /// Device override. None = auto-detect.
    pub device: Option<Device>,
    /// Default model for generation tasks.
    pub generation_model: String,
    /// Optional preferred model override for generation tasks.
    pub preferred_generation_model: Option<String>,
    /// Default model for embedding tasks.
    pub embedding_model: String,
    /// Optional preferred model override for embedding tasks.
    pub preferred_embedding_model: Option<String>,
    /// Default model for classification tasks.
    pub classification_model: String,
    /// Optional preferred model override for classification tasks.
    pub preferred_classification_model: Option<String>,
}

impl Default for InferenceConfig {
    fn default() -> Self {
        let models_dir = dirs_next()
            .unwrap_or_else(|| std::path::PathBuf::from("."))
            .join(".car")
            .join("models");

        let hw = HardwareInfo::detect();

        Self {
            models_dir,
            device: None,
            generation_model: hw.recommended_model,
            preferred_generation_model: None,
            embedding_model: "Qwen3-Embedding-0.6B".to_string(),
            preferred_embedding_model: None,
            classification_model: "Qwen3-0.6B".to_string(),
            preferred_classification_model: None,
        }
    }
}

fn dirs_next() -> Option<std::path::PathBuf> {
    // `HOME`, falling back to `USERPROFILE` on Windows (where `HOME` is normally
    // unset) — the same fallback used across the workspace. Without it every
    // `InferenceConfig::default()` resolves `models_dir` CWD-relative on Windows.
    std::env::var_os("HOME")
        .or_else(|| std::env::var_os("USERPROFILE"))
        .map(std::path::PathBuf::from)
}

/// Token usage statistics from a model response.
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
pub struct TokenUsage {
    /// Number of tokens in the prompt/input.
    ///
    /// For providers with prompt caching (Anthropic), this is the
    /// *non-cached* prefix only — the tokens after the last cache
    /// breakpoint. The cached portion is reported separately in
    /// [`Self::cache_read_input_tokens`] / [`Self::cache_creation_input_tokens`],
    /// so the true input total is the sum of all three. Pricing those
    /// three buckets at the same rate over- or under-counts cost; see
    /// [`crate::outcome::ModelProfile::usd_per_success`].
    pub prompt_tokens: u64,
    /// Number of tokens in the completion/output.
    pub completion_tokens: u64,
    /// Total tokens (prompt + completion).
    pub total_tokens: u64,
    /// Model's maximum context window size.
    pub context_window: u64,
    /// Prompt-cache hit: input tokens read from a previously written cache
    /// entry. Billed at ~0.1× the base input rate. `0` when the provider
    /// has no prompt caching, caching was disabled, or nothing hit.
    /// (Anthropic `usage.cache_read_input_tokens`.)
    #[serde(default)]
    pub cache_read_input_tokens: u64,
    /// Prompt-cache write: input tokens written into the cache this request.
    /// Billed at ~1.25× (5-minute TTL) or ~2× (1-hour TTL) the base input
    /// rate. `0` when caching is off or nothing was written.
    /// (Anthropic `usage.cache_creation_input_tokens`.)
    #[serde(default)]
    pub cache_creation_input_tokens: u64,
}

/// Result of an inference call, including trace ID for outcome tracking.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct InferenceResult {
    /// The generated text (empty if tool_calls are present).
    pub text: String,
    /// Tool calls returned by the model (when tools were provided in the request).
    pub tool_calls: Vec<crate::tasks::generate::ToolCall>,
    /// Structured bounding boxes when the model emitted Qwen2.5-VL
    /// grounding spans (`<|box_*|>`, `<|object_ref_*|>`) in its text.
    /// Parsed from the same `text` field — the raw span markers remain
    /// visible in `text` for callers that need to see them verbatim.
    /// Empty vec when the model didn't ground anything (typical for
    /// non-VL models or prompts that only ask for description).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub bounding_boxes: Vec<crate::tasks::grounding::BoundingBox>,
    /// Trace ID for reporting outcomes back to the tracker.
    pub trace_id: String,
    /// Which model was used.
    pub model_used: String,
    /// Wall-clock latency in ms.
    pub latency_ms: u64,
    /// Time to first token in milliseconds. Populated by the local
    /// generate paths (Candle/MLX) which observe the prefill→first-decode
    /// transition directly. `None` for paths that can't measure it
    /// honestly without streaming — currently the non-streaming remote
    /// paths. Callers needing TTFT on remote models should use
    /// [`InferenceEngine::generate_tracked_stream`] and time the first
    /// `text` event arrival themselves.
    ///
    /// Always serialized (as `null` when `None`) so downstream
    /// validation harnesses can distinguish "wasn't measured" from
    /// "field doesn't exist on this client's protocol version".
    #[serde(default)]
    pub time_to_first_token_ms: Option<u64>,
    /// Token usage for the call. Populated by the remote providers from their
    /// API response, and by the local backends from their own decode loops —
    /// the in-process MLX and candle paths report the post-truncation prompt
    /// length and the number of tokens they sampled, and the mlx-vlm CLI path
    /// reports the counts the CLI prints (image patches included).
    ///
    /// `None` means nobody could report a count, and it is deliberately not a
    /// zeroed struct: a consumer summing `total_tokens` cannot tell a
    /// fabricated `0` from a real "this used no tokens", so an absent count is
    /// the honest answer and lets callers fall back to their own estimator
    /// (Parslee-ai/car#795). Still `None` on: FoundationModels (Apple's
    /// on-device framework exposes no token counts), a delegated runner that
    /// emits no `usage` stream event, and an mlx-vlm build whose performance
    /// summary doesn't parse.
    ///
    /// [`TokenUsage::context_window`] is `0` on the streaming path — the
    /// accumulator builds usage from stream events, which carry no model
    /// metadata. Non-streaming calls populate it.
    pub usage: Option<TokenUsage>,
    /// Provider-specific output items the protocol emitted alongside
    /// the response — currently used by the OpenAI Responses API to
    /// return reasoning blobs, encrypted_content, web-search results,
    /// etc. as opaque structured items the next request must include
    /// verbatim. Empty for protocols that don't emit them (Chat
    /// Completions, Anthropic, Gemini, all local backends).
    ///
    /// Callers carry these between turns by emitting them as a
    /// [`tasks::generate::Message::ProviderOutputItems`] message in
    /// the next request. Builder paths that don't recognize the
    /// originating protocol drop the variant — the items are
    /// protocol-specific and have no portable rendering.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub provider_output_items: Vec<serde_json::Value>,
    /// Extended-thinking blocks the model produced this turn (Anthropic adaptive
    /// thinking). Captured verbatim (text + opaque signature) so the caller can
    /// attach them to the replayed
    /// [`tasks::generate::Message::Assistant`] and preserve them on the next
    /// turn — Anthropic 400s if prior thinking blocks aren't sent back
    /// unchanged before the tool_use blocks. Empty for providers/models without
    /// thinking (Chat Completions, Gemini, all local backends).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub thinking: Vec<crate::tasks::generate::ThinkingBlock>,
    /// Why generation stopped. For remote models this is the raw
    /// provider string (OpenAI `finish_reason`, Anthropic `stop_reason`,
    /// Google `finishReason`). For local Qwen3 hybrid-thinking models the
    /// runtime also sets it for its reasoning-recovery path
    /// (car-releases#60): `"thinking_recovered"` when reasoning consumed
    /// the whole token budget inside an unclosed `<think>` block and the
    /// runtime retried with reasoning suppressed to produce a direct
    /// answer, or `"thinking_truncated"` when even that retry was empty.
    /// `None` for an ordinary local completion or a provider that didn't
    /// report one. Always serialized (as `null` when `None`) so the wire
    /// contract is stable — see the `inference_result_serializes_*` tests.
    /// Use [`InferenceResult::was_truncated`] to detect a max-tokens cutoff.
    #[serde(default)]
    pub stop_reason: Option<String>,
}

/// Handle returned by [`InferenceEngine::generate_tracked_stream`]: the event
/// receiver plus the stream-level metadata a caller needs to attribute the
/// finished turn. `trace_id` is the same trace the tap task resolves on
/// completion, so a caller can score the turn against it; `model_used` is the
/// resolved model. In-process only (the receiver isn't serializable) — the wire
/// layer forwards events and surfaces these fields on the final response itself.
pub struct TrackedStream {
    /// Resolved model id for this stream.
    pub model_used: String,
    /// Trace id (minted before the first token) the tap resolves on completion.
    pub trace_id: String,
    /// The forwarded event stream.
    pub events: tokio::sync::mpsc::Receiver<stream::StreamEvent>,
}

/// Decide the auto-enabled thinking budget for a turn (F1). Coding turns — the
/// caller's EXPLICIT `IntentHint{task:Code}` (not the coarse keyword classifier,
/// which flags any prose containing "fix"/"bug"/"let ") — get a higher budget
/// than a general reasoning-heavy (Complex) turn; both require the model to
/// advertise extended thinking. Returns `None` when thinking should not be
/// auto-enabled. The budget only selects the effort level via
/// `reasoning_effort_from_budget` (24000 -> "high", 8000 -> "medium"); the
/// adaptive API decides the actual depth.
fn auto_thinking_budget(
    is_code_intent: bool,
    is_complex: bool,
    supports_thinking: bool,
) -> Option<usize> {
    if !supports_thinking {
        return None;
    }
    if is_code_intent {
        Some(24_000)
    } else if is_complex {
        Some(8_000)
    } else {
        None
    }
}

/// Whether the caller EXPLICITLY tagged this turn as a coding task
/// (`IntentHint{task:Code}`) — the signal F1 keys the coding thinking budget on.
///
/// Deliberately NOT the keyword classifier's `decision.task`: the classifier
/// flags any prose containing "fix"/"bug"/"let " as Code, which would
/// over-provision high-effort thinking on incidental words, and a model-pin
/// clobbers `decision.task` to Generate (losing a pinned coder). Keeping this a
/// named pure fn (rather than an inline expression at the call site) pins that
/// invariant against a regression that re-keys the gate onto `decision.task`.
fn is_explicit_code_intent(intent: Option<&intent::IntentHint>) -> bool {
    intent.and_then(|h| h.task) == Some(intent::TaskHint::Code)
}

/// Whether to append an installed on-device model as the remote-only last
/// resort. It fires only when the chain has no local model AND the request is
/// not a hard pin: a `strict_model` caller (the coder's `--model`, an A/B arm)
/// must fail loudly on a remote outage rather than silently degrade to local.
fn should_append_local_last_resort(chain_has_local: bool, strict_model: bool) -> bool {
    !chain_has_local && !strict_model
}

impl InferenceResult {
    /// Returns true if the model chose to call tools instead of generating text.
    pub fn has_tool_calls(&self) -> bool {
        !self.tool_calls.is_empty()
    }

    /// Returns true when the provider terminated the response because it hit the
    /// output-token cap. Matches every provider spelling: OpenAI chat `"length"`,
    /// OpenAI Responses `"max_output_tokens"`, Anthropic `"max_tokens"`, Google
    /// `"MAX_TOKENS"`, and the local MLX/Candle `"length"`. A truncated response
    /// often carries a half-written tool_use argument the validator will reject,
    /// so callers (e.g. car-cli run_task) should detect this and ask the model
    /// to retry in smaller chunks rather than re-emitting the oversized call.
    pub fn was_truncated(&self) -> bool {
        matches!(
            self.stop_reason.as_deref(),
            Some("length" | "max_tokens" | "max_output_tokens" | "MAX_TOKENS")
        )
    }

    /// Append this result to a caller-owned multi-turn history.
    ///
    /// Responses continuity items belong immediately before the assistant
    /// message they accompanied in the provider's output sequence. Keeping the
    /// ordering here centralized prevents CAR's agent, coder, bench, and CLI
    /// loops from independently dropping or misordering opaque reasoning state.
    /// Personal Chat Completions and non-Responses providers leave
    /// `provider_output_items` empty, so their history shape is unchanged.
    pub fn append_assistant_history(
        &self,
        messages: &mut Vec<crate::tasks::generate::Message>,
        tool_calls: Vec<crate::tasks::generate::ToolCall>,
    ) {
        if !self.provider_output_items.is_empty() {
            messages.push(crate::tasks::generate::Message::ProviderOutputItems {
                protocol: crate::protocol::OPENAI_RESPONSES_PROTOCOL.to_string(),
                items: self.provider_output_items.clone(),
            });
        }
        messages.push(crate::tasks::generate::Message::Assistant {
            content: self.text.clone(),
            tool_calls,
            thinking: self.thinking.clone(),
        });
    }
}

#[derive(Debug, Clone, Serialize)]
pub struct SpeechRuntimeHealth {
    pub root: PathBuf,
    pub installed: bool,
    pub python: PathBuf,
    pub stt_command: PathBuf,
    pub tts_command: PathBuf,
    pub configured_python: Option<String>,
    pub detected_python: Option<String>,
}

#[derive(Debug, Clone, Serialize)]
pub struct SpeechModelHealth {
    pub id: String,
    pub name: String,
    pub provider: String,
    pub capability: ModelCapability,
    pub is_local: bool,
    pub available: bool,
    pub cached: bool,
    pub selected_by_default: bool,
    pub source: String,
}

#[derive(Debug, Clone, Serialize)]
pub struct SpeechHealthReport {
    pub runtime: SpeechRuntimeHealth,
    pub local_models: Vec<SpeechModelHealth>,
    pub remote_models: Vec<SpeechModelHealth>,
    pub elevenlabs_configured: bool,
    pub prefer_local: bool,
    pub allow_remote_fallback: bool,
    pub preferred_local_stt: Option<String>,
    pub preferred_local_tts: Option<String>,
    pub preferred_remote_stt: Option<String>,
    pub preferred_remote_tts: Option<String>,
    pub local_stt_default: Option<String>,
    pub local_tts_default: Option<String>,
    pub remote_stt_default: Option<String>,
    pub remote_tts_default: Option<String>,
}

#[derive(Debug, Clone, Serialize)]
pub struct ModelDefaultHealth {
    pub capability: ModelCapability,
    pub configured_model: String,
    pub available: bool,
    pub is_local: bool,
    pub provider: Option<String>,
}

#[derive(Debug, Clone, Serialize)]
pub struct ModelProviderHealth {
    pub provider: String,
    pub configured: bool,
    pub local_models: usize,
    pub remote_models: usize,
    pub available_models: usize,
    pub capabilities: Vec<ModelCapability>,
}

#[derive(Debug, Clone, Serialize)]
pub struct ModelCapabilityHealth {
    pub capability: ModelCapability,
    pub total_models: usize,
    pub available_models: usize,
    pub local_available_models: usize,
    pub remote_available_models: usize,
}

#[derive(Debug, Clone, Serialize)]
pub struct RoutingScenarioHealth {
    pub name: String,
    pub workload: RoutingWorkload,
    pub task_family: String,
    pub has_tools: bool,
    pub has_vision: bool,
    pub prefer_local: bool,
    pub quality_first_cold_start: bool,
    pub bootstrap_min_task_observations: u64,
    pub bootstrap_quality_floor: f64,
    pub model_id: String,
    pub model_name: String,
    pub reason: String,
    pub strategy: RoutingStrategy,
}

#[derive(Debug, Clone, Serialize)]
pub struct ModelBenchmarkPriorHealth {
    pub model_id: String,
    pub model_name: Option<String>,
    pub overall_score: f64,
    pub overall_latency_ms: Option<f64>,
    pub task_scores: std::collections::HashMap<String, f64>,
    pub task_latency_ms: std::collections::HashMap<String, f64>,
    pub source_path: PathBuf,
}

#[derive(Debug, Clone, Serialize)]
pub struct ModelHealthReport {
    pub total_models: usize,
    pub available_models: usize,
    pub local_models: usize,
    pub remote_models: usize,
    pub defaults: Vec<ModelDefaultHealth>,
    pub providers: Vec<ModelProviderHealth>,
    pub capabilities: Vec<ModelCapabilityHealth>,
    pub routing_prefer_local: bool,
    pub routing_quality_first_cold_start: bool,
    pub routing_min_observations: u64,
    pub routing_bootstrap_min_task_observations: u64,
    pub routing_bootstrap_quality_floor: f64,
    pub routing_quality_weight: f64,
    pub routing_latency_weight: f64,
    pub routing_cost_weight: f64,
    pub routing_scenarios: Vec<RoutingScenarioHealth>,
    pub benchmark_priors: Vec<ModelBenchmarkPriorHealth>,
    pub speech: SpeechHealthReport,
}

#[derive(Debug, Clone, Serialize)]
pub struct SpeechInstallReport {
    pub name: String,
    pub hf_repo: String,
    pub snapshot_path: PathBuf,
    pub files_downloaded: usize,
}

#[derive(Debug, Clone, Serialize)]
pub struct SpeechSmokePathReport {
    pub path: String,
    pub tts_model: String,
    pub stt_model: String,
    pub audio_path: PathBuf,
    pub transcript: String,
}

#[derive(Debug, Clone, Serialize, Default)]
pub struct SpeechSmokeReport {
    pub local: Option<SpeechSmokePathReport>,
    pub remote: Option<SpeechSmokePathReport>,
    pub skipped: Vec<String>,
}

#[derive(Debug, Clone, Serialize, Default)]
pub struct SpeechPolicy {
    pub prefer_local: bool,
    pub allow_remote_fallback: bool,
    pub preferred_local_stt: Option<String>,
    pub preferred_local_tts: Option<String>,
    pub preferred_remote_stt: Option<String>,
    pub preferred_remote_tts: Option<String>,
}

/// Pre-render a request for an in-process (MLX/candle) backend. Those backends
/// have no native `messages`/`tools` API — they complete a single prompt string
/// — so when a request carries multi-turn `messages` and/or `tools`, fold them
/// into a Qwen3 chat-format `prompt` (signatures in a `<tools>` block; the model
/// emits `<tool_call>` which `parse_tool_calls` recovers) and clear the
/// structured fields so the downstream `apply_chat_template` pass-through uses
/// the rendered text. A request with neither is returned unchanged (the local
/// generate path stays byte-for-byte identical for plain text completion).
fn render_for_local_backend(mut req: GenerateRequest) -> GenerateRequest {
    let has_msgs = req.messages.as_ref().is_some_and(|m| !m.is_empty());
    let has_tools = req.tools.as_ref().is_some_and(|t| !t.is_empty());
    if has_msgs || has_tools {
        req.prompt = tasks::generate::render_chat_prompt(&req);
        req.messages = None;
        req.tools = None;
    }
    req
}

/// The main inference engine. Thread-safe, lazily loads models.
///
/// Now includes the unified registry, adaptive router, and outcome tracker
/// for schema-driven model selection with learned performance profiles.
pub struct InferenceEngine {
    pub config: InferenceConfig,
    /// Unified model registry (local + remote).
    pub unified_registry: UnifiedRegistry,
    /// Adaptive router with three-phase selection.
    pub adaptive_router: AdaptiveRouter,
    /// Outcome tracker for learning from results.
    pub outcome_tracker: Arc<RwLock<OutcomeTracker>>,
    /// Last time `auto_save_outcomes` flushed the tracker (debounce gate).
    /// `None` until the first flush. Paired with the tracker's dirty flag
    /// so we persist at most once per `OUTCOME_FLUSH_INTERVAL` and only
    /// when a profile actually changed — instead of rewriting the whole
    /// file after every inference call.
    last_outcome_flush: Arc<std::sync::Mutex<Option<Instant>>>,
    /// Serializes all mutations of the outcome-ledger file so a concurrent
    /// append (from a per-call flush) and a prune (read+rename) can't
    /// interleave and drop a receipt — the ledger's whole value is that no
    /// receipt is silently lost.
    ledger_io_lock: Arc<tokio::sync::Mutex<()>>,
    /// Optional spend limits (I4). When `per_request_usd` is set, the
    /// streaming path arms a [`routing_ext::MidStreamSpendGuard`] so a
    /// runaway long output is cancelled mid-stream instead of billed to
    /// completion. Rust-embedder API (no FFI surface by design — see the
    /// I4 handoff note); set via [`InferenceEngine::set_spend_limits`].
    spend_limits: Arc<std::sync::RwLock<Option<SpendLimits>>>,
    /// In-memory cache of lane defaults (Phase D1), so the hot routing
    /// path consults the user's pinned models without a disk read per
    /// inference. Loaded at construction; kept in sync by
    /// `set_lane_default`/`clear_lane_default` (which also persist).
    lane_defaults_cache: Arc<std::sync::RwLock<crate::lane_defaults::LaneDefaults>>,
    /// Serializes lane-mutating concierge operations (apply / rollback /
    /// canary revert) so the action-ledger read-modify-write is atomic —
    /// the canary watcher and a user `apply` can't interleave and revert a
    /// switch the user just made. The model download in `apply` stays
    /// OUTSIDE this lock (no blocking the canary tick on a multi-GB pull).
    concierge_action_lock: Arc<tokio::sync::Mutex<()>>,
    /// Monotonic counter for concierge action `seq` (the canary's anchor
    /// identity). Initialized past the max seq already in the ledger so it
    /// stays monotonic across restarts.
    concierge_action_seq: Arc<std::sync::atomic::AtomicU64>,
    /// HTTP client for remote API models.
    remote_backend: RemoteBackend,
    /// Native MLX text-gen / embedding backends keyed by model id.
    /// Same cache shape as `flux_cache` / `ltx_cache` / `kokoro_cache`:
    /// per-entry `Arc<Mutex<MlxBackend>>` so concurrent calls for the
    /// same model serialize, while calls for different models proceed
    /// in parallel. Also bounded by `CAR_INFERENCE_MODEL_CACHE_MB`.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    mlx_backends: Arc<backend_cache::BackendCache<backend::MlxBackend>>,
    /// Polymorphic cache of NEW-architecture in-process MLX backends (Gemma 4,
    /// …) dispatched via [`backend::local::local_backend_for`] and driven by the
    /// shared `drive_generation` loop. Qwen3 keeps the dedicated `mlx_backends`
    /// cache above (which also backs streaming / tokenize / embeddings); each
    /// model lives in exactly one cache by architecture, so there is no
    /// double-load.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    local_backends:
        Arc<backend_cache::BackendCache<Box<dyn backend::local::LocalInferenceBackend>>>,
    /// LRU-evicting, mutex-serialized cache of loaded Flux image backends.
    /// Avoids reloading the 4–5 GB model on every generate_image call,
    /// and serializes concurrent calls onto the same backend (MLX ops
    /// are not `Sync`).
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    flux_cache: Arc<backend_cache::BackendCache<backend::mlx_flux::FluxBackend>>,
    /// Same for LTX video (~9 GB: transformer + Gemma 3 12B + VAE + vocoder).
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    ltx_cache: Arc<backend_cache::BackendCache<backend::mlx_ltx::LtxBackend>>,
    /// Same for Kokoro TTS (~160 MB). Small but reloading per-utterance
    /// added ~1 s of latency to every `synth` call.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    kokoro_cache: Arc<backend_cache::BackendCache<backend::mlx_kokoro::KokoroBackend>>,
    // Legacy fields kept for backward compatibility
    pub registry: models::ModelRegistry,
    pub router: ModelRouter,
    #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
    backend: Arc<RwLock<Option<CandleBackend>>>,
    #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
    embedding_backend: Arc<RwLock<Option<EmbeddingBackend>>>,
    speech_runtime: Arc<Mutex<Option<SpeechRuntime>>>,
    speech_policy: SpeechPolicy,
    /// On-demand supervised `vllm-mlx` servers for `vllm-mlx/*` models. Lazy-
    /// started on dispatch, idle-evicted alongside the in-process backends, so a
    /// server-backed model is indistinguishable from an in-process one.
    vllm_pool: Arc<vllm_pool::VllmServerPool>,
}

impl InferenceEngine {
    /// Install (or clear) spend limits (I4). `per_request_usd` also arms
    /// the mid-stream guard on streaming calls: the stream is cancelled
    /// with a terminal `StopReason("spend_limit: ...")` the moment the
    /// estimated running cost (prompt + streamed output) crosses the
    /// budget.
    pub fn set_spend_limits(&self, limits: Option<SpendLimits>) {
        *self.spend_limits.write().unwrap() = limits;
    }

    fn preferred_model_for_capability(&self, capability: ModelCapability) -> Option<&str> {
        match capability {
            ModelCapability::Generate => self.config.preferred_generation_model.as_deref(),
            ModelCapability::Embed => self.config.preferred_embedding_model.as_deref(),
            ModelCapability::Classify => self.config.preferred_classification_model.as_deref(),
            _ => None,
        }
    }

    /// True when the request carries a NON-EMPTY tool catalog.
    /// `tools: Some(vec![])` is "no tools": it must not require the
    /// ToolUse capability in routing, and it must not push the
    /// FoundationModels dispatch onto the tool path (which would drop
    /// a `response_format` JsonSchema constraint for zero tools).
    fn request_has_tools(req: &GenerateRequest) -> bool {
        req.tools.as_ref().is_some_and(|t| !t.is_empty())
    }

    fn request_needs_vision(req: &GenerateRequest) -> bool {
        req.images.as_ref().is_some_and(|images| !images.is_empty())
            || req.messages.as_ref().is_some_and(|messages| {
                messages
                    .iter()
                    .any(|msg| matches!(msg, Message::UserMultimodal { .. }))
            })
    }

    /// True when any content block in the request carries video data.
    /// Backends without a video-tokenization path use this to reject
    /// the request up front with [`InferenceError::UnsupportedMode`]
    /// rather than silently dropping the content.
    #[allow(dead_code)] // conditionally compiled — used only on the FoundationModels (macOS) dispatch branch
    fn request_has_video(req: &GenerateRequest) -> bool {
        let images_have_video = req
            .images
            .as_ref()
            .is_some_and(|blocks| blocks.iter().any(ContentBlock::is_video));
        let messages_have_video = req.messages.as_ref().is_some_and(|messages| {
            messages.iter().any(|msg| match msg {
                Message::UserMultimodal { content } => content.iter().any(ContentBlock::is_video),
                _ => false,
            })
        });
        images_have_video || messages_have_video
    }

    /// True when any content block in the request carries audio data.
    /// Same role as [`request_has_video`] but for the audio path
    /// (Gemma 4 small variants, Gemini).
    #[allow(dead_code)] // conditionally compiled — used only on the FoundationModels (macOS) dispatch branch
    fn request_has_audio(req: &GenerateRequest) -> bool {
        let images_have_audio = req
            .images
            .as_ref()
            .is_some_and(|blocks| blocks.iter().any(ContentBlock::is_audio));
        let messages_have_audio = req.messages.as_ref().is_some_and(|messages| {
            messages.iter().any(|msg| match msg {
                Message::UserMultimodal { content } => content.iter().any(ContentBlock::is_audio),
                _ => false,
            })
        });
        images_have_audio || messages_have_audio
    }

    pub fn new(config: InferenceConfig) -> Self {
        let registry = models::ModelRegistry::new(config.models_dir.clone());
        let hw = HardwareInfo::detect();
        // ONE budget shared across all backend caches (text/image/video/TTS), so
        // the aggregate resident model working set is bounded by ~60% of RAM (or
        // CAR_INFERENCE_MODEL_CACHE_MB) instead of a flat 24 GB *per* cache (#427).
        // Only the MLX caches exist on Apple Silicon, so gate the budget likewise.
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        let cache_budget = backend_cache::SharedModelBudget::from_env_or(hw.max_model_mb);
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        let cache_idle = backend_cache::idle_ttl_from_env();
        let router = ModelRouter::new(hw.clone());
        let unified_registry = UnifiedRegistry::new(config.models_dir.clone());
        let adaptive_router = AdaptiveRouter::with_default_config(hw);
        let mut tracker = OutcomeTracker::new();
        // Load persisted profiles from previous sessions (#13)
        let profiles_path = config.models_dir.join("outcome_profiles.json");
        if let Ok(n) = tracker.load_from_file(&profiles_path) {
            if n > 0 {
                tracing::info!(loaded = n, "loaded persisted model profiles");
            }
        }
        let mut benchmark_models_loaded = 0usize;
        for path in benchmark_priors_paths(&config.models_dir) {
            match routing_ext::load_benchmark_priors(&path) {
                Ok(priors) if !priors.is_empty() => {
                    benchmark_models_loaded += priors.len();
                    routing_ext::apply_benchmark_priors(&mut tracker, &priors);
                    tracing::info!(
                        path = %path.display(),
                        loaded = priors.len(),
                        "loaded benchmark quality priors"
                    );
                }
                Ok(_) => {}
                Err(error) => {
                    tracing::warn!(path = %path.display(), %error, "failed to load benchmark priors");
                }
            }
        }
        if benchmark_models_loaded > 0 {
            tracing::info!(
                loaded = benchmark_models_loaded,
                "applied benchmark priors to cold-start routing"
            );
        }
        let outcome_tracker = Arc::new(RwLock::new(tracker));

        let remote_backend = RemoteBackend::new();

        Self {
            config,
            unified_registry,
            adaptive_router,
            outcome_tracker,
            last_outcome_flush: Arc::new(std::sync::Mutex::new(None)),
            ledger_io_lock: Arc::new(tokio::sync::Mutex::new(())),
            spend_limits: Arc::new(std::sync::RwLock::new(None)),
            lane_defaults_cache: Arc::new(std::sync::RwLock::new(crate::lane_defaults::load_from(
                &crate::lane_defaults::default_path(),
            ))),
            concierge_action_lock: Arc::new(tokio::sync::Mutex::new(())),
            concierge_action_seq: Arc::new(std::sync::atomic::AtomicU64::new(
                crate::action_ledger::read_actions(&crate::action_ledger::default_path(), 0)
                    .iter()
                    .map(|a| a.seq)
                    .max()
                    .map(|m| m + 1)
                    .unwrap_or(1),
            )),
            remote_backend,
            #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
            mlx_backends: Arc::new(backend_cache::BackendCache::from_shared(
                cache_budget.clone(),
                cache_idle,
            )),
            #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
            local_backends: Arc::new(backend_cache::BackendCache::from_shared(
                cache_budget.clone(),
                cache_idle,
            )),
            #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
            flux_cache: Arc::new(backend_cache::BackendCache::from_shared(
                cache_budget.clone(),
                cache_idle,
            )),
            #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
            ltx_cache: Arc::new(backend_cache::BackendCache::from_shared(
                cache_budget.clone(),
                cache_idle,
            )),
            #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
            kokoro_cache: Arc::new(backend_cache::BackendCache::from_shared(
                cache_budget,
                cache_idle,
            )),
            registry,
            router,
            #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
            backend: Arc::new(RwLock::new(None)),
            #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
            embedding_backend: Arc::new(RwLock::new(None)),
            speech_runtime: Arc::new(Mutex::new(None)),
            speech_policy: SpeechPolicy {
                prefer_local: cfg!(all(
                    target_os = "macos",
                    target_arch = "aarch64",
                    not(car_skip_mlx)
                )),
                allow_remote_fallback: true,
                preferred_local_stt: None,
                preferred_local_tts: None,
                preferred_remote_stt: None,
                preferred_remote_tts: None,
            },
            vllm_pool: Arc::new(vllm_pool::VllmServerPool::new(
                std::time::Duration::from_secs(
                    std::env::var("CAR_VLLM_IDLE_SECS")
                        .ok()
                        .and_then(|v| v.parse().ok())
                        .unwrap_or(300),
                ),
            )),
        }
    }

    /// Initialize key pool: register keys from all remote models and load persisted stats.
    /// Call this after construction (requires async).
    pub async fn init_key_pool(&self) {
        // Register keys from all remote models in the catalog
        for schema in self.unified_registry.list() {
            if schema.is_remote() {
                self.remote_backend.register_model_keys(schema).await;
            }
        }

        // Load persisted key stats
        let stats_path = self.config.models_dir.join("key_pool_stats.json");
        if let Ok(n) = self.remote_backend.key_pool.load_stats(&stats_path).await {
            if n > 0 {
                tracing::info!(loaded = n, "loaded persisted key pool stats");
            }
        }

        let total = self.remote_backend.key_pool.total_keys().await;
        if total > 0 {
            tracing::info!(keys = total, "key pool initialized");
        }
    }

    /// Get or initialize the generative Candle backend, loading the specified model.
    /// Not used on Apple Silicon where all local inference goes through MLX.
    #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
    async fn ensure_backend(&self, model_name: &str) -> Result<(), InferenceError> {
        let read = self.backend.read().await;
        if read.is_some() {
            return Ok(());
        }
        drop(read);

        let mut write = self.backend.write().await;
        if write.is_some() {
            return Ok(());
        }

        let model_path = self.registry.ensure_model(model_name).await?;
        let device = self.config.device.unwrap_or_else(Device::auto);
        let backend = match CandleBackend::load(&model_path, device) {
            Ok(b) => b,
            Err(load_err) => {
                // A load failure with a provably-corrupt cache (truncated/pruned
                // weights from the shared HF store) self-heals: purge the bad
                // files, re-pull, retry once. An intact cache surfaces the error.
                if crate::download::purge_corrupt_cache_files(&model_path) == 0 {
                    return Err(load_err);
                }
                tracing::warn!(
                    model = model_name,
                    error = %load_err,
                    "candle backend load failed; purged corrupt cache files and re-pulling once"
                );
                let model_path = self.registry.ensure_model(model_name).await?;
                CandleBackend::load(&model_path, device)?
            }
        };
        *write = Some(backend);
        Ok(())
    }

    /// Get or initialize the embedding backend.
    /// On Apple Silicon, uses the MLX backend instead of Candle.
    #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
    async fn ensure_embedding_backend(&self) -> Result<(), InferenceError> {
        let read = self.embedding_backend.read().await;
        if read.is_some() {
            return Ok(());
        }
        drop(read);

        let mut write = self.embedding_backend.write().await;
        if write.is_some() {
            return Ok(());
        }

        let embedding_model = self
            .preferred_model_for_capability(ModelCapability::Embed)
            .unwrap_or(&self.config.embedding_model);
        let model_path = self.registry.ensure_model(embedding_model).await?;
        let device = self.config.device.unwrap_or_else(Device::auto);
        let backend = match EmbeddingBackend::load(&model_path, device) {
            Ok(b) => b,
            Err(load_err) => {
                if crate::download::purge_corrupt_cache_files(&model_path) == 0 {
                    return Err(load_err);
                }
                tracing::warn!(
                    model = embedding_model,
                    error = %load_err,
                    "embedding backend load failed; purged corrupt cache files and re-pulling once"
                );
                let model_path = self.registry.ensure_model(embedding_model).await?;
                EmbeddingBackend::load(&model_path, device)?
            }
        };
        *write = Some(backend);
        Ok(())
    }

    /// On Apple Silicon, ensure the MLX embedding model is loaded.
    /// Returns the schema ID of the embedding model for keying into mlx_backends.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    async fn ensure_mlx_embedding_backend(&self) -> Result<String, InferenceError> {
        let embedding_model_name = self
            .preferred_model_for_capability(ModelCapability::Embed)
            .unwrap_or(&self.config.embedding_model)
            .to_string();
        let schema = self
            .unified_registry
            .get(&embedding_model_name)
            .or_else(|| self.unified_registry.find_by_name(&embedding_model_name))
            .ok_or_else(|| InferenceError::ModelNotFound(embedding_model_name.clone()))?
            .clone();
        self.ensure_mlx_backend(&schema).await?;
        Ok(schema.id)
    }

    /// Load a backend through `cache`, self-healing a corrupt model cache on
    /// failure.
    ///
    /// Loads via `loader`. If the load fails *and* a deep integrity check finds
    /// provably-corrupt files under `model_dir`, those files are purged, the
    /// model is re-pulled via `repull`, and the load is retried exactly once. A
    /// load failure with intact files — an unsupported model, a transient FFI
    /// panic, OOM — surfaces unchanged: we re-pull only when we can *prove* the
    /// on-disk cache is the problem (the shared HF cache is mutated by other
    /// tools, so a load failure is genuinely ambiguous between "bad weights" and
    /// "bad luck"). The deep sha256 pass runs only on this rare failure path and
    /// is bounded to weight blobs (`verify_cache_file` short-circuits configs).
    ///
    /// `get_or_load` does not cache a failed load, so the retry is a clean
    /// second attempt rather than a cached error.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    async fn load_backend_healing<T, F, RF, R>(
        schema_id: &str,
        model_dir: std::path::PathBuf,
        cache: &backend_cache::BackendCache<T>,
        size: u64,
        loader: F,
        repull: RF,
    ) -> Result<backend_cache::CachedBackend<T>, InferenceError>
    where
        T: Send + 'static,
        F: Fn(&Path) -> Result<T, InferenceError>,
        RF: FnOnce() -> R,
        R: std::future::Future<Output = Result<std::path::PathBuf, InferenceError>>,
    {
        match cache.get_or_load(schema_id, size, || loader(&model_dir)) {
            Ok(handle) => Ok(handle),
            Err(load_err) => {
                // The heal is deliberately lock-free: `repull` (redownload_local)
                // takes the per-model `acquire_model_lock` itself, so wrapping
                // this branch in the same lock would deadlock. The only cost is
                // that two callers racing the very first load of the same corrupt
                // model both fail — the first purges+heals, the second sees
                // `purged == 0` and surfaces the error. Rare and fail-safe: the
                // next call loads the now-healed model cleanly.
                let purged = crate::download::purge_corrupt_cache_files(&model_dir);
                if purged == 0 {
                    // Cache is intact — not a corruption we can heal by re-pulling.
                    return Err(load_err);
                }
                tracing::warn!(
                    model = schema_id,
                    purged,
                    error = %load_err,
                    "backend load failed; purged corrupt cache files and re-pulling once"
                );
                let fresh_dir = repull().await?;
                cache.get_or_load(schema_id, size, || loader(&fresh_dir))
            }
        }
    }

    /// Get or initialize the native MLX backend for a specific model.
    /// Returns a shared mutex handle — the caller locks it for the
    /// duration of an inference call so concurrent requests serialize.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    async fn ensure_mlx_backend(
        &self,
        schema: &ModelSchema,
    ) -> Result<backend_cache::CachedBackend<backend::MlxBackend>, InferenceError> {
        if !Self::supports_native_mlx(schema) {
            return Err(InferenceError::InferenceFailed(format!(
                "native MLX backend does not support {} ({}) yet; use vLLM-MLX or add a family-specific MLX backend",
                schema.name, schema.family
            )));
        }

        let model_dir = self.unified_registry.ensure_local(&schema.id).await?;
        let size = backend_cache::estimate_model_size(&model_dir);
        // Loader runs inside `get_or_load` only on a cache miss. Wrap it
        // in `catch_unwind` because MLX/accelerate occasionally panics
        // at the FFI boundary and we don't want the whole engine to die.
        let loader = |dir: &Path| {
            let dir = dir.to_path_buf();
            std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
                backend::MlxBackend::load(&dir)
            }))
            .map_err(|e| {
                InferenceError::InferenceFailed(format!(
                    "MLX backend loading panicked (possible Metal/accelerate exception): {:?}",
                    e
                ))
            })?
        };
        Self::load_backend_healing(
            &schema.id,
            model_dir,
            &self.mlx_backends,
            size,
            loader,
            || self.unified_registry.redownload_local(&schema.id),
        )
        .await
    }

    /// Load (and cache) a polymorphic in-process backend for a NEW-architecture
    /// MLX model — the trait-object analogue of [`ensure_mlx_backend`], keyed
    /// into the separate `local_backends` cache. Dispatch on the model's
    /// `config.json` `model_type` lives in `backend::local::local_backend_for`.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    async fn ensure_local_backend(
        &self,
        schema: &ModelSchema,
    ) -> Result<
        backend_cache::CachedBackend<Box<dyn backend::local::LocalInferenceBackend>>,
        InferenceError,
    > {
        let model_dir = self.unified_registry.ensure_local(&schema.id).await?;
        let size = backend_cache::estimate_model_size(&model_dir);
        let loader = |dir: &Path| {
            let dir = dir.to_path_buf();
            std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
                backend::local::local_backend_for(&dir)
            }))
            .map_err(|e| {
                InferenceError::InferenceFailed(format!(
                    "local backend loading panicked (possible Metal/accelerate exception): {:?}",
                    e
                ))
            })?
        };
        Self::load_backend_healing(
            &schema.id,
            model_dir,
            &self.local_backends,
            size,
            loader,
            || self.unified_registry.redownload_local(&schema.id),
        )
        .await
    }

    /// Clear the in-process KV / prefix cache of a loaded local model.
    ///
    /// Prefix reuse (`begin_prompt`) is a per-conversation optimization: it reuses
    /// the KV state of a shared token prefix across calls. When one engine is
    /// driven through a sequence of *independent* prompts (e.g. a benchmark's task
    /// suite), that reuse leaks decode state between unrelated conversations — and
    /// reusing cached KV instead of a fresh prefill introduces tiny numerical
    /// drift that can flip a greedy (temperature-0) token, making multi-step runs
    /// non-reproducible. Calling this between independent runs restores a clean
    /// slate. No-op for remote models or a backend that isn't currently loaded.
    pub async fn reset_local_kv_cache(&self, model_id: &str) {
        // The in-process `local_backends` cache (and its `ensure_local_backend`
        // loader) only exists on the native-MLX target; elsewhere there is no
        // such cache to clear, so this is a no-op.
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        {
            let Some(schema) = self.unified_registry.get(model_id).cloned() else {
                return;
            };
            // Only the in-process backends (`Mlx`/`Local` GGUF) carry a KV cache;
            // remote sources have nothing to clear and must not be `ensure_local`-ed
            // (it would try to download weights).
            if !matches!(
                schema.source,
                ModelSource::Mlx { .. } | ModelSource::Local { .. }
            ) {
                return;
            }
            if let Ok(handle) = self.ensure_local_backend(&schema).await {
                if let Ok(mut guard) = handle.lock() {
                    guard.clear_kv_cache();
                }
            }
        }
        #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
        let _ = model_id;
    }

    /// Pre-load a set of models into the MLX cache so the first real
    /// inference call doesn't pay the 1–14 s model-load latency. Safe
    /// to call multiple times; already-loaded models are no-ops.
    ///
    /// Handles both text-gen MLX backends (`mlx_backends`) and the
    /// image/video/tts caches. Pass the full `schema.id` values.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    pub async fn warm_up<S: AsRef<str>>(
        &self,
        schema_ids: &[S],
    ) -> Vec<Result<(), InferenceError>> {
        let mut results = Vec::with_capacity(schema_ids.len());
        for id in schema_ids {
            let id = id.as_ref();
            let outcome: Result<(), InferenceError> = async {
                let schema = self.unified_registry.get(id).cloned().ok_or_else(|| {
                    InferenceError::InferenceFailed(format!("warm_up: unknown schema id {id}"))
                })?;
                match schema.capabilities.first().copied() {
                    Some(ModelCapability::ImageGeneration) => {
                        let model_dir = self.unified_registry.ensure_local(&schema.id).await?;
                        let size = backend_cache::estimate_model_size(&model_dir);
                        let _ = self.flux_cache.get_or_load(&schema.id, size, || {
                            backend::mlx_flux::FluxBackend::load(&model_dir)
                        })?;
                    }
                    Some(ModelCapability::VideoGeneration) => {
                        let model_dir = self.unified_registry.ensure_local(&schema.id).await?;
                        let size = backend_cache::estimate_model_size(&model_dir);
                        let _ = self.ltx_cache.get_or_load(&schema.id, size, || {
                            backend::mlx_ltx::LtxBackend::load(&model_dir)
                        })?;
                    }
                    Some(ModelCapability::TextToSpeech) => {
                        let model_dir = self.unified_registry.ensure_local(&schema.id).await?;
                        let size = backend_cache::estimate_model_size(&model_dir);
                        let _ = self.kokoro_cache.get_or_load(&schema.id, size, || {
                            backend::mlx_kokoro::KokoroBackend::load(&model_dir)
                        })?;
                    }
                    _ => {
                        let _ = self.ensure_mlx_backend(&schema).await?;
                    }
                }
                Ok(())
            }
            .await;
            results.push(outcome);
        }
        results
    }

    /// No-op on non-macOS — MLX doesn't run here.
    #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
    pub async fn warm_up<S: AsRef<str>>(
        &self,
        _schema_ids: &[S],
    ) -> Vec<Result<(), InferenceError>> {
        Vec::new()
    }

    /// Ensure the supervised `vllm-mlx` server for a `vllm-mlx/*` schema is
    /// running and return a copy whose endpoint points at the live loopback port.
    /// Non-vllm schemas pass through untouched. This is the seam that lets a
    /// server-backed (multimodal / unsupported-arch) model route exactly like an
    /// in-process one — the caller never starts a server or configures an endpoint.
    async fn vllm_live_schema(&self, schema: ModelSchema) -> Result<ModelSchema, InferenceError> {
        let model_name = match &schema.source {
            ModelSource::VllmMlx { model_name, .. } => model_name.clone(),
            _ => return Ok(schema),
        };
        let endpoint = self
            .vllm_pool
            .ensure(&schema.id, &model_name)
            .await
            .map_err(InferenceError::InferenceFailed)?;
        let mut schema = schema;
        schema.source = ModelSource::VllmMlx {
            endpoint,
            model_name,
        };
        Ok(schema)
    }

    /// Stop idle supervised `vllm-mlx` servers. Driven by the same idle loop that
    /// evicts in-process backends; returns the number stopped.
    pub async fn evict_idle_vllm_servers(&self) -> usize {
        self.vllm_pool.evict_idle().await
    }

    /// Sweep idle model backends out of every LRU cache so a quiet daemon
    /// releases its resident model working set instead of pinning it under
    /// the (large) capacity budget — capacity eviction never fires below
    /// the cap, so without this a single loaded model stays resident
    /// forever. Returns `(entries_evicted, bytes_evicted)` summed across
    /// all backend caches. Idle window is `CAR_INFERENCE_MODEL_IDLE_SECS`
    /// (default 300; 0 disables). Drive it on a timer. (car-releases#67)
    ///
    /// No-op on platforms without the MLX caches (they hold a single
    /// replaceable backend rather than an accumulating cache).
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    pub fn evict_idle_backends(&self) -> (usize, u64) {
        let mut entries = 0usize;
        let mut bytes = 0u64;
        for (n, b) in [
            self.mlx_backends.evict_idle(),
            self.flux_cache.evict_idle(),
            self.ltx_cache.evict_idle(),
            self.kokoro_cache.evict_idle(),
        ] {
            entries += n;
            bytes = bytes.saturating_add(b);
        }
        (entries, bytes)
    }

    /// No-op on non-macOS — there are no accumulating backend caches.
    #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
    pub fn evict_idle_backends(&self) -> (usize, u64) {
        (0, 0)
    }

    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    fn supports_native_mlx(schema: &ModelSchema) -> bool {
        matches!(schema.family.as_str(), "qwen3" | "qwen2.5-vl" | "qwen2-vl")
    }

    fn routing_registry_snapshot(&self) -> UnifiedRegistry {
        let mut registry = self.unified_registry.clone();
        // Availability is a live credential property, not provider-catalog
        // discovery. Refresh the fixed registry snapshot for every list,
        // route, and request so pasted/OAuth key changes take effect without a
        // daemon restart while unregistered OpenRouter ids remain unknown.
        registry.refresh_availability();
        registry
    }

    /// Route a prompt using the adaptive router (new). Returns full decision context.
    pub async fn route_adaptive(&self, prompt: &str) -> AdaptiveRoutingDecision {
        self.route_adaptive_with_intent(prompt, None).await
    }

    /// Like [`route_adaptive`](Self::route_adaptive) but honors a caller
    /// [`IntentHint`](crate::intent::IntentHint) — notably `exclude_models`
    /// for adversarial-reviewer separation: "route me any capable model
    /// that is NOT the one that just did the work" (car#358). An excluded id
    /// is never chosen while any non-excluded capable model exists —
    /// including via the preferred-model override (skipped when it names an
    /// excluded model) and the cold-start fallbacks. The exclusion is soft:
    /// if excluding leaves nothing routable, an excluded model may still be
    /// returned as a last resort (a same-model review beats no review).
    pub async fn route_adaptive_with_intent(
        &self,
        prompt: &str,
        intent: Option<crate::intent::IntentHint>,
    ) -> AdaptiveRoutingDecision {
        let routing_registry = self.routing_registry_snapshot();
        if let Some(model) = self.preferred_model_for_capability(ModelCapability::Generate) {
            let overridden_is_excluded = intent
                .as_ref()
                .map(|h| h.exclude_models.iter().any(|e| e.as_str() == model))
                .unwrap_or(false);
            if !overridden_is_excluded {
                let ctx_len = routing_registry
                    .get(model)
                    .or_else(|| routing_registry.find_by_name(model))
                    .map(|s| s.context_length)
                    .unwrap_or(0);
                return AdaptiveRoutingDecision {
                    model_id: model.to_string(),
                    model_name: model.to_string(),
                    task: InferenceTask::Generate,
                    complexity: TaskComplexity::assess(prompt),
                    reason: "preferred generation model override".into(),
                    strategy: RoutingStrategy::Explicit,
                    predicted_quality: 0.5,
                    fallbacks: vec![],
                    context_length: ctx_len,
                    needs_compaction: false,
                    candidates: vec![],
                };
            }
        }
        let tracker = self.outcome_tracker.read().await;
        match intent {
            Some(hint) => self
                .adaptive_router
                .route_with(crate::adaptive_router::RouteRequest {
                    intent: Some(&hint),
                    ..crate::adaptive_router::RouteRequest::new(prompt, &routing_registry, &tracker)
                }),
            None => self
                .adaptive_router
                .route(prompt, &routing_registry, &tracker),
        }
    }

    /// Route a prompt to the best model without executing (legacy compat).
    pub fn route(&self, prompt: &str) -> RoutingDecision {
        self.router.route_generate(prompt, &self.registry)
    }

    /// Estimate token count for a request against a specific model's context window.
    /// Returns (estimated_input_tokens, context_window_tokens, fits).
    ///
    /// Multimodal content blocks (image/video/audio, in `images` or in
    /// `messages` history) contribute provider-calibrated estimates via
    /// [`media_tokens`] — a minute of video is ~15.8K input tokens at
    /// Gemini's documented rate, not zero — and the multi-turn
    /// `messages` history's *text* is counted too (chars/4), not just
    /// its media. This feeds the adaptive router's window-fit /
    /// `needs_compaction` signal.
    pub fn estimated_tokens(
        &self,
        req: &GenerateRequest,
        model_id: Option<&str>,
    ) -> (usize, usize, bool) {
        let prompt_tokens = remote::estimate_tokens(&req.prompt);
        let context_tokens = req
            .context
            .as_ref()
            .map(|c| remote::estimate_tokens(c))
            .unwrap_or(0);
        let tools_tokens = req
            .tools
            .as_ref()
            .map(|t| remote::estimate_tokens(&serde_json::to_string(t).unwrap_or_default()))
            .unwrap_or(0);
        let media_tokens = media_tokens::request_media_and_history_tokens(
            req.images.as_deref(),
            req.messages.as_deref(),
        );
        let total_input = prompt_tokens + context_tokens + tools_tokens + media_tokens;

        // Build the registry snapshot ONLY when there is an id to look up
        // (car-releases#75). A snapshot runs `refresh_availability`, which
        // re-reads every distinct provider credential — on macOS, keychain
        // queries. All three in-crate callers pass `model_id: None`, so this
        // was doing that entire pass and then discarding the result: the
        // `and_then` short-circuits on None and `context_window` is 0 either
        // way. On the delegated path that was a second full refresh per
        // request, stacked on the one `generate_tracked_inner` already did.
        let context_window = match model_id {
            Some(id) => {
                let routing_registry = self.routing_registry_snapshot();
                routing_registry
                    .get(id)
                    .or_else(|| routing_registry.find_by_name(id))
                    .map(|s| s.context_length)
                    .unwrap_or(0)
            }
            None => 0,
        };

        let fits = context_window == 0 || (total_input + req.params.max_tokens) <= context_window;
        (total_input, context_window, fits)
    }

    /// Normalize caller-supplied cache estimates to the prompt footprint the
    /// router is pricing. Cache reads and writes are mutually exclusive token
    /// buckets in [`CostModel::estimated_usd`], so their sum must never exceed
    /// the total estimated input. Zero stays zero: CAR does not infer a cache
    /// hit/write merely because protocol-level cache controls are enabled.
    fn routing_cache_estimates(req: &GenerateRequest, estimated_input: usize) -> (usize, usize) {
        let read = req
            .params
            .estimated_cache_read_input_tokens
            .min(estimated_input);
        let write = req
            .params
            .estimated_cache_write_input_tokens
            .min(estimated_input.saturating_sub(read));
        (read, write)
    }

    /// The model's context window in tokens, or 0 if the id is unknown
    /// (unregistered). Public so a multi-turn driver (e.g. the assistant
    /// loop) can bound its running message history to the window *before*
    /// it overflows — an overflowed history pushes the model to its context
    /// limit and can truncate the original task provider-side.
    pub fn model_context_window(&self, model_id: &str) -> usize {
        let routing_registry = self.routing_registry_snapshot();
        routing_registry
            .get(model_id)
            .or_else(|| routing_registry.find_by_name(model_id))
            .map(|s| s.context_length)
            .unwrap_or(0)
    }

    /// Generate text with full tracking (tool_calls, usage, trace_id,
    /// latency, TTFT), plus Qwen3 hybrid-thinking recovery.
    ///
    /// Qwen3 (and other hybrid-thinking models) default to reasoning ON.
    /// With a small `max_tokens` budget the model can spend the entire
    /// budget inside an unclosed `<think>` block, so the strip pass returns
    /// empty text — `infer(prompt, model, 16)` then silently yields "" while
    /// a non-thinking model answers fine (car-releases#60, #62).
    ///
    /// When the caller left `thinking` on `Auto` (didn't explicitly opt into
    /// reasoning) and nothing usable came back, retry once with reasoning
    /// suppressed so the caller gets a direct answer — matching the CLI's
    /// `--thinking off` default, but for every FFI/daemon path. Either way,
    /// record *why* via `stop_reason` so an empty result is never silent.
    pub async fn generate_tracked(
        &self,
        req: GenerateRequest,
    ) -> Result<InferenceResult, InferenceError> {
        let recover = matches!(req.params.thinking, ThinkingMode::Auto);
        let mut result = self.generate_tracked_inner(req.clone()).await?;

        if recover && result.text.trim().is_empty() && result.tool_calls.is_empty() {
            result.stop_reason = Some("thinking_truncated".to_string());
            let mut retry = req;
            retry.params.thinking = ThinkingMode::Off;
            if let Ok(mut recovered) = self.generate_tracked_inner(retry).await {
                if !recovered.text.trim().is_empty() || !recovered.tool_calls.is_empty() {
                    recovered.stop_reason = Some("thinking_recovered".to_string());
                    return Ok(recovered);
                }
            }
        }

        Ok(result)
    }

    #[instrument(
        name = "inference.generate",
        skip_all,
        fields(
            model = tracing::field::Empty,
            max_tokens = req.params.max_tokens,
            prompt_tokens = tracing::field::Empty,
            completion_tokens = tracing::field::Empty,
            latency_ms = tracing::field::Empty,
        )
    )]
    async fn generate_tracked_inner(
        &self,
        req: GenerateRequest,
    ) -> Result<InferenceResult, InferenceError> {
        let start = Instant::now();
        let routing_registry = self.routing_registry_snapshot();
        if let Some(requested) = req.model.as_deref() {
            if routing_registry
                .get(requested)
                .or_else(|| routing_registry.find_by_name(requested))
                .is_none()
            {
                return Err(InferenceError::ModelNotFound(requested.to_string()));
            }
        }

        // Route using adaptive router (context-aware)
        let (estimated_input, _, _) = self.estimated_tokens(&req, None);
        // Full context footprint = input + the reserved output budget. The
        // router's fit / needs_compaction check compares this against each
        // model's context_length. Passing input ALONE (as it used to) let a
        // prompt that fits but leaves no room for `max_tokens` of output route
        // without a compaction signal, then overflow mid-generation. Matches
        // the engine's own `estimated_tokens` fit formula (input + max_tokens).
        // `estimated_input` is kept separately for token accounting below.
        let estimated_footprint = estimated_input.saturating_add(req.params.max_tokens);
        let (estimated_cache_read, estimated_cache_write) =
            Self::routing_cache_estimates(&req, estimated_input);
        let tracker_read = self.outcome_tracker.read().await;
        let has_tools = Self::request_has_tools(&req);
        let has_vision = Self::request_needs_vision(&req);
        let preferred_model = self
            .preferred_model_for_capability(ModelCapability::Generate)
            .map(str::to_string);
        let decision = match req
            .model
            .clone()
            .or_else(|| self.lane_pin_for(&req, &routing_registry))
            .or(preferred_model)
        {
            Some(m) => {
                let ctx_len = routing_registry
                    .get(&m)
                    .or_else(|| routing_registry.find_by_name(&m))
                    .map(|s| s.context_length)
                    .unwrap_or(0);
                AdaptiveRoutingDecision {
                    model_id: m.clone(),
                    model_name: m.clone(),
                    task: InferenceTask::Generate,
                    complexity: TaskComplexity::assess(&req.prompt),
                    reason: "explicit model".into(),
                    strategy: RoutingStrategy::Explicit,
                    predicted_quality: 0.5,
                    fallbacks: vec![],
                    context_length: ctx_len,
                    needs_compaction: ctx_len > 0 && estimated_footprint > ctx_len,
                    candidates: vec![],
                }
            }
            None => self
                .adaptive_router
                .route_with(crate::adaptive_router::RouteRequest {
                    estimated_total_tokens: estimated_footprint,
                    estimated_input_tokens: estimated_input,
                    estimated_output_tokens: req.params.max_tokens,
                    estimated_cache_read_tokens: estimated_cache_read,
                    estimated_cache_write_tokens: estimated_cache_write,
                    has_tools,
                    has_vision,
                    workload: req.params.workload,
                    intent: req.intent.as_ref(),
                    ..crate::adaptive_router::RouteRequest::new(
                        &req.prompt,
                        &routing_registry,
                        &tracker_read,
                    )
                }),
        };
        drop(tracker_read);

        if decision.needs_compaction {
            tracing::info!(
                model = %decision.model_name,
                prompt_tokens = estimated_input,
                context_window = decision.context_length,
                "prompt exceeds model context window — compaction or truncation needed"
            );
        }

        // NOTE: the outcome trace is opened per-candidate inside the fallback
        // loop below (`attempt_trace`), not once here. A single shared trace
        // mis-attributed a fallback success to the first model and let the
        // post-loop failure double-book the first candidate.
        debug!(
            model = %decision.model_name,
            strategy = ?decision.strategy,
            reason = %decision.reason,
            "adaptive-routed generate request"
        );

        // Auto-enable extended thinking for complex tasks when the model supports it
        // and the caller hasn't explicitly set budget_tokens.
        let mut req = req;

        // Default per-turn output budget from the resolved model when the
        // caller left it at the library default (4096). Prevents tool_use JSON
        // truncation runaways on long-horizon tasks (car-cli run_task).
        if req.params.max_tokens == crate::tasks::generate::DEFAULT_MAX_TOKENS {
            if let Some(cap) = routing_registry
                .get(&decision.model_id)
                .or_else(|| routing_registry.find_by_name(&decision.model_id))
                .map(|s| s.effective_max_output())
            {
                req.params.max_tokens = cap;
            }
        }

        // Auto-enable extended/interleaved thinking for reasoning-heavy AND
        // CODING turns on models that support it. Coding turns arrive as
        // InferenceTask::Code (the coder/bench send IntentHint{task:Code}); they
        // never classify as TaskComplexity::Complex, which is exactly why coding
        // had 0 thinking budget on every turn. Code gets a higher budget ("high"
        // effort) than a general Complex task ("medium"). (F1, audit 2026-07-06.)
        // Key the coding budget on the caller's EXPLICIT intent, NOT the keyword
        // classifier's decision.task (see `is_explicit_code_intent`).
        let is_code_intent = is_explicit_code_intent(req.intent.as_ref());
        let is_complex = matches!(decision.complexity, TaskComplexity::Complex);
        if req.params.budget_tokens == 0 && (is_code_intent || is_complex) {
            // Same id-then-name resolution as the max-tokens defaulting
            // above — a name-only route must not silently skip the
            // auto-budget.
            let supports_thinking = routing_registry
                .get(&decision.model_id)
                .or_else(|| routing_registry.find_by_name(&decision.model_id))
                .map(|s| {
                    s.supported_params
                        .contains(&schema::GenerateParam::ExtendedThinking)
                })
                .unwrap_or(false);
            if let Some(budget) =
                auto_thinking_budget(is_code_intent, is_complex, supports_thinking)
            {
                req.params.budget_tokens = budget;
                tracing::info!(
                    model = %decision.model_name,
                    budget,
                    code_intent = is_code_intent,
                    "auto-enabled extended thinking"
                );
            }
        }

        // Execute — dispatch to local or remote backend, with fallback on failure
        let mut models_to_try = vec![decision.model_id.clone()];
        models_to_try.extend(decision.fallbacks.iter().cloned());

        // Resilience last resort: append an installed on-device model to the
        // tail of the chain when nothing already in it is local. An explicitly
        // requested / substituted model (e.g. the assistant's `parslee/advisor`)
        // ships with an EMPTY fallback list, so a single cloud failure — an
        // expired Parslee credential, a 401, an offline network — otherwise
        // errors out with "remaining=0" even on a machine with a working local
        // GPU model. Degrading to on-device beats failing. Only added when the
        // chain is entirely remote; a local primary/fallback already covers it.
        //
        // EXCEPT under a hard pin (`strict_model`): a caller that pinned a
        // specific backbone (the coder's `--model`, an A/B arm) needs the pinned
        // model or a loud error — NOT a silent swap to a weaker local model,
        // which manufactures fake results (a mid-run Parslee outage once
        // degraded a gpt-5.5 coder A/B to local Qwen and fabricated losses).
        let chain_has_local = models_to_try.iter().any(|m| {
            routing_registry
                .get(m)
                .or_else(|| routing_registry.find_by_name(m))
                .map(|s| s.is_local())
                .unwrap_or(false)
        });
        if should_append_local_last_resort(chain_has_local, req.params.strict_model) {
            // Tool-aware: for a tools-bearing turn, only a tool-capable local
            // model can serve it (a text-only one is dropped by the ToolUse
            // guard below), so require that capability before appending.
            if let Some(local) = self.first_installed_local_model(has_tools) {
                tracing::info!(
                    local_model = %local,
                    needs_tools = has_tools,
                    "appended on-device model as last-resort fallback (chain was remote-only)"
                );
                models_to_try.push(local);
            }
        } else if !chain_has_local && req.params.strict_model {
            tracing::info!(
                model = %decision.model_id,
                "strict_model set — not degrading to on-device; a remote failure will surface as an error"
            );
        }

        let mut last_error = None;

        // Pop-front queue (not `for .. in &models_to_try`) so the I4
        // failover below can promote a cross-provider fallback to the
        // front when the primary fails with a transient provider error.
        // A queue keeps the body's pre-existing `continue`s safe — the
        // candidate is already popped, so `continue` moves on instead of
        // retrying the same candidate forever (linus review, critical 1).
        let mut candidate_queue: std::collections::VecDeque<String> =
            models_to_try.iter().cloned().collect();
        let mut is_primary_attempt = true;
        while let Some(candidate_owned) = candidate_queue.pop_front() {
            let was_primary = is_primary_attempt;
            is_primary_attempt = false;
            let candidate_id = &candidate_owned;
            // `mut` is needed on the aarch64-macos cfg branch below;
            // other targets don't rebind.
            #[allow(unused_mut)]
            let mut schema = routing_registry
                .get(candidate_id)
                .or_else(|| routing_registry.find_by_name(candidate_id))
                .cloned();

            // On Apple Silicon, redirect GGUF/Candle models to their MLX
            // equivalents. The adaptive router now pre-resolves this before
            // scoring (#333), so for router-proposed candidates this is a
            // no-op; it remains load-bearing for the explicit-model path
            // (req.model set), which bypasses the router entirely.
            #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
            if let Some(ref s) = schema {
                if let Some(mlx_equiv) = routing_registry.resolve_mlx_equivalent(s) {
                    tracing::info!(
                        from = %s.id, to = %mlx_equiv.id,
                        "redirecting GGUF model to MLX equivalent on Apple Silicon"
                    );
                    schema = Some(mlx_equiv.clone());
                }
            }

            // Tool-capability guard (honest routing): a tools-bearing request
            // must land on a backend that actually parses tool calls. The
            // adaptive router filters on the ToolUse capability, but the
            // explicit-model path bypasses it and the cold-start "last resort"
            // can hand back a capability-lacking default. The in-process
            // mlx/candle generate path ignores `tools` entirely, so without
            // this guard the model would silently return prose for a tool
            // request. Skip this candidate (let fallback try a capable one); if
            // none qualifies, the loop surfaces UnsupportedMode below instead of
            // a misleading text answer.
            if has_tools
                && schema
                    .as_ref()
                    .map(|s| !s.has_capability(ModelCapability::ToolUse))
                    .unwrap_or(false)
            {
                let backend = schema
                    .as_ref()
                    .map(|s| if s.is_local() { "local" } else { "remote" })
                    .unwrap_or("unknown");
                tracing::warn!(
                    model = %candidate_id,
                    backend,
                    "tools requested but resolved model lacks ToolUse capability — skipping candidate"
                );
                last_error = Some(InferenceError::UnsupportedMode {
                    mode: "tool_use",
                    backend,
                    reason: "resolved model does not support structured tool calls; configure a tool-capable model (a remote API model, or run the vllm-mlx OpenAI-compatible server)",
                });
                continue;
            }

            let candidate_name = schema
                .as_ref()
                .map(|s| s.name.clone())
                .unwrap_or_else(|| candidate_id.clone());

            // Book outcomes against the *resolved canonical id* (`schema.id`,
            // post-MLX-redirect) — not the raw `candidate_id` the caller
            // passed. An explicit alias like `claude-sonnet-4-6` and the
            // catalog id `anthropic/claude-sonnet-4-6:latest` resolve to the
            // same schema, so recording the raw alias fragmented the health
            // surface into two "models" for one physical model (the
            // high-volume non-streaming path's half of the split). Mirrors
            // `generate_stream_raw`'s `resolved_model_id`, which already does
            // this for the streaming path. Falls back to the raw id only when
            // the model is unknown to the registry.
            let resolved_id = schema
                .as_ref()
                .map(|s| s.id.clone())
                .unwrap_or_else(|| candidate_id.clone());

            let is_remote = schema
                .as_ref()
                .map(|s| s.is_remote() || s.is_vllm_mlx())
                .unwrap_or(false);
            let is_delegated = schema.as_ref().map(|s| s.is_delegated()).unwrap_or(false);

            // Open one outcome trace per candidate attempt, attributed to THIS
            // model id. Success (record_complete) and failure (record_failure)
            // both resolve this same trace, so each attempt books exactly one
            // outcome against the right model.
            let attempt_trace = {
                let mut tracker = self.outcome_tracker.write().await;
                tracker.record_start(&resolved_id, decision.task, &decision.reason)
            };

            // Delegated dispatch (Parslee-ai/car-releases#24) — route
            // the synchronous path through the runner the same way
            // the streaming path does, then accumulate. Done before
            // the tools-context massaging because delegated models
            // own their own prompt construction.
            if is_delegated {
                let runner = match runner::current_inference_runner() {
                    Some(r) => r,
                    None => {
                        let msg = "model declares ModelSource::Delegated but no inference runner is registered";
                        self.outcome_tracker
                            .write()
                            .await
                            .record_failure(&attempt_trace, msg);
                        last_error = Some(InferenceError::InferenceFailed(msg.into()));
                        continue;
                    }
                };
                let (tx, mut rx) = tokio::sync::mpsc::channel::<stream::StreamEvent>(64);
                let emitter = runner::EventEmitter::new(tx);
                let runner_req = req.clone();
                let runner_handle =
                    tokio::spawn(async move { runner.run(runner_req, emitter).await });
                let mut accumulator = stream::StreamAccumulator::default();
                while let Some(evt) = rx.recv().await {
                    accumulator.push(&evt);
                }
                // Wait for the runner future so its return value is
                // observed. The accumulator is preferred when it has anything,
                // because a streaming runner's deltas are the authoritative
                // text; but a runner that emits NO events and answers with
                // `inference.runner.complete` alone is legitimate — a delegated
                // model returning a short non-streaming answer has nothing to
                // stream. Falling back to `RunnerResult` in that case is what
                // makes complete-alone terminal (Parslee-ai/car-releases#76).
                //
                // Discarding it was worse than losing the text. An empty result
                // trips the ThinkingMode::Auto truncation-recovery retry in
                // `generate_tracked`, which re-runs the WHOLE call — so the
                // runner is invoked a second time, wall time doubles, and
                // `latency_ms` (stamped in here, per leg) reports half of it.
                // `finish_with_usage`, not `finish` (#795). The accumulator
                // already captures `StreamEvent::Usage` — a runner that reports
                // counts had them collected and then thrown away one line before
                // they were needed, so every delegated call reported
                // `usage: null`. A consumer summing `total_tokens` read a silent
                // zero, which is worse than an error because it looks valid.
                //
                // Still `None` when the runner emits no usage event; that is
                // honest — CAR cannot know a foreign runner's tokenization — and
                // callers can fall back to their own estimator, which is what
                // `finish_with_usage` documents. The provider stop_reason comes
                // back on the same tuple and was being dropped too; it feeds
                // `InferenceResult::was_truncated`, which read as "not truncated"
                // for every delegated call.
                let (acc_text, acc_tool_calls, acc_usage, acc_stop_reason) =
                    accumulator.finish_with_usage();
                match runner_handle.await {
                    Ok(Ok(runner_result)) => {
                        let elapsed = start.elapsed().as_millis() as u64;
                        let acc_text = if acc_text.trim().is_empty() {
                            runner_result.text
                        } else {
                            acc_text
                        };
                        let acc_tool_calls = if acc_tool_calls.is_empty() {
                            runner_result.tool_calls
                        } else {
                            acc_tool_calls
                        };
                        // Estimate output tokens from the accumulated text so
                        // this delegated-runner path (NAPI/registered runners)
                        // records real token stats AND qualifies for the #312
                        // mechanical-success credit — a hardcoded 0 here failed
                        // the `output_tokens > 0` gate in outcome::sweep_pending
                        // and left these models stuck at the 0.5 EMA prior.
                        let est_out = acc_text.split_whitespace().count();
                        {
                            let mut tracker = self.outcome_tracker.write().await;
                            tracker.record_complete(
                                &attempt_trace,
                                elapsed,
                                estimated_input,
                                est_out,
                            );
                        }
                        return Ok(InferenceResult {
                            text: acc_text,
                            tool_calls: acc_tool_calls,
                            bounding_boxes: vec![],
                            trace_id: attempt_trace,
                            model_used: candidate_name,
                            latency_ms: elapsed,
                            time_to_first_token_ms: None,
                            // Whatever the runner reported (#795); None when it
                            // reported nothing, rather than a fabricated zero.
                            usage: acc_usage,
                            provider_output_items: vec![],
                            // Streaming thinking capture is a follow-up (stream.rs
                            // would accumulate thinking blocks); empty for now.
                            thinking: vec![],
                            stop_reason: acc_stop_reason,
                        });
                    }
                    Ok(Err(e)) => {
                        self.outcome_tracker
                            .write()
                            .await
                            .record_failure(&attempt_trace, &e.to_string());
                        last_error = Some(InferenceError::InferenceFailed(e.to_string()));
                        continue;
                    }
                    Err(join_err) => {
                        let msg = format!("runner task panicked: {join_err}");
                        self.outcome_tracker
                            .write()
                            .await
                            .record_failure(&attempt_trace, &msg);
                        last_error = Some(InferenceError::InferenceFailed(msg));
                        continue;
                    }
                }
            }

            let has_tools = Self::request_has_tools(&req);

            // Reinforce done tool instructions in context (fixes #10: empty done results)
            let context = if has_tools
                && req.tools.as_ref().is_some_and(|t| {
                    t.iter().any(|tool| {
                        tool.get("function")
                            .and_then(|f| f.get("name"))
                            .and_then(|n| n.as_str())
                            == Some("done")
                    })
                }) {
                let base = req.context.as_deref().unwrap_or("");
                Some(format!(
                    "{base}\n\nIMPORTANT: When calling the `done` tool, the `result` field MUST contain a DETAILED summary of everything you found and did. This is the ONLY output the user sees. Do NOT just say 'completed' — include specific findings, data, and conclusions."
                ))
            } else {
                req.context.clone()
            };

            // Only the remote path produces thinking blocks; capture them here
            // (the tuple below stays 5-element so no other arm changes) and read
            // them into the InferenceResult after the match. (F1.)
            let mut captured_thinking: Vec<crate::tasks::generate::ThinkingBlock> = Vec::new();
            let mut captured_provider_output_items: Vec<serde_json::Value> = Vec::new();
            let result = if is_remote {
                // vllm-mlx: start + health-wait its supervised server, then route
                // to the live port. A startup failure is a per-candidate failure,
                // recorded like any other so the router can fall through.
                let schema_val = match self.vllm_live_schema(schema.unwrap()).await {
                    Ok(s) => s,
                    Err(e) => {
                        self.outcome_tracker
                            .write()
                            .await
                            .record_failure(&attempt_trace, &e.to_string());
                        last_error = Some(e);
                        continue;
                    }
                };
                let _ctx_len = schema_val.context_length;
                // Strip unsupported params based on model schema (#15).
                // Use -1.0 as sentinel: remote backends omit temperature entirely.
                let temperature = if !schema_val.supported_params.is_empty()
                    && !schema_val
                        .supported_params
                        .contains(&crate::schema::GenerateParam::Temperature)
                {
                    -1.0
                } else {
                    req.params.temperature
                };

                // Always use the multi path so token usage is preserved on
                // both tool and non-tool requests. The bare `generate()` helper
                // in remote_backend wraps this same call but drops the usage
                // tuple, which breaks observability for plain text inference
                // (sc-3 in outcome 043).
                self.remote_backend
                    .generate_with_tools_multi(
                        &schema_val,
                        &req.prompt,
                        context.as_deref(),
                        temperature,
                        req.params.max_tokens,
                        req.tools.as_deref(),
                        req.images.as_deref(),
                        req.messages.as_deref(),
                        req.params.tool_choice.as_deref(),
                        req.params.parallel_tool_calls,
                        req.params.budget_tokens,
                        req.cache_control,
                        req.params.cache_ttl,
                        req.context_stable_prefix.as_deref(),
                        req.response_format.as_ref(),
                    )
                    .await
                    // Non-streaming remote APIs don't expose a
                    // first-token timestamp. Set TTFT=None and let
                    // streaming-aware callers measure it themselves
                    // via generate_tracked_stream. The 4th tuple element
                    // from generate_with_tools_multi is the provider stop_reason.
                    .map(|(t, c, thinking, provider_items, u, stop)| {
                        captured_thinking = thinking;
                        captured_provider_output_items = provider_items;
                        (t, c, u, None::<u64>, stop)
                    })
            } else if let Some(offload) = crate::offload::current_local_offload() {
                // On-device generation is isolated in a worker subprocess
                // (car-releases#74): a large local MLX/Candle generation can
                // abort the process from the Metal/MLX C++ side, below every
                // Rust `catch_unwind`, taking the shared daemon down. When an
                // offloader is installed we hand it the fully-resolved request
                // instead of running the Metal decode loop here; a native abort
                // then kills only the worker (this returns `Err`, the daemon
                // fails one RPC and stays up, the next call respawns the worker).
                // Pin the model to the resolved id so the worker doesn't re-run
                // adaptive routing and land on a different backend.
                let mut offload_req = req.clone();
                offload_req.model = Some(resolved_id.clone());
                match offload.generate(offload_req).await {
                    Ok(ir) => {
                        // The worker already ran the full tracked generation
                        // (tool-call parsing, thinking capture, stop reason);
                        // adapt its InferenceResult into this arm's tuple and
                        // let the shared post-dispatch code (outcome tracking,
                        // grounding parse, InferenceResult assembly with the
                        // daemon-side trace_id/latency) run unchanged.
                        captured_thinking = ir.thinking;
                        captured_provider_output_items = ir.provider_output_items;
                        Ok((
                            ir.text,
                            ir.tool_calls,
                            ir.usage,
                            ir.time_to_first_token_ms,
                            ir.stop_reason,
                        ))
                    }
                    Err(e) => Err(e),
                }
            } else {
                #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
                {
                    // On Apple Silicon, all local models must go through MLX.
                    // GGUF models were redirected to MLX equivalents above;
                    // if we still have a non-MLX model here, it has no MLX equivalent.
                    let schema_ref = schema
                        .as_ref()
                        .ok_or_else(|| InferenceError::ModelNotFound(candidate_id.clone()))?;

                    // Apple FoundationModels — on-device system model.
                    // Text generation, tool calling (capture-and-return
                    // bridge), and JsonSchema-constrained output are
                    // wired; vision/audio/video are rejected upstream
                    // (the public FM API is text-only) so the router
                    // falls through to a richer model rather than
                    // silently dropping capabilities.
                    if schema_ref.is_foundation_models() {
                        if Self::request_has_video(&req)
                            || Self::request_has_audio(&req)
                            || req.images.as_ref().is_some_and(|imgs| !imgs.is_empty())
                        {
                            Err(InferenceError::UnsupportedMode {
                                mode: "multimodal-content",
                                backend: "foundation-models",
                                reason: "the FoundationModels bridge currently exposes text-only \
                                     generation — route image/audio/video to a remote VL model",
                            })
                        } else if has_tools {
                            // One FM turn is either tool-enabled or
                            // schema-constrained, not both. Tools win;
                            // a JsonSchema response_format is dropped
                            // loudly (same policy as the Anthropic
                            // handler, which has no native field).
                            if req.response_format.is_some() {
                                tracing::warn!(
                                    "FoundationModels: response_format is ignored when tools \
                                     are present — one turn is either tool-enabled or \
                                     schema-constrained"
                                );
                            }
                            let prompt = req.prompt.clone();
                            let instructions = context.clone();
                            let tools_defs = req.tools.clone().unwrap_or_default();
                            let max_tokens = req.params.max_tokens as u32;
                            let temperature = req.params.temperature;
                            tokio::task::spawn_blocking(move || {
                                crate::backend::foundation_models::generate_with_tools(
                                    &prompt,
                                    instructions.as_deref(),
                                    &tools_defs,
                                    max_tokens,
                                    temperature as f32,
                                )
                            })
                            .await
                            .map_err(|e| {
                                InferenceError::InferenceFailed(format!(
                                    "FoundationModels task panicked: {e}"
                                ))
                            })
                            .and_then(|r| r)
                            .map(|(text, calls)| (text, calls, None, None, None))
                        } else if let Some(crate::tasks::generate::ResponseFormat::JsonSchema {
                            schema,
                            ..
                        }) = &req.response_format
                        {
                            // Native constrained decoding via
                            // DynamicGenerationSchema — the framework
                            // enforces the schema, not the prompt.
                            let prompt = req.prompt.clone();
                            let instructions = context.clone();
                            let schema_val = schema.clone();
                            let max_tokens = req.params.max_tokens as u32;
                            let temperature = req.params.temperature;
                            tokio::task::spawn_blocking(move || {
                                crate::backend::foundation_models::generate_structured(
                                    &prompt,
                                    instructions.as_deref(),
                                    &schema_val,
                                    max_tokens,
                                    temperature as f32,
                                )
                            })
                            .await
                            .map_err(|e| {
                                InferenceError::InferenceFailed(format!(
                                    "FoundationModels task panicked: {e}"
                                ))
                            })
                            .and_then(|r| r)
                            .map(|text| (text, vec![], None, None, None))
                        } else {
                            // Plain text turn. JsonObject (schema-free
                            // JSON mode) has no native FM equivalent —
                            // enforce by instruction, loudly.
                            let instructions = if matches!(
                                req.response_format,
                                Some(crate::tasks::generate::ResponseFormat::JsonObject)
                            ) {
                                tracing::warn!(
                                    "FoundationModels: JsonObject response_format has no native \
                                     constrained mode — enforcing via instruction injection"
                                );
                                let base = context.clone().unwrap_or_default();
                                Some(format!(
                                    "{base}\n\nRespond with a single valid JSON object and \
                                     nothing else."
                                ))
                            } else {
                                context.clone()
                            };
                            let prompt = req.prompt.clone();
                            let max_tokens = req.params.max_tokens as u32;
                            let temperature = req.params.temperature;
                            tokio::task::spawn_blocking(move || {
                                crate::backend::foundation_models::generate(
                                    &prompt,
                                    instructions.as_deref(),
                                    max_tokens,
                                    temperature as f32,
                                )
                            })
                            .await
                            .map_err(|e| {
                                InferenceError::InferenceFailed(format!(
                                    "FoundationModels task panicked: {e}"
                                ))
                            })
                            .and_then(|r| r)
                            .map(|text| (text, vec![], None, None, None))
                        }
                    } else if !schema_ref.is_mlx() {
                        Err(InferenceError::InferenceFailed(format!(
                            "model '{}' has no MLX equivalent; Candle backend disabled on Apple Silicon",
                            schema_ref.id
                        )))
                    } else if schema_ref.tags.iter().any(|t| t == "mlx-vlm-cli") {
                        // Schemas explicitly tagged for the
                        // mlx-vlm CLI shell-out path skip the
                        // wasteful native-MLX text-tower load
                        // entirely — `mlx_vlm.generate` loads its
                        // own weights from the HF cache and
                        // performs vision tokenization that the
                        // native backend does not. Falls through
                        // to the same error message as the
                        // post-load fallback when mlx-vlm is not
                        // installed, so the user-facing failure
                        // is consistent.
                        let has_images = req.images.as_ref().is_some_and(|imgs| !imgs.is_empty());
                        if !has_images {
                            return Err(InferenceError::UnsupportedMode {
                                mode: "text-only-on-mlx-vlm-id",
                                backend: "mlx-vlm-cli",
                                reason: "the `mlx-vlm/...` model IDs route exclusively \
                                     through the mlx-vlm CLI for image inference. \
                                     For text-only generation, route to a Qwen3 \
                                     text model (`mlx/qwen3-4b:4bit` etc.) — the \
                                     CLI shell-out has higher latency than the \
                                     in-process MLX text tower.",
                            });
                        }
                        let vlm_status = crate::backend::mlx_vlm_cli::runtime_status();
                        if !vlm_status.is_available() {
                            return Err(InferenceError::InferenceFailed(vlm_status.user_message()));
                        }
                        let repo = match &schema_ref.source {
                            crate::schema::ModelSource::Mlx { hf_repo, .. } => hf_repo.clone(),
                            _ => {
                                return Err(InferenceError::InferenceFailed(format!(
                                    "model '{}' is tagged mlx-vlm-cli but its \
                                     source isn't ModelSource::Mlx — registry bug",
                                    schema_ref.id
                                )));
                            }
                        };
                        let imgs = req.images.clone().unwrap_or_default();
                        let temp = req.params.temperature;
                        let max_t = req.params.max_tokens;
                        let prompt = req.prompt.clone();
                        let (text, cli_usage) = tokio::task::spawn_blocking(move || {
                            crate::backend::mlx_vlm_cli::generate(
                                &repo, &prompt, &imgs, temp, max_t,
                            )
                        })
                        .await
                        .map_err(|e| {
                            InferenceError::InferenceFailed(format!(
                                "mlx_vlm CLI task panicked: {e}"
                            ))
                        })??;
                        let bounding_boxes = parse_boxes(&text);
                        let latency_ms = start.elapsed().as_millis() as u64;
                        // mlx-vlm prints its own `Prompt:`/`Generation:` token
                        // counts and CAR used to discard them with the rest of
                        // the perf summary, hardcoding `usage: None`
                        // (Parslee-ai/car#795). They're worth recovering rather
                        // than estimating: the prompt count includes the image
                        // patches, which nothing on this side can reproduce —
                        // the vision tower lives in the Python process. Still
                        // `None` when the summary didn't parse; an absent count
                        // is honest, a zero is not.
                        let usage = cli_usage.map(|u| TokenUsage {
                            prompt_tokens: u.prompt_tokens,
                            completion_tokens: u.completion_tokens,
                            total_tokens: u.prompt_tokens + u.completion_tokens,
                            context_window: schema_ref.context_length as u64,
                            // Local in-process inference has no remote prompt cache.
                            ..Default::default()
                        });
                        {
                            // Real counts when the CLI reported them, else the
                            // word-count estimate — which still has to be
                            // non-zero, because a hardcoded 0 fails the #312
                            // mechanical-success gate in outcome::sweep_pending
                            // (same trap as the delegated-runner path above).
                            let (in_tokens, out_tokens) = match &usage {
                                Some(u) => (u.prompt_tokens as usize, u.completion_tokens as usize),
                                None => (estimated_input, text.split_whitespace().count()),
                            };
                            let mut tracker = self.outcome_tracker.write().await;
                            tracker.record_complete(
                                &attempt_trace,
                                latency_ms,
                                in_tokens,
                                out_tokens,
                            );
                        }
                        return Ok(InferenceResult {
                            text,
                            tool_calls: vec![],
                            bounding_boxes,
                            trace_id: attempt_trace,
                            model_used: schema_ref.id.clone(),
                            latency_ms,
                            time_to_first_token_ms: None,
                            usage,
                            provider_output_items: Vec::new(),
                            thinking: Vec::new(), // local model — no thinking blocks
                            stop_reason: None,
                        });
                    } else if !Self::supports_native_mlx(schema_ref) {
                        // A local MLX checkpoint the dedicated Qwen `MlxBackend`
                        // doesn't service (e.g. Gemma 4) routes through the
                        // polymorphic local-backend dispatch + shared decode
                        // loop. Text-only for now: reject multimodal content
                        // with a precise UnsupportedMode rather than silently
                        // dropping it.
                        if req.images.as_ref().is_some_and(|i| !i.is_empty())
                            || Self::request_has_video(&req)
                            || Self::request_has_audio(&req)
                        {
                            return Err(InferenceError::UnsupportedMode {
                                mode: "multimodal-content-block",
                                backend: "native-mlx-local",
                                reason: "this in-process MLX backend is text-only; route \
                                     image/video/audio understanding to a vLLM-MLX or remote \
                                     multimodal model",
                            });
                        }
                        // NB: do *not* pre-render with `render_for_local_backend`
                        // here. That helper flattens `messages`/`tools` into the
                        // Qwen3 wire format and clears the structured fields —
                        // correct for the native Qwen `MlxBackend`, fatal for a
                        // backend with its own chat template (Gemma 4 would then
                        // render a Qwen-formatted blob through the Gemma grammar
                        // and ramble). `generate_local` defers rendering to the
                        // backend's `render_prompt`, which sees the intact
                        // structured request (its own template, or the Qwen
                        // `render_chat_prompt` default for template-less backends).
                        self.generate_local(req.clone(), &schema_ref.id).await
                    } else {
                        // Load the backend first so we can ask it what
                        // it's actually able to execute. VL checkpoints
                        // currently load as text-only towers (see the
                        // `language_model.` prefix strip in backend/mlx.rs);
                        // the backend's `supports_capability(Vision)`
                        // returns false until GH #58 wires the vision
                        // tower. A registry-level capability claim is
                        // an aspiration for routing; the backend answer
                        // is the execution contract.
                        let handle = self.ensure_mlx_backend(schema_ref).await?;
                        // Native MLX path doesn't have a video
                        // tokenization pipeline yet. Reject video
                        // content blocks up front with a precise
                        // UnsupportedMode so callers don't silently
                        // get a text-only reply.
                        if Self::request_has_video(&req) {
                            return Err(InferenceError::UnsupportedMode {
                                mode: "video-content-block",
                                backend: "native-mlx-qwen25vl",
                                reason: "Qwen2.5-VL video understanding is on the request surface \
                                     but the video-tokenization path (frame sampling + merger) \
                                     is not yet wired; route to a remote VL provider for now",
                            });
                        }
                        if Self::request_has_audio(&req) {
                            return Err(InferenceError::UnsupportedMode {
                                mode: "audio-content-block",
                                backend: "native-mlx-qwen25vl",
                                reason: "audio understanding is on the request surface (Gemma 4 \
                                     E2B/E4B and Gemini accept it) but the native MLX path \
                                     for this model does not — route to Gemini or Gemma-4",
                            });
                        }
                        let has_images = req.images.as_ref().is_some_and(|imgs| !imgs.is_empty());
                        if has_images {
                            let can_do_vision = {
                                let guard = handle.lock().map_err(|_| {
                                    InferenceError::InferenceFailed(
                                        "MLX backend mutex poisoned".into(),
                                    )
                                })?;
                                guard.supports_capability(crate::schema::ModelCapability::Vision)
                            };
                            if !can_do_vision {
                                // The `mlx-vlm-cli`-tagged route handled
                                // above is the primary fix for #115; if
                                // we landed here it means the schema is
                                // a non-tagged `ModelSource::Mlx` (e.g.
                                // a user-registered custom model that
                                // doesn't advertise the CLI route). The
                                // error message points them at the
                                // tagged catalog IDs rather than
                                // claiming nothing local works.
                                return Err(InferenceError::UnsupportedMode {
                                    mode: "image-content-block",
                                    backend: "native-mlx-text",
                                    reason: "this MLX backend is a plain Qwen3 text tower. \
                                         For local image inference, route to \
                                         `mlx-vlm/qwen3-vl-2b:bf16` or another `mlx-vlm/...` \
                                         catalog ID so CAR shells out to `mlx_vlm.generate`. \
                                         Alternatives: a local vLLM-MLX VLM server, or a \
                                         remote VL model. (#115)",
                                });
                            }
                        }
                        self.generate_mlx(render_for_local_backend(req.clone()), &schema_ref.id)
                            .await
                            .map(|(text, usage, ttft, stop)| (text, vec![], usage, ttft, stop))
                    }
                }

                #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
                {
                    match self.ensure_backend(&candidate_name).await {
                        Ok(()) => {
                            let mut write = self.backend.write().await;
                            let backend = write.as_mut().unwrap();
                            // Real counts, not `None`. The candle loop knows
                            // both — post-truncation prompt length and the
                            // number of tokens it sampled — and discarding them
                            // made every local call on this platform report
                            // `usage: null` (Parslee-ai/car#795).
                            let ctx_window = backend.context_length().unwrap_or(0) as u64;
                            tasks::generate::generate(
                                backend,
                                render_for_local_backend(req.clone()),
                            )
                            .await
                            .map(
                                |(text, ttft, prompt_tokens, completion_tokens)| {
                                    let usage = TokenUsage {
                                        prompt_tokens: prompt_tokens as u64,
                                        completion_tokens: completion_tokens as u64,
                                        total_tokens: (prompt_tokens + completion_tokens) as u64,
                                        context_window: ctx_window,
                                        // Local in-process inference has no remote
                                        // prompt cache.
                                        ..Default::default()
                                    };
                                    (text, vec![], Some(usage), ttft, None)
                                },
                            )
                        }
                        Err(e) => Err(e),
                    }
                }
            };

            match result {
                Ok((text, mut tool_calls, usage, time_to_first_token_ms, stop_reason)) => {
                    // In-process (MLX/candle) backends return prose only — they
                    // don't parse structured tool calls. When the caller asked
                    // for tools, recover any <tool_call> blocks the local model
                    // emitted in the text into structured tool_calls (and strip
                    // them from the visible text). Remote/delegated backends
                    // already populate tool_calls, so this is a no-op for them.
                    let text = if !is_remote
                        && !is_delegated
                        && req.tools.is_some()
                        && tool_calls.is_empty()
                    {
                        let (clean, parsed) = tasks::generate::parse_tool_calls(&text);
                        tool_calls = parsed;
                        clean
                    } else {
                        text
                    };
                    let latency_ms = start.elapsed().as_millis() as u64;
                    let estimated_tokens = usage
                        .as_ref()
                        .map(|u| u.completion_tokens as usize)
                        .unwrap_or_else(|| text.split_whitespace().count());
                    // Prefer the provider's real prompt-token count (remote);
                    // fall back to the router's pre-call estimate (local, where
                    // usage is None). Previously hardcoded 0, which zeroed
                    // total_input_tokens and corrupted quality_per_1k_tokens.
                    let input_tokens = usage
                        .as_ref()
                        .map(|u| u.prompt_tokens as usize)
                        .unwrap_or(estimated_input);
                    // Prompt-cache split (Anthropic): `input_tokens` above is
                    // the uncached prefix only, so carry the cached buckets
                    // separately for cache-aware cost accounting. Both 0 for
                    // providers/paths without prompt caching.
                    let (cache_read, cache_creation) = usage
                        .as_ref()
                        .map(|u| {
                            (
                                u.cache_read_input_tokens as usize,
                                u.cache_creation_input_tokens as usize,
                            )
                        })
                        .unwrap_or((0, 0));
                    {
                        let mut tracker = self.outcome_tracker.write().await;
                        tracker.record_complete_cached(
                            &attempt_trace,
                            latency_ms,
                            input_tokens,
                            estimated_tokens,
                            cache_read,
                            cache_creation,
                        );
                    }
                    // Circuit breaker: record success (#25). Key on the
                    // canonical `resolved_id` — the breaker's read side
                    // (`allow_request(&m.id)`, adaptive_router.rs) checks the
                    // canonical schema id, so booking under the raw alias here
                    // would mean the breaker never trips for aliased calls.
                    if let Ok(mut cb) = self.adaptive_router.circuit_breakers.lock() {
                        cb.record_success(&resolved_id);
                    }
                    // Auto-persist profiles after each successful call
                    self.auto_save_outcomes().await;

                    // Record deferred span fields now that we have the result
                    let span = tracing::Span::current();
                    span.record("model", candidate_name.as_str());
                    span.record("latency_ms", latency_ms);
                    if let Some(ttft) = time_to_first_token_ms {
                        span.record("ttft_ms", ttft);
                    }
                    if let Some(ref u) = usage {
                        span.record("prompt_tokens", u.prompt_tokens);
                        span.record("completion_tokens", u.completion_tokens);
                    }

                    // Parse Qwen2.5-VL grounding spans out of the
                    // text output. Empty vec on anything else.
                    let bounding_boxes = tasks::grounding::parse_boxes(&text);
                    return Ok(InferenceResult {
                        text,
                        tool_calls,
                        bounding_boxes,
                        trace_id: attempt_trace,
                        model_used: candidate_name,
                        latency_ms,
                        time_to_first_token_ms,
                        usage,
                        provider_output_items: captured_provider_output_items,
                        thinking: captured_thinking,
                        stop_reason,
                    });
                }
                Err(e) => {
                    tracing::warn!(
                        model = %candidate_name,
                        error = %e,
                        remaining = candidate_queue.len(),
                        "model failed, trying next fallback immediately"
                    );
                    // Resolve every attempt exactly once. A deterministic
                    // request/provider capability mismatch is visible in the
                    // receipt ledger but must not degrade the model's generic
                    // health or answer-quality profile for unrelated traffic.
                    {
                        let mut tracker = self.outcome_tracker.write().await;
                        match &e {
                            InferenceError::UnsupportedMode { .. } => {
                                tracker.record_capability_rejection(&attempt_trace, &e.to_string())
                            }
                            // Someone's billing is not the model's fault
                            // (Parslee-ai/car#650).
                            InferenceError::ProviderAccount { .. } => {
                                tracker.record_account_rejection(&attempt_trace, &e.to_string())
                            }
                            // Nor is someone's missing gateway provisioning.
                            // Booked as an unattributed receipt for the same
                            // reason: the request is real and belongs in the
                            // ledger, but the model never ran and must not wear
                            // the failure (Parslee-ai/car#786).
                            InferenceError::GatewayUnconfigured { .. } => {
                                tracker.record_account_rejection(&attempt_trace, &e.to_string())
                            }
                            // A filter in front of the model refused the
                            // request. Recorded as a capability rejection —
                            // the same bucket as a deterministic mode mismatch,
                            // because that is what it is: this request will be
                            // refused every time, while the model stays healthy
                            // for everything else (Parslee-ai/car#796).
                            InferenceError::ContentRefused { .. } => {
                                tracker.record_capability_rejection(&attempt_trace, &e.to_string())
                            }
                            _ => tracker.record_failure(&attempt_trace, &e.to_string()),
                        }
                    }
                    // Circuit breaker: record failure (#25).
                    // 4xx errors (client errors) use longer cooldown since they indicate
                    // permanent incompatibility (wrong endpoint, unsupported param).
                    // EXCEPTION: `UnsupportedMode` is a deterministic capability
                    // mismatch (e.g. JsonSchema on Anthropic, video on a text-only
                    // provider) — see `error_counts_against_circuit_breaker`. The
                    // The outcome trace above is recorded as a capability
                    // rejection (not a profile failure), and the fallback loop
                    // still advances to a model that supports the mode.
                    if error_counts_against_circuit_breaker(&e) {
                        let err_str = e.to_string();
                        let is_client_error =
                            err_str.contains("API returned 4") && !err_str.contains("429");
                        if let Ok(mut cb) = self.adaptive_router.circuit_breakers.lock() {
                            // Canonical `resolved_id` — see the success path above.
                            cb.record_failure(&resolved_id);
                            // For persistent 4xx errors, lower the threshold by
                            // recording an extra failure to trip faster
                            if is_client_error {
                                cb.record_failure(&resolved_id);
                            }
                        }
                    }
                    // Reset backend so next model can load
                    #[cfg(not(all(
                        target_os = "macos",
                        target_arch = "aarch64",
                        not(car_skip_mlx)
                    )))]
                    {
                        let mut write = self.backend.write().await;
                        *write = None;
                    }
                    // I4 provider failover: when the PRIMARY fails with a
                    // transient provider-side error (5xx/429/timeout), a
                    // same-provider sibling is likely down too — promote
                    // the first CROSS-provider fallback to the queue
                    // front. Permanent errors (auth, bad request) keep the
                    // router's original order: they're caller-shaped, not
                    // provider-shaped.
                    // An account rejection is true of every model on that
                    // account, so trying the rest of its candidates NEXT just
                    // replays the identical 401/402 — latency for nothing, and
                    // a pile of duplicate receipts. Send them to the back of
                    // the chain so another provider is tried first
                    // (Parslee-ai/car#650).
                    //
                    // Demoted, not dropped: soft like every other constraint on
                    // this path. Two credentials can share one provider label
                    // (per-model `api_key_env`, a multi-key pool), so a hard
                    // drop could remove the chain's last working option.
                    // An unconfigured gateway namespace is stronger than an
                    // account rejection: the deployment has NO upstream to
                    // proxy to, so every remaining alias under the prefix is
                    // certain to fail, not merely likely. Drop them outright
                    // rather than demoting — demotion is the right hedge for
                    // ProviderAccount, where two credentials can share one
                    // provider label and the chain's last working option might
                    // sit behind it, but here the prefix IS the condition's
                    // scope and nothing under it can differ (car#786).
                    if let InferenceError::GatewayUnconfigured { namespace, .. } = &e {
                        let before = candidate_queue.len();
                        candidate_queue.retain(|id| !id.starts_with(namespace.as_str()));
                        let dropped = before - candidate_queue.len();
                        if dropped > 0 {
                            tracing::info!(
                                %namespace,
                                dropped,
                                remaining = candidate_queue.len(),
                                "gateway has no upstream for this namespace; dropping its \
                                 remaining candidates instead of replaying the same rejection"
                            );
                        }
                    }
                    if let InferenceError::ProviderAccount { provider, .. } = &e {
                        // Resolve the provider from the REGISTRY, not a string
                        // split on the id — same reasoning as the cross-provider
                        // promotion below (linus review #4 on I4).
                        let mut rest: Vec<String> = candidate_queue.iter().cloned().collect();
                        let demoted = routing_ext::demote_provider(provider, &mut rest, |id| {
                            routing_registry
                                .get(id)
                                .or_else(|| routing_registry.find_by_name(id))
                                .map(|s| s.provider.clone())
                        });
                        candidate_queue = rest.into();
                        if demoted > 0 {
                            tracing::info!(
                                %provider,
                                demoted,
                                remaining = candidate_queue.len(),
                                "account-level rejection; deferring this provider's \
                                 remaining candidates to the end of the chain"
                            );
                        }
                    }
                    if was_primary && !candidate_queue.is_empty() {
                        let err_str = e.to_string();
                        // Recover the HTTP status the remote backend baked
                        // into "API returned <status>: <body>" so a body
                        // that merely QUOTES a transient phrase (e.g. a 400
                        // whose message says "timeout param invalid") can't
                        // classify as transient (linus review #3). Typed
                        // error plumbing is the named follow-up.
                        let status = parse_api_returned_status(&err_str);
                        if routing_ext::is_provider_transient(status, &err_str) {
                            // Resolve provider from the REGISTRY, not a
                            // string split — slashless aliases would make
                            // every candidate look cross-provider (linus
                            // review #4).
                            let provider_of = |id: &str| {
                                routing_registry
                                    .get(id)
                                    .or_else(|| routing_registry.find_by_name(id))
                                    .map(|s| s.provider.clone())
                            };
                            let primary = provider_of(candidate_id).unwrap_or_default();
                            let queue_vec: Vec<String> = candidate_queue.iter().cloned().collect();
                            if let Some(cross) =
                                routing_ext::first_cross_provider(&primary, &queue_vec, provider_of)
                            {
                                let cross = cross.to_string();
                                if let Some(pos) = candidate_queue.iter().position(|m| *m == cross)
                                {
                                    if pos > 0 {
                                        if let Some(m) = candidate_queue.remove(pos) {
                                            tracing::info!(
                                                promoted = %m,
                                                "transient provider error on primary; promoting cross-provider fallback"
                                            );
                                            candidate_queue.push_front(m);
                                        }
                                    }
                                }
                            }
                        }
                    }
                    last_error = Some(e);
                }
            }
        }

        // All models failed.
        let underlying = last_error.unwrap_or(InferenceError::InferenceFailed(
            "no models available".into(),
        ));

        // A fresh install with no Parslee auth exhausts the entire
        // fallback chain and surfaces an opaque "no credential for
        // proprietary provider 'parslee'" with zero recovery guidance —
        // the #231 §7.1 DX failure (acute on Windows, which has no MLX
        // path and no bundled local model). When the exhaustion is a
        // missing-backend/credential case, wrap it with the two
        // concrete recovery paths; other errors pass through unchanged
        // so a genuine 500/timeout/429 isn't buried under setup advice.
        // Classify the exhaustion: a never-signed-in / no-backend case gets the
        // setup hint; an expired-credential (auth-rejection) exhaustion gets the
        // re-authenticate hint — otherwise a 401 from a lapsed Parslee session
        // surfaced verbatim as a raw HTTP status with no guidance. A genuine
        // 500/timeout/429 matches neither and passes through unchanged.
        let underlying_str = underlying.to_string();
        let e = match no_backend_recovery_hint(&underlying_str)
            .or_else(|| auth_expired_recovery_hint(&underlying_str))
        {
            Some(msg) => InferenceError::InferenceFailed(msg),
            None => underlying,
        };
        // Each candidate already recorded its own failure against its
        // per-attempt trace inside the loop, so there is nothing to record
        // here — doing so was the source of the fail_count > total_calls skew.
        self.auto_save_outcomes().await;
        Err(e)
    }

    /// Internal producer for [`generate_tracked_stream`]: resolves the model,
    /// spawns the backend generation task, and returns the resolved model id
    /// alongside the event receiver. The public wrapper taps this stream to
    /// record an outcome when it finishes.
    async fn generate_stream_raw(
        &self,
        req: GenerateRequest,
    ) -> Result<(String, tokio::sync::mpsc::Receiver<stream::StreamEvent>), InferenceError> {
        let routing_registry = self.routing_registry_snapshot();
        if let Some(requested) = req.model.as_deref() {
            if routing_registry
                .get(requested)
                .or_else(|| routing_registry.find_by_name(requested))
                .is_none()
            {
                return Err(InferenceError::ModelNotFound(requested.to_string()));
            }
        }
        let has_tools = Self::request_has_tools(&req);
        let has_vision = Self::request_needs_vision(&req);
        let (estimated_input, _, _) = self.estimated_tokens(&req, None);
        let estimated_footprint = estimated_input.saturating_add(req.params.max_tokens);
        let (estimated_cache_read, estimated_cache_write) =
            Self::routing_cache_estimates(&req, estimated_input);
        let preferred_model = self
            .preferred_model_for_capability(ModelCapability::Generate)
            .map(str::to_string);
        let decision = match req
            .model
            .clone()
            .or_else(|| self.lane_pin_for(&req, &routing_registry))
            .or(preferred_model)
        {
            Some(m) => {
                let ctx_len = routing_registry
                    .get(&m)
                    .or_else(|| routing_registry.find_by_name(&m))
                    .map(|s| s.context_length)
                    .unwrap_or(0);
                AdaptiveRoutingDecision {
                    model_id: m.clone(),
                    model_name: m,
                    task: InferenceTask::Generate,
                    complexity: TaskComplexity::assess(&req.prompt),
                    reason: "explicit model".into(),
                    strategy: RoutingStrategy::Explicit,
                    predicted_quality: 0.5,
                    fallbacks: vec![],
                    context_length: ctx_len,
                    needs_compaction: false,
                    candidates: vec![],
                }
            }
            None => {
                let tracker_read = self.outcome_tracker.read().await;
                self.adaptive_router
                    .route_with(crate::adaptive_router::RouteRequest {
                        estimated_total_tokens: estimated_footprint,
                        estimated_input_tokens: estimated_input,
                        estimated_output_tokens: req.params.max_tokens,
                        estimated_cache_read_tokens: estimated_cache_read,
                        estimated_cache_write_tokens: estimated_cache_write,
                        has_tools,
                        has_vision,
                        workload: req.params.workload,
                        intent: req.intent.as_ref(),
                        ..crate::adaptive_router::RouteRequest::new(
                            &req.prompt,
                            &routing_registry,
                            &tracker_read,
                        )
                    })
            }
        };

        // `mut` is needed on the aarch64-macos cfg branch below;
        // other targets don't rebind.
        #[allow(unused_mut)]
        let mut schema = routing_registry
            .get(&decision.model_id)
            .or_else(|| routing_registry.find_by_name(&decision.model_id))
            .cloned();

        // On Apple Silicon, redirect GGUF/Candle models to their MLX equivalents.
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        if let Some(ref s) = schema {
            if let Some(mlx_equiv) = routing_registry.resolve_mlx_equivalent(s) {
                tracing::info!(
                    from = %s.id, to = %mlx_equiv.id,
                    "redirecting GGUF model to MLX equivalent on Apple Silicon (stream)"
                );
                schema = Some(mlx_equiv.clone());
            }
        }

        // Tool-capability guard (honest routing) — streaming parity with the
        // non-streaming generate path. A tools-bearing request that resolved to
        // a backend which can't parse tool calls (e.g. the in-process
        // mlx/candle path) would otherwise stream prose and silently drop the
        // tools. Fail clearly instead.
        if has_tools
            && schema
                .as_ref()
                .map(|s| !s.has_capability(ModelCapability::ToolUse))
                .unwrap_or(false)
        {
            let backend = schema
                .as_ref()
                .map(|s| if s.is_local() { "local" } else { "remote" })
                .unwrap_or("unknown");
            return Err(InferenceError::UnsupportedMode {
                mode: "tool_use",
                backend,
                reason: "resolved model does not support structured tool calls; configure a tool-capable model (a remote API model, or run the vllm-mlx OpenAI-compatible server)",
            });
        }

        // Identity the tap records the outcome against (post-MLX-redirect).
        let resolved_model_id = schema
            .as_ref()
            .map(|s| s.id.clone())
            .unwrap_or_else(|| decision.model_id.clone());

        // Default per-turn output budget from the resolved model when the
        // caller left it at the library default (4096) — mirrors the
        // non-streaming generate_tracked path so streamed long-horizon tool_use
        // JSON isn't truncated at 4096 either.
        let mut req = req;
        if req.params.max_tokens == crate::tasks::generate::DEFAULT_MAX_TOKENS {
            if let Some(cap) = schema.as_ref().map(|s| s.effective_max_output()) {
                req.params.max_tokens = cap;
            }
        }

        let is_remote = schema
            .as_ref()
            .map(|s| s.is_remote() || s.is_vllm_mlx())
            .unwrap_or(false);

        let is_delegated = schema.as_ref().map(|s| s.is_delegated()).unwrap_or(false);

        if is_delegated {
            // Closes Parslee-ai/car-releases#24. The host owns the
            // wire format; CAR just plays back the events the runner
            // emits and stays in the policy/replay path.
            let runner = runner::current_inference_runner().ok_or_else(|| {
                InferenceError::InferenceFailed(
                    "model declares ModelSource::Delegated but no inference runner is registered \
                     (call set_inference_runner / registerInferenceRunner / register_inference_runner)"
                        .into(),
                )
            })?;
            let (tx, rx) = tokio::sync::mpsc::channel::<stream::StreamEvent>(64);
            let emitter = runner::EventEmitter::new(tx);
            let request = req.clone();
            tokio::spawn(async move {
                if let Err(e) = runner.run(request, emitter).await {
                    tracing::warn!(error = %e, "delegated inference runner failed");
                }
            });
            return Ok((resolved_model_id, rx));
        }

        // On-device streaming isolated in a worker subprocess (car-releases#74)
        // — the streaming mirror of the non-streaming offload in
        // `generate_tracked_inner`. Only local models route here; a remote HTTP
        // stream can't abort the process, so it stays in-daemon. A mid-stream
        // worker death drops the sender, which the caller sees as a normal
        // stream end (the accumulator surfaces whatever arrived).
        if !is_remote {
            if let Some(offload) = crate::offload::current_local_offload() {
                let mut offload_req = req.clone();
                offload_req.model = Some(resolved_model_id.clone());
                let rx = offload.stream(offload_req).await?;
                return Ok((resolved_model_id, rx));
            }
        }

        if is_remote {
            let mut candidates = vec![schema.unwrap()];
            let mut local_fallback_ids = Vec::new();
            for fallback_id in &decision.fallbacks {
                if let Some(fallback) = routing_registry
                    .get(fallback_id)
                    .or_else(|| routing_registry.find_by_name(fallback_id))
                {
                    if (fallback.is_remote() || fallback.is_vllm_mlx())
                        && (!has_tools || fallback.has_capability(ModelCapability::ToolUse))
                        && (!has_vision || fallback.has_capability(ModelCapability::Vision))
                        && !candidates
                            .iter()
                            .any(|candidate| candidate.id == fallback.id)
                    {
                        candidates.push(fallback.clone());
                    } else if fallback.is_local()
                        && !fallback.is_vllm_mlx()
                        && (!has_tools || fallback.has_capability(ModelCapability::ToolUse))
                        && (!has_vision || fallback.has_capability(ModelCapability::Vision))
                    {
                        local_fallback_ids.push(fallback.id.clone());
                    }
                }
            }
            let mut last_error = None;
            for candidate in candidates {
                // For a vllm-mlx model this starts (and health-waits) its
                // supervised server and rewrites the endpoint to the live port.
                let candidate = match self.vllm_live_schema(candidate).await {
                    Ok(candidate) => candidate,
                    Err(error) => {
                        last_error = Some(error);
                        continue;
                    }
                };
                self.remote_backend.register_model_keys(&candidate).await;

                let spend_guard = self
                    .spend_limits
                    .read()
                    .unwrap()
                    .as_ref()
                    .and_then(|limits| limits.per_request_usd)
                    .map(|budget| {
                        let mut prompt_tokens =
                            routing_ext::MidStreamSpendGuard::estimate_tokens(&req.prompt)
                                + req
                                    .context
                                    .as_deref()
                                    .map(routing_ext::MidStreamSpendGuard::estimate_tokens)
                                    .unwrap_or(0);
                        prompt_tokens += media_tokens::request_media_and_history_tokens(
                            req.images.as_deref(),
                            req.messages.as_deref(),
                        ) as u64;
                        if let Some(tools) = &req.tools {
                            prompt_tokens += routing_ext::MidStreamSpendGuard::estimate_tokens(
                                &serde_json::to_string(tools).unwrap_or_default(),
                            );
                        }
                        let prices = candidate.cost.prices_for(prompt_tokens as usize);
                        let input_price = prices
                            .input_per_mtok
                            .map(|c| c / 1_000_000.0)
                            .unwrap_or(0.0);
                        let output_price = prices
                            .output_per_mtok
                            .map(|c| c / 1_000_000.0)
                            .unwrap_or(0.0);
                        routing_ext::MidStreamSpendGuard::new(
                            Some(budget),
                            prompt_tokens as f64 * input_price,
                            input_price,
                            output_price,
                        )
                    });

                match self
                    .remote_backend
                    .generate_stream(
                        &candidate,
                        &req.prompt,
                        req.messages.as_deref(),
                        req.context.as_deref(),
                        req.params.temperature,
                        req.params.max_tokens,
                        req.tools.as_deref(),
                        req.images.as_deref(),
                        req.params.tool_choice.as_deref(),
                        req.params.parallel_tool_calls,
                        req.response_format.as_ref(),
                        spend_guard,
                    )
                    .await
                {
                    Ok(receiver) => return Ok((candidate.id, receiver)),
                    Err(error) => {
                        tracing::warn!(
                            model = %candidate.id,
                            %error,
                            "remote stream setup failed; trying routed fallback"
                        );
                        last_error = Some(error);
                    }
                }
            }

            // Remote-primary streaming must retain compatible local candidates
            // and re-enter the ordinary dispatcher for them. That preserves
            // offload/FoundationModels/native behavior instead of duplicating
            // a partial local backend path in this branch.
            if !req.params.strict_model {
                if let Some(local) = self.first_installed_local_model(has_tools) {
                    let schema = routing_registry
                        .get(&local)
                        .or_else(|| routing_registry.find_by_name(&local));
                    let supports_request = schema.is_some_and(|schema| {
                        !has_vision || schema.has_capability(ModelCapability::Vision)
                    });
                    if supports_request
                        && !local_fallback_ids.iter().any(|candidate| {
                            routing_registry
                                .get(candidate)
                                .or_else(|| routing_registry.find_by_name(candidate))
                                .is_some_and(|schema| schema.id == local || schema.name == local)
                        })
                    {
                        local_fallback_ids.push(local);
                    }
                }
                for local_id in local_fallback_ids {
                    let mut fallback_req = req.clone();
                    fallback_req.model = Some(local_id);
                    fallback_req.params.strict_model = true;
                    match Box::pin(self.generate_stream_raw(fallback_req)).await {
                        Ok(stream) => return Ok(stream),
                        Err(error) => {
                            tracing::warn!(%error, "local streaming fallback failed");
                            last_error = Some(error);
                        }
                    }
                }
            }

            Err(last_error.unwrap_or_else(|| {
                InferenceError::InferenceFailed(
                    "no compatible remote streaming model available".to_string(),
                )
            }))
        } else {
            let schema =
                schema.ok_or_else(|| InferenceError::ModelNotFound(decision.model_id.clone()))?;
            let (tx, rx) = tokio::sync::mpsc::channel(64);

            // FoundationModels streaming dispatch — reachable on the
            // Apple-aarch64 targets where build.rs compiles the shim
            // (macOS, iOS device, iOS simulator on Apple Silicon).
            // Split out from the MLX block below because MLX is
            // macOS-only — `mlx-rs` can't cross-compile for iOS.
            #[cfg(any(
                all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)),
                all(target_os = "ios", target_arch = "aarch64")
            ))]
            {
                if schema.is_foundation_models() {
                    // Same text-only boundary as the non-streaming FM
                    // branch: multimodal blocks error out instead of
                    // being silently dropped by the text-only bridge.
                    if Self::request_has_video(&req)
                        || Self::request_has_audio(&req)
                        || req.images.as_ref().is_some_and(|imgs| !imgs.is_empty())
                    {
                        return Err(InferenceError::UnsupportedMode {
                            mode: "multimodal-content",
                            backend: "foundation-models",
                            reason: "the FoundationModels bridge currently exposes text-only \
                                 generation — route image/audio/video to a remote VL model",
                        });
                    }
                    // Tool-enabled streaming: FM tool capture is a
                    // blocking round-trip (the framework invokes the
                    // capture tool mid-turn), so run the blocking
                    // bridge and emit the outcome as one TextDelta +
                    // Done{tool_calls} — same events, coarser grain.
                    if let Some(tools_defs) = req.tools.clone().filter(|t| !t.is_empty()) {
                        let prompt = req.prompt.clone();
                        let instructions = req.context.clone();
                        let max_tokens = req.params.max_tokens as u32;
                        let temperature = req.params.temperature;
                        tokio::task::spawn_blocking(move || {
                            match crate::backend::foundation_models::generate_with_tools(
                                &prompt,
                                instructions.as_deref(),
                                &tools_defs,
                                max_tokens,
                                temperature as f32,
                            ) {
                                Ok((text, tool_calls)) => {
                                    if !text.is_empty() {
                                        let _ = tx.blocking_send(stream::StreamEvent::TextDelta(
                                            text.clone(),
                                        ));
                                    }
                                    let _ = tx.blocking_send(stream::StreamEvent::Done {
                                        text,
                                        tool_calls,
                                    });
                                }
                                Err(e) => {
                                    // Match the MLX streaming error
                                    // convention: log and drop the
                                    // sender so the channel closes
                                    // without a Done event.
                                    tracing::warn!(
                                        error = %e,
                                        "FoundationModels tool-enabled stream failed"
                                    );
                                }
                            }
                        });
                        return Ok((resolved_model_id, rx));
                    }
                    let prompt = req.prompt.clone();
                    let instructions = req.context.clone();
                    let max_tokens = req.params.max_tokens as u32;
                    let temperature = req.params.temperature;
                    let tx_clone = tx.clone();
                    tokio::task::spawn_blocking(move || {
                        // Share the accumulator between the streaming
                        // callback and the post-stream Done event so
                        // the FoundationModels path matches Candle/MLX
                        // shape — `Done.text` is the full assembled
                        // generation, not an empty sentinel that
                        // forces consumers to reassemble.
                        let accum = std::sync::Arc::new(std::sync::Mutex::new(String::new()));
                        let accum_cb = accum.clone();
                        let cb = crate::backend::foundation_models::StreamCallback::new(
                            move |delta: &str| {
                                if let Ok(mut g) = accum_cb.lock() {
                                    g.push_str(delta);
                                }
                                tx_clone
                                    .blocking_send(stream::StreamEvent::TextDelta(
                                        delta.to_string(),
                                    ))
                                    .is_ok()
                            },
                        );
                        let result = crate::backend::foundation_models::stream(
                            &prompt,
                            instructions.as_deref(),
                            max_tokens,
                            temperature as f32,
                            cb,
                        );
                        let final_text = accum.lock().map(|g| g.clone()).unwrap_or_default();
                        let _ = tx.blocking_send(stream::StreamEvent::Done {
                            text: final_text,
                            tool_calls: vec![],
                        });
                        result
                    });
                    return Ok((resolved_model_id, rx));
                }
            }

            // MLX streaming — macOS-aarch64 only.
            #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
            {
                // On Apple Silicon macOS, all local models must go
                // through MLX.
                if !schema.is_mlx() {
                    return Err(InferenceError::InferenceFailed(format!(
                        "model '{}' has no MLX equivalent; Candle backend disabled on Apple Silicon",
                        schema.id
                    )));
                }
                let backend = self.ensure_mlx_backend(&schema).await?;
                let model_id = schema.id.clone();
                let cache = Arc::clone(&self.mlx_backends);
                // Serialize on the shared Metal device (see `mlx_device_lock`)
                // before the blocking eval, mirroring the media paths: acquire the
                // owned guard here and move it INTO the blocking closure so it is
                // held for the whole stream and survives RPC-deadline abandonment.
                // Without it a concurrent embed/other-model MLX eval (e.g. memory
                // consolidation) can wedge the one Metal device.
                let device_guard = Self::mlx_device_lock().lock_owned().await;
                // MLX ops are blocking (GPU-bound) and `MutexGuard<MlxBackend>`
                // isn't `Send`, so run the whole generation on a blocking
                // worker. `tx.blocking_send` bridges tokens back to the
                // async stream consumer without holding the guard across
                // an `.await`.
                tokio::task::spawn_blocking(move || {
                    let _device_guard = device_guard;
                    let _ = Self::stream_local_mlx(backend, cache, model_id, req, tx);
                });
                Ok((resolved_model_id, rx))
            }

            #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
            {
                self.ensure_backend(&schema.name).await?;
                let backend = self.backend.clone();
                tokio::spawn(async move {
                    let _ = Self::stream_local_candle(backend, req, tx).await;
                });
                Ok((resolved_model_id, rx))
            }
        }
    }

    /// Stream a generation and record an outcome when it finishes.
    ///
    /// Wraps [`generate_stream_raw`] with a forwarding "tap" task: it
    /// accumulates the event stream (via [`stream::StreamAccumulator`]),
    /// forwards every event to the caller unchanged, and on completion books a
    /// success/failure against the model's profile — the same outcome telemetry
    /// the non-streaming `generate_tracked` path records. Without this, every
    /// streamed inference (voice/realtime, the daemon's `infer` stream) was
    /// invisible to model-health scoring. Cancellation propagates: if the
    /// caller drops the returned receiver, the tap stops forwarding, drops the
    /// producer receiver, and the backend task observes the closed channel.
    ///
    /// Returns a [`TrackedStream`] carrying the resolved model + this call's
    /// `trace_id` alongside the event receiver. The trace_id is known up front
    /// (minted by `record_start` before the first token), so a caller can score
    /// the finished turn against the same trace the tap will resolve — the
    /// streaming counterpart of the non-streaming path's `InferenceResult`
    /// `{trace_id, model_used}`, which the conversation-outcome signal needs.
    ///
    /// The `events` receiver yields `StreamEvent` variants (`TextDelta`,
    /// `ToolCallStart`, `ToolCallDelta`, `Usage`, `StopReason`,
    /// `ProviderOutputItem`, `Error`, `Done`); use a
    /// [`stream::StreamAccumulator`] to collect them into a final result. Local
    /// backends (MLX, Candle) emit true incremental `TextDelta`s per token,
    /// enabling token-by-token UI, overlapping TTS, and early cancellation. The
    /// channel buffers 64 events so burst tokens don't block generation.
    ///
    /// ## Example: voice app integration
    ///
    /// ```rust,ignore
    /// let mut handle = engine.generate_tracked_stream(req).await?;
    /// let mut text_buf = String::new();
    /// while let Some(event) = handle.events.recv().await {
    ///     match event {
    ///         StreamEvent::TextDelta(delta) => {
    ///             text_buf.push_str(&delta);
    ///             // Feed text_buf to TTS when a sentence boundary is reached
    ///         }
    ///         StreamEvent::Done { text, .. } => break,
    ///         _ => {}
    ///     }
    /// }
    /// // handle.trace_id / handle.model_used identify the turn for scoring.
    /// ```
    pub async fn generate_tracked_stream(
        &self,
        req: GenerateRequest,
    ) -> Result<TrackedStream, InferenceError> {
        // Pre-call input estimate (used when the provider reports no usage,
        // e.g. local backends). Computed before `req` is moved into the raw
        // producer.
        let (estimated_input, _, _) = self.estimated_tokens(&req, None);
        let start = Instant::now();

        // Setup/routing errors (unknown model, no runner) propagate unchanged
        // and are not booked as model failures — same as the non-streaming
        // path, which only records once a candidate actually runs.
        let (model_id, mut producer_rx) = self.generate_stream_raw(req).await?;

        let trace = {
            let mut t = self.outcome_tracker.write().await;
            t.record_start(&model_id, InferenceTask::Generate, "stream")
        };
        // Surface trace_id + model to the caller. Cloned before the tap task
        // moves `trace` in to resolve the outcome on completion; `model_id` is
        // unused after `record_start`, so it moves straight into the handle.
        let trace_for_return = trace.clone();

        let (out_tx, out_rx) = tokio::sync::mpsc::channel::<stream::StreamEvent>(64);
        let tracker = Arc::clone(&self.outcome_tracker);
        tokio::spawn(async move {
            let mut acc = stream::StreamAccumulator::default();
            let mut stream_error: Option<String> = None;
            let mut saw_done = false;
            let mut receiver_abandoned = false;
            while let Some(evt) = producer_rx.recv().await {
                if let stream::StreamEvent::Error(message) = &evt {
                    stream_error = Some(message.clone());
                }
                if matches!(evt, stream::StreamEvent::Done { .. }) {
                    saw_done = true;
                }
                acc.push(&evt);
                if out_tx.send(evt).await.is_err() {
                    receiver_abandoned = true;
                    break;
                }
            }
            if stream_error.is_none() && !saw_done && !receiver_abandoned {
                let error = "stream ended without positive provider completion".to_string();
                stream_error = Some(error.clone());
                let _ = out_tx.send(stream::StreamEvent::Error(error)).await;
            } else if stream_error.is_none() && receiver_abandoned {
                stream_error = Some("stream receiver was abandoned before completion".to_string());
            }
            let (text, tool_calls, usage, _stop) = acc.finish_with_usage();
            let latency_ms = start.elapsed().as_millis() as u64;
            let input_tokens = usage
                .as_ref()
                .map(|u| u.prompt_tokens as usize)
                .unwrap_or(estimated_input);
            // Output token count: provider usage if present, else word count.
            // A tool-only response (no text) is still a success, so floor the
            // count at 1 when tool calls were produced — record_complete gates
            // its mechanical-success credit on output_tokens > 0.
            let mut output_tokens = usage
                .as_ref()
                .map(|u| u.completion_tokens as usize)
                .unwrap_or_else(|| text.split_whitespace().count());
            if output_tokens == 0 && !tool_calls.is_empty() {
                output_tokens = 1;
            }
            // Cache split — currently always 0 on the streaming path because the
            // accumulator does not yet decode Anthropic `message_start` cache
            // deltas; threaded anyway so this path prices correctly the moment
            // it does.
            let (cache_read, cache_creation) = usage
                .as_ref()
                .map(|u| {
                    (
                        u.cache_read_input_tokens as usize,
                        u.cache_creation_input_tokens as usize,
                    )
                })
                .unwrap_or((0, 0));
            let mut t = tracker.write().await;
            if let Some(error) = stream_error {
                t.record_failure(&trace, &error);
            } else {
                t.record_complete_cached(
                    &trace,
                    latency_ms,
                    input_tokens,
                    output_tokens,
                    cache_read,
                    cache_creation,
                );
            }
        });

        Ok(TrackedStream {
            model_used: model_id,
            trace_id: trace_for_return,
            events: out_rx,
        })
    }

    #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
    async fn stream_local_candle(
        backend_lock: Arc<RwLock<Option<CandleBackend>>>,
        req: GenerateRequest,
        tx: tokio::sync::mpsc::Sender<stream::StreamEvent>,
    ) -> Result<(), InferenceError> {
        let mut write = backend_lock.write().await;
        let backend = write
            .as_mut()
            .ok_or_else(|| InferenceError::InferenceFailed("backend not initialized".into()))?;
        backend.clear_kv_cache();

        let formatted = tasks::generate::render_chat_prompt(&req);
        let tokens = backend.encode(&formatted)?;
        let eos = backend.eos_token_id();
        let eos_alt = backend.token_id("<|im_end|>");
        let params = &req.params;

        if tokens.is_empty() {
            let _ = tx
                .send(stream::StreamEvent::Done {
                    text: String::new(),
                    tool_calls: vec![],
                })
                .await;
            return Ok(());
        }

        let max_ctx = backend.context_length().unwrap_or(32768);
        let headroom = params.max_tokens.min(max_ctx / 4);
        let max_prompt = max_ctx.saturating_sub(headroom);
        let tokens = if tokens.len() > max_prompt {
            tokens[tokens.len() - max_prompt..].to_vec()
        } else {
            tokens
        };

        let mut generated = Vec::new();
        let logits = backend.forward(&tokens, 0)?;
        let mut next_token = tasks::generate::sample_token(&logits, params)?;

        for _ in 0..params.max_tokens {
            if (eos == Some(next_token)) || (eos_alt == Some(next_token)) {
                break;
            }

            generated.push(next_token);
            let delta = backend.decode(&[next_token])?;
            if !delta.is_empty()
                && tx
                    .send(stream::StreamEvent::TextDelta(delta))
                    .await
                    .is_err()
            {
                return Ok(());
            }

            if !params.stop.is_empty() {
                let text_so_far = backend.decode(&generated)?;
                if params.stop.iter().any(|s| text_so_far.contains(s)) {
                    break;
                }
            }

            let pos = tokens.len() + generated.len() - 1;
            let logits = backend.forward(&[next_token], pos)?;
            next_token = tasks::generate::sample_token(&logits, params)?;
        }

        let trimmed = tasks::generate::truncate_at_stop(&backend.decode(&generated)?, &params.stop);
        let text = tasks::generate::strip_thinking(&trimmed, params.thinking);
        // Real counts, same as the MLX stream and the non-streaming candle
        // path — see the note in `stream_local_mlx` (Parslee-ai/car#795).
        // `tokens.len()` is post-truncation: what the model actually saw.
        let _ = tx
            .send(stream::StreamEvent::Usage {
                input_tokens: tokens.len() as u64,
                output_tokens: generated.len() as u64,
                cache_read_input_tokens: 0,
                cache_creation_input_tokens: 0,
            })
            .await;
        let _ = tx
            .send(stream::StreamEvent::Done {
                text,
                tool_calls: vec![],
            })
            .await;
        Ok(())
    }

    /// Blocking streaming generator — runs on a `spawn_blocking` worker
    /// so the sync MLX mutex guard isn't held across an async `.await`.
    /// Uses `tx.blocking_send` to push tokens back to the caller.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    fn stream_local_mlx(
        handle: backend_cache::CachedBackend<backend::MlxBackend>,
        cache: Arc<backend_cache::BackendCache<backend::MlxBackend>>,
        model_id: String,
        req: GenerateRequest,
        tx: tokio::sync::mpsc::Sender<stream::StreamEvent>,
    ) -> Result<(), InferenceError> {
        let mut guard = handle.lock().map_err(|_| {
            InferenceError::InferenceFailed(format!("MLX backend mutex poisoned for {model_id}"))
        })?;
        let backend: &mut backend::MlxBackend = &mut guard;
        backend.clear_kv_cache();

        let formatted = tasks::generate::render_chat_prompt(&req);
        let tokens = backend.encode(&formatted)?;
        let eos = backend.eos_token_id();
        let eos_alt = backend.token_id("<|im_end|>");
        let params = &req.params;

        if tokens.is_empty() {
            let _ = tx.blocking_send(stream::StreamEvent::Done {
                text: String::new(),
                tool_calls: vec![],
            });
            return Ok(());
        }

        let max_ctx = backend.context_length();
        let headroom = params.max_tokens.min(max_ctx / 4);
        let max_prompt = max_ctx.saturating_sub(headroom);
        let tokens = if tokens.len() > max_prompt {
            tokens[tokens.len() - max_prompt..].to_vec()
        } else {
            tokens
        };

        let mut generated = Vec::new();
        // Wrap MLX forward calls to catch panics. On panic, drop this
        // backend from the cache — its KV cache may be in an
        // indeterminate state and subsequent callers would inherit it.
        // Outstanding handles continue to work until their Arc drops.
        let logits = match Self::catch_mlx("stream prefill", || backend.forward(&tokens, 0)) {
            Ok(v) => v,
            Err(e) => {
                cache.invalidate(&model_id);
                return Err(e);
            }
        };
        let mut next_token = Self::sample_from_logits(&logits, params)?;

        for _ in 0..params.max_tokens {
            if (eos == Some(next_token)) || (eos_alt == Some(next_token)) {
                break;
            }

            generated.push(next_token);
            let delta = backend.decode(&[next_token])?;
            if !delta.is_empty()
                && tx
                    .blocking_send(stream::StreamEvent::TextDelta(delta))
                    .is_err()
            {
                return Ok(());
            }

            if !params.stop.is_empty() {
                let text_so_far = backend.decode(&generated)?;
                if params.stop.iter().any(|s| text_so_far.contains(s)) {
                    break;
                }
            }

            let pos = tokens.len() + generated.len() - 1;
            let logits =
                match Self::catch_mlx("stream forward", || backend.forward(&[next_token], pos)) {
                    Ok(v) => v,
                    Err(e) => {
                        cache.invalidate(&model_id);
                        return Err(e);
                    }
                };
            next_token = Self::sample_from_logits(&logits, params)?;
        }

        let trimmed = tasks::generate::truncate_at_stop(&backend.decode(&generated)?, &params.stop);
        let text = tasks::generate::strip_thinking(&trimmed, params.thinking);
        // Report the counts this loop already knows, the way a remote provider
        // reports its own (Parslee-ai/car#795). Without this event the
        // accumulator's `saw_usage` stays false and EVERY streamed local
        // generation ends with `usage: null`, while the non-streaming MLX path
        // right next to it returns real numbers — so the same model reported
        // tokens or didn't purely on whether the caller streamed.
        // `tokens.len()` is post-truncation: what the model actually saw.
        let _ = tx.blocking_send(stream::StreamEvent::Usage {
            input_tokens: tokens.len() as u64,
            output_tokens: generated.len() as u64,
            // In-process inference has no remote prompt cache.
            cache_read_input_tokens: 0,
            cache_creation_input_tokens: 0,
        });
        let _ = tx.blocking_send(stream::StreamEvent::Done {
            text,
            tool_calls: vec![],
        });
        Ok(())
    }

    /// Route a prompt using the adaptive router without executing inference.
    pub async fn route_context_snapshot(
        &self,
        prompt: &str,
        workload: RoutingWorkload,
        has_tools: bool,
        has_vision: bool,
    ) -> AdaptiveRoutingDecision {
        let routing_registry = self.routing_registry_snapshot();
        let tracker = self.outcome_tracker.read().await;
        self.adaptive_router.route_context_aware(
            prompt,
            0,
            &routing_registry,
            &tracker,
            has_tools,
            has_vision,
            workload,
        )
    }

    /// Generate text from a prompt (legacy API, no outcome tracking).
    /// When `req.model` is None, uses intelligent routing based on prompt complexity.
    pub async fn generate(&self, req: GenerateRequest) -> Result<String, InferenceError> {
        Ok(self.generate_tracked(req).await?.text)
    }

    /// Encode `text` via the named model's tokenizer. Returns raw token IDs
    /// without any chat-template wrapping or BOS-prepending — pair with
    /// [`Self::detokenize`] for the round-trip property
    /// `detokenize(model, tokenize(model, s)) == s` for any UTF-8 `s`.
    ///
    /// Only local models have a tokenizer the runtime can call directly
    /// (Candle/GGUF on Linux/Windows, MLX on Apple Silicon). For remote
    /// models the call returns
    /// [`InferenceError::UnsupportedMode`] — provider tokenizer endpoints
    /// vary too widely to be portable here, and bundling tiktoken-style
    /// tables would lock the registry to a fixed set of providers.
    pub async fn tokenize(&self, model: &str, text: &str) -> Result<Vec<u32>, InferenceError> {
        self.assert_local_for_tokenize(model)?;

        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        {
            let schema = self
                .unified_registry
                .get(model)
                .or_else(|| self.unified_registry.find_by_name(model))
                .ok_or_else(|| InferenceError::ModelNotFound(model.to_string()))?
                .clone();
            let handle = self.ensure_mlx_backend(&schema).await?;
            let guard = handle.lock().map_err(|_| {
                InferenceError::InferenceFailed(format!(
                    "MLX backend mutex poisoned for {}",
                    schema.id
                ))
            })?;
            guard.tokenize_raw(text)
        }

        #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
        {
            self.ensure_backend(model).await?;
            let read = self.backend.read().await;
            let backend = read.as_ref().ok_or_else(|| {
                InferenceError::InferenceFailed(
                    "candle backend missing after ensure_backend".to_string(),
                )
            })?;
            backend.tokenize_raw(text)
        }
    }

    /// Inverse of [`Self::tokenize`]: decode token IDs back to text.
    pub async fn detokenize(&self, model: &str, tokens: &[u32]) -> Result<String, InferenceError> {
        self.assert_local_for_tokenize(model)?;

        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        {
            let schema = self
                .unified_registry
                .get(model)
                .or_else(|| self.unified_registry.find_by_name(model))
                .ok_or_else(|| InferenceError::ModelNotFound(model.to_string()))?
                .clone();
            let handle = self.ensure_mlx_backend(&schema).await?;
            let guard = handle.lock().map_err(|_| {
                InferenceError::InferenceFailed(format!(
                    "MLX backend mutex poisoned for {}",
                    schema.id
                ))
            })?;
            guard.detokenize_raw(tokens)
        }

        #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
        {
            self.ensure_backend(model).await?;
            let read = self.backend.read().await;
            let backend = read.as_ref().ok_or_else(|| {
                InferenceError::InferenceFailed(
                    "candle backend missing after ensure_backend".to_string(),
                )
            })?;
            backend.detokenize_raw(tokens)
        }
    }

    /// Common pre-flight for [`Self::tokenize`] / [`Self::detokenize`]: bail
    /// early on remote models with the same `UnsupportedMode` taxonomy used
    /// elsewhere on the engine surface.
    fn assert_local_for_tokenize(&self, model: &str) -> Result<(), InferenceError> {
        if let Some(schema) = self
            .unified_registry
            .get(model)
            .or_else(|| self.unified_registry.find_by_name(model))
        {
            if !schema.is_local() {
                return Err(InferenceError::UnsupportedMode {
                    mode: "tokenize/detokenize",
                    backend: "remote",
                    reason: "remote provider tokenizer is not exposed by the runtime; \
                         use a local model (Qwen3 GGUF / MLX) for tokenizer-correctness checks",
                });
            }
        }
        // Unknown model name: let the load step surface ModelNotFound below.
        Ok(())
    }

    /// Wrap an MLX FFI call with catch_unwind to catch Rust panics at the boundary.
    /// NOTE: This catches Rust panics only, NOT C++ exceptions from Metal/MLX.
    /// True C++ exceptions will still abort the process — that requires an upstream
    /// fix in mlx-rs to catch C++ exceptions before they cross the FFI boundary.
    /// On panic, callers MUST remove the backend from the map — it is poisoned.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    fn catch_mlx<F, T>(context: &str, f: F) -> Result<T, InferenceError>
    where
        F: FnOnce() -> Result<T, InferenceError>,
    {
        std::panic::catch_unwind(std::panic::AssertUnwindSafe(f)).map_err(|e| {
            InferenceError::InferenceFailed(format!("MLX panicked during {context}: {e:?}"))
        })?
    }

    /// Architecture-neutral decode loop over any [`TextDecoder`] (macOS MLX
    /// backends — Qwen3, Gemma 4, …). Owns prompt
    /// encoding, context-window truncation, prefill, the sampling/stop loop,
    /// TTFT timing, and the FFI-boundary panic-catch — everything that used to
    /// be inlined per-backend in `generate_mlx`. The eos convention is the
    /// backend's (`eos_ids`), so this loop knows nothing about `<|im_end|>` or
    /// any other family's turn-enders. Cache invalidation on a caught panic is
    /// the caller's job (it owns the lock guard) — signaled via
    /// [`DriveError::BackendCorrupted`].
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    fn drive_generation(
        backend: &mut dyn backend::local::TextDecoder,
        prompt: &str,
        params: &GenerateParams,
    ) -> Result<backend::local::LocalGeneration, backend::local::DriveError> {
        use backend::local::{DriveError, LocalGeneration};

        let start = std::time::Instant::now();

        let tokens = backend.encode(prompt).map_err(DriveError::Recoverable)?;
        let eos_ids = backend.eos_ids();

        if tokens.is_empty() {
            backend.clear_kv_cache();
            return Ok(LocalGeneration {
                text: String::new(),
                ttft_ms: None,
                stop_reason: None,
                prompt_tokens: 0,
                completion_tokens: 0,
            });
        }

        // Truncate to context length, reserving headroom for the response.
        let max_ctx = backend.context_length();
        let headroom = params.max_tokens.min(max_ctx / 4);
        let max_prompt = max_ctx.saturating_sub(headroom);
        let tokens = if tokens.len() > max_prompt {
            tokens[tokens.len() - max_prompt..].to_vec()
        } else {
            tokens
        };

        let mut generated = Vec::new();

        // Reuse any cached matching prefix (prompt caching); prefill only the
        // new suffix. `begin_prompt` returns the position to start from; the
        // default (Qwen) clears and returns 0 (full re-prefill).
        let offset = backend.begin_prompt(&tokens);
        let logits = Self::catch_mlx("prefill", || backend.forward(&tokens[offset..], offset))
            .map_err(DriveError::BackendCorrupted)?;
        let mut next_token =
            Self::sample_from_logits(&logits, params).map_err(DriveError::Recoverable)?;
        let ttft_ms = Some(start.elapsed().as_millis() as u64);

        // Track why the loop ended: a natural EOS / stop-sequence finish vs.
        // exhausting the max_tokens budget (truncation).
        let mut natural_stop = false;
        for _ in 0..params.max_tokens {
            if eos_ids.contains(&next_token) {
                natural_stop = true;
                break;
            }

            generated.push(next_token);

            if !params.stop.is_empty() {
                let text_so_far = backend
                    .decode(&generated)
                    .map_err(DriveError::Recoverable)?;
                if params.stop.iter().any(|s| text_so_far.contains(s)) {
                    natural_stop = true;
                    break;
                }
            }

            let pos = tokens.len() + generated.len() - 1;
            let logits = Self::catch_mlx("forward", || backend.forward(&[next_token], pos))
                .map_err(DriveError::BackendCorrupted)?;
            next_token =
                Self::sample_from_logits(&logits, params).map_err(DriveError::Recoverable)?;
        }

        let decoded = backend
            .decode(&generated)
            .map_err(DriveError::Recoverable)?;
        let text = tasks::generate::truncate_at_stop(&decoded, &params.stop);
        let stop_reason = Some(if natural_stop { "stop" } else { "length" }.to_string());
        Ok(LocalGeneration {
            text: tasks::generate::strip_thinking(&text, params.thinking),
            ttft_ms,
            stop_reason,
            prompt_tokens: tokens.len(),
            completion_tokens: generated.len(),
        })
    }

    /// Generate text using the MLX backend.
    /// Mirrors the Candle generate loop but uses MlxBackend::forward which returns Vec<f32>.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    /// Returns `(text, time_to_first_token_ms, stop_reason)`. `stop_reason`
    /// is `Some("stop")` when generation ended at EOS or a stop sequence and
    /// `Some("length")` when it hit the `max_tokens` cap — the OpenAI spelling
    /// so [`InferenceResult::was_truncated`] works for local models too
    /// (previously local always reported `None`, so a max_tokens cutoff was
    /// indistinguishable from a clean finish and the truncation-retry path
    /// never fired locally).
    async fn generate_mlx(
        &self,
        req: GenerateRequest,
        model_id: &str,
    ) -> Result<(String, Option<TokenUsage>, Option<u64>, Option<String>), InferenceError> {
        let schema = self
            .unified_registry
            .get(model_id)
            .cloned()
            .ok_or_else(|| {
                InferenceError::InferenceFailed(format!(
                    "generate_mlx: unknown schema id {model_id}"
                ))
            })?;
        let handle = self.ensure_mlx_backend(&schema).await?;
        // Serialize on the shared Metal device (see `mlx_device_lock`) before the
        // per-model lock + synchronous decode loop. The per-model mutex alone does
        // NOT prevent a device-level race with a concurrent embed/other-model MLX
        // eval — e.g. memory consolidation embedding on a DIFFERENT backend while
        // the coder generates — which hangs the one Metal device (the daemon
        // "wedge"). Held across the whole generation, released on function return.
        let _device_guard = Self::mlx_device_lock().lock_owned().await;
        let mut guard = handle.lock().map_err(|_| {
            InferenceError::InferenceFailed(format!("MLX backend mutex poisoned for {model_id}"))
        })?;
        let backend: &mut backend::MlxBackend = &mut guard;

        let formatted = tasks::generate::render_chat_prompt(&req);

        // The shared decode loop owns everything from encode through sampling.
        // We only translate its corrupted-backend signal into the cache
        // eviction that needs our lock guard.
        let ctx_window = backend.context_length() as u64;
        match Self::drive_generation(backend, &formatted, &req.params) {
            Ok(gen) => {
                let usage = TokenUsage {
                    prompt_tokens: gen.prompt_tokens as u64,
                    completion_tokens: gen.completion_tokens as u64,
                    total_tokens: (gen.prompt_tokens + gen.completion_tokens) as u64,
                    context_window: ctx_window,
                    // Local in-process inference has no remote prompt cache.
                    ..Default::default()
                };
                Ok((gen.text, Some(usage), gen.ttft_ms, gen.stop_reason))
            }
            Err(backend::local::DriveError::Recoverable(e)) => Err(e),
            Err(backend::local::DriveError::BackendCorrupted(e)) => {
                drop(guard);
                self.mlx_backends.invalidate(model_id);
                Err(e)
            }
        }
    }

    /// Trait-object analogue of [`generate_mlx`](Self::generate_mlx) for
    /// NEW-architecture in-process backends (Gemma 4, …). The backend renders
    /// its own architecture-specific prompt; the shared decode loop does the
    /// rest. Evicts from `local_backends` on a caught panic.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    async fn generate_local(
        &self,
        req: GenerateRequest,
        model_id: &str,
    ) -> Result<
        (
            String,
            Vec<tasks::generate::ToolCall>,
            Option<TokenUsage>,
            Option<u64>,
            Option<String>,
        ),
        InferenceError,
    > {
        let schema = self
            .unified_registry
            .get(model_id)
            .cloned()
            .ok_or_else(|| {
                InferenceError::InferenceFailed(format!(
                    "generate_local: unknown schema id {model_id}"
                ))
            })?;
        let handle = self.ensure_local_backend(&schema).await?;
        // Device serialization (see `generate_mlx`) — same one Metal device.
        let _device_guard = Self::mlx_device_lock().lock_owned().await;
        let mut guard = handle.lock().map_err(|_| {
            InferenceError::InferenceFailed(format!("local backend mutex poisoned for {model_id}"))
        })?;

        // The backend renders its own (architecture-specific) prompt, then the
        // shared loop drives it through the `TextDecoder` primitives.
        let formatted = guard.render_prompt(&req)?;
        let backend: &mut dyn backend::local::TextDecoder = &mut **guard;
        let outcome = Self::drive_generation(backend, &formatted, &req.params);

        match outcome {
            Ok(gen) => {
                // Parse tool calls with the backend's own grammar (gemma4 uses
                // `call:NAME{...}`, not the Qwen Hermes `<tool_call>` form the
                // downstream fallback understands).
                let (clean, tool_calls) = guard.parse_tool_calls(&gen.text);
                let usage = TokenUsage {
                    prompt_tokens: gen.prompt_tokens as u64,
                    completion_tokens: gen.completion_tokens as u64,
                    total_tokens: (gen.prompt_tokens + gen.completion_tokens) as u64,
                    context_window: guard.context_length() as u64,
                    // Local in-process inference has no remote prompt cache.
                    ..Default::default()
                };
                Ok((clean, tool_calls, Some(usage), gen.ttft_ms, gen.stop_reason))
            }
            Err(backend::local::DriveError::Recoverable(e)) => Err(e),
            Err(backend::local::DriveError::BackendCorrupted(e)) => {
                drop(guard);
                self.local_backends.invalidate(model_id);
                Err(e)
            }
        }
    }

    /// Apply top-k then top-p (nucleus) truncation to a probability vector
    /// in place: keep the `top_k` highest-probability entries (k=0 disables),
    /// then keep the smallest prefix whose cumulative mass exceeds `top_p`
    /// (p>=1.0 disables), zeroing the rest and renormalizing. Pure and
    /// platform-independent (not cfg-gated) so it's unit-testable without an
    /// MLX backend. Mirrors the Candle sampler's ordering.
    #[allow(dead_code)] // used by the MLX sampler + unit tests; dead in car_skip_mlx builds
    fn apply_top_k_top_p(probs: &mut [f32], top_k: usize, top_p: f64) {
        // Top-k: zero everything outside the k highest probabilities.
        if top_k > 0 && top_k < probs.len() {
            let mut indexed: Vec<(usize, f32)> = probs.iter().copied().enumerate().collect();
            indexed.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
            let allowed: std::collections::HashSet<usize> =
                indexed[..top_k].iter().map(|(i, _)| *i).collect();
            for (i, p) in probs.iter_mut().enumerate() {
                if !allowed.contains(&i) {
                    *p = 0.0;
                }
            }
            let sum: f32 = probs.iter().sum();
            if sum > 0.0 {
                for p in probs.iter_mut() {
                    *p /= sum;
                }
            }
        }

        // Top-p (nucleus): keep the smallest high-prob prefix exceeding top_p.
        if top_p < 1.0 {
            let mut indexed: Vec<(usize, f32)> = probs.iter().copied().enumerate().collect();
            indexed.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
            let mut cumsum = 0.0f32;
            let mut cutoff_idx = indexed.len();
            for (i, &(_, p)) in indexed.iter().enumerate() {
                cumsum += p;
                if cumsum > top_p as f32 {
                    cutoff_idx = i + 1;
                    break;
                }
            }
            let allowed: std::collections::HashSet<usize> =
                indexed[..cutoff_idx].iter().map(|(i, _)| *i).collect();
            for (i, p) in probs.iter_mut().enumerate() {
                if !allowed.contains(&i) {
                    *p = 0.0;
                }
            }
            let sum: f32 = probs.iter().sum();
            if sum > 0.0 {
                for p in probs.iter_mut() {
                    *p /= sum;
                }
            }
        }
    }

    /// Sample a token from a logits Vec<f32> (shared by every local backend).
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    fn sample_from_logits(logits: &[f32], params: &GenerateParams) -> Result<u32, InferenceError> {
        if params.temperature <= 0.0 {
            // Greedy: argmax
            let (idx, _) = logits
                .iter()
                .enumerate()
                .max_by(|a, b| a.1.partial_cmp(b.1).unwrap_or(std::cmp::Ordering::Equal))
                .ok_or_else(|| InferenceError::InferenceFailed("empty logits".into()))?;
            return Ok(idx as u32);
        }

        // Temperature-scaled softmax sampling
        let temp = params.temperature as f32;
        let max_logit = logits.iter().cloned().fold(f32::NEG_INFINITY, f32::max);
        let mut probs: Vec<f32> = logits
            .iter()
            .map(|&l| ((l - max_logit) / temp).exp())
            .collect();
        let sum: f32 = probs.iter().sum();
        for p in &mut probs {
            *p /= sum;
        }

        // Top-k then top-p (nucleus) truncation. Pulled into a pure helper so
        // it's deterministic and unit-testable (only the final draw below uses
        // rng). top_k was previously absent here — a request specifying top_k
        // was silently a no-op on Apple Silicon while the Candle sampler
        // (tasks::generate::sample_token) honored it.
        Self::apply_top_k_top_p(&mut probs, params.top_k, params.top_p);

        // Sample from distribution
        use rand::Rng;
        let mut rng = rand::rng();
        let r: f32 = rng.random();
        let mut cumsum = 0.0;
        for (i, &p) in probs.iter().enumerate() {
            cumsum += p;
            if cumsum >= r {
                return Ok(i as u32);
            }
        }
        Ok((probs.len() - 1) as u32)
    }

    /// Generate embeddings for text using the dedicated embedding model.
    /// On Apple Silicon, uses the native MLX backend; on other platforms, uses Candle.
    pub async fn embed(&self, req: EmbedRequest) -> Result<Vec<Vec<f32>>, InferenceError> {
        let instruction = req
            .instruction
            .as_deref()
            .unwrap_or("Retrieve relevant memory facts");

        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        {
            let model_id = self.ensure_mlx_embedding_backend().await?;
            let schema = self
                .unified_registry
                .get(&model_id)
                .cloned()
                .ok_or_else(|| {
                    InferenceError::InferenceFailed(format!("embed: unknown schema id {model_id}"))
                })?;
            let handle = self.ensure_mlx_backend(&schema).await?;
            // Device serialization (see `generate_mlx`): this embed path is the
            // memory-consolidation caller that was racing the coder's generate on
            // a different backend and wedging the Metal device. Same device lock.
            let _device_guard = Self::mlx_device_lock().lock_owned().await;
            let mut guard = handle.lock().map_err(|_| {
                InferenceError::InferenceFailed(format!(
                    "MLX embedding backend mutex poisoned for {model_id}"
                ))
            })?;
            let backend: &mut backend::MlxBackend = &mut guard;

            let mut results = Vec::with_capacity(req.texts.len());
            for text in &req.texts {
                let embedding = if req.is_query {
                    backend.embed_query(text, instruction)?
                } else {
                    backend.embed_one(text)?
                };
                results.push(embedding);
            }
            Ok(results)
        }

        #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
        {
            self.ensure_embedding_backend().await?;
            let mut write = self.embedding_backend.write().await;
            let backend = write.as_mut().unwrap();

            let mut results = Vec::with_capacity(req.texts.len());
            for text in &req.texts {
                let embedding = if req.is_query {
                    backend.embed_query(text, instruction)?
                } else {
                    backend.embed_one(text)?
                };
                results.push(embedding);
            }
            Ok(results)
        }
    }

    /// Rerank candidate documents against a query using a cross-encoder
    /// reranker model (Qwen3-Reranker family). Returns documents sorted
    /// by descending relevance.
    ///
    /// ## Scoring
    ///
    /// Qwen3-Reranker is a Qwen3 base LM fine-tuned so that the first
    /// assistant token is `"yes"` or `"no"` given the templated
    /// `<Instruct>/<Query>/<Document>` user turn. We run a short
    /// greedy decode (≤ 3 tokens, so a leading space, BOS artifact, or
    /// the occasional newline don't break us) and score
    /// `yes → 1.0`, `no → 0.0`, anything else → `0.5` with a warning.
    ///
    /// This is a **binary** score — the soft probability
    /// `softmax(logit_yes, logit_no)` would give finer ordering but
    /// requires per-token logit access on [`backend::MlxBackend`],
    /// which isn't exposed publicly yet. Tracked as a follow-up;
    /// binary scores still produce a correct partial ordering, just
    /// with coarser tiebreaks within the {yes} or {no} groups.
    ///
    /// ## Prompt template
    ///
    /// We emit the upstream Qwen3-Reranker chat template verbatim:
    /// a dedicated system prompt fixing the yes/no answer space,
    /// then the user turn with `<Instruct>/<Query>/<Document>`, then
    /// the assistant prefix with a closed empty `<think>` block to
    /// suppress thinking (reranker is not a reasoner — it's a
    /// classifier). Deviating from this template produces sharply
    /// degraded yes/no distributions.
    pub async fn rerank(&self, req: RerankRequest) -> Result<RerankResult, InferenceError> {
        if req.documents.is_empty() {
            return Ok(RerankResult {
                ranked: Vec::new(),
                model_used: None,
            });
        }

        let model_name = match req.model.clone() {
            Some(m) => m,
            None => self
                .preferred_model_for_capability(ModelCapability::Rerank)
                .map(str::to_string)
                .ok_or_else(|| {
                    InferenceError::InferenceFailed(
                        "no reranker model available — pull a Qwen3-Reranker model first".into(),
                    )
                })?,
        };

        let schema = self
            .unified_registry
            .find_by_name(&model_name)
            .or_else(|| self.unified_registry.get(&model_name))
            .cloned()
            .ok_or_else(|| {
                InferenceError::InferenceFailed(format!(
                    "rerank: unknown reranker model {model_name}"
                ))
            })?;
        if !schema.has_capability(ModelCapability::Rerank) {
            return Err(InferenceError::InferenceFailed(format!(
                "model {} does not declare the Rerank capability",
                schema.name
            )));
        }

        let instruction = req.instruction.as_deref().unwrap_or(
            "Given a web search query, retrieve relevant passages that answer the query",
        );

        let mut scored: Vec<RerankedDocument> = Vec::with_capacity(req.documents.len());
        for (idx, doc) in req.documents.iter().enumerate() {
            let prompt = rerank_prompt(instruction, &req.query, doc);
            let gen_req = GenerateRequest {
                prompt,
                model: Some(schema.id.clone()),
                params: tasks::generate::GenerateParams {
                    temperature: 0.0,
                    // Three tokens is enough to scan past a leading
                    // space, BOS, or newline that some tokenizers
                    // insert before the real yes/no token.
                    max_tokens: 3,
                    thinking: tasks::generate::ThinkingMode::Off,
                    ..Default::default()
                },
                context: None,
                context_stable_prefix: None,
                tools: None,
                images: None,
                messages: None,
                cache_control: false,
                response_format: None,
                intent: None,
                client_ref: None,
                caller: None,
            };
            let out = self.generate(gen_req).await?;
            let score = score_from_rerank_output(&out, &schema.name);
            scored.push(RerankedDocument {
                index: idx,
                score,
                document: doc.clone(),
            });
        }

        // Sort descending by score; preserve original index as a
        // deterministic tiebreaker. top_n must truncate after sorting.
        scored.sort_by(|a, b| {
            b.score
                .partial_cmp(&a.score)
                .unwrap_or(std::cmp::Ordering::Equal)
                .then_with(|| a.index.cmp(&b.index))
        });
        if let Some(n) = req.top_n {
            scored.truncate(n);
        }

        Ok(RerankResult {
            ranked: scored,
            model_used: Some(schema.name),
        })
    }

    /// Dedicated endpoint for structured visual grounding.
    ///
    /// Runs a VL generate call under the hood and parses Qwen2.5-VL's
    /// inline `<|object_ref_*|>...<|box_*|>(x1,y1),(x2,y2)` spans into
    /// typed [`BoundingBox`]es. Distinct from the generic
    /// [`InferenceEngine::generate`] + `InferenceResult.bounding_boxes`
    /// path so callers can express "I want boxes" as a first-class
    /// intent — which also lets the router prefer models that declare
    /// the `Grounding` capability.
    pub async fn ground(&self, req: GroundRequest) -> Result<GroundResult, InferenceError> {
        let model_name = match req.model.clone() {
            Some(m) => m,
            None => self
                .preferred_model_for_capability(ModelCapability::Grounding)
                .map(str::to_string)
                .ok_or_else(|| {
                    InferenceError::InferenceFailed(
                        "no grounding-capable model available — pull a Qwen2.5-VL model first"
                            .into(),
                    )
                })?,
        };

        let gen_req = GenerateRequest {
            prompt: req.prompt.clone(),
            model: Some(model_name),
            params: GenerateParams::default(),
            context: None,
            context_stable_prefix: None,
            tools: None,
            images: Some(vec![req.image.clone()]),
            messages: None,
            cache_control: false,
            response_format: None,
            intent: None,
            client_ref: None,
            caller: None,
        };
        let result = self.generate_tracked(gen_req).await?;
        Ok(GroundResult {
            boxes: result.bounding_boxes,
            raw_text: result.text,
            model_used: Some(result.model_used),
        })
    }

    /// Classify text against candidate labels.
    /// When `req.model` is None, routes to the smallest available model.
    pub async fn classify(
        &self,
        req: ClassifyRequest,
    ) -> Result<Vec<ClassifyResult>, InferenceError> {
        let model = match req.model.clone().or_else(|| {
            self.preferred_model_for_capability(ModelCapability::Classify)
                .map(str::to_string)
        }) {
            Some(m) => m,
            None => {
                let m = self.router.route_small(&self.registry);
                debug!(model = %m, "auto-routed classify request");
                m
            }
        };

        // On Apple Silicon, route through the main generate path (which uses MLX)
        // instead of the Candle backend directly.
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        {
            return self.classify_via_generate(req, &model).await;
        }

        #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
        {
            self.ensure_backend(&model).await?;
            let mut write = self.backend.write().await;
            let backend = write.as_mut().unwrap();
            tasks::classify::classify(backend, req).await
        }
    }

    /// Classify by routing through the main generate path (uses MLX on Apple Silicon).
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    async fn classify_via_generate(
        &self,
        req: ClassifyRequest,
        model: &str,
    ) -> Result<Vec<ClassifyResult>, InferenceError> {
        let labels_str = req
            .labels
            .iter()
            .enumerate()
            .map(|(i, l)| format!("{}. {}", i + 1, l))
            .collect::<Vec<_>>()
            .join("\n");

        let prompt = format!(
            "Classify the following text into one of these categories:\n\
             {labels_str}\n\n\
             Text: {}\n\n\
             Respond with ONLY the category name, nothing else.",
            req.text
        );

        let gen_req = GenerateRequest {
            prompt,
            model: Some(model.to_string()),
            params: tasks::generate::GenerateParams {
                temperature: 0.0,
                max_tokens: 32,
                // Classification is latency-sensitive and single-label;
                // force the fast no-thinking path even on Qwen3.
                thinking: tasks::generate::ThinkingMode::Off,
                ..Default::default()
            },
            context: None,
            context_stable_prefix: None,
            tools: None,
            images: None,
            messages: None,
            cache_control: false,
            response_format: None,
            intent: None,
            client_ref: None,
            caller: None,
        };

        let response = self.generate(gen_req).await?;
        let response_lower = response.trim().to_lowercase();

        let mut results: Vec<ClassifyResult> = req
            .labels
            .iter()
            .map(|label| {
                let label_lower = label.to_lowercase();
                let score = if response_lower == label_lower {
                    1.0
                } else if response_lower.contains(&label_lower) {
                    0.8
                } else {
                    let label_words: Vec<&str> = label_lower.split_whitespace().collect();
                    let matches = label_words
                        .iter()
                        .filter(|w| response_lower.contains(**w))
                        .count();
                    if label_words.is_empty() {
                        0.0
                    } else {
                        0.5 * (matches as f64 / label_words.len() as f64)
                    }
                };
                ClassifyResult {
                    label: label.clone(),
                    score,
                }
            })
            .collect();

        results.sort_by(|a, b| {
            b.score
                .partial_cmp(&a.score)
                .unwrap_or(std::cmp::Ordering::Equal)
        });

        let total: f64 = results.iter().map(|r| r.score).sum();
        if total > 0.0 {
            for r in &mut results {
                r.score /= total;
            }
        }

        Ok(results)
    }

    /// Transcribe an audio file using the best available STT model.
    pub async fn transcribe(
        &self,
        req: TranscribeRequest,
    ) -> Result<TranscribeResult, InferenceError> {
        let candidates =
            self.speech_candidates(ModelCapability::SpeechToText, req.model.as_deref())?;
        let mut last_error = None;

        for schema in candidates {
            let result = match &schema.source {
                ModelSource::Mlx { .. } => self.transcribe_local_mlx(&schema, &req).await,
                ModelSource::WhisperCpp { model } => {
                    self.transcribe_whisper(&schema, model, &req).await
                }
                ModelSource::Proprietary { provider, .. } if provider == "elevenlabs" => {
                    self.transcribe_elevenlabs(&schema, &req).await
                }
                _ => Err(InferenceError::InferenceFailed(format!(
                    "speech-to-text not implemented for model source: {}",
                    schema.id
                ))),
            };

            match result {
                Ok(result) => return Ok(result),
                Err(err) => last_error = Some(err),
            }
        }

        Err(last_error.unwrap_or_else(|| {
            InferenceError::InferenceFailed("no speech-to-text models available".into())
        }))
    }

    /// Synthesize speech using the best available TTS model.
    pub async fn synthesize(
        &self,
        req: SynthesizeRequest,
    ) -> Result<SynthesizeResult, InferenceError> {
        let candidates =
            self.speech_candidates(ModelCapability::TextToSpeech, req.model.as_deref())?;
        let mut last_error = None;

        for schema in candidates {
            let result = match &schema.source {
                ModelSource::Mlx { .. } => self.synthesize_local_mlx(&schema, &req).await,
                ModelSource::WindowsSpeech {} => {
                    self.synthesize_windows_speech(&schema, &req).await
                }
                ModelSource::Proprietary { provider, .. } if provider == "elevenlabs" => {
                    self.synthesize_elevenlabs(&schema, &req).await
                }
                _ => Err(InferenceError::InferenceFailed(format!(
                    "text-to-speech not implemented for model source: {}",
                    schema.id
                ))),
            };

            match result {
                Ok(result) => return Ok(result),
                Err(err) => last_error = Some(err),
            }
        }

        Err(last_error.unwrap_or_else(|| {
            InferenceError::InferenceFailed("no text-to-speech models available".into())
        }))
    }

    /// Synthesize speech with the Windows OS synthesizer (`WindowsSpeech`,
    /// WinRT `Windows.Media.SpeechSynthesis`) — the catalog-side counterpart of
    /// car-voice's live `TtsProvider::WindowsSpeech`. Writes a WAV file at the
    /// requested (or a temp) path. Windows-only; the availability gate keeps
    /// this off the candidate list on every other target.
    async fn synthesize_windows_speech(
        &self,
        schema: &ModelSchema,
        req: &SynthesizeRequest,
    ) -> Result<SynthesizeResult, InferenceError> {
        #[cfg(target_os = "windows")]
        {
            let text = req.text.clone();
            let voice = req.voice.clone().unwrap_or_default();
            let rate = req.speed.unwrap_or(1.0) as f64;
            let bytes =
                tokio::task::spawn_blocking(move || winrt_synthesize_wav(&text, &voice, rate))
                    .await
                    .map_err(|e| {
                        InferenceError::InferenceFailed(format!("winrt tts join: {e}"))
                    })??;
            let dest = requested_or_temp_output(req.output_path.as_deref(), "wav")?;
            ensure_parent_dir(&dest)?;
            std::fs::write(&dest, &bytes)?;
            Ok(SynthesizeResult {
                audio_path: dest.to_string_lossy().to_string(),
                media_type: "audio/wav".to_string(),
                model_used: Some(schema.name.clone()),
                voice_used: req.voice.clone(),
            })
        }
        #[cfg(not(target_os = "windows"))]
        {
            let _ = (schema, req);
            Err(InferenceError::InferenceFailed(
                "Windows OS TTS is only available on Windows".into(),
            ))
        }
    }

    /// Generate an image using the best available local MLX image model.
    pub async fn generate_image(
        &self,
        req: GenerateImageRequest,
    ) -> Result<GenerateImageResult, InferenceError> {
        // Dispatch: the native Rust MLX Flux backend now reaches prompt-faithful
        // parity at 512×512×4-step against mflux (verified via the parity harness
        // in tools/parity/ref_flux.py + diff_flux_blocks.py). Default to native;
        // `CAR_IMAGE_BACKEND=external` still routes to the Python mflux fallback
        // for A/B comparison, `CAR_IMAGE_BACKEND=auto` reads env preference then
        // auto-detects.
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        {
            use crate::backend::external_flux;
            let backend =
                std::env::var("CAR_IMAGE_BACKEND").unwrap_or_else(|_| "native".to_string());
            let use_external = match backend.as_str() {
                "external" => true,
                "native" => false,
                // `auto` honors external only when the subprocess CLI is on PATH.
                _ => external_flux::is_available() && backend == "auto-external",
            };
            if use_external {
                tracing::info!(
                    "routing image generation to external mflux \
                     (set CAR_IMAGE_BACKEND=native to use the Rust port)"
                );
                let mut req = req;
                req.model = self.resolve_external_hf_repo(
                    req.model.as_deref(),
                    ModelCapability::ImageGeneration,
                );
                return external_flux::generate_image(&req);
            }
            tracing::info!("using native Rust MLX Flux backend");
        }

        let candidates = self
            .media_generation_candidates(ModelCapability::ImageGeneration, req.model.as_deref())?;
        let mut last_error = None;

        for schema in candidates {
            let result = match &schema.source {
                #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
                ModelSource::Mlx { .. } => self.generate_image_native_mlx(&schema, &req).await,
                _ => Err(InferenceError::InferenceFailed(format!(
                    "image generation not implemented for model source: {}",
                    schema.id
                ))),
            };

            match result {
                Ok(result) => return Ok(result),
                Err(err) => last_error = Some(err),
            }
        }

        Err(last_error.unwrap_or_else(|| {
            InferenceError::InferenceFailed("no image generation models available".into())
        }))
    }

    /// Generate one or more variants in a single call.
    ///
    /// Returns `req.variant_count` results (defaulting to 1). The
    /// current MLX Flux backend doesn't support native batching, so
    /// this loops over `generate_image` with the seed advanced per
    /// variant for visual diversity. A future hosted backend
    /// (gpt-image-2, Replicate) can short-circuit this with one
    /// network call producing N coherent images.
    ///
    /// Per-variant errors abort the batch — there's no partial-
    /// success semantics today. Callers needing more lenient
    /// behaviour should call `generate_image` directly in their own
    /// loop.
    ///
    /// Closes #110.
    pub async fn generate_image_batch(
        &self,
        req: GenerateImageRequest,
    ) -> Result<Vec<GenerateImageResult>, InferenceError> {
        let count = req.variant_count.unwrap_or(1).max(1);
        if count == 1 {
            return self.generate_image(req).await.map(|r| vec![r]);
        }
        let base_seed = req.seed.unwrap_or(0);
        let mut results = Vec::with_capacity(count as usize);
        for i in 0..count {
            // Vary the seed per variant so backends that key prompt
            // → output deterministically actually produce different
            // images. Callers wanting reproducible single-seed
            // variants override `seed` per call themselves.
            let mut variant_req = req.clone();
            variant_req.seed = Some(base_seed.wrapping_add(i as u64));
            // Suppress variant_count on the inner call to avoid
            // recursion — generate_image ignores the field today,
            // but this also documents intent.
            variant_req.variant_count = Some(1);
            results.push(self.generate_image(variant_req).await?);
        }
        Ok(results)
    }

    /// One process-wide lock over the single Metal device, shared by EVERY
    /// native MLX generate path (flux image, ltx video, and any future MLX
    /// media backend such as kokoro TTS). Two concurrent MLX evals race the
    /// command encoder and segfault the whole process inside
    /// `mlx::core::metal::Device::end_encoding`. The per-model `handle.lock()`
    /// only serializes calls that share ONE cached backend — the LRU cache can
    /// hand a second call a freshly-loaded instance on a different mutex, and
    /// image-vs-video are different mutexes entirely — so a device-wide lock is
    /// the only thing that actually serializes the GPU. Held *inside* the
    /// `spawn_blocking` closure so it survives RPC-deadline abandonment of the
    /// outer future.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    fn mlx_device_lock() -> Arc<tokio::sync::Mutex<()>> {
        static MLX_DEVICE_LOCK: std::sync::OnceLock<Arc<tokio::sync::Mutex<()>>> =
            std::sync::OnceLock::new();
        MLX_DEVICE_LOCK
            .get_or_init(|| Arc::new(tokio::sync::Mutex::new(())))
            .clone()
    }

    /// Native MLX Flux image generation (no Python shelling).
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    async fn generate_image_native_mlx(
        &self,
        schema: &ModelSchema,
        req: &GenerateImageRequest,
    ) -> Result<GenerateImageResult, InferenceError> {
        let model_dir = self.unified_registry.ensure_local(&schema.id).await?;
        let size = backend_cache::estimate_model_size(&model_dir);
        let handle = Self::load_backend_healing(
            &schema.id,
            model_dir,
            &self.flux_cache,
            size,
            backend::mlx_flux::FluxBackend::load,
            || self.unified_registry.redownload_local(&schema.id),
        )
        .await?;
        // Serialize on the shared Metal device (see `mlx_device_lock`) before
        // running the synchronous, GPU-bound eval on a blocking worker. The
        // per-model mutex alone does NOT prevent a device-level race with a
        // concurrent video/other-model eval.
        let req = req.clone();
        let device_guard = Self::mlx_device_lock().lock_owned().await;
        tokio::task::spawn_blocking(move || -> Result<GenerateImageResult, InferenceError> {
            // Held for the full native eval; released at closure end.
            let _device_guard = device_guard;
            let mut guard = handle.lock().map_err(|_| {
                InferenceError::InferenceFailed("flux backend mutex poisoned".into())
            })?;
            guard.generate(&req)
        })
        .await
        .map_err(|e| InferenceError::InferenceFailed(format!("flux task join: {e}")))?
    }

    /// Native MLX LTX-2.3 video generation (no Python shelling).
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    async fn generate_video_native_mlx(
        &self,
        schema: &ModelSchema,
        req: &GenerateVideoRequest,
    ) -> Result<GenerateVideoResult, InferenceError> {
        let model_dir = self.unified_registry.ensure_local(&schema.id).await?;
        let size = backend_cache::estimate_model_size(&model_dir);
        let handle = Self::load_backend_healing(
            &schema.id,
            model_dir,
            &self.ltx_cache,
            size,
            backend::mlx_ltx::LtxBackend::load,
            || self.unified_registry.redownload_local(&schema.id),
        )
        .await?;
        let req = req.clone();

        // Process-wide single-permit lock on the in-process MLX *video*
        // device eval. Two concurrent MLX evals on the one Metal device
        // race the command encoder and segfault the whole daemon inside
        // `mlx::core::metal::Device::end_encoding` (null encoder; observed
        // 2026-06-24, two `LtxBackend::generate` threads live at once).
        //
        // Neither existing guard prevents this:
        //   * the admission semaphore (`car-server-core::admission`) is
        //     RAM-sized (≈1 permit / 8 GB, up to 8) — it bounds LLM
        //     activations, not GPU eval, so it freely admits N>1 video
        //     generations on a roomy host;
        //   * the per-instance `handle.lock()` below only serializes
        //     calls that share ONE cached backend — the LRU cache can
        //     hand a second call a freshly-loaded instance (esp. after a
        //     deadline-orphaned first call), so the two lock different
        //     mutexes and run the device concurrently.
        //
        // This lock is independent of both: it gates the device itself.
        // The guard is MOVED into the blocking closure rather than held
        // by this async future, so it survives an RPC-deadline abandon:
        // a `spawn_blocking` job can't be cancelled, so the orphaned
        // native eval keeps the lock until it actually finishes and the
        // next video eval waits instead of overlapping (and crashing).
        // NOTE: other in-process MLX backends (flux image, kokoro TTS)
        // share the same Metal device and should adopt this lock too for
        // full cross-modality coverage — tracked as a follow-up; this
        // change fixes the observed video-vs-video crash.
        // Shared with flux image + any future MLX media path (see
        // `mlx_device_lock`) — a video eval must not run concurrently with an
        // image eval on the one Metal device.
        let device_guard = Self::mlx_device_lock().lock_owned().await;

        tokio::task::spawn_blocking(move || -> Result<GenerateVideoResult, InferenceError> {
            // Held for the full native eval; released at closure end,
            // which is what lets the next waiting video eval proceed.
            let _device_guard = device_guard;
            let mut guard = handle.lock().map_err(|_| {
                InferenceError::InferenceFailed("ltx backend mutex poisoned".into())
            })?;
            guard.generate(&req)
        })
        .await
        .map_err(|e| InferenceError::InferenceFailed(format!("ltx task join: {e}")))?
    }

    /// Generate a video using the best available local MLX video model.
    pub async fn generate_video(
        &self,
        req: GenerateVideoRequest,
    ) -> Result<GenerateVideoResult, InferenceError> {
        // Validate the request shape up front so callers get a clean
        // error rather than a backend failure deep in the stack.
        if let Err(msg) = req.validate() {
            return Err(InferenceError::InferenceFailed(format!(
                "invalid GenerateVideoRequest: {}",
                msg
            )));
        }
        // Consumed only by the MLX LTX video path below; unused on non-MLX builds.
        #[allow(unused_variables)]
        let requires_audio_conditioning = req.requires_audio_passthrough_opt_in();
        // Backend selection: LTX can use CAR's native Rust MLX backend,
        // or the legacy external `ltx-2-mlx` bridge when requested.
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        {
            use crate::backend::external_ltx;
            // Default flipped to `native` now that the Rust port reaches
            // quality parity with upstream ltx-2-mlx (matching prompt
            // produces a matching subject; see the cascade of fixes in
            // #40 / #45). `external` still honored for A/B comparison.
            let backend =
                std::env::var("CAR_VIDEO_BACKEND").unwrap_or_else(|_| "native".to_string());
            let use_external = match backend.as_str() {
                "external" => true,
                "native" => false,
                // `auto-external` is an opt-in to the old behavior: use
                // the Python CLI if it happens to be on PATH, else fall
                // back to native.
                "auto-external" => external_ltx::is_available(),
                _ => false,
            };
            if use_external {
                tracing::info!(
                    "CAR_VIDEO_BACKEND requested external LTX routing for LTX-family models"
                );
            } else {
                tracing::info!("using family-aware MLX video routing");
            }
        }

        let candidates = self
            .media_generation_candidates(ModelCapability::VideoGeneration, req.model.as_deref())?;
        let mut last_error = None;

        for schema in candidates {
            let result = match &schema.source {
                #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
                ModelSource::Mlx { hf_repo, .. } => {
                    let backend =
                        std::env::var("CAR_VIDEO_BACKEND").unwrap_or_else(|_| "native".to_string());
                    let use_external_ltx = match backend.as_str() {
                        "external" => true,
                        "native" => false,
                        "auto-external" => crate::backend::external_ltx::is_available(),
                        _ => false,
                    };
                    let use_external_ltx = use_external_ltx || requires_audio_conditioning;
                    if requires_audio_conditioning && !crate::backend::external_ltx::is_available()
                    {
                        return Err(InferenceError::InferenceFailed(
                            "audio-reference video conditioning requires the external `ltx-2-mlx a2v` CLI on PATH"
                                .to_string(),
                        ));
                    }
                    if use_external_ltx {
                        let mut req = req.clone();
                        req.model = Some(hf_repo.clone());
                        crate::backend::external_ltx::generate_video(&req)
                    } else {
                        self.generate_video_native_mlx(&schema, &req).await
                    }
                }
                _ => Err(InferenceError::InferenceFailed(format!(
                    "video generation not implemented for model source: {}",
                    schema.id
                ))),
            };

            match result {
                Ok(result) => return Ok(result),
                Err(err) => last_error = Some(err),
            }
        }

        Err(last_error.unwrap_or_else(|| {
            InferenceError::InferenceFailed("no video generation models available".into())
        }))
    }

    /// List all known models and their status (new registry).
    pub fn list_models_unified(&self) -> Vec<ModelInfo> {
        self.routing_registry_snapshot()
            .list()
            .iter()
            .map(|m| ModelInfo::from(*m))
            .collect()
    }

    /// Report installed models that have curated newer replacements.
    pub fn available_model_upgrades(&self) -> Vec<ModelUpgrade> {
        self.unified_registry.available_upgrades()
    }

    /// The proactive-upgrade decision for right now: which curated upgrades to
    /// auto-apply (under `Auto` policy) and the single nudge to surface, with
    /// throttling and dismissals applied. The daemon calls this on its periodic
    /// check and broadcasts `decision.nudge` over WebSocket. Returns the loaded
    /// `NudgeState` too so the caller can stamp `last_nudge_secs` after sending.
    pub async fn check_upgrade_nudge(
        &self,
        inference_active: bool,
    ) -> (crate::nudge::NudgeDecision, crate::nudge::NudgeState) {
        let findings = self.detect_upgrades().await;
        let prefs = self.update_prefs();
        let state = crate::nudge::NudgeState::load_from(&crate::nudge::NudgeState::default_path());
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_secs())
            .unwrap_or(0);
        let decision = crate::nudge::decide_nudge(
            &findings,
            &prefs,
            &state,
            now,
            crate::nudge::DEFAULT_THROTTLE_SECS,
            inference_active,
        );
        (decision, state)
    }

    /// Record that the user dismissed a nudge (by its `dismiss_key`), so it is
    /// never surfaced again. Persists to `~/.car/nudge-state.json`.
    pub fn dismiss_upgrade_nudge(&self, dismiss_key: &str) -> Result<(), InferenceError> {
        let path = crate::nudge::NudgeState::default_path();
        let mut state = crate::nudge::NudgeState::load_from(&path);
        state.dismiss(dismiss_key);
        state
            .save_to(&path)
            .map_err(InferenceError::InferenceFailed)
    }

    /// Run the proactive concierge decision: for the default watched lanes,
    /// suggest a model to acquire for any lane the user has nothing installed
    /// for. Returns the suggestions plus the loaded [`NudgeState`] so the caller
    /// can stamp `last_concierge_secs` after surfacing (mirrors the
    /// stamp-after-deliver pattern of [`Self::check_upgrade_nudge`]). The
    /// concierge throttles independently of the upgrade nudge.
    pub async fn check_concierge(
        &self,
        inference_active: bool,
    ) -> (
        Vec<crate::concierge::ConciergeSuggestion>,
        crate::nudge::NudgeState,
    ) {
        let prefs = self.update_prefs();
        let state = crate::nudge::NudgeState::load_from(&crate::nudge::NudgeState::default_path());
        let hw = crate::hardware::HardwareInfo::detect();
        let schemas = self.list_schemas();
        let refs: Vec<&ModelSchema> = schemas.iter().collect();
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_secs())
            .unwrap_or(0);
        let suggestions = crate::concierge::decide_concierge(
            &refs,
            &hw,
            crate::concierge::DEFAULT_WATCHED_USE_CASES,
            crate::intent::QualityTier::Balanced,
            &prefs,
            &state,
            now,
            crate::concierge::DEFAULT_CONCIERGE_THROTTLE_SECS,
            inference_active,
        );
        (suggestions, state)
    }

    /// Record that the user dismissed a concierge suggestion (by its
    /// `dismiss_key`), so it is never surfaced again. Shares the same
    /// `~/.car/nudge-state.json` `dismissed` list as the upgrade nudge — the key
    /// namespaces are disjoint (`concierge:…` vs `from=>to`).
    pub fn dismiss_concierge_suggestion(&self, dismiss_key: &str) -> Result<(), InferenceError> {
        self.dismiss_upgrade_nudge(dismiss_key)
    }

    /// Record a *labeled* concierge dismissal (Phase B4/C1) so the Act
    /// gate can treat the reason as signal (permanent reasons suppress;
    /// `NotNow` cools down). Persists to `~/.car/nudge-state.json`.
    pub fn dismiss_concierge_labeled(
        &self,
        dismiss_key: &str,
        reason: crate::concierge::DismissReason,
    ) -> Result<(), String> {
        let path = crate::nudge::NudgeState::default_path();
        let mut state = crate::nudge::NudgeState::load_from(&path);
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_secs())
            .unwrap_or(0);
        state.dismiss_labeled(dismiss_key, reason, now);
        state.save_to(&path).map_err(|e| e.to_string())
    }

    /// Net-positive verification (Phase F3): for each lane whose latest
    /// action was a `SetDefault` (a switch not yet rolled back), compare
    /// the new model's *observed* post-switch success in that lane against
    /// the prior model's baseline; if it's measurably worse with enough
    /// samples, **auto-revert** to the prior. Never self-graded — the
    /// signal is the outcome ledger's verifier/outcome receipts. The
    /// daemon calls this on its periodic tick. Returns the reverted lanes.
    pub async fn check_canaries(&self) -> Vec<crate::intent::UseCase> {
        use crate::action_ledger::ConciergeActionKind;
        use crate::concierge::{
            canary_verdict, CanaryVerdict, CANARY_MIN_SAMPLES, CANARY_REGRESSION_MARGIN,
        };
        use std::collections::BTreeMap;

        let actions = self.concierge_actions(0);
        let ledger_path = self.config.models_dir.join("outcome_ledger.jsonl");
        let entries = crate::outcome::read_ledger(&ledger_path, 0);

        // Latest action per global (project=None) lane — append order, last wins.
        let mut latest: BTreeMap<
            crate::intent::UseCase,
            &crate::action_ledger::ConciergeActionEntry,
        > = BTreeMap::new();
        for a in &actions {
            if a.project.is_some() {
                continue; // only global lanes canaried for now
            }
            if let Some(uc) = a.use_case {
                latest.insert(uc, a);
            }
        }

        // Decide first (under the tracker read lock), then execute reverts
        // after releasing it — rollback acquires the action lock and must
        // not nest under the tracker lock.
        // (lane, anchor seq) — seq uniquely identifies the standing switch.
        let mut reverts: Vec<(crate::intent::UseCase, u64)> = Vec::new();
        let tracker = self.outcome_tracker.read().await;
        for (uc, a) in latest {
            // Only a standing switch (not already rolled back) with a prior
            // to fall back to is a canary candidate.
            if a.kind != ConciergeActionKind::SetDefault {
                continue;
            }
            let Some(prior) = a.prior_model_id.as_deref() else {
                continue; // no baseline → nothing to compare/revert to
            };

            // New model's post-switch resolved success in this lane.
            let (mut succ, mut total) = (0u64, 0u64);
            for e in &entries {
                if e.timestamp < a.timestamp
                    || e.model_id != a.model_id
                    || crate::usage_profile::use_case_for_task(e.task) != uc
                {
                    continue;
                }
                match e.success {
                    Some(true) => {
                        succ += 1;
                        total += 1;
                    }
                    Some(false) => total += 1,
                    None => {}
                }
            }
            let new_rate = if total == 0 {
                None
            } else {
                Some(succ as f64 / total as f64)
            };

            // Baseline must be LANE-SCOPED to compare like-for-like: sum the
            // prior model's per-task stats across tasks that map to THIS
            // lane (not its global lifetime success rate, which mixes other
            // lanes and would revert good switches / keep bad ones).
            let (mut base_succ, mut base_total) = (0u64, 0u64);
            if let Some(profile) = tracker.profile(prior) {
                for t in [
                    crate::outcome::InferenceTask::Generate,
                    crate::outcome::InferenceTask::Embed,
                    crate::outcome::InferenceTask::Classify,
                    crate::outcome::InferenceTask::Code,
                    crate::outcome::InferenceTask::Reasoning,
                ] {
                    if crate::usage_profile::use_case_for_task(t) != uc {
                        continue;
                    }
                    if let Some(ts) = profile.task_stats(t) {
                        base_succ += ts.successes;
                        base_total += ts.successes + ts.failures;
                    }
                }
            }
            // No real lane baseline for the prior → never auto-revert (don't
            // revert against a made-up neutral prior).
            if base_total == 0 {
                continue;
            }
            let baseline = base_succ as f64 / base_total as f64;

            if canary_verdict(
                new_rate,
                total,
                baseline,
                CANARY_MIN_SAMPLES,
                CANARY_REGRESSION_MARGIN,
            ) == CanaryVerdict::Revert
            {
                // Conditional revert under the action lock: only undo if
                // this exact switch is still the standing one (the user may
                // have applied a newer one since we read). Atomic vs. apply.
                reverts.push((uc, a.seq));
            }
        }
        drop(tracker);

        // Execute the reverts: each is conditional on its anchor still being
        // the standing switch (rollback_lane_inner re-checks under the lock).
        let mut reverted = Vec::new();
        for (uc, seq) in reverts {
            if self.rollback_lane_inner(uc, None, Some(seq)).await.is_ok() {
                tracing::info!(lane = ?uc, "concierge canary: auto-reverted a worse model switch");
                reverted.push(uc);
            }
        }
        reverted
    }

    /// Conversational concierge (Phase F1/F2): answer a free-form
    /// question about the user's models/portfolio, grounded in the
    /// observed-usage evidence + the deterministic `recommend()` candidate
    /// menu. The LLM *explains* — it runs on a local model, is told to
    /// answer ONLY from the supplied evidence, and must not invent a model
    /// or assert fit (the grounding oracle already decided fit). This is
    /// the ModelConcierge "agent": a thin, constrained `generate` call
    /// over assembled receipts, not a freelancing chat.
    pub async fn concierge_ask(&self, question: &str) -> Result<String, String> {
        use std::fmt::Write as _;
        let status = self.concierge_status(false).await;
        let hw = crate::hardware::HardwareInfo::detect();
        let schemas = self.list_schemas();
        let refs: Vec<&ModelSchema> = schemas.iter().collect();

        let mut evidence = String::new();
        evidence.push_str("OBSERVED USAGE (last 30 days):\n");
        if status.lanes.is_empty() {
            evidence.push_str("  (no usage recorded yet)\n");
        }
        for lane in &status.lanes {
            let rate = lane
                .success_rate()
                .map(|r| format!("{:.0}% success", r * 100.0))
                .unwrap_or_else(|| "no resolved signal".into());
            let _ = writeln!(
                evidence,
                "  {:?}: {} calls, {}{}",
                lane.use_case,
                lane.calls,
                rate,
                if lane.failing_models.is_empty() {
                    String::new()
                } else {
                    format!(
                        ", failing on {}",
                        lane.failing_models
                            .iter()
                            .cloned()
                            .collect::<Vec<_>>()
                            .join(", ")
                    )
                }
            );
        }
        evidence.push_str("\nMODEL HEALTH:\n");
        for m in &status.models {
            let success = match m.success_rate {
                Some(r) => format!("{:.0}% success", r * 100.0),
                None => "no resolved signal".to_string(),
            };
            let _ = writeln!(
                evidence,
                "  {}: {} calls, {}, {:.0}ms avg{}",
                m.model_id,
                m.calls,
                success,
                m.avg_latency_ms,
                if m.excluded { " (excluded)" } else { "" }
            );
        }
        // Grounded candidate menu — the ONLY models the answer may
        // reference (with their real fit on this machine). Cover the
        // default-watched lanes PLUS every lane the user actually uses, so
        // a question about vision/transcription/search has grounded
        // candidates instead of forcing the model to improvise.
        let mut menu_lanes: Vec<crate::intent::UseCase> =
            crate::concierge::DEFAULT_WATCHED_USE_CASES.to_vec();
        for lane in &status.lanes {
            if !menu_lanes.contains(&lane.use_case) {
                menu_lanes.push(lane.use_case);
            }
        }
        evidence.push_str("\nGROUNDED CANDIDATES (fit verified for this machine):\n");
        for uc in menu_lanes {
            let set = crate::recommend::recommend(
                &refs,
                &hw,
                uc,
                crate::intent::QualityTier::Balanced,
                crate::intent::Privacy::OnDevice,
            );
            for p in set.picks.iter().take(3) {
                let _ = writeln!(
                    evidence,
                    "  [{:?}] {} — {}{}",
                    uc,
                    p.display_name,
                    if p.already_installed {
                        "installed"
                    } else {
                        "available"
                    },
                    if p.fit == crate::recommend::FitStatus::Fits {
                        ", fits"
                    } else {
                        ", does NOT fit"
                    }
                );
            }
        }
        if let Some(s) = &status.decision.suggestion {
            let _ = writeln!(evidence, "\nCURRENT SUGGESTION: {}", s.message);
        }

        let prompt = format!(
            "You are CAR's model concierge. Answer the user's question ONLY from the \
             EVIDENCE provided as context — the user's observed model usage, model \
             health, and the grounded candidate menu (the only models you may \
             mention). NEVER invent a model name and NEVER claim a model fits or is \
             better than the evidence states. If the evidence doesn't answer the \
             question, say so plainly. Be concise and concrete.\n\nQUESTION: {question}"
        );
        let evidence_lc = evidence.to_lowercase();
        let req = crate::tasks::generate::GenerateRequest {
            prompt,
            context: Some(evidence),
            intent: Some(crate::intent::IntentHint {
                task: Some(crate::intent::TaskHint::Chat),
                prefer_local: true,
                ..Default::default()
            }),
            ..Default::default()
        };
        let answer = self.generate(req).await.map_err(|e| e.to_string())?;

        // Soft grounding guard: a local model may still name a model family
        // outside the evidence. Don't strip mid-sentence (garbles output) —
        // flag it, so a hallucinated recommendation can't pass as verified.
        const FAMILIES: [&str; 9] = [
            "llama", "gpt", "mistral", "gemma", "deepseek", "phi", "claude", "grok", "qwen",
        ];
        let answer_lc = answer.to_lowercase();
        let leaked = FAMILIES
            .iter()
            .any(|fam| answer_lc.contains(fam) && !evidence_lc.contains(fam));
        let answer = if leaked {
            format!(
                "{answer}\n\n(Note: I can only verify models in your catalog — any others \
                 named above aren't checked for fit on your machine.)"
            )
        } else {
            answer
        };
        Ok(answer)
    }

    /// Refresh the model catalog from the configured signed source
    /// (Phase E1): fetch + verify (detached ed25519 against the pinned
    /// key) + cache the verified models. Source is `CAR_CATALOG_URL` +
    /// `CAR_CATALOG_PUBKEY` (no key → refused). The new models load into
    /// the registry at next startup (the registry is immutable at
    /// runtime), then surface as `recommend()` candidates / concierge
    /// suggestions. Returns the number of models in the verified catalog.
    pub async fn refresh_catalog(&self) -> Result<usize, String> {
        let url = std::env::var("CAR_CATALOG_URL")
            .map_err(|_| "no catalog source configured (set CAR_CATALOG_URL)".to_string())?;
        let pubkey = std::env::var("CAR_CATALOG_PUBKEY")
            .map_err(|_| "no catalog public key configured (set CAR_CATALOG_PUBKEY)".to_string())?;
        // Not `Client::new()`: that is `build().expect(..)`, which panics when
        // the OS trust store loads zero valid certificates. Degrading here is
        // safe even for a privately-hosted catalog — authenticity comes from
        // the detached ed25519 signature checked below, not from TLS.
        let http = crate::tls_client::catalog_refresh_client();
        let verified = crate::catalog::fetch_and_verify(&http, &url, &pubkey).await?;
        let path = crate::catalog::cache_path(&self.config.models_dir);
        // Signature verification alone proves authenticity, not freshness.
        // Compare the authenticated cached version and atomically replace it
        // under one process-local lock so concurrent N/N+1 refreshes cannot
        // commit the lower version last.
        crate::catalog::install_if_newer(&path, &verified, &pubkey).await
    }

    /// Auto-discover provider models (Phase E2): query the provider's
    /// `/v1/models` list and cache previously-unknown chat/reasoning models as
    /// `TrustTier::Community` entries (cloning a curated same-provider schema as
    /// a template). Best-effort — no key or no OpenAI provider configured is
    /// a no-op, not an error. Discovered models load into the registry at next
    /// startup (the registry is immutable at runtime). Returns the total number
    /// of cached discovered models. This is what lets the catalog (and the
    /// router) pick up new models like a `gpt-5.5` without a release.
    pub async fn discover_models(&self) -> Result<usize, String> {
        use crate::schema::{ModelSource, TrustTier};
        // Template = a curated, remote OpenAI model — gives the endpoint, key
        // env, protocol, and routing metadata new entries inherit. `all()` is
        // HashMap-ordered (non-deterministic), so pick the MOST-CAPABLE curated
        // OpenAI remote (tie-break by id for determinism) rather than the first
        // one — otherwise a discovered model could inherit a reduced-capability
        // entry like `-mini`.
        let template = self
            .unified_registry
            .all()
            .filter(|m| {
                m.provider.eq_ignore_ascii_case("openai")
                    && m.trust_tier == TrustTier::Curated
                    && matches!(m.source, ModelSource::RemoteApi { .. })
            })
            .max_by(|a, b| {
                a.capabilities
                    .len()
                    .cmp(&b.capabilities.len())
                    .then_with(|| a.id.cmp(&b.id))
            })
            .cloned();
        let Some(template) = template else {
            return Ok(0); // no OpenAI provider configured → nothing to discover
        };
        let (endpoint, api_key_env) = match &template.source {
            ModelSource::RemoteApi {
                endpoint,
                api_key_env,
                ..
            } => (endpoint.clone(), api_key_env.clone()),
            _ => return Ok(0),
        };
        let Some(models_url) = crate::discovery::models_url_from_endpoint(&endpoint) else {
            return Ok(0);
        };
        let key = match car_secrets::resolve_env_or_keychain(&api_key_env) {
            Some(k) if !k.is_empty() => k,
            _ => return Ok(0), // no key (env or keychain) → best-effort skip
        };

        // Bounded HTTP: this runs on a background daily timer, so a hung
        // provider endpoint must not wedge the loop (which is
        // `discover(); sleep(24h)` — a stuck await never reaches the sleep).
        let http = reqwest::Client::builder()
            .timeout(std::time::Duration::from_secs(20))
            .build()
            .map_err(|e| format!("discovery client: {e}"))?;
        let ids = crate::discovery::fetch_model_ids(&http, &models_url, &key).await?;

        // Merge new finds with anything already cached (don't drop prior runs).
        let cache = crate::discovery::cache_path(&self.config.models_dir);
        let mut cached = crate::discovery::load_cache(&cache);
        let mut have: std::collections::HashSet<String> =
            cached.iter().map(|m| m.id.clone()).collect();
        for id in ids {
            if !crate::discovery::is_chat_model(&id) {
                continue;
            }
            let schema = crate::discovery::discovered_schema("openai", &id, &template);
            // Dedup by the constructed id against BOTH the live registry
            // (curated + signed + already-loaded discovered) and this run's
            // cache — discovery only ever ADDS ids nothing else owns. Keying on
            // the id is more robust than matching the provider's bare id
            // against curated `name`s.
            if self.unified_registry.get(&schema.id).is_some() {
                continue;
            }
            if have.insert(schema.id.clone()) {
                cached.push(schema);
            }
        }
        let count = cached.len();
        crate::discovery::save_cache(&cache, &cached)?;
        Ok(count)
    }

    /// All configured lane defaults (Phase D1), from the in-memory cache.
    pub fn lane_defaults(&self) -> crate::lane_defaults::LaneDefaults {
        self.lane_defaults_cache.read().unwrap().clone()
    }

    /// Resolve the default model for `(project, use_case)`, if set.
    /// Routing consults this as a strong preference before falling back
    /// to adaptive selection. Reads the cache (no disk).
    pub fn lane_default(
        &self,
        project: Option<&str>,
        use_case: crate::intent::UseCase,
    ) -> Option<String> {
        self.lane_defaults_cache
            .read()
            .unwrap()
            .resolve(project, use_case)
            .map(str::to_string)
    }

    /// The lane-default model to honor for a request when the caller
    /// didn't pin one — `None` unless the request carries a use-case
    /// intent whose lane default resolves to a known, available model.
    /// A stale/uninstalled pin returns `None` so routing falls through to
    /// adaptive selection rather than wedging on a missing model.
    fn lane_pin_for(
        &self,
        req: &GenerateRequest,
        routing_registry: &UnifiedRegistry,
    ) -> Option<String> {
        let task = req.intent.as_ref().and_then(|h| h.task)?;
        let use_case = crate::usage_profile::use_case_for_task_hint(task);
        let id = self.lane_default(None, use_case)?;
        // Validate against the same per-request snapshot the adaptive router
        // and dispatch path consume. That snapshot refreshes live credential
        // availability for the fixed reviewed registry, so key changes apply
        // without allowing an unregistered lane id through.
        let known = routing_registry
            .get(&id)
            .or_else(|| routing_registry.find_by_name(&id));
        match known {
            Some(s) if s.available_now() => Some(id),
            _ => None,
        }
    }

    /// Set the default model for `(project, use_case)` (Phase D1) — the
    /// durable target of the concierge's "set it up" action.
    pub fn set_lane_default(
        &self,
        project: Option<String>,
        use_case: crate::intent::UseCase,
        model_id: &str,
    ) -> Result<(), String> {
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_secs())
            .unwrap_or(0);
        // Update cache (hot path reads it) + persist, under the cache lock
        // so the two stay consistent for the single-writer concierge.
        let mut defaults = self.lane_defaults_cache.write().unwrap();
        defaults.set(project, use_case, model_id.to_string(), now);
        crate::lane_defaults::save_to(&crate::lane_defaults::default_path(), &defaults)
            .map_err(|e| e.to_string())
    }

    /// Clear the default for `(project, use_case)`. Returns whether one
    /// existed (used by rollback in D3).
    pub fn clear_lane_default(
        &self,
        project: Option<&str>,
        use_case: crate::intent::UseCase,
    ) -> Result<bool, String> {
        let mut defaults = self.lane_defaults_cache.write().unwrap();
        let removed = defaults.clear(project, use_case);
        crate::lane_defaults::save_to(&crate::lane_defaults::default_path(), &defaults)
            .map_err(|e| e.to_string())?;
        Ok(removed)
    }

    /// User-facing lane-default set (the `concierge.set_default` WS path):
    /// like [`set_lane_default`] but serialized under the concierge action
    /// lock AND recorded in the action ledger. Without the ledger entry a
    /// manual pin would be invisible to the canary, which could then revert
    /// it based on a stale ledger view — so this records a `SetDefault`
    /// (with the prior captured) exactly like `apply`, keeping the ledger
    /// and the live default consistent.
    pub async fn user_set_lane_default(
        &self,
        use_case: crate::intent::UseCase,
        model_id: &str,
        project: Option<String>,
    ) -> Result<(), String> {
        use crate::action_ledger::{ConciergeActionEntry, ConciergeActionKind};
        let _guard = self.concierge_action_lock.lock().await;
        let prior = self.lane_default(project.as_deref(), use_case);
        self.set_lane_default(project.clone(), use_case, model_id)?;
        self.record_concierge_action(ConciergeActionEntry {
            seq: 0,
            kind: ConciergeActionKind::SetDefault,
            model_id: model_id.to_string(),
            use_case: Some(use_case),
            project,
            prior_model_id: prior,
            detail: "user set lane default".into(),
            timestamp: now_unix(),
        });
        Ok(())
    }

    /// User-facing lane-default clear (the `concierge.clear_default` WS
    /// path): serialized + ledgered like [`user_set_lane_default`]. Records
    /// a `ClearDefault` so the canary sees the lane is no longer a standing
    /// switch (its `latest` action is the clear, not a `SetDefault`).
    pub async fn user_clear_lane_default(
        &self,
        use_case: crate::intent::UseCase,
        project: Option<String>,
    ) -> Result<bool, String> {
        use crate::action_ledger::{ConciergeActionEntry, ConciergeActionKind};
        let _guard = self.concierge_action_lock.lock().await;
        let prior = self.lane_default(project.as_deref(), use_case);
        let removed = self.clear_lane_default(project.as_deref(), use_case)?;
        if removed {
            self.record_concierge_action(ConciergeActionEntry {
                seq: 0,
                kind: ConciergeActionKind::ClearDefault,
                model_id: prior.clone().unwrap_or_default(),
                use_case: Some(use_case),
                project,
                prior_model_id: prior,
                detail: "user cleared lane default".into(),
                timestamp: now_unix(),
            });
        }
        Ok(removed)
    }

    /// The recorded concierge actions (Phase D2), most recent last.
    pub fn concierge_actions(
        &self,
        limit: usize,
    ) -> Vec<crate::action_ledger::ConciergeActionEntry> {
        crate::action_ledger::read_actions(&crate::action_ledger::default_path(), limit)
    }

    fn record_concierge_action(&self, mut entry: crate::action_ledger::ConciergeActionEntry) {
        entry.seq = self
            .concierge_action_seq
            .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
        if let Err(e) =
            crate::action_ledger::append_action(&crate::action_ledger::default_path(), &entry)
        {
            tracing::debug!("record concierge action failed: {e}");
        }
    }

    /// Closed-loop "set it up" (Phase D3): acquire `model_id`, then set it
    /// as the lane default — capturing the prior default so the change is
    /// reversible ([`rollback_lane`]). Every step is recorded in the
    /// action ledger.
    ///
    /// Consent: the caller (CarHost) owns the pre-download confirmation —
    /// this primitive assumes the user has already agreed to the (possibly
    /// multi-GB) download; the ledger entry is the audit record that it
    /// happened. Single-writer: lane defaults assume one concierge writer
    /// (CarHost); concurrent `apply`s would last-write-wins the JSON (the
    /// F3 canary watcher must coordinate before it becomes a 2nd writer).
    pub async fn apply_concierge(
        &self,
        use_case: crate::intent::UseCase,
        model_id: &str,
        project: Option<String>,
    ) -> Result<crate::action_ledger::ConciergeApplyResult, String> {
        use crate::action_ledger::{ConciergeActionEntry, ConciergeActionKind};
        let now = || {
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map(|d| d.as_secs())
                .unwrap_or(0)
        };
        // Lane-fit guard: refuse to pin a model that structurally can't
        // serve the lane (e.g. a vision-only model on the coding lane).
        // A model id unknown to the registry is left to `pull_model` to
        // reject as not-found.
        if let Some(schema) = self
            .list_schemas()
            .into_iter()
            .find(|s| s.id == model_id || s.name == model_id)
        {
            let serves = use_case
                .required_capabilities()
                .iter()
                .all(|c| schema.capabilities.contains(c));
            if !serves {
                return Err(format!(
                    "model '{model_id}' does not serve the {use_case:?} lane"
                ));
            }
        }

        // 1. Acquire (idempotent — `ensure_local` skips an already-present
        //    model; the Install record means "ensured present", not
        //    necessarily a fresh download). OUTSIDE the action lock so a
        //    long download doesn't block the canary tick.
        self.pull_model(model_id).await.map_err(|e| e.to_string())?;

        // 2+3 under the action lock: capture prior + record + set default
        //    atomically vs. a concurrent canary revert.
        let _guard = self.concierge_action_lock.lock().await;
        // Capture what we're replacing AFTER taking the lock, so a canary
        // revert can't slip in between the read and the write.
        let prior = self.lane_default(project.as_deref(), use_case);
        self.record_concierge_action(ConciergeActionEntry {
            seq: 0, // assigned by record_concierge_action
            kind: ConciergeActionKind::Install,
            model_id: model_id.to_string(),
            use_case: Some(use_case),
            project: project.clone(),
            prior_model_id: None,
            detail: "concierge apply: ensured model present".into(),
            timestamp: now(),
        });

        // 2. Set as the lane default (reversible — prior captured).
        self.set_lane_default(project.clone(), use_case, model_id)?;
        self.record_concierge_action(ConciergeActionEntry {
            seq: 0, // assigned by record_concierge_action
            kind: ConciergeActionKind::SetDefault,
            model_id: model_id.to_string(),
            use_case: Some(use_case),
            project: project.clone(),
            prior_model_id: prior.clone(),
            detail: "concierge apply: set lane default".into(),
            timestamp: now(),
        });

        Ok(crate::action_ledger::ConciergeApplyResult {
            model_id: model_id.to_string(),
            use_case,
            installed: true,
            set_default: true,
            prior_model_id: prior,
        })
    }

    /// Revert a lane default to its value before the last `apply` (Phase
    /// D3 rollback). Restores the prior model (or clears the default if
    /// there was none), recording the rollback. Returns the restored
    /// model id, or `None` if the default was cleared / nothing to undo.
    pub async fn rollback_lane(
        &self,
        use_case: crate::intent::UseCase,
        project: Option<String>,
    ) -> Result<Option<String>, String> {
        self.rollback_lane_inner(use_case, project, None).await
    }

    /// Inner rollback: serialized under the concierge action lock so the
    /// anchor read + restore + record is atomic vs. a concurrent `apply`.
    /// `expected_anchor_ts` (the canary's) makes the revert conditional:
    /// if the latest SetDefault is no longer the one we decided on (the
    /// user applied a newer switch), refuse rather than undo their choice.
    async fn rollback_lane_inner(
        &self,
        use_case: crate::intent::UseCase,
        project: Option<String>,
        expected_anchor_seq: Option<u64>,
    ) -> Result<Option<String>, String> {
        use crate::action_ledger::{ConciergeActionEntry, ConciergeActionKind};
        let _guard = self.concierge_action_lock.lock().await;
        // One-shot "undo the last apply": anchor on the most recent
        // SetDefault *or* Rollback for this (lane, project). If the latest
        // is already a Rollback, there's nothing left to undo — refuse
        // rather than restore a stale value a second time.
        let actions = self.concierge_actions(0);
        let anchor = actions.iter().rev().find(|a| {
            matches!(
                a.kind,
                ConciergeActionKind::SetDefault | ConciergeActionKind::Rollback
            ) && a.use_case == Some(use_case)
                && a.project == project
        });
        let set = match anchor {
            None => return Err("no prior set-default to roll back".into()),
            Some(a) if a.kind == ConciergeActionKind::Rollback => {
                return Err("already rolled back to the prior default; nothing to undo".into())
            }
            Some(a) => a,
        };
        // Conditional revert (canary): only proceed if the anchor is still
        // the switch we decided on — the user may have applied a newer one.
        if let Some(seq) = expected_anchor_seq {
            if set.seq != seq {
                return Err("lane default changed since the canary decision; not reverting".into());
            }
        }
        let prior = set.prior_model_id.clone();
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_secs())
            .unwrap_or(0);

        match &prior {
            Some(m) => self.set_lane_default(project.clone(), use_case, m)?,
            None => {
                self.clear_lane_default(project.as_deref(), use_case)?;
            }
        }
        let detail = match &prior {
            Some(_) => "concierge rollback: restored prior lane default",
            None => "concierge rollback: cleared lane default (no prior)",
        };
        self.record_concierge_action(ConciergeActionEntry {
            seq: 0, // assigned by record_concierge_action
            kind: ConciergeActionKind::Rollback,
            model_id: prior.clone().unwrap_or_default(),
            use_case: Some(use_case),
            project,
            prior_model_id: Some(set.model_id.clone()),
            detail: detail.into(),
            timestamp: now,
        });
        Ok(prior)
    }

    /// Assemble the ambient concierge status (Phase C1): per-lane usage +
    /// friction from the outcome ledger, the current grounded decision
    /// (`evaluate_concierge`), and per-model health from the profiles. A
    /// pull (the UI asks); proactive push stays separate.
    pub async fn concierge_status(
        &self,
        inference_active: bool,
    ) -> crate::concierge::ConciergeStatus {
        /// Lookback window for the usage profile: 30 days.
        const USAGE_WINDOW_SECS: u64 = 30 * 24 * 60 * 60;

        let prefs = self.update_prefs();
        let state = crate::nudge::NudgeState::load_from(&crate::nudge::NudgeState::default_path());
        let hw = crate::hardware::HardwareInfo::detect();
        let schemas = self.list_schemas();
        let refs: Vec<&ModelSchema> = schemas.iter().collect();
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_secs())
            .unwrap_or(0);

        let ledger_path = self.config.models_dir.join("outcome_ledger.jsonl");
        let entries = crate::outcome::read_ledger(&ledger_path, 0);
        let usage =
            crate::usage_profile::UsageProfile::from_ledger(&entries, now, USAGE_WINDOW_SECS);

        let decision = crate::concierge::evaluate_concierge(
            &refs,
            &hw,
            &usage,
            crate::intent::QualityTier::Balanced,
            &prefs,
            &state,
            now,
            crate::concierge::DEFAULT_CONCIERGE_THROTTLE_SECS,
            inference_active,
        );

        let tracker = self.outcome_tracker.read().await;
        let models = tracker
            .export_profiles()
            .iter()
            .map(|p| crate::concierge::ModelHealth {
                model_id: p.model_id.clone(),
                calls: p.total_calls,
                // Display-only: `None` when nothing resolved (not the router's
                // 0.5 prior), so the UI shows "no resolved signal" rather than
                // a misleading "50%" for a never-measured model.
                success_rate: p.success_rate_resolved(),
                avg_latency_ms: p.avg_latency_ms(),
                quality: p.ema_quality,
                excluded: tracker.is_excluded(&p.model_id),
            })
            .collect();
        drop(tracker);

        // Pending verification: standing switches old enough that we'd
        // expect to have verified them, but lacking the resolved samples a
        // canary needs (low-resolution lanes). Surface them so the user can
        // decide rather than leaving them silently unverifiable.
        const STALE_VERIFY_SECS: u64 = 14 * 24 * 60 * 60;
        let actions = self.concierge_actions(0);
        let mut latest: std::collections::BTreeMap<
            crate::intent::UseCase,
            &crate::action_ledger::ConciergeActionEntry,
        > = std::collections::BTreeMap::new();
        for a in &actions {
            if a.project.is_none() {
                if let Some(uc) = a.use_case {
                    latest.insert(uc, a);
                }
            }
        }
        let mut pending_verification = Vec::new();
        for (uc, a) in latest {
            if a.kind != crate::action_ledger::ConciergeActionKind::SetDefault {
                continue;
            }
            if now.saturating_sub(a.timestamp) < STALE_VERIFY_SECS {
                continue; // still within the verification window
            }
            let resolved = entries
                .iter()
                .filter(|e| {
                    e.timestamp >= a.timestamp
                        && e.model_id == a.model_id
                        && crate::usage_profile::use_case_for_task(e.task) == uc
                        && e.success.is_some()
                })
                .count() as u64;
            if resolved < crate::concierge::CANARY_MIN_SAMPLES {
                pending_verification.push(crate::concierge::PendingVerification {
                    use_case: uc,
                    model_id: a.model_id.clone(),
                    set_at: a.timestamp,
                    resolved_samples: resolved,
                    needed: crate::concierge::CANARY_MIN_SAMPLES,
                });
            }
        }

        crate::concierge::ConciergeStatus {
            lanes: usage.active_lanes().into_iter().cloned().collect(),
            decision,
            models,
            pending_verification,
        }
    }

    /// Detect upgrades combining curated rules with upstream Hub discovery,
    /// honoring update preferences (channel/policy) and the TTL cache. Upstream
    /// probing only happens on the `Latest` channel and is offline-safe.
    pub async fn detect_upgrades(&self) -> Vec<crate::upgrade::UpgradeFinding> {
        let prefs = self.update_prefs();
        let curated = self.unified_registry.available_upgrades();
        let schemas = self.list_schemas();
        let refs: Vec<&ModelSchema> = schemas.iter().collect();
        let probe = crate::upgrade::HuggingFaceProbe::new();
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_secs())
            .unwrap_or(0);
        crate::upgrade::detect_upgrades(
            curated,
            &refs,
            &prefs,
            &probe,
            &crate::upgrade::UpgradeCache::default_path(),
            now,
            crate::upgrade::DEFAULT_TTL_SECS,
        )
        .await
    }

    /// List all known models and their download status (legacy).
    /// List all model schemas from the unified registry (full metadata).
    pub fn list_schemas(&self) -> Vec<ModelSchema> {
        self.routing_registry_snapshot()
            .list()
            .into_iter()
            .cloned()
            .collect()
    }

    /// Return one registered schema without refreshing availability.
    ///
    /// This is for identity/provenance checks that must reflect signed catalog
    /// overrides while remaining local and side-effect free.
    pub fn registered_schema(&self, id: &str) -> Option<ModelSchema> {
        self.unified_registry.registered_schema(id).cloned()
    }

    pub fn list_models(&self) -> Vec<models::ModelInfo> {
        self.registry.list_models()
    }

    /// The name of a downloaded, generation-capable on-device model to use as a
    /// last-resort fallback so a remote-only chain that fails (an expired cloud
    /// credential, an offline network) can still answer locally instead of
    /// erroring with nothing left. Prefers the smallest installed model (fastest
    /// to load) and excludes dedicated embedding models.
    ///
    /// When `needs_tools` is set, ONLY an installed model that actually parses
    /// tool calls (the `ToolUse` capability) qualifies — a text-only local model
    /// would be dropped by the tool-capability guard in the generate loop and
    /// help nothing, so returning it as a "fallback" just wastes an attempt.
    /// Returns `None` when no installed model can serve the turn (the chain then
    /// surfaces the actionable remote error, e.g. the re-authenticate hint).
    fn first_installed_local_model(&self, needs_tools: bool) -> Option<String> {
        // Enumerate through the UNIFIED registry, not the legacy GGUF-only
        // `list_models()`. The legacy catalog keys `downloaded` off a
        // `{name}/model.gguf` file, so it is blind to MLX installs (stored as
        // config.json + safetensors, no `.gguf`) — i.e. every model on Apple
        // Silicon, the platform where degrading to on-device matters most. The
        // unified registry's `ready_without_download` understands both the GGUF
        // and MLX layouts, so this fallback fires on macOS too.
        let mut candidates: Vec<_> = self
            .unified_registry
            .all()
            // In-process on-device backends ONLY (GGUF via candle, or in-process
            // MLX) — the same set `ensure_local_backend` drives. `is_local()`
            // also matches `VllmMlx`, whose `ready_without_download` is
            // unconditionally true but which needs an external vLLM-MLX server
            // that is usually not running (and never on Windows/Linux); picking
            // one would be a dead fallback, not an on-device answer.
            .filter(|s| s.is_local() && !s.is_vllm_mlx())
            // Apple's FoundationModels reports `ready_without_download == true`
            // on every platform (there is nothing to download), but it only
            // EXECUTES on Apple Silicon — off-Apple its `available` is false, a
            // platform-static fact, so the registry's boot-time value is reliable
            // here even though the frozen registry is otherwise untrustworthy for
            // availability (car#651). Without this, a remote-only fallback chain
            // on Windows/Linux appends `apple-foundation` as a "local last
            // resort", it fails with `model not found: apple-foundation`, and that
            // error MASKS the real remote failure (a Windows CRLF-broken fixture
            // surfaced exactly this). Scoped to this source on purpose: other
            // local models' availability CAN change at runtime (a GGUF pulled
            // after boot), which is why the readiness gate below stays
            // `ready_without_download`, not `available`. `is_foundation_models`'s
            // own docs say callers must verify runtime availability before
            // dispatch — this is that check.
            .filter(|s| !s.is_foundation_models() || s.available)
            .filter(|s| s.has_capability(ModelCapability::Generate))
            // A tools-bearing turn needs a model that actually parses tool calls
            // (ToolUse); a text-only local model would be dropped by the
            // generate loop's capability guard and waste an attempt.
            .filter(|s| !needs_tools || s.has_capability(ModelCapability::ToolUse))
            .filter(|s| self.unified_registry.ready_without_download(&s.id) == Some(true))
            .collect();
        // Smallest first — fastest to load for a last-resort answer.
        candidates.sort_by_key(|s| s.size_mb());

        // Don't hand back a model this machine can't actually run RIGHT NOW.
        // The last-resort fallback fires when a remote call fails, and that
        // often coincides with a loaded machine; picking a local model without
        // the free RAM to run it turns a recoverable remote error into a hard
        // Metal OOM abort mid-generation (observed: a transient Parslee outage
        // during a browser-automation run fell back to on-device and crashed
        // with a 48 GB `[metal::malloc]` allocation on a box with ~2 GB free).
        // The routing-time `fits_now` guard covers model SELECTION; this covers
        // the fallback-APPEND path, which bypasses it. Weights plus a working
        // reserve for the KV cache and activations must fit in available RAM.
        // If availability can't be read, keep prior behavior (append anyway).
        if let Some(avail) = crate::hardware::available_ram_mb() {
            const WORKING_RESERVE_MB: u64 = 2048;
            candidates.retain(|s| s.size_mb().saturating_add(WORKING_RESERVE_MB) <= avail);
        }

        candidates.first().map(|s| s.name.clone())
    }

    /// Download a model if not already present.
    pub async fn pull_model(&self, name: &str) -> Result<std::path::PathBuf, InferenceError> {
        self.pull_model_with_progress(name, &crate::download::ProgressSink::none())
            .await
    }

    /// Download a model if not already present, reporting progress to `sink`
    /// and enforcing the acquisition lifecycle (per-model lock, disk preflight,
    /// lifecycle events). The CLI and daemon use this to show live progress.
    pub async fn pull_model_with_progress(
        &self,
        name: &str,
        sink: &crate::download::ProgressSink,
    ) -> Result<std::path::PathBuf, InferenceError> {
        let schema = self
            .unified_registry
            .find_by_name(name)
            .or_else(|| self.unified_registry.get(name))
            .ok_or_else(|| InferenceError::ModelNotFound(name.to_string()))?;
        self.unified_registry
            .ensure_local_with_progress(&schema.id, sink)
            .await
    }

    /// Current update preferences. A team-shared project `.car/update-prefs.json`
    /// (found by walking up from cwd) overrides the user `~/.car/update-prefs.json`;
    /// defaults if neither exists. Loaded on demand — read at onboarding/
    /// upgrade-check frequency, not on the inference hot path.
    pub fn update_prefs(&self) -> crate::update_prefs::UpdatePreferences {
        let cwd = std::env::current_dir().unwrap_or_else(|_| std::path::PathBuf::from("."));
        crate::update_prefs::UpdatePreferences::load_effective(&cwd).unwrap_or_default()
    }

    /// Persist update preferences to `~/.car/update-prefs.json`.
    pub fn set_update_prefs(
        &self,
        prefs: &crate::update_prefs::UpdatePreferences,
    ) -> Result<(), InferenceError> {
        prefs.save().map_err(InferenceError::InferenceFailed)
    }

    /// Remove a downloaded model.
    pub fn remove_model(&self, name: &str) -> Result<(), InferenceError> {
        let schema = self
            .unified_registry
            .get(name)
            .or_else(|| {
                self.unified_registry
                    .list()
                    .into_iter()
                    .find(|schema| schema.name.eq_ignore_ascii_case(name))
            })
            .or_else(|| self.unified_registry.find_by_name(name))
            .ok_or_else(|| InferenceError::ModelNotFound(name.to_string()))?;
        let model_dir = self.unified_registry.models_dir().join(&schema.name);
        if model_dir.exists() {
            std::fs::remove_dir_all(&model_dir)?;
        }
        match &schema.source {
            ModelSource::Mlx { hf_repo, .. } => {
                remove_huggingface_repo_cache(hf_repo)?;
            }
            ModelSource::Local {
                hf_repo,
                tokenizer_repo,
                ..
            } => {
                remove_huggingface_repo_cache(hf_repo)?;
                remove_huggingface_repo_cache(tokenizer_repo)?;
            }
            _ => {}
        }
        Ok(())
    }

    /// Register a model at the public runtime boundary.
    ///
    /// The registry normalizes every such schema to Community trust. Project
    /// curation is reserved for compiled builtins and signature-verified
    /// catalogs inside this crate.
    pub fn register_model(&mut self, schema: ModelSchema) {
        self.unified_registry.register(schema);
    }

    /// Register a model from a user-controlled schema boundary.
    pub fn register_user_model(&mut self, schema: ModelSchema) {
        self.unified_registry.register_user_model(schema);
    }

    /// Discover generic MLX models from a running vLLM-MLX server and register them.
    /// Returns the number of discovered models added or refreshed in the registry.
    pub async fn discover_vllm_mlx_models(&mut self) -> usize {
        let config = vllm_mlx::VllmMlxConfig::default();
        if !config.auto_discover {
            return 0;
        }
        vllm_mlx::discover_and_register(&config, &mut self.unified_registry).await
    }

    /// Get outcome tracker for external use (e.g., memgine integration).
    pub fn outcome_tracker(&self) -> Arc<RwLock<OutcomeTracker>> {
        self.outcome_tracker.clone()
    }

    /// Auto-save outcomes and key pool stats silently (called after every
    /// inference call). Debounced: the outcome profiles are only written
    /// when the tracker is dirty AND at least `OUTCOME_FLUSH_INTERVAL` has
    /// passed since the last flush — so a busy machine doesn't serialize
    /// and rewrite the whole profiles file on every single call. A forced,
    /// unconditional flush is available via [`save_outcomes`] (used on
    /// shutdown / by the dream task).
    async fn auto_save_outcomes(&self) {
        const OUTCOME_FLUSH_INTERVAL: std::time::Duration = std::time::Duration::from_secs(60);

        // An on-device inference worker (car-releases#74) is a stateless compute
        // slave: the parent daemon owns outcome bookkeeping and persistence for
        // every offloaded call (it wraps the offload in its own record_start /
        // record_complete). If the worker also wrote `outcome_profiles.json` /
        // `outcome_ledger.jsonl` in the shared models_dir it would race the
        // daemon's atomic writes and clobber the router's learning with a
        // local-only view. So the worker never persists.
        if crate::offload::is_offload_worker() {
            return;
        }

        // Read the debounce gate without holding the lock across an await.
        let due = {
            let last = self.last_outcome_flush.lock().unwrap();
            last.is_none_or(|t| t.elapsed() >= OUTCOME_FLUSH_INTERVAL)
        };
        if due {
            match self.persist_outcomes().await {
                Ok(did) => {
                    if did {
                        *self.last_outcome_flush.lock().unwrap() = Some(Instant::now());
                    }
                }
                Err(e) => tracing::debug!("auto-save outcomes failed: {}", e),
            }
        }

        if let Err(e) = self.save_key_pool_stats().await {
            tracing::debug!("auto-save key pool stats failed: {}", e);
        }
    }

    /// Persist both outcome artifacts: append the resolved-outcome ledger
    /// (the durable, attributable receipts — append-only JSONL) and save
    /// the derived aggregate profiles (dirty-gated, atomic). Returns
    /// whether anything was written. Shared by the debounced per-call path
    /// and the immediate [`flush_outcomes`] backstop.
    async fn persist_outcomes(&self) -> Result<bool, std::io::Error> {
        const PENDING_TTL_SECS: u64 = 300;
        // Under one write lock: evict stale pending (bounds memory +
        // de-biases the ledger via Inconclusive receipts) and drain the
        // resulting receipts.
        let entries = {
            let mut tracker = self.outcome_tracker.write().await;
            tracker.sweep_pending(PENDING_TTL_SECS);
            tracker.drain_ledger()
        };
        let mut did = false;
        // Privacy opt-out: CAR_NO_OUTCOME_LEDGER drops per-call receipts
        // entirely (the buffer is still drained so it can't grow). Aggregate
        // profiles still persist — routing needs them — but no attributable
        // per-call record is written.
        let ledger_disabled = std::env::var_os("CAR_NO_OUTCOME_LEDGER").is_some();
        if !entries.is_empty() && !ledger_disabled {
            let ledger_path = self.config.models_dir.join("outcome_ledger.jsonl");
            let _guard = self.ledger_io_lock.lock().await;
            crate::outcome::append_ledger_entries(&ledger_path, &entries)?;
            did = true;
        }
        // Profiles: dirty-gated atomic save.
        let profiles_path = self.config.models_dir.join("outcome_profiles.json");
        let wrote = {
            let mut tracker = self.outcome_tracker.write().await;
            tracker.save_if_dirty(&profiles_path)?
        };
        Ok(did || wrote)
    }

    /// Persist outcome profiles to disk for cross-session learning (#13).
    /// Unconditional (force) save — writes even if nothing changed.
    /// Prefer [`flush_outcomes`] for shutdown / periodic flushes; the
    /// per-call path uses [`auto_save_outcomes`], which debounces.
    pub async fn save_outcomes(&self) -> Result<(), std::io::Error> {
        let tracker = self.outcome_tracker.read().await;
        let path = self.config.models_dir.join("outcome_profiles.json");
        tracker.save_to_file(&path)
    }

    /// Flush outcome profiles to disk **iff** dirty, ignoring the per-call
    /// time debounce. Returns whether a write happened. This is the
    /// durable-receipt backstop: the daemon calls it on a periodic timer
    /// and on graceful shutdown so the last (sub-`OUTCOME_FLUSH_INTERVAL`)
    /// window of learning is never lost. Cheap when clean (no write).
    pub async fn flush_outcomes(&self) -> Result<bool, std::io::Error> {
        let did = self.persist_outcomes().await?;
        if did {
            *self.last_outcome_flush.lock().unwrap() = Some(Instant::now());
        }
        Ok(did)
    }

    /// Enforce the outcome-ledger retention bound (privacy + disk). A cheap
    /// no-op when under the cap; the daemon calls it periodically.
    pub async fn prune_outcome_ledger(&self, max_entries: usize) -> std::io::Result<()> {
        let path = self.config.models_dir.join("outcome_ledger.jsonl");
        let _guard = self.ledger_io_lock.lock().await;
        crate::outcome::prune_ledger(&path, max_entries)
    }

    /// Persist key pool stats to disk.
    pub async fn save_key_pool_stats(&self) -> Result<(), std::io::Error> {
        let path = self.config.models_dir.join("key_pool_stats.json");
        self.remote_backend.key_pool.save_stats(&path).await
    }

    /// Get key pool stats for all endpoints.
    pub async fn key_pool_stats(
        &self,
    ) -> std::collections::HashMap<String, Vec<key_pool::KeyStats>> {
        self.remote_backend.key_pool.all_stats().await
    }

    /// Export model performance profiles for persistence.
    pub async fn export_profiles(&self) -> Vec<ModelProfile> {
        let tracker = self.outcome_tracker.read().await;
        tracker.export_profiles()
    }

    /// Fold the durable outcome ledger into the deployment scoreboard — the
    /// per-model, priced, OUTCOME-DENOMINATED view (cost-per-success,
    /// tokens-per-success, success-rate). Reads the same `outcome_ledger.jsonl`
    /// the tracker flushes to (cross-session, survives restart) and joins
    /// per-model catalog prices from the registry so `usd_per_success` is the
    /// honest "cry once" figure. Unpriced models keep a `None` dollar figure
    /// rather than a fabricated one. See [`crate::scoreboard::Scoreboard`].
    pub fn outcome_scoreboard(&self) -> crate::scoreboard::Scoreboard {
        let ledger_path = self.config.models_dir.join("outcome_ledger.jsonl");
        let entries = crate::outcome::read_ledger(&ledger_path, 0);
        // #369: shadow-calibration telemetry folds the SAME durable ledger —
        // surface how the router's quality constants would tune as graded
        // evidence accumulates, without touching the live constants or routing.
        crate::calibration::ShadowCalibration::from_ledger(&entries).emit();
        crate::scoreboard::Scoreboard::from_ledger(&entries, |id| {
            let s = self
                .unified_registry
                .get(id)
                .or_else(|| self.unified_registry.find_by_name(id))?;
            match (s.cost.input_per_mtok, s.cost.output_per_mtok) {
                // Cache economics come from the model's protocol so cached
                // tokens are priced at the right per-provider discount
                // (Anthropic 0.1×/1.25×, OpenAI 0.5×/no-write).
                (Some(input_per_mtok), Some(output_per_mtok)) => {
                    Some(crate::scoreboard::PriceModel {
                        input_per_mtok,
                        output_per_mtok,
                        cache: s.cache_rates(),
                        is_estimate: !s.cost.pricing_tiers.is_empty(),
                    })
                }
                _ => None,
            }
        })
    }

    /// Import model performance profiles (from persistence).
    pub async fn import_profiles(&self, profiles: Vec<ModelProfile>) {
        let mut tracker = self.outcome_tracker.write().await;
        tracker.import_profiles(profiles);
    }

    /// Ensure the managed local speech runtime exists and return its root
    /// directory — the same root [`speech_health`](Self::speech_health)
    /// reports, on every platform.
    ///
    /// Apple Silicon used to short-circuit here: native MLX backends were taken
    /// to replace the Python runtime outright, so this only created
    /// `models_dir` and handed *that* back without ever provisioning the
    /// managed runtime. Since #640 the runtime is a live fallback there too
    /// (the native backends can't load every catalogued checkpoint) and
    /// `speech doctor` reports its real state — so a "successful" install
    /// contradicted doctor, printed a path doctor never mentions, and pushed
    /// the multi-minute venv+pip bootstrap onto the first synthesis
    /// (Parslee-ai/car#649). Provision it up front on every platform instead.
    ///
    /// The one asymmetry that remains is what a bootstrap *failure* means.
    /// Off Apple Silicon the managed runtime is the only local speech path, so
    /// failing to build it fails the call. On Apple Silicon it sits behind
    /// working native backends, so a missing `uv` degrades rather than breaks:
    /// the root comes back either way, and callers should report
    /// `speech_health().runtime.installed` rather than read a returned path as
    /// proof of success. Either way the returned directory exists — a method
    /// called "prepare" leaves the thing prepared (Parslee-ai/car#626).
    pub async fn prepare_speech_runtime(&self) -> Result<PathBuf, InferenceError> {
        match self.ensure_speech_runtime().await {
            Ok(runtime) => Ok(runtime.root),
            #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
            Err(err) => {
                let root = speech_runtime_root_from_models_dir(&self.config.models_dir);
                tracing::warn!(
                    error = %err,
                    root = %root.display(),
                    "managed speech runtime could not be provisioned; native MLX \
                     backends still cover the default local models, but catalogued \
                     checkpoints they cannot load will be unavailable"
                );
                std::fs::create_dir_all(&root)?;
                Ok(root)
            }
            #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
            Err(err) => Err(err),
        }
    }

    /// Override speech routing preferences for the current engine instance.
    pub fn set_speech_policy(&mut self, policy: SpeechPolicy) {
        self.speech_policy = policy;
    }

    pub fn set_routing_config(&mut self, config: RoutingConfig) {
        self.adaptive_router.set_config(config);
    }

    /// Download the curated local speech model set into the shared Hugging Face cache.
    pub async fn install_curated_speech(
        &mut self,
    ) -> Result<Vec<SpeechInstallReport>, InferenceError> {
        // Provisioning the managed runtime is best-effort here, deliberately.
        // It is an Apple-only Python stack (`uv venv` + `pip install
        // mlx-audio`, and `mlx` publishes no Windows/Linux wheels), and off
        // Apple Silicon `prepare_speech_runtime` returns `Err` whenever it
        // cannot be built. Propagating that aborted the whole command before
        // the whisper.cpp block below — the one local speech model that *does*
        // run on Windows and Linux, and the one `car speech doctor` tells
        // users to run this command for (car#678). A runtime that could not be
        // provisioned is reported by `speech_health().runtime.installed`,
        // which the CLI prints; it is not a reason to skip the models.
        // `speech.prepare` still fails loudly, since provisioning the runtime
        // is that call's entire job.
        if let Err(error) = self.prepare_speech_runtime().await {
            tracing::warn!(
                %error,
                "managed speech runtime could not be provisioned; installing the \
                 models that do not depend on it"
            );
        }
        let schemas = self.list_schemas();
        let mut repos = Vec::new();
        for schema in &schemas {
            if !schema.is_mlx() || !schema.tags.iter().any(|tag| tag == "speech") {
                continue;
            }
            // MLX runs on Apple Silicon only — the registry marks every MLX
            // schema unavailable elsewhere. Without this the command would
            // pull well over a gigabyte of Kokoro / Parakeet / Qwen3-TTS
            // weights onto a Windows or Linux box that can never load them,
            // which only became reachable once the abort above was removed.
            if !schema.available {
                continue;
            }
            if let ModelSource::Mlx { hf_repo, .. } = &schema.source {
                if !repos.iter().any(|existing: &String| existing == hf_repo) {
                    repos.push(hf_repo.clone());
                }
            }
        }

        let mut installed = Vec::new();
        for repo in repos {
            let (snapshot_path, files_downloaded) = download_hf_repo_snapshot(&repo).await?;
            let name = schemas
                .iter()
                .find(|schema| {
                    matches!(&schema.source, ModelSource::Mlx { hf_repo, .. } if hf_repo == &repo)
                })
                .map(|schema| schema.name.clone())
                .unwrap_or_else(|| repo.clone());
            installed.push(SpeechInstallReport {
                name,
                hf_repo: repo,
                snapshot_path,
                files_downloaded,
            });
        }

        // whisper.cpp catalog entries (cross-platform local STT) fetch their
        // ggml model from ggerganov/whisper.cpp into ~/.tokhn/whisper/ — a
        // different store than the MLX HF snapshots above, so install it here.
        for schema in &schemas {
            if !schema.tags.iter().any(|tag| tag == "speech") {
                continue;
            }
            if let ModelSource::WhisperCpp { model } = &schema.source {
                let model = model.clone();
                let name = schema.name.clone();
                let path = tokio::task::spawn_blocking(move || car_whisper::ensure_model(&model))
                    .await
                    .map_err(|e| InferenceError::InferenceFailed(format!("whisper join: {e}")))?
                    .map_err(|e| {
                        InferenceError::InferenceFailed(format!("whisper model fetch: {e}"))
                    })?;
                installed.push(SpeechInstallReport {
                    name,
                    hf_repo: "ggerganov/whisper.cpp".to_string(),
                    snapshot_path: path,
                    files_downloaded: 1,
                });
            }
        }

        self.unified_registry.refresh_availability();
        Ok(installed)
    }

    /// Report speech runtime, model cache, and remote-provider health.
    pub fn speech_health(&self) -> SpeechHealthReport {
        let local_stt_default =
            self.speech_health_default_name(ModelCapability::SpeechToText, true, false);
        let local_tts_default =
            self.speech_health_default_name(ModelCapability::TextToSpeech, true, false);
        let remote_stt_default =
            self.speech_health_default_name(ModelCapability::SpeechToText, false, true);
        let remote_tts_default =
            self.speech_health_default_name(ModelCapability::TextToSpeech, false, true);

        let mut local_models = Vec::new();
        let mut remote_models = Vec::new();
        for schema in self.list_schemas() {
            let capability = if schema.has_capability(ModelCapability::SpeechToText) {
                Some(ModelCapability::SpeechToText)
            } else if schema.has_capability(ModelCapability::TextToSpeech) {
                Some(ModelCapability::TextToSpeech)
            } else {
                None
            };
            let Some(capability) = capability else {
                continue;
            };

            let selected_by_default = local_stt_default
                .as_ref()
                .is_some_and(|name| name == &schema.name)
                || local_tts_default
                    .as_ref()
                    .is_some_and(|name| name == &schema.name)
                || remote_stt_default
                    .as_ref()
                    .is_some_and(|name| name == &schema.name)
                || remote_tts_default
                    .as_ref()
                    .is_some_and(|name| name == &schema.name);

            let health = SpeechModelHealth {
                id: schema.id.clone(),
                name: schema.name.clone(),
                provider: schema.provider.clone(),
                capability,
                is_local: schema.is_local(),
                available: schema.available,
                cached: speech_model_cached(&schema),
                selected_by_default,
                source: speech_model_source_label(&schema),
            };
            if schema.is_local() {
                local_models.push(health);
            } else {
                remote_models.push(health);
            }
        }

        // Report the real managed-runtime state on every platform. Apple
        // Silicon used to fabricate `installed: true` with empty paths on the
        // theory that native MLX backends replaced the Python runtime — but
        // those backends can't load every catalogued speech checkpoint, so the
        // runtime is a live fallback there too and `car speech doctor` should
        // say whether it is actually present (Parslee-ai/car#640).
        let runtime = {
            let rt =
                SpeechRuntime::new(speech_runtime_root_from_models_dir(&self.config.models_dir));
            SpeechRuntimeHealth {
                root: rt.root.clone(),
                installed: rt.is_ready(),
                python: rt.python.clone(),
                stt_command: rt.stt_program.clone(),
                tts_command: rt.tts_program.clone(),
                configured_python: std::env::var("CAR_SPEECH_PYTHON")
                    .ok()
                    .filter(|value| !value.trim().is_empty()),
                detected_python: detect_speech_python(),
            }
        };

        SpeechHealthReport {
            runtime,
            local_models,
            remote_models,
            elevenlabs_configured: car_secrets::resolve_env_or_keychain("ELEVENLABS_API_KEY")
                .is_some(),
            prefer_local: self.speech_policy.prefer_local,
            allow_remote_fallback: self.speech_policy.allow_remote_fallback,
            preferred_local_stt: self.speech_policy.preferred_local_stt.clone(),
            preferred_local_tts: self.speech_policy.preferred_local_tts.clone(),
            preferred_remote_stt: self.speech_policy.preferred_remote_stt.clone(),
            preferred_remote_tts: self.speech_policy.preferred_remote_tts.clone(),
            local_stt_default,
            local_tts_default,
            remote_stt_default,
            remote_tts_default,
        }
    }

    /// Report the current model catalog, configured defaults, capability coverage,
    /// and speech runtime/provider health in one place.
    pub async fn model_health(&self) -> ModelHealthReport {
        let schemas = self.list_schemas();
        let total_models = schemas.len();
        let available_models = schemas
            .iter()
            .filter(|schema| schema.available_now())
            .count();
        let local_models = schemas.iter().filter(|schema| schema.is_local()).count();
        let remote_models = total_models.saturating_sub(local_models);

        let defaults = vec![
            self.model_default_health(
                ModelCapability::Generate,
                self.preferred_model_for_capability(ModelCapability::Generate)
                    .unwrap_or(&self.config.generation_model),
            ),
            self.model_default_health(
                ModelCapability::Embed,
                self.preferred_model_for_capability(ModelCapability::Embed)
                    .unwrap_or(&self.config.embedding_model),
            ),
            self.model_default_health(
                ModelCapability::Classify,
                self.preferred_model_for_capability(ModelCapability::Classify)
                    .unwrap_or(&self.config.classification_model),
            ),
        ];

        let mut providers = std::collections::BTreeMap::new();
        for schema in &schemas {
            let entry =
                providers
                    .entry(schema.provider.clone())
                    .or_insert_with(|| ProviderAccumulator {
                        configured: false,
                        local_models: 0,
                        remote_models: 0,
                        available_models: 0,
                        capabilities: std::collections::HashSet::new(),
                    });

            entry.configured |= model_source_configured(schema);
            if schema.is_local() {
                entry.local_models += 1;
            } else {
                entry.remote_models += 1;
            }
            if schema.available_now() {
                entry.available_models += 1;
            }
            for capability in &schema.capabilities {
                entry.capabilities.insert(*capability);
            }
        }

        let providers = providers
            .into_iter()
            .map(|(provider, acc)| ModelProviderHealth {
                provider,
                configured: acc.configured,
                local_models: acc.local_models,
                remote_models: acc.remote_models,
                available_models: acc.available_models,
                capabilities: sort_capabilities(acc.capabilities.into_iter().collect()),
            })
            .collect();

        let capabilities = all_model_capabilities()
            .into_iter()
            .map(|capability| {
                let relevant: Vec<&ModelSchema> = schemas
                    .iter()
                    .filter(|schema| schema.has_capability(capability))
                    .collect();
                let available: Vec<&ModelSchema> = relevant
                    .iter()
                    .copied()
                    .filter(|schema| schema.available_now())
                    .collect();
                ModelCapabilityHealth {
                    capability,
                    total_models: relevant.len(),
                    available_models: available.len(),
                    local_available_models: available
                        .iter()
                        .filter(|schema| schema.is_local())
                        .count(),
                    remote_available_models: available
                        .iter()
                        .filter(|schema| !schema.is_local())
                        .count(),
                }
            })
            .collect();

        let routing = self.routing_scenarios().await;
        let routing_config = self.adaptive_router.config().clone();
        let benchmark_priors = load_benchmark_prior_health(&self.config.models_dir, &schemas);

        ModelHealthReport {
            total_models,
            available_models,
            local_models,
            remote_models,
            defaults,
            providers,
            capabilities,
            routing_prefer_local: routing_config.prefer_local,
            routing_quality_first_cold_start: routing_config.quality_first_cold_start,
            routing_min_observations: routing_config.min_observations,
            routing_bootstrap_min_task_observations: routing_config.bootstrap_min_task_observations,
            routing_bootstrap_quality_floor: routing_config.bootstrap_quality_floor,
            routing_quality_weight: routing_config.quality_weight,
            routing_latency_weight: routing_config.latency_weight,
            routing_cost_weight: routing_config.cost_weight,
            routing_scenarios: routing,
            benchmark_priors,
            speech: self.speech_health(),
        }
    }

    async fn routing_scenarios(&self) -> Vec<RoutingScenarioHealth> {
        let tracker = self.outcome_tracker.read().await;
        let config = self.adaptive_router.config().clone();
        let scenarios = [
            (
                "interactive_text",
                "Summarize the benefits of local-first AI routing in two sentences.",
                "text",
                RoutingWorkload::Interactive,
                false,
                false,
            ),
            (
                "background_code",
                "Write a Python function named fibonacci(n) that returns the nth Fibonacci number.",
                "code",
                RoutingWorkload::Background,
                false,
                false,
            ),
            (
                "interactive_tool_use",
                "Use the provided weather tool to get the weather for Boston.",
                "tool_use",
                RoutingWorkload::Interactive,
                true,
                false,
            ),
            (
                "interactive_vision",
                "What is in this image? Answer in one word.",
                "vision",
                RoutingWorkload::Interactive,
                false,
                true,
            ),
        ];

        // Preview against the same live snapshot real routing uses, not the
        // construction-time registry. `self.unified_registry` is frozen at
        // engine construction — on the daemon's long-lived shared engine that
        // means a key connected or a model pulled since boot is invisible here,
        // so this health surface would claim a routing decision that differs
        // from what a real request now takes (the #651 staleness class).
        let routing_registry = self.routing_registry_snapshot();

        scenarios
            .into_iter()
            .map(
                |(name, prompt, task_family, workload, has_tools, has_vision)| {
                    let decision = self.adaptive_router.route_context_aware(
                        prompt,
                        0,
                        &routing_registry,
                        &tracker,
                        has_tools,
                        has_vision,
                        workload,
                    );
                    let quality_first_cold_start = if has_tools || has_vision {
                        config.quality_first_cold_start
                    } else if task_family == "code"
                        && matches!(workload, RoutingWorkload::Background)
                    {
                        false
                    } else {
                        config.quality_first_cold_start
                    };
                    RoutingScenarioHealth {
                        name: name.to_string(),
                        task_family: task_family.to_string(),
                        workload,
                        has_tools,
                        has_vision,
                        prefer_local: if task_family == "speech" {
                            self.speech_policy.prefer_local
                        } else {
                            config.prefer_local
                        },
                        quality_first_cold_start,
                        bootstrap_min_task_observations: config.bootstrap_min_task_observations,
                        bootstrap_quality_floor: config.bootstrap_quality_floor,
                        model_id: decision.model_id,
                        model_name: decision.model_name,
                        reason: decision.reason,
                        strategy: decision.strategy,
                    }
                },
            )
            .collect()
    }

    /// Run a real speech smoke test through the configured local and/or remote paths.
    pub async fn smoke_test_speech(
        &self,
        local: bool,
        remote: bool,
    ) -> Result<SpeechSmokeReport, InferenceError> {
        let mut report = SpeechSmokeReport::default();

        if local {
            let tts = self
                .preferred_speech_schema(ModelCapability::TextToSpeech, true, false)
                .ok_or_else(|| {
                    InferenceError::InferenceFailed(
                        "no local text-to-speech model available".into(),
                    )
                })?;
            let stt = self
                .preferred_speech_schema(ModelCapability::SpeechToText, true, false)
                .ok_or_else(|| {
                    InferenceError::InferenceFailed(
                        "no local speech-to-text model available".into(),
                    )
                })?;
            report.local = Some(
                self.run_speech_smoke_path("local", &tts, &stt, "Testing CAR local speech path.")
                    .await?,
            );
        } else {
            report.skipped.push("local".to_string());
        }

        if remote {
            let tts = self
                .preferred_speech_schema(ModelCapability::TextToSpeech, false, true)
                .ok_or_else(|| {
                    InferenceError::InferenceFailed(
                        "no remote text-to-speech model available".into(),
                    )
                })?;
            let stt = self
                .preferred_speech_schema(ModelCapability::SpeechToText, false, true)
                .ok_or_else(|| {
                    InferenceError::InferenceFailed(
                        "no remote speech-to-text model available".into(),
                    )
                })?;
            report.remote = Some(
                self.run_speech_smoke_path("remote", &tts, &stt, "Testing CAR remote speech path.")
                    .await?,
            );
        } else {
            report.skipped.push("remote".to_string());
        }

        Ok(report)
    }

    fn speech_candidates(
        &self,
        capability: ModelCapability,
        explicit: Option<&str>,
    ) -> Result<Vec<ModelSchema>, InferenceError> {
        if let Some(model) = explicit {
            let schema = self
                .unified_registry
                .get(model)
                .or_else(|| self.unified_registry.find_by_name(model))
                .cloned()
                .ok_or_else(|| InferenceError::ModelNotFound(model.to_string()))?;
            if !schema.has_capability(capability) {
                return Err(InferenceError::InferenceFailed(format!(
                    "model {} does not support {:?}",
                    schema.name, capability
                )));
            }
            return Ok(vec![schema]);
        }

        let mut candidates: Vec<ModelSchema> = self
            .unified_registry
            .query(&ModelFilter {
                capabilities: vec![capability],
                ..Default::default()
            })
            .into_iter()
            .cloned()
            .collect();

        if candidates.is_empty() {
            return Err(InferenceError::InferenceFailed(format!(
                "no models registered for capability {:?}",
                capability
            )));
        }

        candidates.sort_by_key(|model| self.speech_sort_key(capability, model));
        if !self.speech_policy.allow_remote_fallback
            && candidates.iter().any(|model| model.is_local())
        {
            candidates.retain(|model| model.is_local());
        }

        Ok(candidates)
    }

    /// Resolve a car-canonical model id (e.g. `mlx/flux-1-lite-8b:q4`) to the
    /// HuggingFace repo (`mlx-community/Flux-1.lite-8B-MLX-Q4`) that the
    /// external Python CLIs expect. Falls back to the input if no schema
    /// matches or the schema is not MLX-sourced.
    #[allow(dead_code)] // conditionally compiled — used only on external-agent HF resolution paths
    fn resolve_external_hf_repo(
        &self,
        explicit: Option<&str>,
        capability: ModelCapability,
    ) -> Option<String> {
        let id = explicit?;
        let schema = self
            .unified_registry
            .get(id)
            .or_else(|| self.unified_registry.find_by_name(id))?;
        if !schema.has_capability(capability) {
            return Some(id.to_string());
        }
        if let ModelSource::Mlx { hf_repo, .. } = &schema.source {
            return Some(hf_repo.clone());
        }
        Some(id.to_string())
    }

    fn media_generation_candidates(
        &self,
        capability: ModelCapability,
        explicit: Option<&str>,
    ) -> Result<Vec<ModelSchema>, InferenceError> {
        if let Some(model) = explicit {
            let schema = self
                .unified_registry
                .get(model)
                .or_else(|| self.unified_registry.find_by_name(model))
                .cloned()
                .ok_or_else(|| InferenceError::ModelNotFound(model.to_string()))?;
            if !schema.has_capability(capability) {
                return Err(InferenceError::InferenceFailed(format!(
                    "model {} does not support {:?}",
                    schema.name, capability
                )));
            }
            return Ok(vec![schema]);
        }

        let mut candidates: Vec<ModelSchema> = self
            .unified_registry
            .query(&ModelFilter {
                capabilities: vec![capability],
                local_only: true,
                ..Default::default()
            })
            .into_iter()
            .cloned()
            .collect();
        candidates.sort_by_key(|schema| (!schema.available, schema.size_mb()));
        if candidates.is_empty() {
            return Err(InferenceError::InferenceFailed(format!(
                "no models registered for capability {:?}",
                capability
            )));
        }
        Ok(candidates)
    }

    fn preferred_speech_schema(
        &self,
        capability: ModelCapability,
        local_only: bool,
        remote_only: bool,
    ) -> Option<ModelSchema> {
        let available_only = remote_only;
        let mut candidates: Vec<ModelSchema> = self
            .unified_registry
            .query(&ModelFilter {
                capabilities: vec![capability],
                available_only,
                ..Default::default()
            })
            .into_iter()
            .filter(|schema| {
                (!local_only || schema.is_local()) && (!remote_only || schema.is_remote())
            })
            .cloned()
            .collect();
        candidates.sort_by_key(|model| self.speech_sort_key(capability, model));
        candidates.into_iter().next()
    }

    fn speech_health_default_name(
        &self,
        capability: ModelCapability,
        local_only: bool,
        remote_only: bool,
    ) -> Option<String> {
        let preferred = match capability {
            ModelCapability::SpeechToText if local_only => {
                self.speech_policy.preferred_local_stt.as_ref()
            }
            ModelCapability::SpeechToText if remote_only => {
                self.speech_policy.preferred_remote_stt.as_ref()
            }
            ModelCapability::TextToSpeech if local_only => {
                self.speech_policy.preferred_local_tts.as_ref()
            }
            ModelCapability::TextToSpeech if remote_only => {
                self.speech_policy.preferred_remote_tts.as_ref()
            }
            _ => None,
        };

        preferred
            .filter(|name| {
                self.unified_registry.list().iter().any(|schema| {
                    schema.name == **name
                        && schema.has_capability(capability)
                        && (!local_only || schema.is_local())
                        && (!remote_only || schema.is_remote())
                })
            })
            .cloned()
            .or_else(|| {
                self.preferred_speech_schema(capability, local_only, remote_only)
                    .map(|schema| schema.name)
            })
    }

    fn model_default_health(
        &self,
        capability: ModelCapability,
        configured_model: &str,
    ) -> ModelDefaultHealth {
        let schema = self
            .unified_registry
            .find_by_name(configured_model)
            .or_else(|| self.unified_registry.get(configured_model));

        ModelDefaultHealth {
            capability,
            configured_model: configured_model.to_string(),
            available: schema.is_some_and(ModelSchema::available_now),
            is_local: schema.is_some_and(ModelSchema::is_local),
            provider: schema.map(|model| model.provider.clone()),
        }
    }

    fn speech_sort_key(
        &self,
        capability: ModelCapability,
        model: &ModelSchema,
    ) -> (u8, u8, u8, u8, u64, u64) {
        let policy_preference = match capability {
            ModelCapability::SpeechToText if model.is_local() => {
                self.speech_policy.preferred_local_stt.as_ref()
            }
            ModelCapability::SpeechToText => self.speech_policy.preferred_remote_stt.as_ref(),
            ModelCapability::TextToSpeech if model.is_local() => {
                self.speech_policy.preferred_local_tts.as_ref()
            }
            ModelCapability::TextToSpeech => self.speech_policy.preferred_remote_tts.as_ref(),
            _ => None,
        };
        let local_rank = if self.speech_policy.prefer_local {
            if model.is_local() {
                0
            } else {
                1
            }
        } else if model.is_remote() {
            0
        } else {
            1
        };
        let availability_rank = if model.available {
            0
        } else if model.is_local() {
            1
        } else {
            2
        };
        let policy_rank: u8 = if policy_preference.is_some_and(|preferred| preferred == &model.name)
        {
            0
        } else {
            1
        };
        let speech_rank = match capability {
            // Kokoro first, deliberately. `Qwen3-TTS-12Hz-1.7B-Base-5bit` used
            // to rank 0 here, but CAR has **no Qwen3-TTS backend** — the only
            // local MLX TTS loaders are `backend::mlx_kokoro` and
            // `backend::mlx_parakeet`, and the TTS path calls
            // `KokoroBackend::load` unconditionally. Preferring Qwen3-TTS
            // therefore fed Qwen3 weights to Kokoro's architecture and every
            // synthesis died on `missing tensor:
            // bert.embeddings.word_embeddings.weight`, so local TTS never
            // worked at all (Parslee-ai/car#640).
            //
            // Ranking follows what can actually be loaded. Restore Qwen3-TTS to
            // the front when a backend for it exists — its advanced controls
            // (voice cloning, `voice_instruction`) are already modelled in
            // `SynthesizeRequest` and are worth preferring once loadable.
            ModelCapability::TextToSpeech => {
                if model.name == "Kokoro-82M-bf16" {
                    0
                } else if model.name == "Kokoro-82M-6bit" {
                    1
                } else if model.name == "Qwen3-TTS-12Hz-1.7B-Base-5bit" {
                    // Last among curated TTS: cataloged and downloadable, but
                    // not loadable until it has a backend.
                    3
                } else {
                    2
                }
            }
            ModelCapability::SpeechToText => {
                if model.name == "Parakeet-TDT-0.6B-v3-MLX" {
                    0
                } else {
                    1
                }
            }
            _ => 0,
        };
        let latency_rank = model.performance.latency_p50_ms.unwrap_or(u64::MAX);
        let size_rank = model.cost.size_mb.unwrap_or(u64::MAX);
        (
            local_rank,
            availability_rank,
            policy_rank,
            speech_rank,
            latency_rank,
            size_rank,
        )
    }

    async fn run_speech_smoke_path(
        &self,
        path: &str,
        tts: &ModelSchema,
        stt: &ModelSchema,
        text: &str,
    ) -> Result<SpeechSmokePathReport, InferenceError> {
        let work_dir = temp_work_dir(&format!("speech-smoke-{path}"))?;
        let audio_path = work_dir.join(format!("{path}.wav"));
        let synth = self
            .synthesize(SynthesizeRequest {
                text: text.to_string(),
                model: Some(tts.name.clone()),
                voice: default_speech_voice(tts),
                language: Some("en".to_string()),
                output_path: Some(audio_path.display().to_string()),
                ..SynthesizeRequest::default()
            })
            .await?;
        let transcript = self
            .transcribe(TranscribeRequest {
                audio_path: synth.audio_path.clone(),
                model: Some(stt.name.clone()),
                language: Some("en".to_string()),
                prompt: None,
                timestamps: false,
            })
            .await?;

        Ok(SpeechSmokePathReport {
            path: path.to_string(),
            tts_model: synth.model_used.unwrap_or_else(|| tts.name.clone()),
            stt_model: transcript.model_used.unwrap_or_else(|| stt.name.clone()),
            audio_path: PathBuf::from(synth.audio_path),
            transcript: transcript.text,
        })
    }

    async fn ensure_speech_runtime(&self) -> Result<SpeechRuntime, InferenceError> {
        let mut guard = self.speech_runtime.lock().await;
        if let Some(runtime) = guard.as_ref() {
            if runtime.is_ready() {
                return Ok(runtime.clone());
            }
        }

        let runtime =
            SpeechRuntime::new(speech_runtime_root_from_models_dir(&self.config.models_dir));
        if !runtime.is_ready() {
            bootstrap_speech_runtime(&runtime).await?;
        }
        if !runtime.is_ready() {
            return Err(InferenceError::InferenceFailed(format!(
                "managed speech runtime is not ready at {}",
                runtime.root.display()
            )));
        }

        *guard = Some(runtime.clone());
        Ok(runtime)
    }

    /// Transcribe an audio file with the in-process whisper.cpp backend — the
    /// cross-platform on-device STT (`ModelSource::WhisperCpp`) that the `car
    /// speech` catalog offers where MLX isn't available. The ggml model
    /// lazy-downloads on first use via `car-whisper`. Runs on a blocking pool
    /// (whisper.cpp is synchronous + CPU/GPU-bound).
    ///
    /// NB: loads the model per call for now — a resident-context cache is a
    /// follow-up; the catalog STT path is setup/smoke/occasional, not hot.
    async fn transcribe_whisper(
        &self,
        schema: &ModelSchema,
        model: &str,
        req: &TranscribeRequest,
    ) -> Result<TranscribeResult, InferenceError> {
        let model = model.to_string();
        // whisper.cpp accepts "auto" for language auto-detection.
        let language = req.language.clone().unwrap_or_else(|| "auto".to_string());
        let audio_path = std::path::PathBuf::from(&req.audio_path);
        let name = schema.name.clone();
        let req_language = req.language.clone();
        let text = tokio::task::spawn_blocking(move || -> Result<String, InferenceError> {
            let stt = car_whisper::WhisperStt::load(&model, &language)
                .map_err(|e| InferenceError::InferenceFailed(format!("whisper load: {e}")))?;
            stt.transcribe_file(&audio_path)
                .map_err(|e| InferenceError::InferenceFailed(format!("whisper transcribe: {e}")))
        })
        .await
        .map_err(|e| InferenceError::InferenceFailed(format!("whisper join: {e}")))??;
        Ok(TranscribeResult::text_only(text, Some(name), req_language))
    }

    async fn transcribe_local_mlx(
        &self,
        schema: &ModelSchema,
        req: &TranscribeRequest,
    ) -> Result<TranscribeResult, InferenceError> {
        // Native MLX transcription via Parakeet backend (no Python shelling).
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        {
            let model_dir = self.unified_registry.ensure_local(&schema.id).await?;
            // Same story as TTS: the native backend can't load every catalogued
            // STT checkpoint, so hand off to the managed mlx-audio runtime
            // instead of failing outright (Parslee-ai/car#640).
            let parakeet = match backend::mlx_parakeet::ParakeetBackend::load(&model_dir) {
                Ok(p) => p,
                Err(native_err) => {
                    tracing::info!(
                        model = %schema.name,
                        error = %native_err,
                        "native MLX STT backend can't load this model; \
                         falling back to the managed mlx-audio runtime"
                    );
                    return self
                        .transcribe_via_speech_runtime(schema, req)
                        .await
                        .map_err(|runtime_err| {
                            InferenceError::InferenceFailed(format!(
                                "native MLX backend failed ({native_err}); \
                                 mlx-audio runtime fallback also failed ({runtime_err}). \
                                 Install the runtime with `car speech install`."
                            ))
                        });
                }
            };
            // Only pay the word-grouping cost when the caller asked.
            let (text, words) = if req.timestamps {
                parakeet
                    .transcribe_detailed(Path::new(&req.audio_path))
                    .map_err(|e| InferenceError::InferenceFailed(format!("native STT: {e}")))?
            } else {
                let t = parakeet
                    .transcribe(Path::new(&req.audio_path))
                    .map_err(|e| InferenceError::InferenceFailed(format!("native STT: {e}")))?;
                (t, Vec::new())
            };
            Ok(TranscribeResult {
                text,
                model_used: Some(schema.name.clone()),
                language: req.language.clone(),
                words,
            })
        }

        // Non-Apple-Silicon: the Python speech runtime is the only path.
        #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
        {
            self.transcribe_via_speech_runtime(schema, req).await
        }
    }

    /// Transcribe through the managed `mlx-audio` Python runtime.
    ///
    /// Twin of [`Self::synthesize_via_speech_runtime`], and available on every
    /// platform for the same reason: the native MLX Parakeet backend cannot load
    /// the shipped checkpoint (`missing tensor: encoder.layers.0.ff1.norm.weight`),
    /// so without this local STT is dead on Apple Silicon (Parslee-ai/car#640).
    async fn transcribe_via_speech_runtime(
        &self,
        schema: &ModelSchema,
        req: &TranscribeRequest,
    ) -> Result<TranscribeResult, InferenceError> {
        {
            let runtime = self.ensure_speech_runtime().await?;
            let hf_repo = match &schema.source {
                ModelSource::Mlx { hf_repo, .. } => hf_repo.clone(),
                _ => {
                    return Err(InferenceError::InferenceFailed(format!(
                        "speech runtime needs an MLX model repo; {} is not one",
                        schema.id
                    )))
                }
            };
            let output_dir = temp_work_dir("stt")?;
            let output_prefix = output_dir.join("transcript");
            let mut args = vec![
                "--model".to_string(),
                hf_repo,
                "--audio".to_string(),
                req.audio_path.clone(),
                "--output-path".to_string(),
                output_prefix.display().to_string(),
                "--format".to_string(),
                "json".to_string(),
            ];
            if let Some(language) = &req.language {
                args.push("--language".to_string());
                args.push(normalize_lang_code(language));
            }
            if let Some(prompt) = &req.prompt {
                args.push("--context".to_string());
                args.push(prompt.clone());
            }
            if req.timestamps {
                args.push("--verbose".to_string());
            }

            let output = run_mlx_audio_command(&runtime, "stt.generate", &args).await?;
            let text = read_transcription_result(&output_prefix)?
                .or_else(|| extract_text_from_payload(&output.stdout))
                .ok_or_else(|| {
                    InferenceError::InferenceFailed(format!(
                        "mlx-audio transcription returned no text: {}",
                        output.stderr
                    ))
                })?;

            Ok(TranscribeResult {
                text,
                model_used: Some(schema.name.clone()),
                language: req.language.clone(),
                words: Vec::new(),
            })
        }
    }

    async fn synthesize_local_mlx(
        &self,
        schema: &ModelSchema,
        req: &SynthesizeRequest,
    ) -> Result<SynthesizeResult, InferenceError> {
        // Single entry-point check for Qwen3-TTS advanced controls.
        // Hoisted here so that a Kokoro → Kokoro-bf16 fallback chain
        // doesn't double-warn, and so strict callers get one clean
        // error instead of being lied to by partial success.
        let requested = req.requested_advanced_controls();
        let repo_supports_advanced = match &schema.source {
            ModelSource::Mlx { hf_repo, .. } => hf_repo.to_ascii_lowercase().contains("qwen3-tts"),
            _ => false,
        };
        if !requested.is_empty() && !repo_supports_advanced {
            if req.strict_capabilities {
                return Err(InferenceError::InferenceFailed(format!(
                    "model {name} does not support Qwen3-TTS advanced controls {requested:?}; \
                     route to a Qwen3-TTS model or set strict_capabilities = false to degrade",
                    name = schema.name,
                )));
            }
            tracing::warn!(
                model = %schema.name,
                fields = ?requested,
                "Qwen3-TTS advanced controls set on non-Qwen3-TTS backend — ignored \
                 (set strict_capabilities=true to error instead)"
            );
        }

        // Native MLX synthesis via Kokoro backend (no Python shelling).
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        {
            // The native Apple-Silicon path is Kokoro-only today; a
            // Qwen3-TTS schema would have routed here but the backend
            // has no cloning support yet. Strict callers are already
            // stopped above; degrade-ok callers get a second, narrower
            // note about the native-vs-Python capability gap.
            if repo_supports_advanced && !requested.is_empty() {
                if req.strict_capabilities {
                    return Err(InferenceError::InferenceFailed(format!(
                        "native MLX TTS backend does not yet implement Qwen3-TTS advanced \
                         controls {requested:?}; run on non-Apple-Silicon to use the Python \
                         mlx-audio fallback, or set strict_capabilities = false"
                    )));
                }
                tracing::warn!(
                    model = %schema.name,
                    fields = ?requested,
                    "Qwen3-TTS advanced controls are not yet implemented in the native MLX TTS \
                     backend; synthesizing without cloning/voice-design"
                );
            }
            let model_dir = self.unified_registry.ensure_local(&schema.id).await?;
            let size = backend_cache::estimate_model_size(&model_dir);
            let handle = match Self::load_backend_healing(
                &schema.id,
                model_dir,
                &self.kokoro_cache,
                size,
                backend::mlx_kokoro::KokoroBackend::load,
                || self.unified_registry.redownload_local(&schema.id),
            )
            .await
            {
                Ok(handle) => handle,
                // The native MLX backend can't serve every catalogued TTS model
                // — it implements a plain iSTFTNet vocoder, while Kokoro's
                // shipped checkpoint is StyleTTS2 and Qwen3-TTS has no backend
                // at all (Parslee-ai/car#640). Rather than fail outright, hand
                // off to the managed `mlx-audio` runtime, which is upstream's
                // own implementation and loads all of them. Mirrors the
                // native/external split `generate_image` uses for Flux.
                Err(native_err) => {
                    tracing::info!(
                        model = %schema.name,
                        error = %native_err,
                        "native MLX TTS backend can't load this model; \
                         falling back to the managed mlx-audio runtime"
                    );
                    return self
                        .synthesize_via_speech_runtime(schema, req)
                        .await
                        .map_err(|runtime_err| {
                            InferenceError::InferenceFailed(format!(
                                "native MLX backend failed ({native_err}); \
                                 mlx-audio runtime fallback also failed ({runtime_err}). \
                                 Install the runtime with `car speech install`."
                            ))
                        });
                }
            };

            let output_path = req.output_path.clone().unwrap_or_else(|| {
                let dir = std::env::temp_dir().join("car_tts");
                let _ = std::fs::create_dir_all(&dir);
                dir.join("output.wav").display().to_string()
            });
            let voice = req.voice.as_deref().unwrap_or("af_heart").to_string();
            let text = req.text.clone();
            // Serialize on the shared Metal device (see `mlx_device_lock`): a
            // kokoro eval concurrent with a flux/ltx eval races the command
            // encoder and segfaults the process. The per-model `handle.lock()`
            // alone does not prevent a cross-model device race. Held inside the
            // blocking closure so it survives request-deadline abandonment.
            let device_guard = Self::mlx_device_lock().lock_owned().await;
            let op = tokio::task::spawn_blocking(move || -> Result<PathBuf, InferenceError> {
                let _device_guard = device_guard;
                let mut guard = handle.lock().map_err(|_| {
                    InferenceError::InferenceFailed("kokoro backend mutex poisoned".into())
                })?;
                guard
                    .synthesize(&text, Some(&voice), Path::new(&output_path))
                    .map_err(|e| InferenceError::InferenceFailed(format!("native TTS: {e}")))
            })
            .await
            .map_err(|e| InferenceError::InferenceFailed(format!("kokoro task join: {e}")))??;

            let final_path =
                materialize_audio_output(&op, req.output_path.as_deref(), &req.format)?;
            Ok(SynthesizeResult {
                audio_path: final_path.display().to_string(),
                media_type: media_type_for_format(&req.format),
                model_used: Some(schema.name.clone()),
                voice_used: req.voice.clone(),
            })
        }

        // Non-Apple-Silicon: the Python speech runtime is the only path.
        #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
        {
            self.synthesize_via_speech_runtime(schema, req).await
        }
    }

    /// Synthesize through the managed `mlx-audio` Python runtime.
    ///
    /// This is upstream's own Kokoro implementation, so it is the reference for
    /// what local TTS should sound like. It was the only path on non-Apple
    /// platforms and was compiled out on Apple Silicon, which assumed the native
    /// MLX backend worked; that backend implements a plain iSTFTNet vocoder while
    /// Kokoro is StyleTTS2 (AdaIN conditioning, Snake activations, a
    /// harmonic-plus-noise source), so it can't load the shipped checkpoint and
    /// local TTS was dead on macOS (Parslee-ai/car#640). Now available on every
    /// platform, as the fallback when the native backend can't serve a model —
    /// the same native/external split `generate_image` already uses for Flux
    /// vs. mflux.
    async fn synthesize_via_speech_runtime(
        &self,
        schema: &ModelSchema,
        req: &SynthesizeRequest,
    ) -> Result<SynthesizeResult, InferenceError> {
        let runtime = self.ensure_speech_runtime().await?;
        let primary_hf_repo = match &schema.source {
            ModelSource::Mlx { hf_repo, .. } => hf_repo.clone(),
            _ => {
                return Err(InferenceError::InferenceFailed(format!(
                    "speech runtime needs an MLX model repo; {} is not one",
                    schema.id
                )))
            }
        };
        let (produced, model_used) = match self
            .synthesize_local_mlx_repo(&runtime, &primary_hf_repo, schema.name.as_str(), req)
            .await
        {
            Ok(result) => result,
            Err(primary_err)
                if primary_hf_repo == "mlx-community/Kokoro-82M-6bit"
                    && kokoro_runtime_fallback_enabled() =>
            {
                let fallback_repo = "mlx-community/Kokoro-82M-bf16";
                let fallback_name = "Kokoro-82M-bf16";
                match self
                    .synthesize_local_mlx_repo(&runtime, fallback_repo, fallback_name, req)
                    .await
                {
                    Ok(result) => result,
                    Err(fallback_err) => {
                        return Err(InferenceError::InferenceFailed(format!(
                            "{primary_err}; fallback {fallback_name} also failed: {fallback_err}"
                        )));
                    }
                }
            }
            Err(err) => return Err(err),
        };
        let final_path =
            materialize_audio_output(&produced, req.output_path.as_deref(), &req.format)?;

        Ok(SynthesizeResult {
            audio_path: final_path.display().to_string(),
            media_type: media_type_for_format(&req.format),
            model_used: Some(model_used),
            voice_used: req.voice.clone(),
        })
    }

    async fn synthesize_local_mlx_repo(
        &self,
        runtime: &SpeechRuntime,
        hf_repo: &str,
        model_name: &str,
        req: &SynthesizeRequest,
    ) -> Result<(PathBuf, String), InferenceError> {
        let output_dir = temp_work_dir("tts")?;
        let mut args = vec![
            "--model".to_string(),
            hf_repo.to_string(),
            "--text".to_string(),
            req.text.clone(),
            "--output_path".to_string(),
            output_dir.display().to_string(),
        ];
        if let Some(voice) = &req.voice {
            args.push("--voice".to_string());
            args.push(voice.clone());
        }
        if let Some(speed) = req.speed {
            args.push("--speed".to_string());
            args.push(speed.to_string());
        }
        let repo_lower = hf_repo.to_ascii_lowercase();
        if repo_lower.contains("kokoro") {
            args.push("--lang_code".to_string());
            args.push(kokoro_lang_code(req.language.as_deref()).to_string());
        } else if let Some(language) = &req.language {
            args.push("--lang_code".to_string());
            args.push(normalize_lang_code(language));
        }

        // Qwen3-TTS advanced controls — reference-audio cloning and
        // voice-design natural-language instruction. The
        // supported/unsupported decision was already made at the
        // `synthesize_local_mlx` entry point; here we only need to
        // forward the flags to the mlx-audio CLI for Qwen3-TTS repos.
        if repo_lower.contains("qwen3-tts") {
            if let Some(ref_audio) = &req.reference_audio_path {
                args.push("--ref_audio".to_string());
                args.push(ref_audio.clone());
            }
            if let Some(ref_text) = &req.reference_text {
                args.push("--ref_text".to_string());
                args.push(ref_text.clone());
            }
            if let Some(instruct) = &req.voice_instruction {
                args.push("--instruct".to_string());
                args.push(instruct.clone());
            }
        }

        let output = if repo_lower.contains("kokoro") {
            let device = std::env::var("CAR_SPEECH_KOKORO_DEVICE")
                .or_else(|_| std::env::var("CAR_SPEECH_MLX_DEVICE"))
                .unwrap_or_else(|_| "cpu".to_string());
            let extra_env = vec![
                // Force MLX device (defaults to CPU to avoid Metal/NSRangeException crashes)
                ("MLX_DEVICE".to_string(), device),
                // Prevent MPS/Metal kernel crashes by enabling CPU fallback
                ("PYTORCH_ENABLE_MPS_FALLBACK".to_string(), "1".to_string()),
            ];
            run_mlx_audio_command_with_env(runtime, "tts.generate", &args, &extra_env).await?
        } else {
            run_mlx_audio_command(runtime, "tts.generate", &args).await?
        };
        let produced = find_audio_file(&output_dir)?.ok_or_else(|| {
            let hint = if repo_lower.contains("kokoro") {
                ". Kokoro models may crash on GPU — try CAR_SPEECH_KOKORO_DEVICE=cpu or use the default Qwen3-TTS model"
            } else {
                ""
            };
            InferenceError::InferenceFailed(format!(
                "mlx-audio synthesis produced no audio file: {}{}",
                output.stderr, hint
            ))
        })?;
        Ok((produced, model_name.to_string()))
    }

    async fn transcribe_elevenlabs(
        &self,
        schema: &ModelSchema,
        req: &TranscribeRequest,
    ) -> Result<TranscribeResult, InferenceError> {
        let (endpoint, api_key) = elevenlabs_auth(schema)?;
        let file_name = Path::new(&req.audio_path)
            .file_name()
            .and_then(|f| f.to_str())
            .unwrap_or("audio.wav")
            .to_string();
        let audio_bytes = tokio::fs::read(&req.audio_path).await?;
        let file_part = Part::bytes(audio_bytes).file_name(file_name);
        let mut form = Form::new()
            .text("model_id", schema.name.clone())
            .part("file", file_part);
        if let Some(language) = &req.language {
            form = form.text("language_code", language.clone());
        }

        let resp = self
            .remote_backend
            .client
            .post(format!(
                "{}/v1/speech-to-text",
                endpoint.trim_end_matches('/')
            ))
            .header("xi-api-key", api_key)
            .multipart(form)
            .send()
            .await
            .map_err(|e| {
                self.remote_backend
                    .request_error("ElevenLabs STT request failed", &e)
            })?;
        let status = resp.status();
        let body = resp.text().await.map_err(|e| {
            InferenceError::InferenceFailed(format!("read ElevenLabs STT body: {e}"))
        })?;
        if !status.is_success() {
            return Err(InferenceError::InferenceFailed(format!(
                "ElevenLabs STT returned {status}: {body}"
            )));
        }
        let payload: serde_json::Value = serde_json::from_str(&body).map_err(|e| {
            InferenceError::InferenceFailed(format!("parse ElevenLabs STT response: {e}"))
        })?;
        let text = payload
            .get("text")
            .and_then(|v| v.as_str())
            .map(str::to_string)
            .ok_or_else(|| {
                InferenceError::InferenceFailed("ElevenLabs STT response missing text".into())
            })?;

        Ok(TranscribeResult {
            text,
            model_used: Some(schema.name.clone()),
            language: payload
                .get("language_code")
                .and_then(|v| v.as_str())
                .map(str::to_string),
            words: Vec::new(),
        })
    }

    async fn synthesize_elevenlabs(
        &self,
        schema: &ModelSchema,
        req: &SynthesizeRequest,
    ) -> Result<SynthesizeResult, InferenceError> {
        // ElevenLabs doesn't expose a Qwen3-TTS-style cloning or
        // voice-design surface on its `/v1/text-to-speech` endpoint;
        // honor the strict_capabilities contract here too.
        let requested = req.requested_advanced_controls();
        if !requested.is_empty() {
            if req.strict_capabilities {
                return Err(InferenceError::InferenceFailed(format!(
                    "ElevenLabs backend does not support Qwen3-TTS advanced controls \
                     {requested:?}; route to a Qwen3-TTS model or set strict_capabilities = false"
                )));
            }
            tracing::warn!(
                model = %schema.name,
                fields = ?requested,
                "Qwen3-TTS advanced controls ignored by ElevenLabs backend"
            );
        }
        let (endpoint, api_key) = elevenlabs_auth(schema)?;
        let voice_id = req
            .voice
            .clone()
            .unwrap_or_else(|| "JBFqnCBsd6RMkjVDRZzb".to_string());
        let output_format = elevenlabs_output_format(&req.format);
        let url = format!(
            "{}/v1/text-to-speech/{}?output_format={}",
            endpoint.trim_end_matches('/'),
            voice_id,
            output_format
        );

        let mut body = serde_json::json!({
            "text": req.text,
            "model_id": schema.name,
        });
        if let Some(language) = &req.language {
            body["language_code"] = serde_json::Value::String(language.clone());
        }

        let resp = self
            .remote_backend
            .client
            .post(url)
            .header("xi-api-key", api_key)
            .header("Content-Type", "application/json")
            .json(&body)
            .send()
            .await
            .map_err(|e| {
                self.remote_backend
                    .request_error("ElevenLabs TTS request failed", &e)
            })?;
        let status = resp.status();
        let audio = resp.bytes().await.map_err(|e| {
            InferenceError::InferenceFailed(format!("read ElevenLabs TTS body: {e}"))
        })?;
        if !status.is_success() {
            let err_body = String::from_utf8_lossy(&audio);
            return Err(InferenceError::InferenceFailed(format!(
                "ElevenLabs TTS returned {status}: {err_body}"
            )));
        }

        let final_path = requested_or_temp_output(req.output_path.as_deref(), &req.format)?;
        ensure_parent_dir(&final_path)?;
        tokio::fs::write(&final_path, &audio).await?;

        Ok(SynthesizeResult {
            audio_path: final_path.display().to_string(),
            media_type: media_type_for_format(&req.format),
            model_used: Some(schema.name.clone()),
            voice_used: Some(voice_id),
        })
    }
}

#[derive(Default)]
struct ProviderAccumulator {
    configured: bool,
    local_models: usize,
    remote_models: usize,
    available_models: usize,
    capabilities: std::collections::HashSet<ModelCapability>,
}

// ─── Python Speech Runtime (non-Apple-Silicon only) ──────────────────────────
// On Apple Silicon, speech uses native MLX backends (mlx_parakeet, mlx_kokoro).

struct CommandOutput {
    stdout: String,
    stderr: String,
}

#[derive(Debug, Clone)]
struct SpeechRuntime {
    root: PathBuf,
    python: PathBuf,
    stt_program: PathBuf,
    tts_program: PathBuf,
}

impl SpeechRuntime {
    fn new(root: PathBuf) -> Self {
        let bin_dir = root.join("bin");
        Self {
            root,
            python: bin_dir.join("python"),
            stt_program: bin_dir.join("mlx_audio.stt.generate"),
            tts_program: bin_dir.join("mlx_audio.tts.generate"),
        }
    }

    fn is_ready(&self) -> bool {
        self.python.exists() && self.stt_program.exists() && self.tts_program.exists()
    }

    fn command_for(&self, subcommand: &str) -> Result<&Path, InferenceError> {
        match subcommand {
            "stt.generate" => Ok(&self.stt_program),
            "tts.generate" => Ok(&self.tts_program),
            _ => Err(InferenceError::InferenceFailed(format!(
                "unknown speech subcommand: {subcommand}"
            ))),
        }
    }
}

async fn run_mlx_audio_command(
    runtime: &SpeechRuntime,
    subcommand: &str,
    args: &[String],
) -> Result<CommandOutput, InferenceError> {
    run_mlx_audio_command_with_env(runtime, subcommand, args, &[]).await
}

async fn run_mlx_audio_command_with_env(
    runtime: &SpeechRuntime,
    subcommand: &str,
    args: &[String],
    envs: &[(String, String)],
) -> Result<CommandOutput, InferenceError> {
    let program = runtime.command_for(subcommand)?;
    let mut command = Command::new(program);
    command.args(args);
    for (key, value) in envs {
        command.env(key, value);
    }
    let output = command
        .output()
        .await
        .map_err(|err| InferenceError::InferenceFailed(format!("{}: {err}", program.display())))?;

    if output.status.success() {
        Ok(CommandOutput {
            stdout: String::from_utf8_lossy(&output.stdout).to_string(),
            stderr: String::from_utf8_lossy(&output.stderr).to_string(),
        })
    } else {
        Err(InferenceError::InferenceFailed(format!(
            "{} exited with {}: {}",
            program.display(),
            output.status,
            String::from_utf8_lossy(&output.stderr)
        )))
    }
}

async fn bootstrap_speech_runtime(runtime: &SpeechRuntime) -> Result<(), InferenceError> {
    std::fs::create_dir_all(&runtime.root)?;
    let python = select_speech_python()?;

    run_command(
        "uv",
        &[
            "venv".to_string(),
            "--python".to_string(),
            python,
            runtime.root.display().to_string(),
        ],
    )
    .await?;

    run_command(
        "uv",
        &[
            "pip".to_string(),
            "install".to_string(),
            "--python".to_string(),
            runtime.python.display().to_string(),
            speech_runtime_mlx_audio_spec(),
            "misaki[en]".to_string(),
            speech_runtime_spacy_model_spec(),
        ],
    )
    .await?;

    Ok(())
}

async fn run_command(program: &str, args: &[String]) -> Result<(), InferenceError> {
    let output = Command::new(program)
        .args(args)
        .output()
        .await
        .map_err(|err| InferenceError::InferenceFailed(format!("{program}: {err}")))?;

    if output.status.success() {
        Ok(())
    } else {
        Err(InferenceError::InferenceFailed(format!(
            "{} exited with {}: {}",
            program,
            output.status,
            String::from_utf8_lossy(&output.stderr)
        )))
    }
}

fn select_speech_python() -> Result<String, InferenceError> {
    if let Ok(path) = std::env::var("CAR_SPEECH_PYTHON") {
        if !path.trim().is_empty() {
            return Ok(path);
        }
    }

    for candidate in ["python3.13", "python3.12", "python3.11"] {
        if command_in_path(candidate) {
            return Ok(candidate.to_string());
        }
    }

    // Nothing supported on PATH — hand `uv` a bare version instead of a binary
    // name and let it provision one. `uv venv --python 3.12` downloads and
    // manages the interpreter itself, and uv is already a hard prerequisite of
    // this bootstrap, so this adds no new dependency.
    //
    // Without this, a machine whose only Python is newer than the supported
    // range (e.g. 3.14, which mlx-audio does not yet build against) could not
    // install the speech runtime at all, and local voice was simply unavailable
    // — even though the fix was one flag away (Parslee-ai/car#640).
    Ok(SPEECH_RUNTIME_FALLBACK_PYTHON.to_string())
}

/// Python version `uv` provisions when no supported interpreter is on PATH.
///
/// Pinned to a version `mlx-audio` and `misaki` actually support — deliberately
/// not "whatever is newest", since the newest release is routinely ahead of what
/// the speech stack builds against, which is the situation this exists for.
const SPEECH_RUNTIME_FALLBACK_PYTHON: &str = "3.12";

fn detect_speech_python() -> Option<String> {
    if let Ok(path) = std::env::var("CAR_SPEECH_PYTHON") {
        if !path.trim().is_empty() {
            return Some(path);
        }
    }

    ["python3.13", "python3.12", "python3.11"]
        .into_iter()
        .find(|candidate| command_in_path(candidate))
        .map(str::to_string)
}

fn speech_runtime_root_from_models_dir(_models_dir: &Path) -> PathBuf {
    if let Ok(path) = std::env::var("CAR_SPEECH_RUNTIME_DIR") {
        if !path.trim().is_empty() {
            return PathBuf::from(path);
        }
    }

    std::env::var_os("HOME")
        .or_else(|| std::env::var_os("USERPROFILE"))
        .map(PathBuf::from)
        .unwrap_or_else(|| PathBuf::from("."))
        .join(".car")
        .join("speech-runtime")
}

fn command_in_path(name: &str) -> bool {
    std::env::var_os("PATH")
        .map(|paths| {
            std::env::split_paths(&paths).any(|dir| {
                let path = dir.join(name);
                path.exists() && path.is_file()
            })
        })
        .unwrap_or(false)
}

fn speech_model_cached(schema: &ModelSchema) -> bool {
    match &schema.source {
        ModelSource::Mlx { hf_repo, .. } => huggingface_repo_has_snapshot(hf_repo),
        ModelSource::WhisperCpp { model } => car_whisper::model_cached(model),
        // OS-provided (WinRT) — nothing to cache; "cached" tracks availability.
        ModelSource::WindowsSpeech {} => cfg!(target_os = "windows"),
        ModelSource::Proprietary { auth, .. } => match auth {
            // env OR keychain — a native user configures the key without env vars.
            ProprietaryAuth::ApiKeyEnv { env_var } => {
                car_secrets::resolve_env_or_keychain(env_var).is_some()
            }
            ProprietaryAuth::BearerTokenEnv { env_var } => {
                car_secrets::resolve_env_or_keychain(env_var).is_some()
            }
            ProprietaryAuth::OAuth2Pkce { .. } => false,
        },
        _ => false,
    }
}

fn remove_huggingface_repo_cache(repo_id: &str) -> Result<(), InferenceError> {
    let repo_dir = std::env::var("HF_HOME")
        .map(PathBuf::from)
        .unwrap_or_else(|_| {
            std::env::var_os("HOME")
                .or_else(|| std::env::var_os("USERPROFILE"))
                .map(PathBuf::from)
                .unwrap_or_else(|| PathBuf::from("."))
                .join(".cache")
                .join("huggingface")
        })
        .join("hub")
        .join(format!("models--{}", repo_id.replace('/', "--")));

    if repo_dir.exists() {
        std::fs::remove_dir_all(repo_dir)?;
    }
    Ok(())
}

fn model_source_configured(schema: &ModelSchema) -> bool {
    match &schema.source {
        ModelSource::RemoteApi {
            protocol: ApiProtocol::OpenRouter,
            ..
        } => crate::openrouter::credential_source().is_some(),
        ModelSource::RemoteApi {
            api_key_env,
            api_key_envs,
            ..
        } => {
            car_secrets::resolve_env_or_keychain(api_key_env).is_some()
                || api_key_envs
                    .iter()
                    .any(|env_var| car_secrets::resolve_env_or_keychain(env_var).is_some())
        }
        ModelSource::Proprietary { auth, .. } => match auth {
            ProprietaryAuth::ApiKeyEnv { env_var } => {
                car_secrets::resolve_env_or_keychain(env_var).is_some()
            }
            ProprietaryAuth::BearerTokenEnv { env_var } => {
                car_secrets::resolve_env_or_keychain(env_var).is_some()
            }
            ProprietaryAuth::OAuth2Pkce { .. } => false,
        },
        ModelSource::VllmMlx { .. } => {
            std::env::var("VLLM_MLX_ENDPOINT").is_ok() || schema.available
        }
        ModelSource::Ollama { .. } => schema.available,
        ModelSource::Mlx { .. } | ModelSource::Local { .. } | ModelSource::WhisperCpp { .. } => {
            true
        }
        // OS-provided; "configured" tracks platform availability (Windows-only).
        ModelSource::WindowsSpeech {} => schema.available,
        ModelSource::AppleFoundationModels { .. } => schema.available,
        // Delegated models route through a host-registered runner —
        // the runner's own auth / readiness is opaque here. Treat
        // them as configured; missing-runner errors surface at
        // dispatch time with a clear message.
        ModelSource::Delegated { .. } => true,
    }
}

fn all_model_capabilities() -> [ModelCapability; 13] {
    [
        ModelCapability::Generate,
        ModelCapability::Embed,
        ModelCapability::Classify,
        ModelCapability::Code,
        ModelCapability::Reasoning,
        ModelCapability::Summarize,
        ModelCapability::ToolUse,
        ModelCapability::MultiToolCall,
        ModelCapability::Vision,
        ModelCapability::SpeechToText,
        ModelCapability::TextToSpeech,
        ModelCapability::ImageGeneration,
        ModelCapability::VideoGeneration,
    ]
}

fn sort_capabilities(mut capabilities: Vec<ModelCapability>) -> Vec<ModelCapability> {
    capabilities.sort_by_key(|capability| {
        all_model_capabilities()
            .iter()
            .position(|candidate| candidate == capability)
            .unwrap_or(usize::MAX)
    });
    capabilities
}

fn speech_model_source_label(schema: &ModelSchema) -> String {
    match &schema.source {
        ModelSource::Mlx { hf_repo, .. } => format!("mlx:{hf_repo}"),
        ModelSource::WhisperCpp { model } => format!("whisper:{model}"),
        ModelSource::WindowsSpeech {} => "windows-speech".to_string(),
        ModelSource::Proprietary {
            provider, endpoint, ..
        } => format!("proprietary:{provider}:{endpoint}"),
        ModelSource::RemoteApi { endpoint, .. } => format!("remote:{endpoint}"),
        ModelSource::Local { hf_repo, .. } => format!("local:{hf_repo}"),
        ModelSource::VllmMlx {
            endpoint,
            model_name,
        } => format!("vllm-mlx:{endpoint}:{model_name}"),
        ModelSource::Ollama { model_tag, host } => format!("ollama:{host}:{model_tag}"),
        ModelSource::AppleFoundationModels { use_case } => {
            format!(
                "apple-foundation:{}",
                use_case.as_deref().unwrap_or("default")
            )
        }
        ModelSource::Delegated { hint } => {
            format!("delegated:{}", hint.as_deref().unwrap_or("(none)"))
        }
    }
}

/// Build the Qwen3-Reranker chat-template prompt for a single
/// `(query, document)` candidate.
///
/// The format matches upstream `reranker_quick_start.py`: a system
/// message pinning the answer space to yes/no, a user turn with
/// `<Instruct>/<Query>/<Document>`, and an assistant prefix with a
/// closed empty `<think>` block to force non-thinking classification.
fn rerank_prompt(instruction: &str, query: &str, document: &str) -> String {
    const SYSTEM: &str = "Judge whether the Document meets the requirements based on the Query and the Instruct provided. Note that the answer can only be \"yes\" or \"no\".";
    format!(
        "<|im_start|>system\n{SYSTEM}<|im_end|>\n\
         <|im_start|>user\n<Instruct>: {instruction}\n<Query>: {query}\n<Document>: {document}<|im_end|>\n\
         <|im_start|>assistant\n<think>\n\n</think>\n\n"
    )
}

/// Interpret the first useful token from a Qwen3-Reranker greedy
/// decode as a relevance score. Scans up to the first few tokens so
/// a leading space, BOS artifact, or stray newline doesn't poison the
/// result. Returns 1.0 for "yes", 0.0 for "no", 0.5 on unexpected
/// output (with a warn so the mismatch is visible).
/// Map an exhausted-fallback-chain error to actionable recovery
/// guidance, or `None` when the underlying error isn't a
/// missing-backend/credential case.
///
/// Matches *specific* CAR error phrases, not broad words like "auth"
/// or "token", so a transient failure on an otherwise-configured model
/// — an HTTP 401/403/429 (`API returned 4xx`), a connection refused, a
/// timeout — passes through unchanged and isn't buried under
/// first-run setup advice. The four matched phrases are the ones the
/// engine actually emits when there is genuinely no runnable backend:
/// proprietary provider with no credential, a routed model that isn't
/// installed, an empty registry, or a delegated model with no runner.
/// See Parslee-ai/car#231 §7.1.
/// Recover the HTTP status the remote backend formats into
/// "API returned <status>: <body>" error strings, so transient
/// classification keys on the REAL status instead of substring-sniffing
/// a body that may quote another status or the word "timeout"
/// (I4 review; typed error plumbing is the follow-up).
fn parse_api_returned_status(err: &str) -> Option<u16> {
    let lower = err.to_ascii_lowercase();
    let idx = lower.find("api returned ")?;
    let digits: String = lower[idx + "api returned ".len()..]
        .chars()
        .take_while(|c| c.is_ascii_digit())
        .take(3)
        .collect();
    digits.parse().ok()
}

fn no_backend_recovery_hint(underlying: &str) -> Option<String> {
    let is_no_backend = underlying.contains("no credential")
        || underlying.contains("model not found")
        || underlying.contains("no models available")
        || underlying.contains("no inference runner");
    if !is_no_backend {
        return None;
    }
    Some(format!(
        "no inference backend is available. To install a local, tool-capable \
         model (no account required, works on Windows/Linux/macOS), run:\n    \
         car models pull qwen/qwen3-4b:q4_k_m\n\
         To use Parslee's hosted models instead, run:\n    \
         car auth login\n\
         (underlying error: {underlying})"
    ))
}

/// When the whole fallback chain was exhausted by an AUTH rejection — an
/// expired or revoked Parslee credential (401/403, "org lookup failed",
/// "Authentication required", "invalid_grant") — return actionable re-auth
/// guidance instead of a raw HTTP status. Distinct from
/// [`no_backend_recovery_hint`], which covers "no credential at all": this is
/// the "you WERE signed in but the session lapsed and the refresh didn't
/// recover" case, which otherwise surfaced verbatim as `HTTP 401 Unauthorized`.
/// Only reached on an exhausted chain, so a single transient 401 on an
/// otherwise-healthy alternative never lands here.
fn auth_expired_recovery_hint(underlying: &str) -> Option<String> {
    let l = underlying.to_ascii_lowercase();
    let is_auth = l.contains("org lookup failed")
        || l.contains("authentication required")
        || (l.contains("401") && l.contains("unauthorized"))
        || (l.contains("403") && l.contains("forbidden"))
        || l.contains("invalid_grant")
        || l.contains("token expired");
    if !is_auth {
        return None;
    }
    Some(format!(
        "your Parslee session has expired or was rejected — re-authenticate:\n    \
         car auth login\n\
         Or install a tool-capable on-device model so CAR can answer (including \
         tool use) without an account:\n    \
         car models pull qwen/qwen3-4b:q4_k_m\n\
         (underlying error: {underlying})"
    ))
}

fn score_from_rerank_output(text: &str, model_name: &str) -> f32 {
    // Replace every non-alphanumeric byte with a space, lowercase,
    // and scan the first few whitespace-separated tokens for
    // "yes"/"no". This strips chat-template tags (`<|im_end|>`),
    // punctuation, and underscores cleanly without special-casing.
    let normalized: String = text
        .to_ascii_lowercase()
        .chars()
        .map(|c| if c.is_ascii_alphanumeric() { c } else { ' ' })
        .collect();
    for tok in normalized.split_ascii_whitespace().take(5) {
        match tok {
            "yes" => return 1.0,
            "no" => return 0.0,
            _ => continue,
        }
    }
    tracing::warn!(
        model = %model_name,
        output = %text,
        "rerank: first tokens contain neither `yes` nor `no`; returning neutral 0.5"
    );
    0.5
}

fn default_speech_voice(schema: &ModelSchema) -> Option<String> {
    if schema.provider == "elevenlabs" {
        Some("JBFqnCBsd6RMkjVDRZzb".to_string())
    } else if schema.name == "Kokoro-82M-6bit" || schema.name == "Kokoro-82M-bf16" {
        Some("af_heart".to_string())
    } else if schema.name == "Qwen3-TTS-12Hz-1.7B-Base-5bit" {
        Some("Chelsie".to_string())
    } else {
        None
    }
}

#[allow(dead_code)] // conditionally compiled — used only on MLX-backend (macOS) snapshot-resolution paths
fn huggingface_repo_has_snapshot(repo_id: &str) -> bool {
    find_latest_huggingface_snapshot(repo_id).is_some()
}

fn huggingface_repo_dir(repo_id: &str) -> PathBuf {
    let cache_root = std::env::var("HF_HOME")
        .map(PathBuf::from)
        .unwrap_or_else(|_| {
            std::env::var_os("HOME")
                .or_else(|| std::env::var_os("USERPROFILE"))
                .map(PathBuf::from)
                .unwrap_or_else(|| PathBuf::from("."))
                .join(".cache")
                .join("huggingface")
        })
        .join("hub");
    cache_root.join(format!("models--{}", repo_id.replace('/', "--")))
}

fn find_latest_huggingface_snapshot(repo_id: &str) -> Option<PathBuf> {
    let snapshots = huggingface_repo_dir(repo_id).join("snapshots");
    std::fs::read_dir(snapshots)
        .ok()?
        .filter_map(Result::ok)
        .map(|entry| entry.path())
        .find(|path| path.is_dir() && snapshot_looks_ready(path))
}

fn snapshot_looks_ready(path: &Path) -> bool {
    if path.join("config.json").exists() || path.join("model_index.json").exists() {
        return true;
    }
    snapshot_contains_ext(path, "safetensors")
}

fn snapshot_contains_ext(root: &Path, ext: &str) -> bool {
    let Ok(entries) = std::fs::read_dir(root) else {
        return false;
    };
    entries.filter_map(Result::ok).any(|entry| {
        let path = entry.path();
        if path.is_dir() {
            snapshot_contains_ext(&path, ext)
        } else {
            let ext_matches = path
                .extension()
                .and_then(|value| value.to_str())
                .map(|value| value.eq_ignore_ascii_case(ext))
                .unwrap_or(false);
            // A matching extension only counts when the file is actually usable
            // — a dangling symlink into a pruned blob or a zero-length partial
            // must not make a snapshot look ready.
            ext_matches && crate::download::cache_file_usable(&path)
        }
    })
}

#[allow(dead_code)] // conditionally compiled — used only on MLX-backend (macOS) media-output paths
fn count_files_recursive(root: &Path) -> usize {
    let Ok(entries) = std::fs::read_dir(root) else {
        return 0;
    };
    entries
        .filter_map(Result::ok)
        .map(|entry| entry.path())
        .map(|path| {
            if path.is_dir() {
                count_files_recursive(&path)
            } else if path.is_file() {
                1
            } else {
                0
            }
        })
        .sum()
}

async fn download_hf_repo_snapshot(repo_id: &str) -> Result<(PathBuf, usize), InferenceError> {
    let api = hf_hub::api::tokio::ApiBuilder::from_env()
        .with_progress(false)
        .build()
        .map_err(|e| InferenceError::DownloadFailed(format!("init hf api: {e}")))?;
    let repo = api.model(repo_id.to_string());
    let info = repo
        .info()
        .await
        .map_err(|e| InferenceError::DownloadFailed(format!("{repo_id}: {e}")))?;

    let snapshot_path = huggingface_repo_dir(repo_id)
        .join("snapshots")
        .join(&info.sha);
    let mut downloaded = 0usize;
    for sibling in &info.siblings {
        let local_path = snapshot_path.join(&sibling.rfilename);
        // Presence is not integrity. The shared HF cache can hold a dangling
        // symlink (blob pruned by another tool) or a zero-length partial write
        // (interrupted/out-of-disk download). Skip the re-download only when the
        // cached file is actually usable; otherwise fall through so hf-hub
        // re-fetches metadata and rewrites the blob. (Cheap check only — a full
        // content hash per already-present file would re-hash the whole model
        // on every no-op pull; deep verification lives in the self-heal path.)
        if crate::download::cache_file_usable(&local_path) {
            downloaded += 1;
            continue;
        }
        // Clear a stale/dangling pointer first: hf-hub's symlink recreation
        // returns `AlreadyExists` if the old pointer file is still on disk and
        // the new etag differs, surfacing as a confusing error instead of a
        // repair. Removing it lets hf-hub always recreate the snapshot link.
        let _ = std::fs::remove_file(&local_path);
        repo.download(&sibling.rfilename).await.map_err(|e| {
            InferenceError::DownloadFailed(format!("{repo_id}/{}: {e}", sibling.rfilename))
        })?;
        downloaded += 1;
    }

    Ok((snapshot_path, downloaded))
}

fn temp_work_dir(prefix: &str) -> Result<PathBuf, InferenceError> {
    let unique = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map_err(|e| InferenceError::InferenceFailed(format!("clock error: {e}")))?
        .as_nanos();
    let dir = std::env::temp_dir().join(format!("car-inference-{prefix}-{unique}"));
    std::fs::create_dir_all(&dir)?;
    Ok(dir)
}

fn ensure_parent_dir(path: &Path) -> Result<(), InferenceError> {
    if let Some(parent) = path.parent() {
        std::fs::create_dir_all(parent)?;
    }
    Ok(())
}

fn requested_or_temp_output(
    output_path: Option<&str>,
    format: &str,
) -> Result<PathBuf, InferenceError> {
    if let Some(path) = output_path {
        return Ok(PathBuf::from(path));
    }
    let dir = temp_work_dir("audio-out")?;
    Ok(dir.join(format!("speech.{format}")))
}

#[allow(dead_code)] // conditionally compiled — used only on MLX-backend (macOS) media-output paths
fn requested_or_temp_media_output(
    output_path: Option<&str>,
    format: &str,
    stem: &str,
) -> Result<PathBuf, InferenceError> {
    if let Some(path) = output_path {
        return Ok(PathBuf::from(path));
    }
    let dir = temp_work_dir(&format!("{stem}-out"))?;
    Ok(dir.join(format!("{stem}.{format}")))
}

fn materialize_audio_output(
    produced: &Path,
    requested: Option<&str>,
    format: &str,
) -> Result<PathBuf, InferenceError> {
    if let Some(path) = requested {
        let dest = PathBuf::from(path);
        ensure_parent_dir(&dest)?;
        std::fs::copy(produced, &dest)?;
        Ok(dest)
    } else {
        let dest = requested_or_temp_output(None, format)?;
        ensure_parent_dir(&dest)?;
        std::fs::copy(produced, &dest)?;
        Ok(dest)
    }
}

/// Synthesize `text` to WAV bytes via WinRT `Windows.Media.SpeechSynthesis`.
/// Mirrors car-voice's `windows_speech_tts` (the live path), but returns bytes
/// for the catalog synthesize path (which writes them to a file). The two can't
/// share code without a car-inference→car-voice cycle, and it's a small
/// Windows-only helper, so it's duplicated deliberately. Windows-only.
#[cfg(target_os = "windows")]
fn winrt_synthesize_wav(text: &str, voice: &str, rate: f64) -> Result<Vec<u8>, InferenceError> {
    use windows::core::HSTRING;
    use windows::Media::SpeechSynthesis::SpeechSynthesizer;
    use windows::Storage::Streams::DataReader;

    let err = |m: String| InferenceError::InferenceFailed(m);
    let synth =
        SpeechSynthesizer::new().map_err(|e| err(format!("SpeechSynthesizer::new: {e}")))?;
    if let Ok(opts) = synth.Options() {
        let _ = opts.SetSpeakingRate(rate.clamp(0.5, 6.0));
    }
    if !voice.is_empty() {
        if let Ok(all) = SpeechSynthesizer::AllVoices() {
            let want = voice.to_lowercase();
            let count = all.Size().unwrap_or(0);
            for i in 0..count {
                if let Ok(info) = all.GetAt(i) {
                    if let Ok(name) = info.DisplayName() {
                        if name.to_string_lossy().to_lowercase().contains(&want) {
                            let _ = synth.SetVoice(&info);
                            break;
                        }
                    }
                }
            }
        }
    }
    let stream = synth
        .SynthesizeTextToStreamAsync(&HSTRING::from(text))
        .map_err(|e| err(format!("SynthesizeTextToStreamAsync: {e}")))?
        .get()
        .map_err(|e| err(format!("synthesize await: {e}")))?;
    let size = stream
        .Size()
        .map_err(|e| err(format!("stream size: {e}")))?;
    let input = stream
        .GetInputStreamAt(0)
        .map_err(|e| err(format!("input stream: {e}")))?;
    let reader =
        DataReader::CreateDataReader(&input).map_err(|e| err(format!("data reader: {e}")))?;
    reader
        .LoadAsync(size as u32)
        .map_err(|e| err(format!("load async: {e}")))?
        .get()
        .map_err(|e| err(format!("load await: {e}")))?;
    let mut buf = vec![0u8; size as usize];
    reader
        .ReadBytes(&mut buf)
        .map_err(|e| err(format!("read bytes: {e}")))?;
    Ok(buf)
}

#[allow(dead_code)] // conditionally compiled — used only on backend-conditional transcription paths
fn read_transcription_result(output_prefix: &Path) -> Result<Option<String>, InferenceError> {
    let candidates = [
        output_prefix.with_extension("json"),
        output_prefix.to_path_buf(),
    ];

    for path in candidates {
        if path.exists() {
            let contents = std::fs::read_to_string(path)?;
            if let Some(text) = extract_text_from_payload(&contents) {
                return Ok(Some(text));
            }
        }
    }

    Ok(None)
}

#[allow(dead_code)] // conditionally compiled — used only on backend-conditional transcription paths
fn extract_text_from_payload(payload: &str) -> Option<String> {
    let value: serde_json::Value = serde_json::from_str(payload).ok()?;
    if let Some(text) = value.get("text").and_then(|v| v.as_str()) {
        return Some(text.to_string());
    }
    if let Some(transcripts) = value.get("transcripts").and_then(|v| v.as_array()) {
        let joined = transcripts
            .iter()
            .filter_map(|item| item.get("text").and_then(|v| v.as_str()))
            .collect::<Vec<_>>()
            .join("\n");
        if !joined.is_empty() {
            return Some(joined);
        }
    }
    if let Some(items) = value.as_array() {
        let joined = items
            .iter()
            .filter_map(|item| {
                item.get("text")
                    .or_else(|| item.get("Content"))
                    .and_then(|v| v.as_str())
            })
            .collect::<Vec<_>>()
            .join(" ");
        if !joined.is_empty() {
            return Some(joined);
        }
    }
    None
}

#[allow(dead_code)] // conditionally compiled — used only on backend-conditional speech-output paths
fn find_audio_file(output_dir: &Path) -> Result<Option<PathBuf>, InferenceError> {
    let mut audio_files = Vec::new();
    collect_audio_files(output_dir, &mut audio_files)?;
    audio_files.sort();
    Ok(audio_files.into_iter().next())
}

#[allow(dead_code)] // conditionally compiled — used only on backend-conditional speech-output paths
fn collect_audio_files(dir: &Path, audio_files: &mut Vec<PathBuf>) -> Result<(), InferenceError> {
    for entry in std::fs::read_dir(dir)? {
        let path = entry?.path();
        if path.is_dir() {
            collect_audio_files(&path, audio_files)?;
        } else if matches!(
            path.extension().and_then(|ext| ext.to_str()),
            Some("wav" | "mp3" | "flac" | "pcm" | "m4a")
        ) {
            audio_files.push(path);
        }
    }
    Ok(())
}

fn media_type_for_format(format: &str) -> String {
    match format.to_ascii_lowercase().as_str() {
        "mp3" => "audio/mpeg".to_string(),
        "flac" => "audio/flac".to_string(),
        "pcm" => "audio/L16".to_string(),
        "m4a" => "audio/mp4".to_string(),
        _ => "audio/wav".to_string(),
    }
}

fn kokoro_lang_code(language: Option<&str>) -> &'static str {
    match language.unwrap_or("en").to_ascii_lowercase().as_str() {
        "en-gb" | "british" | "british english" => "b",
        "ja" | "japanese" => "j",
        "zh" | "zh-cn" | "mandarin" | "chinese" => "z",
        "es" | "spanish" => "e",
        "fr" | "french" => "f",
        _ => "a",
    }
}

#[allow(dead_code)] // conditionally compiled — used only on backend-conditional transcription paths
fn normalize_lang_code(language: &str) -> String {
    match language.to_ascii_lowercase().as_str() {
        "english" | "en-us" | "en_us" => "en".to_string(),
        "spanish" => "es".to_string(),
        "french" => "fr".to_string(),
        "japanese" => "ja".to_string(),
        "chinese" | "mandarin" => "zh".to_string(),
        other => match other {
            "en" | "es" | "fr" | "ja" | "zh" => other.to_string(),
            _ => "en".to_string(),
        },
    }
}

fn elevenlabs_auth(schema: &ModelSchema) -> Result<(String, String), InferenceError> {
    match &schema.source {
        ModelSource::Proprietary {
            endpoint,
            auth: schema::ProprietaryAuth::ApiKeyEnv { env_var },
            ..
        } => {
            let key = car_secrets::resolve_env_or_keychain(env_var).ok_or_else(|| {
                InferenceError::InferenceFailed(format!(
                    "missing API key {env_var}; set the environment variable or \
                     store it with `car secrets put {env_var}`"
                ))
            })?;
            Ok((endpoint.clone(), key))
        }
        _ => Err(InferenceError::InferenceFailed(format!(
            "model {} is not an ElevenLabs proprietary model",
            schema.id
        ))),
    }
}

fn elevenlabs_output_format(format: &str) -> &'static str {
    match format.to_ascii_lowercase().as_str() {
        "mp3" => "mp3_44100_128",
        "pcm" => "pcm_16000",
        _ => "wav_44100",
    }
}

fn benchmark_priors_paths(models_dir: &Path) -> Vec<PathBuf> {
    let mut paths = Vec::new();

    let direct = models_dir.join("benchmark_priors.json");
    if !paths.contains(&direct) {
        paths.push(direct);
    }

    if let Some(parent) = models_dir.parent() {
        let parent_path = parent.join("benchmark_priors.json");
        if !paths.contains(&parent_path) {
            paths.push(parent_path);
        }
    }

    if let Some(path) = std::env::var_os("CAR_BENCHMARK_PRIORS_PATH") {
        let path = PathBuf::from(path);
        if !paths.contains(&path) {
            paths.push(path);
        }
    }

    paths
}

fn load_benchmark_prior_health(
    models_dir: &Path,
    schemas: &[ModelSchema],
) -> Vec<ModelBenchmarkPriorHealth> {
    let mut priors = std::collections::BTreeMap::new();
    for path in benchmark_priors_paths(models_dir) {
        let Ok(loaded) = routing_ext::load_benchmark_priors(&path) else {
            continue;
        };
        for (model_id, prior) in loaded {
            let model_name = schemas
                .iter()
                .find(|schema| schema.id == model_id)
                .map(|schema| schema.name.clone());
            priors.insert(
                model_id.clone(),
                ModelBenchmarkPriorHealth {
                    model_id,
                    model_name,
                    overall_score: prior.overall_score,
                    overall_latency_ms: prior.overall_latency_ms,
                    task_scores: prior.task_scores,
                    task_latency_ms: prior.task_latency_ms,
                    source_path: path.clone(),
                },
            );
        }
    }

    priors.into_values().collect()
}

fn kokoro_runtime_fallback_enabled() -> bool {
    std::env::var("CAR_SPEECH_KOKORO_FALLBACK")
        .ok()
        .map(|value| {
            !matches!(
                value.trim().to_ascii_lowercase().as_str(),
                "0" | "false" | "off"
            )
        })
        .unwrap_or(true)
}

fn speech_runtime_mlx_audio_spec() -> String {
    std::env::var("CAR_SPEECH_RUNTIME_MLX_AUDIO_SPEC")
        .ok()
        .filter(|value| !value.trim().is_empty())
        .unwrap_or_else(|| "mlx-audio==0.4.2".to_string())
}

fn speech_runtime_spacy_model_spec() -> String {
    std::env::var("CAR_SPEECH_RUNTIME_SPACY_MODEL_SPEC")
        .ok()
        .filter(|value| !value.trim().is_empty())
        .unwrap_or_else(|| {
            "en-core-web-sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl".to_string()
        })
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::ffi::OsString;
    use tempfile::TempDir;

    struct RestoredEnvironment(Vec<(&'static str, Option<OsString>)>);

    impl RestoredEnvironment {
        fn capture(names: &[&'static str]) -> Self {
            Self(
                names
                    .iter()
                    .map(|name| (*name, std::env::var_os(name)))
                    .collect(),
            )
        }
    }

    impl Drop for RestoredEnvironment {
        fn drop(&mut self) {
            for (name, value) in &self.0 {
                unsafe {
                    match value {
                        Some(value) => std::env::set_var(name, value),
                        None => std::env::remove_var(name),
                    }
                }
            }
        }
    }

    struct FixtureLocalOffload {
        emit_done: bool,
    }

    #[async_trait::async_trait]
    impl crate::offload::LocalGenerationOffload for FixtureLocalOffload {
        async fn generate(
            &self,
            _request: GenerateRequest,
        ) -> Result<InferenceResult, InferenceError> {
            unreachable!("streaming fixture")
        }

        async fn stream(
            &self,
            _request: GenerateRequest,
        ) -> Result<tokio::sync::mpsc::Receiver<StreamEvent>, InferenceError> {
            let (tx, rx) = tokio::sync::mpsc::channel(4);
            let emit_done = self.emit_done;
            tokio::spawn(async move {
                let _ = tx.send(StreamEvent::TextDelta("local answer".into())).await;
                if emit_done {
                    let _ = tx
                        .send(StreamEvent::Done {
                            text: "local answer".into(),
                            tool_calls: vec![],
                        })
                        .await;
                }
            });
            Ok(rx)
        }
    }

    fn install_small_local_fixture(engine: &InferenceEngine) -> String {
        let schema = engine
            .unified_registry
            .find_by_name("Qwen3-0.6B")
            .expect("small built-in local model")
            .clone();
        let model_dir = engine.config.models_dir.join(&schema.name);
        std::fs::create_dir_all(&model_dir).unwrap();
        std::fs::write(model_dir.join("model.gguf"), b"fixture").unwrap();
        std::fs::write(model_dir.join("tokenizer.json"), b"{}").unwrap();
        schema.id
    }

    fn remote_stream_fixture_schema(
        id: &str,
        endpoint: String,
        protocol: schema::ApiProtocol,
        api_key_env: &str,
    ) -> ModelSchema {
        ModelSchema {
            id: id.into(),
            name: "gemini-test".into(),
            provider: "test".into(),
            family: "test".into(),
            version: "1".into(),
            capabilities: vec![ModelCapability::Generate],
            context_length: 128_000,
            max_output_tokens: Some(8_192),
            param_count: String::new(),
            quantization: None,
            performance: Default::default(),
            cost: Default::default(),
            source: ModelSource::RemoteApi {
                endpoint,
                api_key_env: api_key_env.into(),
                api_key_envs: vec![],
                api_version: None,
                protocol,
            },
            tags: vec!["test".into()],
            supported_params: vec![],
            public_benchmarks: vec![],
            trust_tier: TrustTier::Community,
            deprecated: false,
            available: true,
            weights_ready: true,
        }
    }

    /// The Metal device lock (`mlx_device_lock`) must be a process-wide singleton
    /// AND grant only one holder at a time — that is what serializes every local
    /// MLX path (coder generate, streaming, embedding/consolidation) onto the one
    /// Metal device so a background consolidation embed can't run concurrently
    /// with a coder generate and wedge the device (the daemon "wedge" this fixes).
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    #[tokio::test]
    async fn mlx_device_lock_is_singleton_and_serializes() {
        use std::sync::atomic::{AtomicUsize, Ordering};
        use std::sync::Arc;
        // Same underlying mutex across calls (so all MLX paths share one permit).
        assert!(
            Arc::ptr_eq(
                &InferenceEngine::mlx_device_lock(),
                &InferenceEngine::mlx_device_lock()
            ),
            "device lock must be a process-wide singleton"
        );
        // Mutual exclusion: never more than one holder concurrently.
        let inside = Arc::new(AtomicUsize::new(0));
        let peak = Arc::new(AtomicUsize::new(0));
        let mut handles = Vec::new();
        for _ in 0..8 {
            let inside = inside.clone();
            let peak = peak.clone();
            handles.push(tokio::spawn(async move {
                let _g = InferenceEngine::mlx_device_lock().lock_owned().await;
                let n = inside.fetch_add(1, Ordering::SeqCst) + 1;
                peak.fetch_max(n, Ordering::SeqCst);
                tokio::time::sleep(std::time::Duration::from_millis(5)).await;
                inside.fetch_sub(1, Ordering::SeqCst);
            }));
        }
        for h in handles {
            h.await.unwrap();
        }
        assert_eq!(
            peak.load(Ordering::SeqCst),
            1,
            "at most one MLX device holder at a time"
        );
    }

    /// The F1 auto-thinking gate decision: a coding intent gets "high" (24000),
    /// a general Complex turn gets "medium" (8000), and thinking is skipped
    /// entirely when the model can't do it — so a non-thinking model never gets
    /// a budget that would 400.
    #[test]
    fn auto_thinking_budget_gates_code_complex_and_capability() {
        // Coding intent on a thinking-capable model -> high.
        assert_eq!(auto_thinking_budget(true, false, true), Some(24_000));
        // General Complex on a thinking-capable model -> medium.
        assert_eq!(auto_thinking_budget(false, true, true), Some(8_000));
        // Code takes precedence over Complex.
        assert_eq!(auto_thinking_budget(true, true, true), Some(24_000));
        // Model can't think -> None even for a coding turn (no budget -> no 400).
        assert_eq!(auto_thinking_budget(true, true, false), None);
        // Neither coding nor complex -> None (plain turns never auto-think).
        assert_eq!(auto_thinking_budget(false, false, true), None);
    }

    #[test]
    fn is_explicit_code_intent_keys_on_caller_intent_not_keyword_classifier() {
        use crate::intent::{IntentHint, TaskHint};
        // The coder/bench set an explicit Code intent — the gate fires.
        let code = IntentHint {
            task: Some(TaskHint::Code),
            ..Default::default()
        };
        assert!(is_explicit_code_intent(Some(&code)));
        // No caller intent -> NOT code, even if the prompt's keyword-classified
        // decision.task would be Code. This is the exact over-provisioning the
        // gate avoids: a re-key onto decision.task would light up high-effort
        // thinking on any prose containing "fix"/"bug"/"let ".
        assert!(!is_explicit_code_intent(None));
        // A different explicit task is not code.
        let reasoning = IntentHint {
            task: Some(TaskHint::Reasoning),
            ..Default::default()
        };
        assert!(!is_explicit_code_intent(Some(&reasoning)));
        // Intent present but task unset -> NOT code (matches the no-intent path).
        let unset = IntentHint {
            task: None,
            ..Default::default()
        };
        assert!(!is_explicit_code_intent(Some(&unset)));
    }

    #[test]
    fn strict_model_suppresses_the_local_last_resort_append() {
        // Loose (default) remote-only chain → append a local model (resilience).
        assert!(should_append_local_last_resort(false, false));
        // Hard pin, remote-only chain → do NOT append: the pinned remote model
        // must fail loudly, not silently degrade to a weaker local model.
        assert!(!should_append_local_last_resort(false, true));
        // A chain that already has a local model never needs the last resort,
        // strict or not.
        assert!(!should_append_local_last_resort(true, false));
        assert!(!should_append_local_last_resort(true, true));
    }

    #[test]
    fn last_resort_fallback_never_returns_an_unrunnable_apple_foundation() {
        // Regression: apple-foundation is a builtin that is `is_local()` and
        // `ready_without_download == Some(true)` on EVERY platform (there is
        // nothing to download), but it only executes on Apple Silicon. The
        // last-resort local-fallback append used `ready_without_download` alone,
        // so off-Apple it handed back `apple-foundation`; the attempt then failed
        // with `model not found: apple-foundation`, and — being the last candidate
        // — that error MASKED the real remote failure. (Found on Windows when a
        // CRLF-corrupted SSE fixture made the managed primary fail; the surfaced
        // error blamed apple-foundation, not the fixture.)
        //
        // Platform-agnostic invariant: whatever the last resort picks, it must be
        // runnable here — on Apple apple-foundation is `available` and stays
        // eligible; off-Apple it is excluded. Empty models dir ⇒ off-Apple this is
        // simply `None`.
        let tmp = TempDir::new().unwrap();
        let engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        if let Some(name) = engine.first_installed_local_model(false) {
            let runnable = engine
                .unified_registry
                .find_by_name(&name)
                .map(|s| !s.is_foundation_models() || s.available)
                .unwrap_or(false);
            assert!(
                runnable,
                "last-resort fallback returned a non-runnable model: {name}"
            );
        }
    }

    #[test]
    fn empty_tool_catalog_is_no_tools() {
        // `tools: Some(vec![])` must behave exactly like `tools: None`:
        // no ToolUse routing requirement, and the FoundationModels
        // dispatch takes the structured-output path when a JsonSchema
        // response_format is present instead of firing the tool path
        // (which would warn about — and drop — the schema constraint
        // for zero tools).
        let mut req = GenerateRequest {
            prompt: "p".into(),
            ..Default::default()
        };
        assert!(!InferenceEngine::request_has_tools(&req));
        req.tools = Some(vec![]);
        assert!(!InferenceEngine::request_has_tools(&req));
        req.tools = Some(vec![serde_json::json!({
            "name": "t", "description": "d", "parameters": {"type": "object"}
        })]);
        assert!(InferenceEngine::request_has_tools(&req));
    }

    #[test]
    fn top_k_keeps_only_k_highest() {
        // Probs for 5 tokens; top_k=2 keeps the two largest, renormalized.
        let mut probs = vec![0.1, 0.4, 0.2, 0.25, 0.05];
        InferenceEngine::apply_top_k_top_p(&mut probs, 2, 1.0);
        // 0.4 (idx1) and 0.25 (idx3) survive; others zeroed.
        assert!(probs[0] == 0.0 && probs[2] == 0.0 && probs[4] == 0.0);
        assert!(probs[1] > 0.0 && probs[3] > 0.0);
        let sum: f32 = probs.iter().sum();
        assert!((sum - 1.0).abs() < 1e-5, "renormalized to 1.0, got {sum}");
    }

    #[test]
    fn top_k_zero_is_a_noop() {
        let mut probs = vec![0.1, 0.4, 0.2, 0.3];
        let before = probs.clone();
        InferenceEngine::apply_top_k_top_p(&mut probs, 0, 1.0);
        assert_eq!(probs, before);
    }

    #[test]
    fn top_p_nucleus_truncates_tail() {
        let mut probs = vec![0.6, 0.3, 0.07, 0.03];
        InferenceEngine::apply_top_k_top_p(&mut probs, 0, 0.9);
        // 0.6 + 0.3 = 0.9 crosses the threshold at the 2nd token; tail zeroed.
        assert!(probs[2] == 0.0 && probs[3] == 0.0);
        assert!(probs[0] > 0.0 && probs[1] > 0.0);
    }

    #[test]
    fn truncate_at_stop_excludes_stop_sequence() {
        let stops = vec!["<|end|>".to_string(), "STOP".to_string()];
        assert_eq!(
            tasks::generate::truncate_at_stop("hello world<|end|>extra", &stops),
            "hello world"
        );
        // Earliest match wins.
        assert_eq!(
            tasks::generate::truncate_at_stop("aSTOPb<|end|>c", &stops),
            "a"
        );
        // No match -> unchanged.
        assert_eq!(
            tasks::generate::truncate_at_stop("clean output", &stops),
            "clean output"
        );
        // Empty stop entries ignored.
        assert_eq!(
            tasks::generate::truncate_at_stop("text", &["".to_string()]),
            "text"
        );
    }

    #[test]
    fn no_backend_hint_fires_on_missing_backend_phrases() {
        // The four phrases the engine emits when nothing is runnable.
        for phrase in [
            "no credential for proprietary provider 'parslee'",
            "model not found",
            "no models available",
            "model declares ModelSource::Delegated but no inference runner is registered",
        ] {
            let hint = no_backend_recovery_hint(phrase)
                .unwrap_or_else(|| panic!("expected a hint for {phrase:?}"));
            assert!(hint.contains("car models pull"));
            // The CLI verb is `car auth login` (no `parslee` positional — that
            // was a stale doc-ism the hint used to print).
            assert!(hint.contains("car auth login"));
            // Underlying error is preserved for diagnosis.
            assert!(hint.contains(phrase));
        }
    }

    /// Parslee-ai/car#797 item 2 — the credential failure is matchable as DATA,
    /// not by substring-matching English that can be reworded at any time.
    ///
    /// The distinction that matters to a consumer: a token that aged out
    /// mid-run is a *resumable* condition for anything that can checkpoint,
    /// while a signed-out account is a hard stop, and an unreadable keychain is
    /// neither (re-authenticating does not help it).
    #[test]
    fn credential_failure_is_matchable_as_data() {
        let expired = InferenceError::CredentialUnavailable {
            provider: "parslee".into(),
            model: "parslee/reasoning".into(),
            reason: CredentialFailure::Expired {
                expires_at: 1_754_257_929,
            },
            detail: "the Parslee token expired at unix 1754257929 and could not be refreshed"
                .into(),
        };
        let InferenceError::CredentialUnavailable { reason, .. } = &expired else {
            panic!("expected CredentialUnavailable");
        };
        assert_eq!(
            *reason,
            CredentialFailure::Expired {
                expires_at: 1_754_257_929
            },
            "a consumer must be able to branch on the expiry without parsing prose"
        );
        // The four failure modes are distinct values, because each has a
        // different remedy and collapsing any two would send a user to the
        // wrong one.
        assert_ne!(
            CredentialFailure::SignedOut,
            CredentialFailure::StoreUnreadable
        );
        assert_ne!(
            CredentialFailure::SignedOut,
            CredentialFailure::Expired { expires_at: 0 }
        );
        assert_ne!(
            CredentialFailure::StoreUnreadable,
            CredentialFailure::RaceRetryable
        );
    }

    /// The typed variant must keep rendering the historical prefix, because two
    /// downstream classifiers substring-match it.
    ///
    /// `native_loop::is_auth_failure` drives the wait-for-sign-in path, and the
    /// coder-ab harness's `INFRA_MARKERS` keeps auth casualties out of a
    /// benchmark denominator. Both look for `no credential for proprietary`.
    /// Changing the error from a formatted string to a typed variant is exactly
    /// the kind of refactor that silently breaks them, so this pins the
    /// rendering rather than trusting the `#[error]` attribute to stay put.
    #[test]
    fn typed_credential_error_still_satisfies_the_substring_classifiers() {
        for reason in [
            CredentialFailure::Expired { expires_at: 1 },
            CredentialFailure::SignedOut,
            CredentialFailure::StoreUnreadable,
            CredentialFailure::RaceRetryable,
            CredentialFailure::EnvVarMissing {
                env_var: "OPENAI_API_KEY".into(),
            },
        ] {
            let rendered = InferenceError::CredentialUnavailable {
                provider: "parslee".into(),
                model: "parslee/reasoning".into(),
                reason: reason.clone(),
                detail: "detail text".into(),
            }
            .to_string();
            // `native_loop::is_auth_failure` + coder_ab INFRA_MARKERS.
            assert!(
                rendered
                    .to_ascii_lowercase()
                    .contains("no credential for proprietary"),
                "classifier substring lost for {reason:?}: {rendered}"
            );
            // The model is named, so a multi-model run can tell which call died.
            assert!(rendered.contains("parslee/reasoning"), "{rendered}");
            // And the human-facing detail survives.
            assert!(rendered.contains("detail text"), "{rendered}");
        }
    }

    #[test]
    fn auth_expired_hint_fires_on_auth_rejection_but_not_transient() {
        // Auth-rejection exhaustion → actionable re-auth guidance.
        for phrase in [
            "Parslee org lookup failed: HTTP 401 Unauthorized: Authentication required",
            "HTTP 403: forbidden",
            "invalid_grant: The refresh token is invalid or expired",
            "token expired",
        ] {
            let hint = auth_expired_recovery_hint(phrase)
                .unwrap_or_else(|| panic!("expected an auth hint for {phrase:?}"));
            assert!(hint.contains("car auth login"));
            assert!(hint.contains(phrase));
        }
        // A genuine transient (5xx / timeout) must NOT be classified as auth.
        assert!(auth_expired_recovery_hint("API returned 503: service unavailable").is_none());
        assert!(auth_expired_recovery_hint("request timed out").is_none());
    }

    #[test]
    fn no_backend_hint_passes_through_transient_errors() {
        // Real failures on otherwise-configured models must NOT be
        // relabeled as "no backend / run setup" — they pass through.
        for phrase in [
            "API returned 401 Unauthorized",
            "API returned 429 Too Many Requests",
            "API returned 500 Internal Server Error",
            "connection refused",
            "request timed out",
            "parse response: unexpected end of input",
        ] {
            assert!(
                no_backend_recovery_hint(phrase).is_none(),
                "transient error wrongly classified as no-backend: {phrase:?}"
            );
        }
    }

    /// Tests that mutate process-wide env vars must hold this lock to avoid
    /// races with parallel tests (env vars are global mutable state).
    static ENV_MUTEX: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());

    fn test_config(models_dir: PathBuf) -> InferenceConfig {
        InferenceConfig {
            models_dir,
            device: None,
            generation_model: "Qwen3-0.6B".into(),
            preferred_generation_model: None,
            embedding_model: "Qwen3-Embedding-0.6B".into(),
            preferred_embedding_model: None,
            classification_model: "Qwen3-0.6B".into(),
            preferred_classification_model: None,
        }
    }

    #[derive(Clone, Copy)]
    enum CacheRoutingSurface {
        Generate,
        Stream,
    }

    /// Exercise cache-aware pricing through the public tracked generation
    /// surfaces, including adaptive selection and a real mocked OpenRouter HTTP
    /// request. This deliberately does not call the scorer directly: a routing
    /// field that exists only in `RouteRequest` but is dropped by either
    /// production call path must make these tests fail.
    async fn invoke_cache_routed_openrouter(
        surface: CacheRoutingSurface,
        cache_read_estimate: usize,
        cache_write_estimate: usize,
    ) -> String {
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let _credential_scope = crate::openrouter::test_credential_scope();
        crate::openrouter::set_test_credential(Some("test-openrouter-key"));
        let server = MockServer::start().await;
        let response = match surface {
            CacheRoutingSurface::Generate => ResponseTemplate::new(200).set_body_json(
                serde_json::json!({
                    "choices": [{
                        "message": {"role": "assistant", "content": "cache-route-ok"},
                        "finish_reason": "stop"
                    }],
                    "usage": {"prompt_tokens": 40_000, "completion_tokens": 8}
                }),
            ),
            CacheRoutingSurface::Stream => ResponseTemplate::new(200).set_body_raw(
                concat!(
                    "data: {\"choices\":[{\"delta\":{\"content\":\"cache-route-ok\"},\"finish_reason\":\"stop\"}]}\n\n",
                    "data: [DONE]\n\n"
                ),
                "text/event-stream",
            ),
        };
        Mock::given(method("POST"))
            .and(path("/v1/chat/completions"))
            .respond_with(response)
            .mount(&server)
            .await;

        let tmp = TempDir::new().unwrap();
        let mut engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let mut uncached_cheap = crate::openrouter::curated_schemas()
            .into_iter()
            .find(|schema| schema.id == "openrouter/deepseek/deepseek-v3.2")
            .unwrap();
        uncached_cheap.id = "openrouter/test/uncached-cheap".into();
        uncached_cheap.name = uncached_cheap.id.clone();
        uncached_cheap.cost = CostModel {
            input_per_mtok: Some(1.0),
            output_per_mtok: Some(1.0),
            cache_read_input_per_mtok: Some(100.0),
            cache_write_input_per_mtok: Some(100.0),
            ..Default::default()
        };
        if let ModelSource::RemoteApi { endpoint, .. } = &mut uncached_cheap.source {
            *endpoint = server.uri();
        }

        let mut cached_cheap = uncached_cheap.clone();
        cached_cheap.id = "openrouter/test/cached-cheap".into();
        cached_cheap.name = cached_cheap.id.clone();
        cached_cheap.cost = CostModel {
            input_per_mtok: Some(80.0),
            output_per_mtok: Some(1.0),
            cache_read_input_per_mtok: Some(0.001),
            cache_write_input_per_mtok: Some(0.001),
            ..Default::default()
        };

        let uncached_id = uncached_cheap.id.clone();
        let cached_id = cached_cheap.id.clone();
        engine
            .unified_registry
            .register_project_model(uncached_cheap);
        engine.unified_registry.register_project_model(cached_cheap);
        let exclude_models = engine
            .list_schemas()
            .into_iter()
            .map(|schema| schema.id)
            .filter(|id| id != &uncached_id && id != &cached_id)
            .collect();

        // bytes/4 => 40K estimated prompt tokens. An explicit read estimate is
        // clamped to that footprint; zero remains an honest "no cache knowledge"
        // rather than being inferred from cache_control.
        let mut params = GenerateParams {
            max_tokens: 8,
            ..Default::default()
        };
        assert_eq!(params.estimated_cache_read_input_tokens, 0);
        assert_eq!(params.estimated_cache_write_input_tokens, 0);
        params.estimated_cache_read_input_tokens = cache_read_estimate;
        params.estimated_cache_write_input_tokens = cache_write_estimate;
        let req = GenerateRequest {
            prompt: "x".repeat(160_000),
            params,
            cache_control: true,
            intent: Some(IntentHint {
                prefer_quality: true,
                exclude_models,
                ..Default::default()
            }),
            ..Default::default()
        };

        match surface {
            CacheRoutingSurface::Generate => {
                engine
                    .generate_tracked(req)
                    .await
                    .expect("mocked OpenRouter generation should succeed")
                    .model_used
            }
            CacheRoutingSurface::Stream => {
                let mut handle = engine
                    .generate_tracked_stream(req)
                    .await
                    .expect("mocked OpenRouter stream should start");
                let selected = handle.model_used.clone();
                while handle.events.recv().await.is_some() {}
                selected
            }
        }
    }

    #[tokio::test(flavor = "current_thread")]
    async fn tracked_generate_uses_explicit_cache_estimate_and_defaults_to_zero() {
        let without_estimate =
            invoke_cache_routed_openrouter(CacheRoutingSurface::Generate, 0, 0).await;
        let with_estimate =
            invoke_cache_routed_openrouter(CacheRoutingSurface::Generate, 40_000, 0).await;
        assert_eq!(without_estimate, "openrouter/test/uncached-cheap");
        assert_eq!(with_estimate, "openrouter/test/cached-cheap");
    }

    #[tokio::test(flavor = "current_thread")]
    async fn tracked_stream_uses_explicit_cache_estimate_and_defaults_to_zero() {
        let without_estimate =
            invoke_cache_routed_openrouter(CacheRoutingSurface::Stream, 0, 0).await;
        let with_estimate =
            invoke_cache_routed_openrouter(CacheRoutingSurface::Stream, 0, 40_000).await;
        assert_eq!(without_estimate, "openrouter/test/uncached-cheap");
        assert_eq!(with_estimate, "openrouter/test/cached-cheap");
    }

    #[tokio::test(flavor = "current_thread")]
    async fn authenticated_openrouter_registry_stays_static_and_rejects_unknown_ids() {
        let _credential_scope = crate::openrouter::test_credential_scope();
        crate::openrouter::set_test_credential(Some("static-key"));
        let tmp = TempDir::new().unwrap();
        let engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let personal: Vec<_> = engine
            .list_schemas()
            .into_iter()
            .filter(|schema| schema.id.starts_with("openrouter/"))
            .collect();
        assert_eq!(personal.len(), crate::openrouter::curated_model_count());
        assert!(personal.iter().all(ModelSchema::available_now));
        assert!(personal
            .iter()
            .all(|schema| schema.trust_tier == TrustTier::Curated));
        assert!(personal
            .iter()
            .all(|schema| !schema.tags.iter().any(|tag| tag == "dynamic")));

        for unknown in [
            "openrouter/vendor/brand-new-model",
            "openrouter/openai/gpt-5.4-typo",
        ] {
            assert!(engine
                .list_schemas()
                .iter()
                .all(|schema| schema.id != unknown));
            assert_eq!(engine.model_context_window(unknown), 0);
            let error = engine
                .generate_tracked(GenerateRequest {
                    prompt: "must fail before transport".into(),
                    model: Some(unknown.into()),
                    params: GenerateParams {
                        strict_model: true,
                        ..Default::default()
                    },
                    ..Default::default()
                })
                .await
                .expect_err("unregistered personal OpenRouter ids must not reach inference");
            assert!(
                matches!(&error, InferenceError::ModelNotFound(id) if id == unknown),
                "{unknown}: {error}"
            );
            let stream_error = match engine
                .generate_tracked_stream(GenerateRequest {
                    prompt: "must fail before stream transport".into(),
                    model: Some(unknown.into()),
                    ..Default::default()
                })
                .await
            {
                Ok(_) => panic!("unregistered ids must also fail before streaming"),
                Err(error) => error,
            };
            assert!(
                matches!(&stream_error, InferenceError::ModelNotFound(id) if id == unknown),
                "{unknown}: {stream_error}"
            );
        }
    }

    #[tokio::test(flavor = "current_thread")]
    async fn static_openrouter_rows_participate_in_adaptive_routing_only_with_a_key() {
        let _credential_scope = crate::openrouter::test_credential_scope();
        let _provider_env = crate::openrouter::test_environment_scope_async().await;
        let tmp = TempDir::new().unwrap();
        crate::openrouter::set_test_credential(Some("static-key"));
        unsafe {
            std::env::set_var("CAR_STATIC_ROUTING_PEER_KEY", "peer-key");
        }
        let mut engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let mut peer = remote_stream_fixture_schema(
            "test/openai-routing-peer",
            "http://127.0.0.1:9".into(),
            schema::ApiProtocol::OpenAiCompat,
            "CAR_STATIC_ROUTING_PEER_KEY",
        );
        peer.provider = "openai".into();
        peer.trust_tier = TrustTier::Curated;
        engine.unified_registry.register_project_model(peer);
        let reviewed: std::collections::HashSet<_> = engine
            .list_schemas()
            .into_iter()
            .filter(|schema| schema.id.starts_with("openrouter/"))
            .map(|schema| schema.id)
            .collect();
        assert_eq!(reviewed.len(), crate::openrouter::curated_model_count());

        let with_key = engine
            .route_adaptive_with_intent(
                "Answer this simple question cheaply.",
                Some(IntentHint::default()),
            )
            .await;
        let openrouter_candidates: Vec<_> = std::iter::once(with_key.model_id.as_str())
            .chain(
                with_key
                    .candidates
                    .iter()
                    .map(|candidate| candidate.model_id.as_str()),
            )
            .chain(with_key.fallbacks.iter().map(String::as_str))
            .filter(|id| id.starts_with("openrouter/"))
            .collect();
        assert!(
            !openrouter_candidates.is_empty(),
            "keyed adaptive decision must include a reviewed OpenRouter row: {with_key:?}"
        );
        assert!(openrouter_candidates
            .iter()
            .all(|id| reviewed.contains(*id)));
        assert!(
            std::iter::once(with_key.model_id.as_str())
                .chain(with_key.fallbacks.iter().map(String::as_str),)
                .any(|id| !id.starts_with("openrouter/")),
            "fallback chain must retain cross-provider alternatives: {with_key:?}"
        );

        crate::openrouter::set_test_credential(None);
        let without_key = engine
            .route_adaptive_with_intent(
                "Answer this simple question cheaply.",
                Some(IntentHint::default()),
            )
            .await;
        assert!(!std::iter::once(without_key.model_id.as_str())
            .chain(
                without_key
                    .candidates
                    .iter()
                    .map(|candidate| candidate.model_id.as_str()),
            )
            .chain(without_key.fallbacks.iter().map(String::as_str))
            .any(|id| id.starts_with("openrouter/")));
        unsafe {
            std::env::remove_var("CAR_STATIC_ROUTING_PEER_KEY");
        }
    }

    #[tokio::test(flavor = "current_thread")]
    async fn v2_parslee_auth_drives_managed_registration_routing_lane_and_logout() {
        let tmp = TempDir::new().unwrap();
        let _credential_scope = crate::openrouter::test_credential_scope();
        let _provider_env = crate::openrouter::test_environment_scope_async().await;
        let _restore = RestoredEnvironment::capture(&[
            "CAR_SECRETS_FILE_DIR",
            car_auth::PARSLEE_ACCESS_TOKEN_KEY,
        ]);
        let secrets_dir = tmp.path().join("secrets");
        unsafe {
            std::env::set_var("CAR_SECRETS_FILE_DIR", &secrets_dir);
            std::env::remove_var(car_auth::PARSLEE_ACCESS_TOKEN_KEY);
        }
        crate::openrouter::set_test_credential(Some("personal-openrouter-key"));

        let store = car_secrets::SecretStore::new();
        let state_ref =
            car_secrets::SecretRef::with_default_service(car_secrets::PARSLEE_AUTH_STATE_V2_KEY);
        store
            .publish(
                &state_ref,
                &serde_json::json!({
                    "schema": 2,
                    "revision": 7,
                    "generation": 3,
                    "active": {
                        "account_id": "account-v2",
                        "access_token": "v2-access",
                        "refresh_token": "v2-refresh",
                        "expires_at": 9_999_999_999_u64,
                        "api_base": "https://api.parslee.ai"
                    },
                    "accounts": [{
                        "account_id": "account-v2",
                        "access_token": "v2-access",
                        "refresh_token": "v2-refresh",
                        "expires_at": 9_999_999_999_u64,
                        "api_base": "https://api.parslee.ai"
                    }],
                    "tombstone": false
                })
                .to_string(),
            )
            .unwrap();
        assert_eq!(car_auth::access_token().as_deref(), Some("v2-access"));
        assert!(
            !store
                .status(&car_secrets::SecretRef::with_default_service(
                    car_auth::PARSLEE_ACCESS_TOKEN_KEY,
                ))
                .unwrap()
                .exists,
            "the regression must exercise V2 state without the import-only legacy slot"
        );

        let managed_ids = [
            "parslee/openrouter/frontier-general",
            "parslee/openrouter/balanced-general",
        ];
        let personal_id = "openrouter/deepseek/deepseek-v3.2";
        let rogue_id = "community/custom-oauth";
        let schemas = crate::openrouter::curated_schemas();
        let mut registry = UnifiedRegistry::new_empty(tmp.path().join("registry-models"));
        for id in managed_ids.into_iter().chain(std::iter::once(personal_id)) {
            registry.register_project_model(
                schemas
                    .iter()
                    .find(|schema| schema.id == id)
                    .unwrap_or_else(|| panic!("missing curated schema {id}"))
                    .clone(),
            );
        }
        for id in managed_ids {
            assert!(
                registry.get(id).unwrap().available_now(),
                "{id} must be available immediately when registered from V2 auth"
            );
        }
        assert!(registry.get(personal_id).unwrap().available_now());
        let mut rogue = schemas
            .iter()
            .find(|schema| schema.id == managed_ids[0])
            .unwrap()
            .clone();
        rogue.id = rogue_id.into();
        rogue.provider = "community".into();
        if let ModelSource::Proprietary {
            provider, endpoint, ..
        } = &mut rogue.source
        {
            *provider = "community".into();
            *endpoint = "https://untrusted.example".into();
        } else {
            panic!("managed fixture must remain proprietary");
        }
        registry.register(rogue);
        assert!(
            !registry.get(rogue_id).unwrap().available_now(),
            "a non-Parslee OAuth schema must not inherit Parslee V2 availability"
        );

        registry.refresh_availability();
        for id in managed_ids {
            assert!(
                registry.get(id).unwrap().available_now(),
                "{id} must stay available in a refreshed V2-auth snapshot"
            );
        }
        assert!(
            !registry.get(rogue_id).unwrap().available_now(),
            "refresh must keep non-Parslee OAuth schemas unavailable"
        );

        let router = AdaptiveRouter::new(
            crate::hardware::HardwareInfo::detect(),
            RoutingConfig {
                prefer_local: false,
                prior_strength: 1_000_000.0,
                quality_first_cold_start: false,
                ..RoutingConfig::default()
            },
        );
        let tracker = OutcomeTracker::new();
        let intent = IntentHint {
            task: Some(crate::intent::TaskHint::Chat),
            exclude_models: vec![personal_id.into()],
            ..Default::default()
        };
        let decision = router.route_with(crate::adaptive_router::RouteRequest {
            intent: Some(&intent),
            ..crate::adaptive_router::RouteRequest::new(
                "Explain this architecture.",
                &registry,
                &tracker,
            )
        });
        assert!(
            managed_ids.contains(&decision.model_id.as_str()),
            "managed V2-auth alias must be selectable: {decision:?}"
        );
        assert!(
            decision
                .candidates
                .iter()
                .any(|candidate| managed_ids.contains(&candidate.model_id.as_str())),
            "managed V2-auth alias must appear in adaptive candidates: {decision:?}"
        );
        assert!(
            decision
                .fallbacks
                .iter()
                .any(|id| managed_ids.contains(&id.as_str())),
            "managed V2-auth alias must appear in adaptive fallbacks: {decision:?}"
        );
        assert!(
            !std::iter::once(decision.model_id.as_str())
                .chain(
                    decision
                        .candidates
                        .iter()
                        .map(|candidate| candidate.model_id.as_str())
                )
                .chain(decision.fallbacks.iter().map(String::as_str))
                .any(|id| id == rogue_id),
            "a non-Parslee OAuth schema must never enter adaptive selection, candidates, or fallbacks: {decision:?}"
        );

        let engine = InferenceEngine::new(test_config(tmp.path().join("engine-models")));
        let managed_lane_id = managed_ids[0];
        engine.lane_defaults_cache.write().unwrap().set(
            None,
            crate::intent::UseCase::Assistant,
            managed_lane_id.into(),
            1,
        );
        let request = GenerateRequest {
            prompt: "lane default".into(),
            intent: Some(IntentHint {
                task: Some(crate::intent::TaskHint::Chat),
                ..Default::default()
            }),
            ..Default::default()
        };
        assert_eq!(
            engine.lane_pin_for(&request, &engine.routing_registry_snapshot()),
            Some(managed_lane_id.to_string()),
            "a managed lane default must resolve from authoritative V2 auth"
        );

        store
            .publish(
                &state_ref,
                r#"{"schema":2,"revision":8,"generation":4,"accounts":[],"tombstone":true}"#,
            )
            .unwrap();
        assert_eq!(car_auth::access_token(), None);

        registry.refresh_availability();
        for id in managed_ids {
            assert!(
                !registry.get(id).unwrap().available_now(),
                "{id} must disappear from routing after the signed-out tombstone"
            );
        }
        assert!(
            registry.get(personal_id).unwrap().available_now(),
            "personal rows must continue to follow their independent personal-key seam"
        );

        let signed_out = engine.routing_registry_snapshot();
        assert!(
            signed_out
                .list()
                .into_iter()
                .filter(|schema| schema.id.starts_with("parslee/openrouter/"))
                .all(|schema| !schema.available_now()),
            "the next engine snapshot must exclude every managed alias after logout"
        );
        assert!(
            signed_out.get(personal_id).unwrap().available_now(),
            "logout must not disable a still-keyed personal OpenRouter row"
        );
        assert_eq!(
            engine.lane_pin_for(&request, &signed_out),
            None,
            "a signed-out managed lane default must stop resolving"
        );

        crate::openrouter::set_test_credential(None);
        registry.refresh_availability();
        assert!(
            !registry.get(personal_id).unwrap().available_now(),
            "personal row availability must still turn off with the personal-key seam"
        );
    }

    #[tokio::test(flavor = "current_thread")]
    async fn legacy_parslee_auth_is_routable_only_until_v2_tombstone_then_migrates() {
        let tmp = TempDir::new().unwrap();
        let _provider_env = crate::openrouter::test_environment_scope_async().await;
        let _restore = RestoredEnvironment::capture(&[
            "CAR_SECRETS_FILE_DIR",
            car_auth::PARSLEE_ACCESS_TOKEN_KEY,
        ]);
        unsafe {
            std::env::remove_var(car_auth::PARSLEE_ACCESS_TOKEN_KEY);
        }

        let secret = |key| car_secrets::SecretRef::with_default_service(key);
        let seed_legacy = |store: &car_secrets::SecretStore| {
            store
                .put(
                    &secret(car_secrets::PARSLEE_ACCESS_TOKEN_KEY),
                    "legacy-access",
                )
                .unwrap();
            store
                .put(
                    &secret(car_secrets::PARSLEE_ACTIVE_ACCOUNT_ID_KEY),
                    "legacy-account",
                )
                .unwrap();
            store.put(
                &secret(car_secrets::PARSLEE_ACCOUNTS_KEY),
                r#"{"active":"legacy-account","accounts":[{"id":"legacy-account","email":"legacy@example.test"}]}"#,
            )
            .unwrap();
        };
        let state_ref = secret(car_secrets::PARSLEE_AUTH_STATE_V2_KEY);
        let managed = crate::openrouter::curated_schemas()
            .into_iter()
            .find(|schema| schema.id == "parslee/openrouter/frontier-general")
            .unwrap();

        unsafe {
            std::env::set_var("CAR_SECRETS_FILE_DIR", tmp.path().join("tombstone-secrets"));
        }
        let tombstoned_store = car_secrets::SecretStore::new();
        seed_legacy(&tombstoned_store);
        tombstoned_store
            .publish(
                &state_ref,
                r#"{"schema":2,"revision":1,"generation":1,"accounts":[],"tombstone":true}"#,
            )
            .unwrap();
        let mut tombstoned_registry =
            UnifiedRegistry::new_empty(tmp.path().join("tombstoned-models"));
        tombstoned_registry.register_project_model(managed.clone());
        assert!(
            !tombstoned_registry
                .get(&managed.id)
                .unwrap()
                .available_now(),
            "an authoritative V2 tombstone must win over stale legacy cleanup"
        );
        tombstoned_registry.refresh_availability();
        assert!(!tombstoned_registry
            .get(&managed.id)
            .unwrap()
            .available_now());

        unsafe {
            std::env::set_var(
                "CAR_SECRETS_FILE_DIR",
                tmp.path().join("legacy-only-secrets"),
            );
        }
        let legacy_store = car_secrets::SecretStore::new();
        seed_legacy(&legacy_store);
        assert!(!legacy_store.status(&state_ref).unwrap().exists);
        let mut registry = UnifiedRegistry::new_empty(tmp.path().join("legacy-models"));
        registry.register_project_model(managed.clone());
        assert!(
            registry.get(&managed.id).unwrap().available_now(),
            "an attributable pre-V2 token must keep managed aliases routable so request-time migration can run"
        );
        registry.refresh_availability();
        assert!(
            registry.get(&managed.id).unwrap().available_now(),
            "legacy availability must survive a refreshed snapshot until request-time migration"
        );
        let snapshot = car_auth::local_auth_snapshot().await.unwrap();
        assert!(snapshot.authenticated);
        assert_eq!(
            snapshot.active_account_id.as_deref(),
            Some("legacy-account")
        );
        assert!(
            legacy_store.status(&state_ref).unwrap().exists,
            "request-time auth reconciliation must publish the migrated V2 record"
        );
        assert!(
            !legacy_store
                .status(&secret(car_secrets::PARSLEE_ACCESS_TOKEN_KEY))
                .unwrap()
                .exists,
            "successful V2 migration must clean the legacy access slot"
        );
    }

    #[test]
    fn reviewed_openrouter_lane_default_tracks_live_credential_availability() {
        let _credential_scope = crate::openrouter::test_credential_scope();
        crate::openrouter::set_test_credential(Some("static-key"));
        let tmp = TempDir::new().unwrap();
        let engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let reviewed_id = "openrouter/deepseek/deepseek-v3.2";
        engine.lane_defaults_cache.write().unwrap().set(
            None,
            crate::intent::UseCase::Assistant,
            reviewed_id.into(),
            1,
        );
        let request = GenerateRequest {
            prompt: "lane default".into(),
            intent: Some(IntentHint {
                task: Some(crate::intent::TaskHint::Chat),
                ..Default::default()
            }),
            ..Default::default()
        };
        assert_eq!(
            engine.lane_pin_for(&request, &engine.routing_registry_snapshot()),
            Some(reviewed_id.to_string()),
            "a reviewed keyed row must be eligible as a lane default"
        );
        crate::openrouter::set_test_credential(None);
        assert_eq!(
            engine.lane_pin_for(&request, &engine.routing_registry_snapshot()),
            None,
            "the same static lane default must stop being eligible immediately after key removal"
        );
    }

    #[tokio::test(flavor = "current_thread")]
    async fn personal_openrouter_baseline_remains_visible_but_disabled_without_a_credential() {
        let _credential_scope = crate::openrouter::test_credential_scope();
        crate::openrouter::set_test_credential(None);
        let tmp = TempDir::new().unwrap();
        let engine = InferenceEngine::new(test_config(tmp.path().join("models")));

        let personal: Vec<_> = engine
            .list_schemas()
            .into_iter()
            .filter(|schema| schema.id.starts_with("openrouter/"))
            .collect();
        assert_eq!(
            personal.len(),
            crate::openrouter::curated_model_count(),
            "the vetted personal rows stay discoverable as a disabled baseline"
        );
        assert!(
            personal.iter().all(|schema| !schema.available_now()),
            "no-key baseline rows must never become routing candidates"
        );

        let error = engine
            .generate_tracked(GenerateRequest {
                prompt: "hello".into(),
                model: Some("openrouter/openai/gpt-5.4".into()),
                params: GenerateParams {
                    strict_model: true,
                    ..Default::default()
                },
                ..Default::default()
            })
            .await
            .expect_err("explicitly selecting a disabled baseline row must be actionable");
        let message = error.to_string();
        assert!(
            message.contains("car keys set openrouter") && message.contains("CarHost"),
            "disabled personal row must explain how to connect OpenRouter: {message}"
        );
    }

    #[test]
    fn reviewed_openrouter_metadata_stays_static_across_credential_changes() {
        let _credential_scope = crate::openrouter::test_credential_scope();
        crate::openrouter::set_test_credential(Some("static-key"));

        let tmp = TempDir::new().unwrap();
        let engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let live = engine.routing_registry_snapshot();
        let vetted = live.get("openrouter/openai/gpt-5.4").unwrap();
        assert!(vetted.available_now());
        assert_eq!(vetted.context_length, 1_050_000);
        assert_eq!(vetted.max_output_tokens, Some(128_000));
        assert_eq!(vetted.cost.input_per_mtok, Some(2.5));
        assert_eq!(vetted.cost.output_per_mtok, Some(15.0));
        assert!(
            !vetted.cost.pricing_tiers.is_empty(),
            "reviewed high-context pricing tiers must remain in the static row"
        );
        assert_eq!(vetted.trust_tier, TrustTier::Curated);
        assert!(vetted.tags.iter().any(|tag| tag == "frontier"));
        assert!(vetted.has_capability(ModelCapability::Code));
        assert!(vetted
            .supported_params
            .contains(&schema::GenerateParam::ExtendedThinking));

        assert!(live.get("openrouter/vendor/unreviewed-model").is_none());

        crate::openrouter::set_test_credential(None);
        let reverted = engine.routing_registry_snapshot();
        assert!(reverted.get("openrouter/vendor/unreviewed-model").is_none());
        let baseline = reverted.get("openrouter/openai/gpt-5.4").unwrap();
        assert!(
            !baseline.available_now(),
            "credential removal must disable the reviewed row without removing it"
        );
    }

    /// Parslee-ai/car#651 — a model pulled against a **running** daemon must
    /// count as ready without a restart.
    ///
    /// `weights_ready` is assigned in `UnifiedRegistry::register`, and the
    /// daemon's engine is a `get_or_init` singleton behind an `Arc` with no
    /// interior mutability on the registry — so if that assignment were the
    /// only one, the flag would be frozen to the on-disk state at boot for the
    /// daemon's lifetime. The `require_ready` filter would keep skipping a
    /// freshly-pulled model, the soft fallback would drop `require_ready`
    /// entirely, and the remedy the #638 timeout message prints (`car models
    /// pull <id>`) would do nothing until a restart.
    ///
    /// It isn't the only one: `refresh_availability` recomputes `weights_ready`
    /// too, and every routing and listing entry point goes through
    /// `routing_registry_snapshot` (clone + refresh) rather than the frozen
    /// registry. This pins that contract from the outside — through the engine
    /// surface, with no `&mut` and no re-registration, exactly as the daemon
    /// holds it. `list_schemas` reads the same snapshot the router filters on.
    #[test]
    fn model_pulled_at_runtime_is_ready_without_a_daemon_restart() {
        let tmp = TempDir::new().unwrap();
        let models_dir = tmp.path().join("models");
        let mut engine = InferenceEngine::new(test_config(models_dir.clone()));
        engine.register_model(ModelSchema {
            id: "mlx/pulled-later".into(),
            name: "PulledLater".into(),
            provider: "local".into(),
            family: "qwen3".into(),
            version: "test".into(),
            capabilities: vec![ModelCapability::Generate, ModelCapability::Code],
            context_length: 4096,
            max_output_tokens: None,
            param_count: String::new(),
            quantization: None,
            performance: schema::PerformanceEnvelope::default(),
            cost: schema::CostModel::default(),
            source: ModelSource::Mlx {
                hf_repo: "example/pulled-later".into(),
                hf_weight_file: None,
            },
            tags: vec![],
            supported_params: vec![],
            public_benchmarks: vec![],
            trust_tier: TrustTier::Curated,
            deprecated: false,
            available: true,
            weights_ready: false,
        });

        // From here on the engine is shared-immutable — the daemon regime.
        let engine = &engine;
        let is_ready = || {
            engine
                .list_schemas()
                .into_iter()
                .find(|s| s.id == "mlx/pulled-later")
                .expect("registered model must be listed")
                .weights_ready
        };

        assert!(!is_ready(), "precondition: no weights on disk yet");

        // `car models pull` against the running daemon: weights land on disk
        // via `ensure_local` (&self), and nothing re-registers the schema.
        let dir = models_dir.join("PulledLater");
        std::fs::create_dir_all(&dir).unwrap();
        std::fs::write(dir.join("config.json"), "{}").unwrap();
        std::fs::write(dir.join("model.safetensors"), b"weights").unwrap();

        assert!(
            is_ready(),
            "a model pulled at runtime must be ready without restarting the daemon"
        );

        // And the inverse, so this can't pass on a flag that is merely stuck
        // true: weights removed out from under a live daemon stop being ready.
        std::fs::remove_file(dir.join("model.safetensors")).unwrap();
        assert!(
            !is_ready(),
            "readiness must track the disk in both directions, not latch"
        );
    }

    /// Parslee-ai/car#650 — an out-of-credits account must not be recorded as
    /// the *model* being unreliable.
    ///
    /// A 402 (and 401/403) is account-wide: every model on that account fails
    /// it identically. Booking it through `record_failure` degraded the model's
    /// 30-day health EMA and tripped its per-model circuit breaker, and because
    /// the fallback loop walked every candidate on the account it did that to
    /// all of them at once. The user tops up their credits and the router keeps
    /// deprioritizing the models — a penalty that outlives its cause.
    ///
    /// The receipt is still written (operators need to see what happened); it
    /// just carries no success/quality verdict against the model.
    #[tokio::test(flavor = "current_thread")]
    async fn openrouter_out_of_credits_does_not_degrade_the_model() {
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let _credential_scope = crate::openrouter::test_credential_scope();
        crate::openrouter::set_test_credential(Some("test-openrouter-key"));
        let server = MockServer::start().await;
        Mock::given(method("POST"))
            .and(path("/v1/chat/completions"))
            .respond_with(
                ResponseTemplate::new(402)
                    .set_body_string(r#"{"error":{"code":402,"message":"Insufficient credits"}}"#),
            )
            .mount(&server)
            .await;

        let tmp = TempDir::new().unwrap();
        let models_dir = tmp.path().join("models");
        let mut engine = InferenceEngine::new(test_config(models_dir.clone()));
        let mut schema = crate::openrouter::curated_schemas()
            .into_iter()
            .find(|schema| schema.id == "openrouter/deepseek/deepseek-v3.2")
            .unwrap();
        if let ModelSource::RemoteApi { endpoint, .. } = &mut schema.source {
            *endpoint = server.uri();
        }
        let model_id = schema.id.clone();
        engine.unified_registry.register_project_model(schema);

        let err = engine
            .generate_tracked(GenerateRequest {
                prompt: "bill me".into(),
                model: Some(model_id.clone()),
                params: GenerateParams {
                    strict_model: true,
                    ..Default::default()
                },
                ..Default::default()
            })
            .await
            .expect_err("402 must not succeed");

        match &err {
            InferenceError::ProviderAccount {
                provider, status, ..
            } => {
                assert_eq!(status, &402);
                assert_eq!(provider, "openrouter");
            }
            other => panic!("expected ProviderAccount, got {other:?}"),
        }
        assert!(
            !error_counts_against_circuit_breaker(&err),
            "an account rejection must not feed the per-model breaker"
        );

        // The model's routing profile carries no failure from someone's billing.
        let tracker_handle = engine.outcome_tracker();
        let tracker = tracker_handle.read().await;
        let profile = tracker.profile(&model_id).cloned();
        assert!(
            profile.as_ref().is_none_or(|p| p.fail_count == 0),
            "account rejection degraded the model profile: {profile:?}"
        );
        drop(tracker);

        // ...but the attempt is still on the receipt ledger, unattributed. The
        // post-call auto-save has already drained the in-memory buffer to disk,
        // so read it back from where operators actually look.
        let ledger = crate::outcome::read_ledger(&models_dir.join("outcome_ledger.jsonl"), 0);
        let entry = ledger
            .iter()
            .find(|e| e.model_id == model_id)
            .expect("the attempt must still produce a receipt");
        assert!(
            entry.success.is_none() && entry.quality.is_none(),
            "receipt must record the attempt without a verdict: {entry:?}"
        );

        // And the breaker was never touched for this model.
        assert!(
            engine
                .adaptive_router
                .circuit_breakers
                .lock()
                .unwrap()
                .state(&model_id)
                .is_none(),
            "account rejection must not create breaker state for the model"
        );
    }

    #[tokio::test(flavor = "current_thread")]
    async fn openrouter_stream_error_records_failure_and_never_completes_successfully() {
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let _credential_scope = crate::openrouter::test_credential_scope();
        crate::openrouter::set_test_credential(Some("test-openrouter-key"));
        let server = MockServer::start().await;
        Mock::given(method("POST"))
            .and(path("/v1/chat/completions"))
            .respond_with(ResponseTemplate::new(200).set_body_raw(
                "data: {\"error\":{\"code\":402,\"message\":\"private balance details\"}}\n\n",
                "text/event-stream",
            ))
            .mount(&server)
            .await;

        let tmp = TempDir::new().unwrap();
        let mut engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let mut schema = crate::openrouter::curated_schemas()
            .into_iter()
            .find(|schema| schema.id == "openrouter/deepseek/deepseek-v3.2")
            .unwrap();
        if let ModelSource::RemoteApi { endpoint, .. } = &mut schema.source {
            *endpoint = server.uri();
        }
        let model_id = schema.id.clone();
        engine.unified_registry.register_project_model(schema);

        let mut handle = engine
            .generate_tracked_stream(GenerateRequest {
                prompt: "fail after headers".into(),
                model: Some(model_id.clone()),
                ..Default::default()
            })
            .await
            .unwrap();
        let mut events = Vec::new();
        while let Some(event) = handle.events.recv().await {
            events.push(event);
        }
        assert!(matches!(
            events.as_slice(),
            [StreamEvent::Error(message)] if message == "OpenRouter account is out of credits"
        ));
        assert!(!events
            .iter()
            .any(|event| matches!(event, StreamEvent::Done { .. })));

        for _ in 0..50 {
            if engine
                .outcome_tracker()
                .read()
                .await
                .profile(&model_id)
                .is_some_and(|profile| profile.fail_count == 1)
            {
                break;
            }
            tokio::task::yield_now().await;
        }
        let tracker = engine.outcome_tracker();
        let profile = tracker.read().await.profile(&model_id).cloned().unwrap();
        assert_eq!(profile.fail_count, 1);
        assert_eq!(profile.success_count, 0);
    }

    #[tokio::test(flavor = "current_thread")]
    async fn tracked_stream_without_done_records_failure_not_success() {
        let _offload_guard = crate::offload::test_offload_lock().lock().await;
        let tmp = TempDir::new().unwrap();
        let engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let model_id = install_small_local_fixture(&engine);
        crate::offload::set_local_offload(Some(Arc::new(FixtureLocalOffload { emit_done: false })));

        let mut stream = engine
            .generate_tracked_stream(GenerateRequest {
                prompt: "must not count as success".into(),
                model: Some(model_id.clone()),
                params: GenerateParams {
                    strict_model: true,
                    ..Default::default()
                },
                ..Default::default()
            })
            .await
            .unwrap();
        while stream.events.recv().await.is_some() {}
        crate::offload::set_local_offload(None);

        for _ in 0..50 {
            if engine
                .outcome_tracker()
                .read()
                .await
                .profile(&model_id)
                .is_some_and(|profile| profile.fail_count == 1)
            {
                break;
            }
            tokio::task::yield_now().await;
        }
        let profile = engine
            .outcome_tracker()
            .read()
            .await
            .profile(&model_id)
            .cloned()
            .unwrap();
        assert_eq!(profile.fail_count, 1);
        assert_eq!(profile.success_count, 0);
    }

    #[tokio::test(flavor = "current_thread")]
    async fn google_vertex_terminal_matrix_records_only_deliberate_finishes_as_success() {
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let _provider_env = crate::openrouter::test_environment_scope_async().await;
        let _env = ENV_MUTEX.lock().await;
        unsafe { std::env::set_var("CAR_GOOGLE_OUTCOME_MATRIX_KEY", "matrix-key") };

        for (protocol, reason, should_succeed) in [
            (schema::ApiProtocol::Google, "STOP", true),
            (schema::ApiProtocol::Google, "SAFETY", false),
            (schema::ApiProtocol::VertexAi, "MAX_TOKENS", true),
            (
                schema::ApiProtocol::VertexAi,
                "MALFORMED_FUNCTION_CALL",
                false,
            ),
        ] {
            let server = MockServer::start().await;
            let expected_path = match protocol {
                schema::ApiProtocol::Google => "/v1beta/models/gemini-test:streamGenerateContent",
                schema::ApiProtocol::VertexAi => {
                    "/publishers/google/models/gemini-test:streamGenerateContent"
                }
                _ => unreachable!(),
            };
            Mock::given(method("POST"))
                .and(path(expected_path))
                .respond_with(ResponseTemplate::new(200).set_body_raw(
                    format!(
                        "data: {{\"candidates\":[{{\"content\":{{\"parts\":[{{\"text\":\"matrix\"}}]}},\"finishReason\":\"{reason}\"}}]}}\n\n"
                    ),
                    "text/event-stream",
                ))
                .mount(&server)
                .await;

            let id = format!("test/{protocol:?}-{reason}");
            let tmp = TempDir::new().unwrap();
            let mut engine = InferenceEngine::new(test_config(tmp.path().join("models")));
            engine.register_model(remote_stream_fixture_schema(
                &id,
                server.uri(),
                protocol,
                "CAR_GOOGLE_OUTCOME_MATRIX_KEY",
            ));
            let mut stream = engine
                .generate_tracked_stream(GenerateRequest {
                    prompt: "matrix".into(),
                    model: Some(id.clone()),
                    params: GenerateParams {
                        strict_model: true,
                        ..Default::default()
                    },
                    ..Default::default()
                })
                .await
                .unwrap();
            let mut events = Vec::new();
            while let Some(event) = stream.events.recv().await {
                events.push(event);
            }
            for _ in 0..50 {
                if engine
                    .outcome_tracker()
                    .read()
                    .await
                    .profile(&id)
                    .is_some_and(|profile| profile.total_calls == 1)
                {
                    break;
                }
                tokio::task::yield_now().await;
            }
            let profile = engine
                .outcome_tracker()
                .read()
                .await
                .profile(&id)
                .cloned()
                .unwrap();
            assert_eq!(
                (profile.success_count, profile.fail_count),
                if should_succeed { (1, 0) } else { (0, 1) },
                "{protocol:?}/{reason}: {events:?}"
            );
        }

        unsafe { std::env::remove_var("CAR_GOOGLE_OUTCOME_MATRIX_KEY") };
    }

    #[tokio::test(flavor = "current_thread")]
    async fn remote_primary_stream_setup_failure_falls_back_to_installed_local_dispatch() {
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let _offload_guard = crate::offload::test_offload_lock().lock().await;
        let _env = ENV_MUTEX.lock().await;
        let server = MockServer::start().await;
        Mock::given(method("POST"))
            .and(path("/v1/chat/completions"))
            .respond_with(ResponseTemplate::new(503))
            .mount(&server)
            .await;
        unsafe { std::env::set_var("CAR_STREAM_FALLBACK_TEST_KEY", "fixture") };

        let tmp = TempDir::new().unwrap();
        let mut engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let _local_id = install_small_local_fixture(&engine);
        let remote_id = "test/remote-primary";
        engine.register_model(ModelSchema {
            id: remote_id.into(),
            name: "remote-primary".into(),
            provider: "test".into(),
            family: "test".into(),
            version: "1".into(),
            capabilities: vec![ModelCapability::Generate],
            context_length: 8_192,
            max_output_tokens: Some(1_024),
            param_count: String::new(),
            quantization: None,
            performance: Default::default(),
            cost: Default::default(),
            source: ModelSource::RemoteApi {
                endpoint: server.uri(),
                api_key_env: "CAR_STREAM_FALLBACK_TEST_KEY".into(),
                api_key_envs: vec![],
                api_version: None,
                protocol: schema::ApiProtocol::OpenAiCompat,
            },
            tags: vec![],
            supported_params: vec![],
            public_benchmarks: vec![],
            trust_tier: TrustTier::Community,
            deprecated: false,
            available: true,
            weights_ready: true,
        });
        crate::offload::set_local_offload(Some(Arc::new(FixtureLocalOffload { emit_done: true })));

        let mut stream = engine
            .generate_tracked_stream(GenerateRequest {
                prompt: "fall back".into(),
                model: Some(remote_id.into()),
                ..Default::default()
            })
            .await
            .expect("compatible installed local model should be dispatched");
        assert_ne!(stream.model_used, remote_id);
        assert!(
            engine
                .unified_registry
                .get(&stream.model_used)
                .is_some_and(ModelSchema::is_local),
            "fallback must stay on a compatible local model: {}",
            stream.model_used
        );
        let mut saw_done = false;
        while let Some(event) = stream.events.recv().await {
            saw_done |= matches!(event, StreamEvent::Done { .. });
        }
        assert!(saw_done);

        crate::offload::set_local_offload(None);
        unsafe { std::env::remove_var("CAR_STREAM_FALLBACK_TEST_KEY") };
    }

    #[tokio::test(flavor = "current_thread")]
    async fn managed_openrouter_reasoning_items_roundtrip_verbatim_across_two_turns() {
        use wiremock::matchers::{header, method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let _provider_env = crate::openrouter::test_environment_scope_async().await;
        let _env = ENV_MUTEX.lock().await;
        let bearer = "managed-reasoning-roundtrip-bearer";

        let server = MockServer::start().await;
        unsafe {
            std::env::set_var(crate::remote::PARSLEE_ACCESS_TOKEN_ENV, bearer);
            std::env::set_var(car_auth::PARSLEE_API_BASE_KEY, server.uri());
        }
        Mock::given(method("GET"))
            .and(path("/api/v1/organizations/me"))
            .and(header("authorization", format!("Bearer {bearer}")))
            .respond_with(
                ResponseTemplate::new(200)
                    .set_body_json(serde_json::json!({"organizationId": "org-roundtrip"})),
            )
            .mount(&server)
            .await;
        Mock::given(method("GET"))
            .and(path("/connect/session"))
            .respond_with(
                ResponseTemplate::new(200)
                    .set_body_json(serde_json::json!({"account": {"email": "user@example.test"}})),
            )
            .mount(&server)
            .await;
        Mock::given(method("POST"))
            .and(path("/api/v1/orgs/org-roundtrip/inference/responses"))
            .respond_with(ResponseTemplate::new(200).set_body_raw(
                include_str!("../tests/fixtures/parslee-openrouter-reasoning-roundtrip.sse"),
                "text/event-stream",
            ))
            .expect(2)
            .mount(&server)
            .await;

        let tmp = TempDir::new().unwrap();
        let mut engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let schema = crate::openrouter::curated_schemas()
            .into_iter()
            .find(|schema| schema.id == "parslee/openrouter/frontier-general")
            .unwrap();
        engine.unified_registry.register_project_model(schema);

        let first = engine
            .generate_tracked(GenerateRequest {
                prompt: "first".into(),
                model: Some("parslee/openrouter/frontier-general".into()),
                ..Default::default()
            })
            .await
            .expect("first managed turn");
        let expected_reasoning = serde_json::json!({
            "type": "reasoning",
            "id": "rs_car_roundtrip",
            "status": "completed",
            "summary": [{"type": "summary_text", "text": "safe summary"}],
            "encrypted_content": "opaque-encrypted-reasoning",
        });
        assert_eq!(
            first.provider_output_items,
            vec![expected_reasoning.clone()]
        );

        let mut history = vec![Message::User {
            content: "first".into(),
        }];
        first.append_assistant_history(&mut history, first.tool_calls.clone());
        history.push(Message::User {
            content: "continue".into(),
        });

        let second = engine
            .generate_tracked(GenerateRequest {
                prompt: String::new(),
                model: Some("parslee/openrouter/frontier-general".into()),
                messages: Some(history),
                ..Default::default()
            })
            .await
            .expect("second managed turn");
        assert_eq!(second.text, "first answer");

        let requests = server.received_requests().await.unwrap();
        let posts: Vec<serde_json::Value> = requests
            .iter()
            .filter(|request| {
                request.method.as_str() == "POST"
                    && request.url.path() == "/api/v1/orgs/org-roundtrip/inference/responses"
            })
            .map(|request| serde_json::from_slice(&request.body).unwrap())
            .collect();
        assert_eq!(posts.len(), 2);
        for body in &posts {
            assert_eq!(body["store"], false);
            assert_eq!(
                body["include"],
                serde_json::json!(["reasoning.encrypted_content"])
            );
        }
        let second_input = posts[1]["input"].as_array().unwrap();
        let reasoning_index = second_input
            .iter()
            .position(|item| item == &expected_reasoning)
            .expect("second request must replay the exact reasoning item");
        let assistant_index = second_input
            .iter()
            .position(|item| item["role"] == "assistant")
            .expect("second request assistant turn");
        let user_index = second_input
            .iter()
            .position(|item| item["content"] == "continue")
            .expect("second request user turn");
        assert!(
            reasoning_index < assistant_index && assistant_index < user_index,
            "provider output order must be reasoning, assistant text, then the next user turn"
        );

        unsafe {
            std::env::remove_var(crate::remote::PARSLEE_ACCESS_TOKEN_ENV);
            std::env::remove_var(car_auth::PARSLEE_API_BASE_KEY);
        }
    }

    #[tokio::test(flavor = "current_thread")]
    async fn managed_partial_eof_fails_buffered_and_streamed_turns_and_records_only_failures() {
        use wiremock::matchers::{header, method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let _provider_env = crate::openrouter::test_environment_scope_async().await;
        let _env = ENV_MUTEX.lock().await;
        let bearer = "managed-partial-outcome-bearer";

        let server = MockServer::start().await;
        unsafe {
            std::env::set_var(crate::remote::PARSLEE_ACCESS_TOKEN_ENV, bearer);
            std::env::set_var(car_auth::PARSLEE_API_BASE_KEY, server.uri());
        }
        Mock::given(method("GET"))
            .and(path("/api/v1/organizations/me"))
            .and(header("authorization", format!("Bearer {bearer}")))
            .respond_with(
                ResponseTemplate::new(200)
                    .set_body_json(serde_json::json!({"organizationId": "org-partial-outcome"})),
            )
            .mount(&server)
            .await;
        Mock::given(method("GET"))
            .and(path("/connect/session"))
            .respond_with(
                ResponseTemplate::new(200)
                    .set_body_json(serde_json::json!({"account": {"email": "user@example.test"}})),
            )
            .mount(&server)
            .await;
        Mock::given(method("POST"))
            .and(path("/api/v1/orgs/org-partial-outcome/inference/responses"))
            .respond_with(ResponseTemplate::new(200).set_body_raw(
                "event: response.output_text.delta\ndata: {\"delta\":\"partial must fail\"}\n\n",
                "text/event-stream",
            ))
            .expect(2)
            .mount(&server)
            .await;

        let tmp = TempDir::new().unwrap();
        let mut engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let model_id = "parslee/openrouter/frontier-general";
        let schema = crate::openrouter::curated_schemas()
            .into_iter()
            .find(|schema| schema.id == model_id)
            .unwrap();
        engine.unified_registry.register_project_model(schema);

        let buffered_error = engine
            .generate_tracked(GenerateRequest {
                prompt: "buffered".into(),
                model: Some(model_id.into()),
                params: GenerateParams {
                    strict_model: true,
                    ..Default::default()
                },
                ..Default::default()
            })
            .await
            .expect_err("buffered partial EOF must fail");
        assert!(
            buffered_error.to_string().contains("response.completed"),
            "unexpected buffered error: {buffered_error}"
        );

        let mut stream = engine
            .generate_tracked_stream(GenerateRequest {
                prompt: "streamed".into(),
                model: Some(model_id.into()),
                params: GenerateParams {
                    strict_model: true,
                    ..Default::default()
                },
                ..Default::default()
            })
            .await
            .expect("HTTP streaming request starts");
        let mut events = Vec::new();
        while let Some(event) = stream.events.recv().await {
            events.push(event);
        }
        assert!(
            matches!(events.last(), Some(StreamEvent::Error(message)) if message.contains("response.completed"))
        );
        assert!(!events
            .iter()
            .any(|event| matches!(event, StreamEvent::Done { .. })));

        for _ in 0..50 {
            if engine
                .outcome_tracker()
                .read()
                .await
                .profile(model_id)
                .is_some_and(|profile| profile.fail_count == 2)
            {
                break;
            }
            tokio::task::yield_now().await;
        }
        let profile = engine
            .outcome_tracker()
            .read()
            .await
            .profile(model_id)
            .cloned()
            .unwrap();
        assert_eq!(profile.fail_count, 2);
        assert_eq!(profile.success_count, 0);

        unsafe {
            std::env::remove_var(crate::remote::PARSLEE_ACCESS_TOKEN_ENV);
            std::env::remove_var(car_auth::PARSLEE_API_BASE_KEY);
        }
    }

    #[tokio::test]
    async fn tokenize_rejects_known_remote_model_with_unsupported_mode() {
        // The unified registry's built-in catalog includes remote models like
        // OpenAI / Anthropic ones. Regardless of which exact id ships, we just
        // need any non-local schema to confirm the pre-flight catches it
        // before we try (and fail) to load a non-existent local backend.
        let tmp = TempDir::new().unwrap();
        let engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let remote_id = engine
            .list_schemas()
            .into_iter()
            .find(|s| !s.is_local())
            .map(|s| s.id)
            .expect("built-in catalog should include at least one remote model schema");

        let err = engine
            .tokenize(&remote_id, "hello")
            .await
            .expect_err("remote tokenize must error");
        match err {
            InferenceError::UnsupportedMode { mode, backend, .. } => {
                assert_eq!(mode, "tokenize/detokenize");
                assert_eq!(backend, "remote");
            }
            other => panic!("expected UnsupportedMode, got {other:?}"),
        }

        let err = engine
            .detokenize(&remote_id, &[1, 2, 3])
            .await
            .expect_err("remote detokenize must error");
        assert!(
            matches!(err, InferenceError::UnsupportedMode { .. }),
            "expected UnsupportedMode, got {err:?}"
        );
    }

    #[test]
    fn unsupported_mode_does_not_trip_circuit_breaker() {
        // A deterministic capability mismatch (JsonSchema response_format on
        // Anthropic, or a video/audio block on a text-only provider) must NOT
        // feed the circuit breaker — it would evict a healthy model for ALL
        // traffic. Genuine availability errors still count. This locks the guard
        // in the dispatch loop's Err arm.
        let unsupported = InferenceError::UnsupportedMode {
            mode: "structured-output-json-schema",
            backend: "anthropic",
            reason: "not wired under the pinned API version",
        };
        assert!(!error_counts_against_circuit_breaker(&unsupported));
        assert!(error_counts_against_circuit_breaker(
            &InferenceError::InferenceFailed("API returned 500".into())
        ));
        assert!(error_counts_against_circuit_breaker(
            &InferenceError::InferenceFailed("API returned 429".into())
        ));
    }

    /// Parslee-ai/car#796 — a content refusal must not reach model health.
    ///
    /// The model handles the same payload correctly when the request gets
    /// through; the refusal came from a filter in front of it. Benching the
    /// model for that would make an adversarial-safety suite progressively
    /// evict the very models it is trying to measure — the suite's whole job is
    /// to send input that trips filters.
    #[test]
    fn a_content_refusal_does_not_trip_the_circuit_breaker() {
        let refused = InferenceError::ContentRefused {
            provider: "parslee".into(),
            kind: Some("invalid_request_error".into()),
            code: Some("content_policy_violation".into()),
            message: "content refused".into(),
        };
        assert!(!error_counts_against_circuit_breaker(&refused));

        // The rendering must carry the classification, since that is what lets
        // a benchmark score a refusal apart from a crash.
        let rendered = refused.to_string();
        assert!(rendered.contains("content grounds"), "{rendered}");
        assert!(rendered.contains("content_policy_violation"), "{rendered}");

        // A generic failure still counts — the exclusion must be narrow.
        assert!(error_counts_against_circuit_breaker(
            &InferenceError::InferenceFailed("managed inference failed".into())
        ));
    }

    /// Parslee-ai/car#786 — an unconfigured gateway namespace must not reach
    /// per-model health.
    ///
    /// The measured cost of it doing so: ten `parslee/openrouter/*` aliases
    /// sitting at 52 calls / 0 successes in `car models stats`, a health record
    /// earned entirely by a deployment that had no upstream to proxy to. The
    /// models never ran.
    #[test]
    fn unconfigured_gateway_does_not_trip_circuit_breaker() {
        let unconfigured = InferenceError::GatewayUnconfigured {
            provider: "parslee".into(),
            namespace: "parslee/openrouter/".into(),
            status: 503,
            message: "OpenRouter inference is not configured on this Parslee environment.".into(),
        };
        assert!(!error_counts_against_circuit_breaker(&unconfigured));
        // The error must still name the namespace and the remedy-relevant
        // detail — a caller that cannot tell WHICH namespace died learns
        // nothing the generic failure did not already tell them.
        let rendered = unconfigured.to_string();
        assert!(rendered.contains("parslee/openrouter/"), "{rendered}");
        assert!(rendered.contains("not configured"), "{rendered}");
    }

    /// The namespace drop must be exact-prefix, not "anything mentioning
    /// parslee". Dropping `parslee/reasoning` on an OpenRouter-namespace
    /// failure would remove working models from the chain — the usable
    /// remainder in car#786 was precisely `parslee/advisor`,
    /// `parslee/reasoning`, and `parslee/fast`.
    #[test]
    fn namespace_drop_spares_siblings_outside_the_prefix() {
        let namespace = "parslee/openrouter/";
        let mut queue: std::collections::VecDeque<String> = [
            "parslee/openrouter/open-fast",
            "parslee/reasoning",
            "parslee/openrouter/frontier-general",
            "parslee/advisor",
            "anthropic/claude-opus-4-8:latest",
        ]
        .into_iter()
        .map(String::from)
        .collect();

        queue.retain(|id| !id.starts_with(namespace));

        assert_eq!(
            queue.iter().collect::<Vec<_>>(),
            vec![
                "parslee/reasoning",
                "parslee/advisor",
                "anthropic/claude-opus-4-8:latest"
            ],
            "only the unconfigured namespace may be dropped"
        );
    }

    #[test]
    fn engine_loads_benchmark_priors_on_startup() {
        let _env = ENV_MUTEX.blocking_lock();
        let tmp = TempDir::new().unwrap();
        let priors_path = tmp.path().join("benchmark_priors.json");
        std::fs::write(
            &priors_path,
            serde_json::json!({
                "model_id": "qwen/qwen3-8b:q4_k_m",
                "overall_score": 0.88
            })
            .to_string(),
        )
        .unwrap();

        unsafe {
            std::env::set_var("CAR_BENCHMARK_PRIORS_PATH", &priors_path);
        }

        let engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let tracker = engine.outcome_tracker.blocking_read();
        let profile = tracker
            .profile("qwen/qwen3-8b:q4_k_m")
            .expect("benchmark prior should create a profile");
        assert!((profile.ema_quality - 0.88).abs() < 0.01);

        unsafe {
            std::env::remove_var("CAR_BENCHMARK_PRIORS_PATH");
        }
    }

    #[test]
    fn benchmark_priors_do_not_override_observed_profiles() {
        let _env = ENV_MUTEX.blocking_lock();
        let tmp = TempDir::new().unwrap();
        let models_dir = tmp.path().join("models");
        std::fs::create_dir_all(&models_dir).unwrap();

        let observed = vec![ModelProfile {
            model_id: "qwen/qwen3-8b:q4_k_m".into(),
            total_calls: 12,
            success_count: 3,
            fail_count: 9,
            total_latency_ms: 1200,
            total_input_tokens: 0,
            total_output_tokens: 0,
            total_cache_read_input_tokens: 0,
            total_cache_creation_input_tokens: 0,
            task_stats: std::collections::HashMap::new(),
            ema_quality: 0.21,
            prior_sample_size: 0,
            quality_observations: 0,
            quality_per_1k_tokens: 0.0,
            updated_at: 1,
        }];
        std::fs::write(
            models_dir.join("outcome_profiles.json"),
            serde_json::to_string(&observed).unwrap(),
        )
        .unwrap();

        let priors_path = tmp.path().join("benchmark_priors.json");
        std::fs::write(
            &priors_path,
            serde_json::json!({
                "model_id": "qwen/qwen3-8b:q4_k_m",
                "overall_score": 0.95
            })
            .to_string(),
        )
        .unwrap();

        unsafe {
            std::env::set_var("CAR_BENCHMARK_PRIORS_PATH", &priors_path);
        }

        let engine = InferenceEngine::new(test_config(models_dir));
        let tracker = engine.outcome_tracker.blocking_read();
        let profile = tracker
            .profile("qwen/qwen3-8b:q4_k_m")
            .expect("observed profile should remain present");
        assert!((profile.ema_quality - 0.21).abs() < 0.01);
        assert_eq!(profile.total_calls, 12);

        unsafe {
            std::env::remove_var("CAR_BENCHMARK_PRIORS_PATH");
        }
    }

    #[test]
    fn speech_runtime_package_spec_defaults_and_overrides() {
        let _env = ENV_MUTEX.blocking_lock();
        unsafe {
            std::env::remove_var("CAR_SPEECH_RUNTIME_MLX_AUDIO_SPEC");
        }
        assert_eq!(speech_runtime_mlx_audio_spec(), "mlx-audio==0.4.2");

        unsafe {
            std::env::set_var("CAR_SPEECH_RUNTIME_MLX_AUDIO_SPEC", "mlx-audio==0.4.1");
        }
        assert_eq!(speech_runtime_mlx_audio_spec(), "mlx-audio==0.4.1");

        unsafe {
            std::env::remove_var("CAR_SPEECH_RUNTIME_MLX_AUDIO_SPEC");
        }
    }

    #[test]
    fn speech_runtime_spacy_model_spec_defaults_and_overrides() {
        let _env = ENV_MUTEX.blocking_lock();
        unsafe {
            std::env::remove_var("CAR_SPEECH_RUNTIME_SPACY_MODEL_SPEC");
        }
        assert!(
            speech_runtime_spacy_model_spec().starts_with("en-core-web-sm @ https://github.com/")
        );

        unsafe {
            std::env::set_var(
                "CAR_SPEECH_RUNTIME_SPACY_MODEL_SPEC",
                "en-core-web-sm==3.8.0",
            );
        }
        assert_eq!(speech_runtime_spacy_model_spec(), "en-core-web-sm==3.8.0");

        unsafe {
            std::env::remove_var("CAR_SPEECH_RUNTIME_SPACY_MODEL_SPEC");
        }
    }

    #[test]
    fn kokoro_runtime_fallback_defaults_on() {
        unsafe {
            std::env::remove_var("CAR_SPEECH_KOKORO_FALLBACK");
        }
        assert!(kokoro_runtime_fallback_enabled());

        unsafe {
            std::env::set_var("CAR_SPEECH_KOKORO_FALLBACK", "false");
        }
        assert!(!kokoro_runtime_fallback_enabled());

        unsafe {
            std::env::remove_var("CAR_SPEECH_KOKORO_FALLBACK");
        }
    }

    #[test]
    fn preferred_local_tts_wins_over_builtin_rank() {
        let tmp = TempDir::new().unwrap();
        let mut engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        engine.set_speech_policy(SpeechPolicy {
            prefer_local: true,
            allow_remote_fallback: false,
            preferred_local_stt: None,
            preferred_local_tts: Some("Kokoro-82M-6bit".into()),
            preferred_remote_stt: None,
            preferred_remote_tts: None,
        });

        let schema = engine
            .preferred_speech_schema(ModelCapability::TextToSpeech, true, false)
            .expect("preferred local TTS should resolve");
        // On macOS/Linux the MLX Kokoro is available (or tied-unavailable with the
        // other local TTS), so the policy preference beats the builtin bf16>6bit
        // rank — the property under test. On Windows the MLX models are
        // unavailable while the OS synthesizer (Windows-Speech) is available, and
        // availability precedes policy in the sort: an unavailable *preferred*
        // model correctly yields to one that actually runs.
        #[cfg(not(target_os = "windows"))]
        assert_eq!(schema.name, "Kokoro-82M-6bit");
        #[cfg(target_os = "windows")]
        assert_eq!(schema.name, "Windows-Speech");
    }

    #[test]
    fn preferred_discovered_vllm_mlx_model_wins_generate_routing() {
        let tmp = TempDir::new().unwrap();
        let mut config = test_config(tmp.path().join("models"));
        config.preferred_generation_model =
            Some("vllm-mlx/mlx-community_gemma-3n-E2B-it-lm-4bit".into());
        let mut engine = InferenceEngine::new(config);
        let schema = crate::vllm_mlx::to_model_schema(
            &crate::vllm_mlx::DiscoveredModel {
                id: "mlx-community/gemma-3n-E2B-it-lm-4bit".into(),
                owned_by: Some("mlx-community".into()),
            },
            "http://127.0.0.1:8001",
        );
        engine.register_model(schema);

        let rt = tokio::runtime::Runtime::new().unwrap();
        let decision = rt.block_on(engine.route_adaptive("say hello in one sentence"));
        assert_eq!(
            decision.model_id,
            "vllm-mlx/mlx-community_gemma-3n-E2B-it-lm-4bit"
        );
        assert_eq!(decision.strategy, RoutingStrategy::Explicit);
        assert_eq!(decision.reason, "preferred generation model override");
    }

    /// Regression (I4 review, critical 1): the fallback loop was converted
    /// from `for` to an index-based `while` whose increment a pre-existing
    /// `continue` (e.g. the ToolUse capability guard) skipped — retrying
    /// the SAME candidate forever at 100% CPU. The loop is now a pop-front
    /// queue, so `continue` always moves on. This pins termination: a
    /// tools request routed to a model without ToolUse must RETURN (the
    /// capability guard fires, the queue drains, all-models-failed), not
    /// hang. Under the buggy loop this test times out.
    #[test]
    fn tools_request_on_non_tool_model_terminates_not_spins() {
        let tmp = TempDir::new().unwrap();
        let mut engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        // "embed" in the name → capabilities [Embed] only (no ToolUse).
        let schema = crate::vllm_mlx::to_model_schema(
            &crate::vllm_mlx::DiscoveredModel {
                id: "test-org/embed-only-model".into(),
                owned_by: None,
            },
            "http://127.0.0.1:1", // nothing listens; must not matter
        );
        let model_id = schema.id.clone();
        engine.register_model(schema);

        let req = GenerateRequest {
            prompt: "call a tool".to_string(),
            model: Some(model_id),
            tools: Some(vec![serde_json::json!({
                "name": "noop", "description": "n", "parameters": {"type": "object"}
            })]),
            ..Default::default()
        };

        let rt = tokio::runtime::Runtime::new().unwrap();
        let out = rt.block_on(async {
            tokio::time::timeout(
                std::time::Duration::from_secs(10),
                engine.generate_tracked(req),
            )
            .await
        });
        // The point is termination; the result is an error (no capable
        // model), which is fine.
        let completed = out.expect("fallback loop must terminate, not spin");
        assert!(completed.is_err());
    }

    /// Lay down a runtime root that [`SpeechRuntime::is_ready`] accepts, so
    /// `prepare_speech_runtime` short-circuits instead of shelling out to `uv`
    /// for a real (multi-minute, network-bound) venv + pip install.
    fn fake_ready_speech_runtime(root: &Path) {
        let bin = root.join("bin");
        std::fs::create_dir_all(&bin).unwrap();
        for program in ["python", "mlx_audio.stt.generate", "mlx_audio.tts.generate"] {
            std::fs::write(bin.join(program), b"").unwrap();
        }
    }

    /// Parslee-ai/car#649 — `speech install` and `speech doctor` contradicted
    /// each other on Apple Silicon: prepare returned `models_dir` (a path
    /// doctor never mentions) after skipping provisioning entirely, so install
    /// printed "ready" while doctor printed `Installed: no` against a different
    /// root. Prepare must hand back exactly the root doctor reports, and that
    /// root must exist (Parslee-ai/car#626 — "prepare" leaves the thing
    /// prepared).
    ///
    /// Unscoped by cfg on purpose: the whole point of the fix is that both
    /// branches now agree on one root. The pre-seeded runtime keeps `uv` out of
    /// it, which is what previously forced this test to be macOS-only.
    #[tokio::test]
    async fn prepare_speech_runtime_returns_the_root_doctor_reports() {
        let _env = ENV_MUTEX.lock().await;
        let tmp = TempDir::new().unwrap();
        let runtime_root = tmp.path().join("speech-runtime");
        fake_ready_speech_runtime(&runtime_root);
        unsafe {
            std::env::set_var("CAR_SPEECH_RUNTIME_DIR", &runtime_root);
        }

        let engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let root = engine
            .prepare_speech_runtime()
            .await
            .expect("prepare should succeed against a ready runtime");
        let health = engine.speech_health();

        assert_eq!(
            root, health.runtime.root,
            "prepare returned a different root than doctor reports"
        );
        assert!(
            root.exists(),
            "prepare returned {} but it does not exist",
            root.display()
        );
        assert!(
            health.runtime.installed,
            "doctor should report a ready runtime as installed"
        );
        // Idempotent — a second call on a provisioned runtime is fine.
        assert_eq!(
            engine
                .prepare_speech_runtime()
                .await
                .expect("second prepare should succeed"),
            root
        );

        unsafe {
            std::env::remove_var("CAR_SPEECH_RUNTIME_DIR");
        }
    }

    /// Parslee-ai/car#649 — on Apple Silicon the managed runtime is a *fallback*
    /// behind working native MLX backends, so a machine without `uv` must still
    /// get a usable install: prepare degrades (warns, returns the created root)
    /// instead of failing, and doctor is left to report the truth. Elsewhere the
    /// managed runtime is the only local speech path and the error propagates.
    ///
    /// The bogus `CAR_SPEECH_PYTHON` makes the bootstrap fail immediately —
    /// `uv venv --python <nonexistent>` cannot resolve an interpreter — so this
    /// never runs a real provision, whether or not `uv` is on PATH.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    #[tokio::test]
    async fn prepare_speech_runtime_degrades_when_bootstrap_fails() {
        let _env = ENV_MUTEX.lock().await;
        let tmp = TempDir::new().unwrap();
        let runtime_root = tmp.path().join("speech-runtime");
        assert!(!runtime_root.exists(), "precondition: root absent");
        unsafe {
            std::env::set_var("CAR_SPEECH_RUNTIME_DIR", &runtime_root);
            std::env::set_var("CAR_SPEECH_PYTHON", tmp.path().join("no-such-python"));
        }

        let engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let root = engine
            .prepare_speech_runtime()
            .await
            .expect("a failed bootstrap must degrade, not fail, on Apple Silicon");
        let health = engine.speech_health();

        assert_eq!(root, health.runtime.root);
        assert!(
            root.exists(),
            "prepare returned {} but it does not exist",
            root.display()
        );
        assert!(
            !health.runtime.installed,
            "doctor must not claim a runtime the bootstrap never built"
        );

        unsafe {
            std::env::remove_var("CAR_SPEECH_RUNTIME_DIR");
            std::env::remove_var("CAR_SPEECH_PYTHON");
        }
    }

    /// car#678: off Apple Silicon the managed mlx-audio runtime cannot be
    /// built (`mlx` publishes no Windows/Linux wheels, and `uv` is often
    /// absent), and `install_curated_speech` propagated that failure with `?`.
    /// So `car speech install` — the command `car speech doctor` explicitly
    /// tells those users to run — aborted before the whisper.cpp block, and
    /// never fetched the one local speech model that does run there.
    ///
    /// Linux-only, and deliberately so on both counts. It is a platform where
    /// the bug is real, unlike Apple Silicon. And the seam is `HOME`: the
    /// whisper cache resolves through `dirs::home_dir()`, which honours `HOME`
    /// on Linux but reads a known-folder API on Windows, so redirecting the
    /// cache — and with it keeping this test offline — only works here.
    #[cfg(target_os = "linux")]
    #[tokio::test]
    async fn a_runtime_that_cannot_be_built_no_longer_blocks_the_whisper_install() {
        let _env = ENV_MUTEX.lock().await;
        let tmp = TempDir::new().unwrap();

        // Pre-seed the whisper cache so `ensure_model` short-circuits. The
        // assertion is that the install *reaches* the download, not that it
        // performs one — a 574 MB fetch has no place in a unit test.
        let cached = tmp
            .path()
            .join(".tokhn")
            .join("whisper")
            .join("ggml-large-v3-turbo-q5_0.bin");
        std::fs::create_dir_all(cached.parent().unwrap()).unwrap();
        std::fs::write(&cached, b"stand-in for the ggml weights").unwrap();

        let previous_home = std::env::var_os("HOME");
        unsafe {
            std::env::set_var("HOME", tmp.path());
            std::env::set_var("CAR_SPEECH_RUNTIME_DIR", tmp.path().join("speech-runtime"));
            // `uv venv --python <nonexistent>` cannot resolve an interpreter,
            // so the bootstrap fails immediately and never provisions for real
            // — whether or not `uv` happens to be on PATH.
            std::env::set_var("CAR_SPEECH_PYTHON", tmp.path().join("no-such-python"));
        }

        let mut engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let installed = engine.install_curated_speech().await;

        let restore = || unsafe {
            match &previous_home {
                Some(value) => std::env::set_var("HOME", value),
                None => std::env::remove_var("HOME"),
            }
            std::env::remove_var("CAR_SPEECH_RUNTIME_DIR");
            std::env::remove_var("CAR_SPEECH_PYTHON");
        };
        let installed = match installed {
            Ok(installed) => installed,
            Err(error) => {
                restore();
                panic!("a runtime that cannot be built must not abort the install: {error}");
            }
        };
        let runtime_installed = engine.speech_health().runtime.installed;
        restore();

        assert!(
            !runtime_installed,
            "precondition: the bootstrap must actually have failed, or this \
             test would pass without exercising anything"
        );
        let whisper = installed
            .iter()
            .find(|report| report.hf_repo == "ggerganov/whisper.cpp")
            .unwrap_or_else(|| {
                panic!(
                    "the cross-platform whisper model must still be installed, got: {installed:?}"
                )
            });
        assert_eq!(whisper.snapshot_path, cached);
        assert!(
            installed
                .iter()
                .all(|report| report.hf_repo == "ggerganov/whisper.cpp"),
            "MLX weights are Apple-only and must not be pulled here — over a \
             gigabyte of them, for models this host can never load; got: {installed:?}"
        );
    }

    /// Regression: the non-streaming `generate_tracked` fallback loop must book
    /// outcomes against the *resolved canonical id* (`schema.id`), not the raw
    /// alias the caller passed. Otherwise an explicit alias like
    /// `claude-sonnet-4-6` and the catalog id `anthropic/claude-sonnet-4-6:latest`
    /// fragment the model-health surface into two "models" for one physical
    /// model. This locks the resolution chain the loop relies on
    /// (`get().or_else(find_by_name())` → `schema.id`) against catalog drift.
    #[test]
    fn alias_resolves_to_canonical_id_for_outcome_keying() {
        let tmp = TempDir::new().unwrap();
        let engine = InferenceEngine::new(test_config(tmp.path().join("models")));

        // (alias passed by a caller, canonical id the outcome tracker must key on)
        let cases = [
            ("claude-sonnet-4-6", "anthropic/claude-sonnet-4-6:latest"),
            ("gpt-5.4", "openai/gpt-5.4:latest"),
            ("gemini-2.5-flash", "google/gemini-2.5-flash:latest"),
        ];
        for (alias, canonical) in cases {
            // Exactly the resolution the fallback loop performs before
            // `record_start` (see the `resolved_id` binding in the loop).
            let resolved = engine
                .unified_registry
                .get(alias)
                .or_else(|| engine.unified_registry.find_by_name(alias))
                .map(|s| s.id.clone())
                .unwrap_or_else(|| alias.to_string());
            assert_eq!(
                resolved, canonical,
                "alias `{alias}` must resolve to canonical `{canonical}` for outcome keying, got `{resolved}`"
            );
            assert_ne!(
                resolved, alias,
                "alias `{alias}` must NOT be recorded raw — that is the fragmentation bug"
            );
        }
    }

    /// Issue #43 — InferenceResult must serialize with all fields preserved
    /// (text, tool_calls, trace_id, model_used, latency_ms, usage) using
    /// snake_case field names. The car-server WebSocket handler relies on
    /// `serde_json::to_value(&InferenceResult)` producing this exact shape.
    #[test]
    fn inference_result_serializes_with_full_shape() {
        use crate::tasks::generate::ToolCall;
        use std::collections::HashMap;

        let mut args = HashMap::new();
        args.insert("path".to_string(), serde_json::json!("README.md"));

        let result = InferenceResult {
            text: String::new(),
            bounding_boxes: Vec::new(),
            tool_calls: vec![ToolCall {
                id: None,
                name: "read_file".into(),
                arguments: args,
            }],
            trace_id: "trace-abc".into(),
            model_used: "test-model".into(),
            latency_ms: 1234,
            time_to_first_token_ms: Some(180),
            usage: Some(TokenUsage {
                prompt_tokens: 100,
                completion_tokens: 50,
                total_tokens: 150,
                context_window: 8192,
                ..Default::default()
            }),
            provider_output_items: Vec::new(),
            thinking: Vec::new(),
            stop_reason: Some("tool_use".into()),
        };

        let json = serde_json::to_value(&result).expect("serialize");

        // stop_reason propagates through serialization when populated.
        assert_eq!(json["stop_reason"].as_str(), Some("tool_use"));

        // Required snake_case fields with type-strict assertions
        assert_eq!(json["text"].as_str(), Some(""));
        assert_eq!(json["trace_id"].as_str(), Some("trace-abc"));
        assert_eq!(json["model_used"].as_str(), Some("test-model"));
        assert_eq!(json["latency_ms"].as_u64(), Some(1234));

        // tool_calls is a non-empty array with name + arguments
        let tool_calls = json["tool_calls"].as_array().expect("tool_calls array");
        assert_eq!(tool_calls.len(), 1);
        assert_eq!(tool_calls[0]["name"].as_str(), Some("read_file"));
        assert_eq!(
            tool_calls[0]["arguments"]["path"].as_str(),
            Some("README.md")
        );

        // usage is an object with all four documented fields
        let usage = &json["usage"];
        assert_eq!(usage["prompt_tokens"].as_u64(), Some(100));
        assert_eq!(usage["completion_tokens"].as_u64(), Some(50));
        assert_eq!(usage["total_tokens"].as_u64(), Some(150));
        assert_eq!(usage["context_window"].as_u64(), Some(8192));

        // TTFT propagates through serialization when populated.
        assert_eq!(json["time_to_first_token_ms"].as_u64(), Some(180));
    }

    /// Issue #43 — Lock the top-level WebSocket `infer` response contract.
    /// If a future change adds a field to `InferenceResult`, this test forces
    /// the developer to deliberately update the protocol surface and the
    /// expected key set here, rather than silently leaking new fields onto
    /// the wire.
    #[test]
    fn inference_result_top_level_keys_are_locked() {
        use std::collections::BTreeSet;

        let result = InferenceResult {
            text: "anything".into(),
            bounding_boxes: Vec::new(),
            tool_calls: vec![],
            trace_id: "t".into(),
            model_used: "m".into(),
            latency_ms: 0,
            time_to_first_token_ms: None,
            usage: None,
            provider_output_items: Vec::new(),
            thinking: Vec::new(),
            stop_reason: None,
        };

        let json = serde_json::to_value(&result).expect("serialize");
        let keys: BTreeSet<&str> = json
            .as_object()
            .expect("top-level object")
            .keys()
            .map(String::as_str)
            .collect();

        let expected: BTreeSet<&str> = [
            "text",
            "tool_calls",
            "trace_id",
            "model_used",
            "latency_ms",
            "time_to_first_token_ms",
            "usage",
            "stop_reason",
        ]
        .into_iter()
        .collect();

        assert_eq!(
            keys, expected,
            "infer response top-level keys drifted -- update both the test \
             and the WebSocket protocol documentation if this is intentional"
        );

        // All keys are snake_case (constraint c-2 in outcome 043).
        for key in &keys {
            assert!(
                !key.chars().any(|c| c.is_uppercase()) && !key.contains('-'),
                "key '{}' is not snake_case",
                key
            );
        }
    }

    /// Plain text result (no tools) must still serialize cleanly with text
    /// populated and tool_calls present as an empty array. Backward compat
    /// for clients that only care about `.text`.
    #[test]
    fn inference_result_serializes_plain_text_response() {
        let result = InferenceResult {
            text: "hello world".into(),
            bounding_boxes: Vec::new(),
            tool_calls: vec![],
            trace_id: "trace-xyz".into(),
            model_used: "test-model".into(),
            latency_ms: 42,
            time_to_first_token_ms: None,
            usage: None,
            provider_output_items: Vec::new(),
            thinking: Vec::new(),
            stop_reason: None,
        };

        let json = serde_json::to_value(&result).expect("serialize");
        assert_eq!(json["text"], "hello world");
        // Always-present null when the provider didn't report one.
        assert!(json["stop_reason"].is_null());
        assert!(json["tool_calls"].is_array());
        assert_eq!(json["tool_calls"].as_array().unwrap().len(), 0);
        assert_eq!(json["model_used"], "test-model");
        assert!(json["usage"].is_null());
        // Honest "wasn't measured" rather than missing key — the field
        // is always present at the protocol surface.
        assert!(json["time_to_first_token_ms"].is_null());
    }

    #[test]
    fn append_assistant_history_preserves_responses_items_in_provider_order() {
        let reasoning = serde_json::json!({
            "type": "reasoning",
            "id": "rs_history",
            "status": "completed",
            "summary": [{"type": "summary_text", "text": "safe"}],
            "encrypted_content": "opaque",
        });
        let result: InferenceResult = serde_json::from_value(serde_json::json!({
            "text": "calling",
            "tool_calls": [{
                "id": "call_1",
                "name": "read_file",
                "arguments": {"path": "README.md"}
            }],
            "trace_id": "trace",
            "model_used": "parslee/openrouter/frontier-general",
            "latency_ms": 1,
            "provider_output_items": [reasoning.clone()],
        }))
        .unwrap();
        let mut history = vec![crate::tasks::generate::Message::User {
            content: "inspect".into(),
        }];

        result.append_assistant_history(&mut history, result.tool_calls.clone());

        assert!(matches!(
            &history[1],
            crate::tasks::generate::Message::ProviderOutputItems { protocol, items }
                if protocol == crate::protocol::OPENAI_RESPONSES_PROTOCOL
                    && items == &vec![reasoning]
        ));
        assert!(matches!(
            &history[2],
            crate::tasks::generate::Message::Assistant { content, tool_calls, .. }
                if content == "calling" && tool_calls[0].id.as_deref() == Some("call_1")
        ));
    }

    #[test]
    fn append_assistant_history_leaves_personal_chat_history_unchanged() {
        let result: InferenceResult = serde_json::from_value(serde_json::json!({
            "text": "plain",
            "tool_calls": [],
            "trace_id": "trace",
            "model_used": "openrouter/openai/gpt-4.1-mini",
            "latency_ms": 1,
        }))
        .unwrap();
        let mut history = Vec::new();

        result.append_assistant_history(&mut history, Vec::new());

        assert_eq!(history.len(), 1);
        assert!(matches!(
            &history[0],
            crate::tasks::generate::Message::Assistant { content, .. } if content == "plain"
        ));
    }

    /// Wire contract — the WebSocket `infer` handler in
    /// `car-server-core/src/handler.rs::handle_infer` deserializes
    /// the entire `GenerateRequest` from JSON-RPC params via
    /// `serde_json::from_value(msg.params.clone())`. That means the
    /// `intent` field must remain a serde-deserialize field of
    /// `GenerateRequest` for the WS surface to honor caller-supplied
    /// routing intent. If a refactor moves intent to a separate
    /// argument or renames the field, this test fails and the WS
    /// handler must be updated to thread intent explicitly. See
    /// `docs/proposals/policy-intent-surface.md` and
    /// `docs/websocket-protocol.md` `infer` section.
    #[test]
    fn generate_request_deserializes_intent_field_from_json_rpc_params() {
        use crate::intent::TaskHint;
        use crate::schema::ModelCapability;

        // Shape mirrors what a WebSocket client sends in the `params`
        // object on an `infer` JSON-RPC method call.
        let params = serde_json::json!({
            "prompt": "summarize this email",
            "intent": {
                "task": "chat",
                "prefer_local": true,
                "require": ["tool_use"],
            },
        });

        let req: GenerateRequest =
            serde_json::from_value(params).expect("GenerateRequest deserialize");

        let intent = req.intent.as_ref().expect("intent field deserialized");
        assert_eq!(intent.task, Some(TaskHint::Chat));
        assert!(intent.prefer_local);
        assert_eq!(intent.require, vec![ModelCapability::ToolUse]);

        // Round-trip through serde_json::to_value to confirm the
        // re-encoded shape matches what handle_infer would forward to
        // the engine without dropping the field.
        let back: serde_json::Value =
            serde_json::to_value(&req).expect("re-serialize GenerateRequest");
        assert_eq!(back["intent"]["task"], "chat");
        assert_eq!(back["intent"]["prefer_local"], true);
        assert_eq!(back["intent"]["require"][0], "tool_use");

        // Default `IntentHint` (no fields set) maps to the no-intent
        // path and must serialize as bare `{}` so missing-keys clients
        // see a stable default — same guarantee `intent.rs::tests` has
        // for the type itself, repeated here at the request boundary.
        let default_req: GenerateRequest = serde_json::from_value(serde_json::json!({
            "prompt": "x",
            "intent": {},
        }))
        .unwrap();
        let default_intent = default_req.intent.expect("present but empty");
        assert_eq!(default_intent.task, None);
        assert!(!default_intent.prefer_local);
        assert!(default_intent.require.is_empty());

        // Missing intent field entirely → `None`, matching pre-intent
        // clients exactly. This is the backwards-compat guarantee.
        let no_intent: GenerateRequest =
            serde_json::from_value(serde_json::json!({"prompt": "x"})).unwrap();
        assert!(no_intent.intent.is_none());
    }

    #[test]
    fn rerank_prompt_matches_upstream_template_shape() {
        let p = rerank_prompt(
            "retrieve relevant passages",
            "who runs the treasury?",
            "doc x",
        );
        assert!(p.contains("<|im_start|>system"));
        assert!(p.contains("Note that the answer can only be \"yes\" or \"no\"."));
        assert!(p.contains("<|im_start|>user\n<Instruct>: retrieve relevant passages"));
        assert!(p.contains("<Query>: who runs the treasury?"));
        assert!(p.contains("<Document>: doc x<|im_end|>"));
        assert!(p.contains("<|im_start|>assistant\n<think>\n\n</think>\n\n"));
    }

    #[test]
    fn rerank_score_yes_and_no_exactly() {
        assert_eq!(score_from_rerank_output("yes", "m"), 1.0);
        assert_eq!(score_from_rerank_output("no", "m"), 0.0);
    }

    #[test]
    fn rerank_score_handles_case_leading_space_and_chat_sentinels() {
        // Real decodes often include leading whitespace, punctuation,
        // or chat-template sentinels around the answer token.
        assert_eq!(score_from_rerank_output(" Yes", "m"), 1.0);
        assert_eq!(score_from_rerank_output("\nno.", "m"), 0.0);
        assert_eq!(score_from_rerank_output("<|im_end|>yes", "m"), 1.0);
    }

    #[test]
    fn rerank_score_scans_up_to_three_tokens() {
        // Tokenizer artifacts can produce a BOS-like leading token
        // before the real answer. Don't miss it.
        assert_eq!(score_from_rerank_output("_bos_ yes", "m"), 1.0);
    }

    #[test]
    fn rerank_score_unexpected_is_neutral() {
        // Plain-base models that aren't reranker-fine-tuned will emit
        // arbitrary completion tokens. Don't partition; go neutral.
        assert_eq!(score_from_rerank_output("maybe", "m"), 0.5);
        assert_eq!(score_from_rerank_output("", "m"), 0.5);
    }
}