car_inference/

lib.rs

//! # 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 catalog_identity;
pub mod concierge;
pub mod discovery;
pub mod doctor;
pub mod download;
pub mod handle;
pub mod hardware;
pub mod hf_schema;
pub mod intent;
pub mod key_pool;
pub mod lane_defaults;
pub mod managed_venv;
pub mod media_tokens;
pub mod model_management;
pub mod models;
pub mod nudge;
pub mod offload;
pub mod openrouter;
pub mod outcome;
pub mod parslee_credential;
pub mod protocol;
pub mod recommend;
pub mod registry;
pub mod remote;
pub mod resource_policy;
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::io::AsyncReadExt;
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 catalog_identity::{CatalogModelRow, CatalogSnapshot};
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::{
    model_fit, platform_compatible, recommend, recommend_with_policy, FitStatus, ModelFit,
    ModelFitStatus, Recommendation, RecommendationSet,
};
pub use resource_policy::{
    estimate_model_memory, estimate_model_memory_with_measured_weights, evaluate_resources,
    AcceleratorResourceBudget, EffectiveResourceBudget, FileResourcePolicyRepository,
    LocalAdmissionCoordinator, LocalLoadPreflight, LocalLoadVerdict, ModelMemoryEstimate,
    ModelResourceEvidence, ResourceEvaluation, ResourcePolicy, ResourcePolicyError,
    ResourcePolicyLoadEvidence, ResourcePolicyLoadSource, ResourcePolicyRepository,
    ResourceProfile, RECOMMENDATION_CONTEXT_TOKENS,
};
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::{
    clear_remote_deadline, current_controlled_termination_token, current_inference_control_id,
    current_local_offload, current_remote_deadline, ensure_not_controlled_terminated,
    is_offload_worker, scope_inference_control_id, set_local_offload, set_remote_deadline,
    ControlledTerminationToken, InferenceTerminationAck, LocalGenerationOffload,
    LocalOffloadResult, LocalOffloadStream, LocalWorkerAdmission, LocalWorkerResidency,
    RemoteDeadline,
};
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, QuantScheme, Quantization, 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),

    /// Adaptive routing could not honor a caller-required model separation
    /// boundary. Raised before dispatch, so no excluded backend serves even a
    /// failed attempt.
    #[error("no eligible model remains after required exclusions: {excluded_models}")]
    NoEligibleModel { excluded_models: String },

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

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

    /// The caller bound inference to a catalog row/revision that no longer
    /// matches the daemon's request snapshot. This is an optimistic
    /// concurrency rejection, not a provider failure; it must fail before any
    /// dispatch and retain a typed wire mapping at the daemon boundary.
    #[error("catalog precondition mismatch: {detail}")]
    CatalogPreconditionMismatch { detail: String },

    /// Exact isolated-worker kill + wait confirmed termination for this
    /// request. The server-owned registry decides whether the outward terminal
    /// is cancel or deadline; the inference engine uses this sentinel only to
    /// stop retries/fallbacks without penalizing model health.
    #[error("controlled inference termination confirmed")]
    ControlledTermination,

    #[error(transparent)]
    ModelManagement(#[from] model_management::ModelManagementError),

    /// A CAR-managed local model could not be admitted without violating the
    /// user's saved allocation or the machine's live emergency reserve.
    #[error("{recovery}")]
    LocalResourceBlocked {
        preflight: resource_policy::LocalLoadPreflight,
        recovery: 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,
    },

    /// The CALLER'S armed deadline (`infer.deadline`) elapsed while the remote
    /// request was still in flight or before a retry could fit inside what
    /// remained. Distinct from [`InferenceError::Transient`] — this is not an
    /// infra blip and re-running with the same deadline hits the same wall;
    /// the caller asked for exactly this bound and the error names it so the
    /// termination is attributable to the deadline that was applied (car-eyj:
    /// the old shape reported -32603 transient at a ceiling no config exposed).
    #[error("deadline exceeded: the caller's {applied_ms} ms infer deadline elapsed after {elapsed_ms} ms; last attempt: {last_error}")]
    DeadlineExceeded {
        applied_ms: u64,
        elapsed_ms: u64,
        last_error: 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),
}

impl From<resource_policy::LocalAdmissionError> for InferenceError {
    fn from(error: resource_policy::LocalAdmissionError) -> Self {
        let recovery = match error.preflight.verdict {
            resource_policy::LocalLoadVerdict::DisabledByPolicy => {
                "Local model loading is disabled by the 0 GB allocation. Increase Local Models RAM in Settings, or choose a remote model. Downloads remain available.".to_string()
            }
            resource_policy::LocalLoadVerdict::ExceedsConfiguredCeiling => format!(
                "This model needs about {} MB for this request, beyond the configured {} MB local-model allocation. Increase the allocation or choose a smaller model.",
                error.preflight.estimated_incremental_mb,
                error.preflight.configured_ceiling_mb
            ),
            resource_policy::LocalLoadVerdict::InsufficientLiveMemory => format!(
                "Not enough memory is free to start this model while preserving CAR's {} MB emergency reserve. Close memory-heavy apps or choose a smaller model.",
                error.preflight.emergency_reserve_mb
            ),
            resource_policy::LocalLoadVerdict::LiveMemoryUnknown => {
                "CAR could not measure live memory. The static allocation fits, but current safety is unknown.".to_string()
            }
            resource_policy::LocalLoadVerdict::ModelMaintenance => {
                "This local model is being removed or maintained. Wait for that operation to finish, then retry.".to_string()
            }
            resource_policy::LocalLoadVerdict::PendingTeardown => {
                "CAR is still confirming that the previous local model process exited. Wait for teardown to finish, then retry.".to_string()
            }
            resource_policy::LocalLoadVerdict::Allowed => error.to_string(),
        };
        Self::LocalResourceBlocked {
            preflight: error.preflight,
            recovery,
        }
    }
}

/// 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 { .. }
            | InferenceError::CatalogPreconditionMismatch { .. }
            | InferenceError::ControlledTermination
    )
}

/// Whether this failure ends the fallback chain instead of advancing it.
///
/// Every other condition the dispatch loop handles is about a *lane* — a dead
/// credential, an unconfigured namespace, a capability the model lacks — and the
/// right move is to try a different one. A content refusal is about the
/// **request**, which is the one thing the chain cannot vary: each remaining
/// candidate replays the identical payload the filter just declined.
///
/// So falling through does not merely waste attempts, it answers dishonestly. A
/// remote-only chain has an installed on-device model appended as a last resort
/// (see [`should_append_local_last_resort`]), and nothing is filtering that one —
/// so a refusal of `parslee/reasoning` comes back as a *local* model's answer
/// attributed to the model the caller asked for. That is the "manufactures fake
/// results" failure the `strict_model` carve-out already exists to prevent, and
/// it is fatal to the case #796 was filed from: an adversarial-safety benchmark
/// drives this path deliberately, so a silent model swap inflates its pass rate
/// and its run-to-run counts stop being reproducible.
///
/// Ending the chain surfaces `ContentRefused`, which the daemon returns as
/// JSON-RPC `-32007` — a ruling the harness can score instead of a crash it has
/// to guess at (Parslee-ai/car#796).
fn error_ends_fallback_chain(e: &InferenceError) -> bool {
    matches!(
        e,
        InferenceError::ContentRefused { .. }
            | InferenceError::CatalogPreconditionMismatch { .. }
            | InferenceError::ControlledTermination
    )
}

/// Apply the exhausted-chain recovery hints, which rewrite an opaque final error
/// into one that names the two concrete things a user can do about it.
///
/// A content refusal is **exempt**. Both hints match on SUBSTRINGS of the Display
/// text, and `ContentRefused` embeds the gateway's own message verbatim — so a
/// refusal whose text happens to quote `403 forbidden` or `token expired` would
/// be re-wrapped as `InferenceFailed` and lose its classification on the way out.
/// That is the same drop-the-type mistake #796 was filed about, arriving one
/// layer later. The variant already IS the answer here; there is nothing left to
/// infer from its prose.
fn apply_exhaustion_recovery_hint(underlying: InferenceError) -> InferenceError {
    if matches!(
        underlying,
        InferenceError::ContentRefused { .. }
            | InferenceError::CatalogPreconditionMismatch { .. }
            | InferenceError::ControlledTermination
    ) {
        return underlying;
    }
    let underlying_str = underlying.to_string();
    match no_backend_recovery_hint(&underlying_str)
        .or_else(|| auth_expired_recovery_hint(&underlying_str))
    {
        Some(msg) => InferenceError::InferenceFailed(msg),
        None => underlying,
    }
}

const AUTH_LOGIN_MARKER: &str = "auth login";
const AUTH_STORE_UNREADABLE_MARKER: &str = "credential store unreadable";
const AUTH_ENV_MISSING_MARKER: &str = "credential environment variable missing";

/// Every stable phrase which means a failure needs credential repair rather
/// than an infrastructure retry. Route-level summaries use these same markers,
/// and `is_auth_failure_message` is the workspace classifier that consumes the
/// table.
const AUTH_FAILURE_MESSAGE_MARKERS: &[&str] = &[
    "no credential for proprietary",
    AUTH_LOGIN_MARKER,
    "session has expired",
    "cannot read parslee credentials",
    AUTH_STORE_UNREADABLE_MARKER,
    AUTH_ENV_MISSING_MARKER,
    // The two non-Parslee route summaries carry no `car auth login` remedy
    // line, so without their own rows here they would render as credential
    // failures the shared classifier calls infrastructure noise. Covers
    // "{provider} credential was rejected for `x` (HTTP 401)" and
    // "credential expired or was rejected for `x` — repair its provider login".
    "credential was rejected",
    "repair its provider login",
];

/// A credential failure from a configured or explicitly requested provider.
///
/// The fallback loop intentionally keeps trying after one account becomes
/// unusable, but if every later candidate fails too, the final candidate's
/// error is not the root cause the operator should fix first. Preserve the
/// most recent actionable credential cause separately so a local resource
/// error cannot overwrite an expired login in the final aggregate, while an
/// ambient missing variable from an unconfigured fallback cannot overwrite
/// the real terminal failure (Parslee-ai/car#1248).
#[derive(Debug, Clone, PartialEq, Eq)]
struct RouteCredentialFailure {
    summary: String,
    source_error: String,
}

fn parslee_signed_out_route_failure() -> RouteCredentialFailure {
    let summary = "Parslee login is absent — run `car auth login` before retrying".to_string();
    RouteCredentialFailure {
        source_error: summary.clone(),
        summary,
    }
}

fn route_credential_failure(
    candidate: &str,
    error: &InferenceError,
    promote_missing_credential: bool,
) -> Option<String> {
    match error {
        InferenceError::CredentialUnavailable {
            provider,
            reason,
            detail,
            ..
        } => {
            let provider_name = if provider.eq_ignore_ascii_case("parslee") {
                "Parslee".to_string()
            } else {
                provider.clone()
            };
            let summary = match reason {
                CredentialFailure::Expired { .. } => format!(
                    "{provider_name} login expired for `{candidate}` — run `car auth login`"
                ),
                CredentialFailure::SignedOut => format!(
                    "{provider_name} login is absent for `{candidate}` — run `car auth login`"
                ),
                CredentialFailure::StoreUnreadable => format!(
                    "{provider_name} {AUTH_STORE_UNREADABLE_MARKER} for `{candidate}` — unlock the credential store, then retry"
                ),
                CredentialFailure::EnvVarMissing { .. } if !promote_missing_credential => {
                    return None;
                }
                CredentialFailure::EnvVarMissing { env_var } => format!(
                    "{provider_name} {AUTH_ENV_MISSING_MARKER}: `{env_var}` for explicitly requested `{candidate}` — {detail}"
                ),
                // The authority re-read found a usable credential. This is a
                // retry signal, not evidence that a person must repair auth.
                CredentialFailure::RaceRetryable => return None,
            };
            Some(summary)
        }
        InferenceError::ProviderAccount {
            provider, status, ..
        } if matches!(*status, 401 | 403) => {
            if provider.eq_ignore_ascii_case("parslee") {
                Some(format!(
                    "Parslee login expired or was rejected for `{candidate}` — run `car auth login`"
                ))
            } else {
                Some(format!(
                    "{provider} credential was rejected for `{candidate}` (HTTP {status})"
                ))
            }
        }
        _ => {
            let rendered = error.to_string();
            let lower = rendered.to_ascii_lowercase();
            if is_auth_rejection_message(&rendered) {
                if candidate
                    .split_once('/')
                    .is_some_and(|(provider, _)| provider.eq_ignore_ascii_case("parslee"))
                {
                    Some(format!(
                        "Parslee login expired or was rejected for `{candidate}` — run `car auth login`"
                    ))
                } else {
                    Some(format!(
                        "credential expired or was rejected for `{candidate}` — repair its provider login"
                    ))
                }
            } else if lower.contains(AUTH_STORE_UNREADABLE_MARKER)
                || (promote_missing_credential && lower.contains("keychain lookup failed"))
            {
                Some(format!(
                    "{AUTH_STORE_UNREADABLE_MARKER} for `{candidate}` — unlock the credential store, then retry"
                ))
            } else {
                None
            }
        }
    }
}

fn record_route_credential_failure(
    slot: &mut Option<RouteCredentialFailure>,
    candidate: &str,
    error: &InferenceError,
    promote_missing_credential: bool,
) {
    if let Some(summary) = route_credential_failure(candidate, error, promote_missing_credential) {
        // Last actionable credential failure wins. In preference order it is
        // the terminal configured/attempted provider, while steady-state
        // EnvVarMissing noise from an unconfigured fallback never enters the
        // slot unless that provider was explicitly requested.
        *slot = Some(RouteCredentialFailure {
            summary,
            source_error: error.to_string(),
        });
    }
}

/// The routing snapshot probes only Parslee's credential store. Preserve its
/// failure only when a Parslee route participates; another provider's API key
/// cannot be repaired by signing in to Parslee. Actual attempted provider auth
/// failures are recorded separately by `record_route_credential_failure`.
fn chain_includes_parslee_route<'a>(
    mut resolve: impl FnMut(&str) -> Option<&'a ModelSchema>,
    chain: &[String],
) -> bool {
    chain.iter().any(|candidate| {
        resolve(candidate).is_some_and(|schema| schema.provider.eq_ignore_ascii_case("parslee"))
    })
}

/// Apply a remembered route-level credential cause before the exhausted-chain
/// hint. The credential summary is deliberately first and the final
/// candidate's error remains secondary detail, so mixed auth + OOM failures
/// tell the operator to repair the login rather than resize a local model.
///
/// The underlying error keeps its TYPE. Downstream consumers branch on the
/// variant, not the prose — `car run-task` re-runs an
/// [`InferenceError::Transient`], account-wide handling keys on
/// [`InferenceError::ProviderAccount`], and
/// [`InferenceError::CredentialUnavailable`] carries [`CredentialFailure`] as
/// data — so the credential context is folded into the variant's human-facing
/// message field instead of collapsing everything to `InferenceFailed`. Only
/// variants with no augmentable message field fall back to a stringified
/// `InferenceFailed`.
///
/// A fresh install exhausts with "no models / no backend" errors; the
/// credential cause does not replace [`no_backend_recovery_hint`]'s setup
/// guidance, because an operator who cannot log in still needs the on-device
/// `car models pull` path.
fn apply_route_failure_context(
    underlying: InferenceError,
    credential: Option<&RouteCredentialFailure>,
) -> InferenceError {
    if matches!(
        underlying,
        InferenceError::ContentRefused { .. }
            | InferenceError::CatalogPreconditionMismatch { .. }
            | InferenceError::ControlledTermination
    ) {
        return underlying;
    }
    let Some(credential) = credential else {
        return apply_exhaustion_recovery_hint(underlying);
    };
    let rendered = underlying.to_string();
    let summary = credential.summary.as_str();
    let setup_hint = no_backend_recovery_hint(&rendered);
    let connective = if rendered == credential.source_error {
        "provider detail"
    } else {
        "fallback then failed"
    };
    let augment = |field: String| match &setup_hint {
        // The hint already embeds the underlying error verbatim.
        Some(hint) => format!("{summary}; {hint}"),
        None => format!("{summary}; {connective}: {field}"),
    };
    match underlying {
        InferenceError::InferenceFailed(message) => {
            InferenceError::InferenceFailed(augment(message))
        }
        InferenceError::Transient { status, message } => InferenceError::Transient {
            status,
            message: augment(message),
        },
        InferenceError::ProviderAccount {
            provider,
            status,
            message,
        } => InferenceError::ProviderAccount {
            provider,
            status,
            message: augment(message),
        },
        InferenceError::CredentialUnavailable {
            provider,
            model,
            reason,
            detail,
        } => InferenceError::CredentialUnavailable {
            provider,
            model,
            reason,
            detail: augment(detail),
        },
        InferenceError::GatewayUnconfigured {
            provider,
            namespace,
            status,
            message,
        } => InferenceError::GatewayUnconfigured {
            provider,
            namespace,
            status,
            message: augment(message),
        },
        InferenceError::LocalResourceBlocked {
            preflight,
            recovery,
        } => InferenceError::LocalResourceBlocked {
            preflight,
            recovery: augment(recovery),
        },
        // No message field to fold the context into — the stringified wrap is
        // the only remaining honest rendering.
        _ => InferenceError::InferenceFailed(augment(rendered)),
    }
}

/// 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/
    ///
    /// This is a machine-global weight cache, NOT per-daemon state: it stays
    /// shared even when `CAR_HOME` relocates a daemon. Anything CAR *writes*
    /// about itself belongs under [`state_root`](Self::state_root) instead.
    pub models_dir: std::path::PathBuf,
    /// CAR state root: `$CAR_HOME`, else `~/.car`.
    ///
    /// Everything the engine persists about itself — the routing outcome
    /// profiles, the receipt ledger, key-pool stats, the signed-catalog cache,
    /// the discovery cache, the user `models.json` — hangs off this. Two
    /// daemons with different roots therefore keep separate bookkeeping while
    /// still sharing the multi-gigabyte weights in `models_dir`. With `CAR_HOME`
    /// unset this is `~/.car`, exactly where all of those files already are.
    pub state_root: 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 {
        // `models_dir` is deliberately anchored at `$HOME/.car`, NOT at the
        // `car_home` state root: model weights (and the python runtimes beside
        // them) are a multi-gigabyte machine-global cache of byte-identical
        // files, not per-instance state. A daemon relocated with `CAR_HOME`
        // moves its own journals, prefs and caches, and goes on sharing these —
        // the alternative is re-downloading tens of gigabytes to end up with
        // the same bytes in a second place.
        //
        // Only the weights get that treatment. Everything the engine writes
        // about *itself* — the outcome profiles and receipt ledger, key-pool
        // stats, the signed-catalog cache, the discovery cache, the user
        // `models.json` — resolves under `state_root` below, so a relocated
        // daemon keeps its own copy. Several of those files historically sat
        // inside `models/`; they still do, just under `state_root/models`
        // rather than under the weights dir, which is the same directory
        // whenever `CAR_HOME` is unset.
        let models_dir = default_models_dir();

        let hw = HardwareInfo::detect();

        Self {
            models_dir,
            state_root: car_home::root_or_relative(),
            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,
        }
    }
}

impl InferenceConfig {
    /// Engine state that has always lived beside the weights, kept at the same
    /// relative path (`models/`) but anchored at
    /// [`state_root`](Self::state_root): the outcome profiles, the receipt
    /// ledger, key-pool stats, benchmark priors, the discovery cache.
    ///
    /// Identical to [`models_dir`](Self::models_dir) whenever `CAR_HOME` is
    /// unset — which is why no existing install's files move — and a separate,
    /// per-daemon directory once it is set.
    pub fn state_models_dir(&self) -> std::path::PathBuf {
        self.state_root.join("models")
    }
}

/// The machine-shared model-weight cache: `$HOME/.car/models`
/// (`$USERPROFILE` on Windows), cwd-relative only when neither resolves.
///
/// Deliberately NOT `car_home`-anchored — see [`InferenceConfig::models_dir`].
/// Exposed so `car doctor` can check the weights the running daemon actually
/// loads, rather than the (possibly relocated) state root's `models/`.
pub fn default_models_dir() -> std::path::PathBuf {
    dirs_next()
        .unwrap_or_else(|| std::path::PathBuf::from("."))
        .join(".car")
        .join("models")
}

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

fn model_source_identity(schema: &ModelSchema) -> &str {
    match &schema.source {
        ModelSource::Local { hf_repo, .. }
        | ModelSource::Mlx { hf_repo, .. }
        | ModelSource::ManagedVllmMlx { hf_repo, .. } => hf_repo,
        ModelSource::WhisperCpp { model } | ModelSource::CodexCli { model } => model,
        _ => &schema.id,
    }
}

/// 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, Default, serde::Serialize, serde::Deserialize, PartialEq, Eq)]
pub struct InferenceModelIdentity {
    /// Exact immutable model id supplied through the protocol `model_id` pin.
    /// `None` for adaptive routing and legacy display-name/alias requests.
    #[serde(default)]
    pub requested_model_id: Option<String>,
    /// Canonical immutable catalog id actually used after routing/fallback.
    #[serde(default)]
    pub resolved_model_id: String,
    /// SHA-256 digest of the resolved immutable `ModelSchema` row.
    #[serde(default)]
    pub row_digest: String,
    /// SHA-256 revision of the exact catalog snapshot captured for this call.
    #[serde(default)]
    pub catalog_revision: String,
}

/// 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. Exact catalog-id pins report the immutable
    /// resolved id; legacy/adaptive routes retain their display-name behavior.
    pub model_used: String,
    /// Immutable catalog identity, flattened onto the v3 inference result so
    /// callers can validate the route without another lookup.
    #[serde(flatten)]
    pub model_identity: InferenceModelIdentity,
    /// 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.
    /// A model decoded in-process also reports
    /// `"local_decode_timeout"` ([`LOCAL_DECODE_TIMEOUT_STOP_REASON`]) when the
    /// wall-clock ceiling cut the pass short (car#851).
    /// `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 cut-short response.
    #[serde(default)]
    pub stop_reason: Option<String>,
    /// The candidate that was skipped because its credential was REJECTED
    /// (not merely absent), when a later candidate in the fallback chain
    /// then succeeded. `None` on the common path.
    ///
    /// Exists so a caller can ANNOUNCE the degrade instead of silently
    /// serving a different model: an operator whose Parslee sign-in lapsed
    /// otherwise sees a working run on a fallback backbone with no hint
    /// that the lane they configured is dead (Parslee-ai/car#888).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub auth_fallback_from: Option<String>,
    /// True when this turn was served by the installed on-device model that
    /// CAR appended behind an otherwise remote-only fallback chain.
    ///
    /// This is distinct from merely using a local model: an explicitly chosen
    /// local primary is ordinary routing. Callers should surface this marker so
    /// a resilience fallback cannot masquerade as the preferred remote model.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub local_last_resort: bool,
    /// Every candidate the chain moved past, in order, and WHY. Empty when the
    /// first candidate served.
    ///
    /// The general form of [`InferenceResult::auth_fallback_from`], which
    /// answers only "was a credential rejected". A run whose backbone changed
    /// mid-session because of a rate limit, a timeout, or an absent credential
    /// had no reason recorded anywhere at all — so a surprising result could be
    /// attributed to the code under test when the real cause was that a
    /// different model wrote it (Parslee-ai/car#1351).
    ///
    /// **Not a superset of `auth_fallback_from`, even though it holds every
    /// hop.** [`FallbackReason::CredentialRejected`] is deliberately broader
    /// than that field's predicate: it includes a provider refusing an API key
    /// (`ProviderAccount` 401), whose remedy is to fix the key.
    /// `auth_fallback_from` names only the narrower set a person clears by
    /// signing in, because the announcement it drives says `car auth login` —
    /// and telling someone to sign in over a bad OpenAI key is the wrong
    /// remedy (Parslee-ai/car#888). Recording both keeps the journal general
    /// without making the announcement wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub fallback_from: Vec<FallbackFrom>,
}

/// A candidate the fallback chain moved past, and why.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct FallbackFrom {
    /// The candidate's name, as the chain knew it.
    pub candidate: String,
    pub reason: FallbackReason,
}

/// Why the chain moved past a candidate.
///
/// Coarse on purpose. The point is to distinguish causes an operator would ACT
/// on differently — sign in, wait, configure a key, look at the provider — not
/// to reproduce every provider's error taxonomy. Anything unrecognized is
/// [`FallbackReason::Failed`] rather than being forced into a bucket it does
/// not belong in.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum FallbackReason {
    /// A credential exists and was REFUSED — an expired Parslee session, or a
    /// provider rejecting an API key (`ProviderAccount` 401/403).
    ///
    /// Deliberately broader than [`InferenceResult::auth_fallback_from`]'s
    /// predicate, which names only the subset a person clears by signing in.
    /// `car auth login` does not fix a bad OpenAI key, so this variant must not
    /// be read as "run that" — the remedy depends on which credential was
    /// refused.
    CredentialRejected,
    /// No credential is configured for that lane at all. A different fix from
    /// `CredentialRejected`: nothing expired, nothing was ever set.
    CredentialAbsent,
    /// The provider rate-limited the call (429 / "too many requests"). Clears
    /// by waiting.
    RateLimited,
    /// The account is out of credits or over quota (402).
    ///
    /// Separate from [`FallbackReason::RateLimited`] because an empty balance
    /// does NOT clear by waiting — the remedy is to top up. Folding it in told
    /// an operator to wait out a billing problem.
    QuotaExhausted,
    /// The call exceeded its deadline.
    ///
    /// Only when a deadline is what was actually hit. A transport failure with
    /// no status — connection refused, DNS, TLS, a truncated body — is
    /// [`FallbackReason::Failed`], because telling someone their call timed out
    /// when the endpoint was never up sends them to raise a timeout instead of
    /// starting the runtime.
    TimedOut,
    /// Anything else — a 5xx, a malformed request, a panicked runner, an
    /// unreadable credential store. The honest bucket, and it has to STAY
    /// honest: a first version of this classifier matched substrings and
    /// silently absorbed every `ProviderAccount` rejection here, which is the
    /// opposite of what this variant is for.
    Failed,
}

/// Classify a candidate's failure into a [`FallbackReason`].
///
/// **On the TYPED error, not on its rendered prose.** Every discriminating fact
/// here already exists as data — `ProviderAccount` carries `status: u16`,
/// `CredentialUnavailable` carries `reason: CredentialFailure`, `Transient`
/// carries `status: Option<u16>` — and `CredentialFailure`'s own doc says why
/// (car#797): 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.
///
/// A first version of this DID substring-match the English, and got four things
/// wrong that this file had already fixed twice elsewhere:
///
/// - `ProviderAccount` 401 renders `"… account rejected the request (HTTP 401):
///   provider rejected the API key …"` — no "unauthorized" token, so the
///   substring rule missed it and a REFUSED API KEY, the most actionable
///   degrade there is, journaled as `Failed`;
/// - a 400 whose provider body merely quotes "401 Unauthorized" classified as
///   `CredentialRejected`, sending an operator to re-auth over a malformed
///   request. `is_provider_transient` anchors on [`parse_api_returned_status`]
///   for exactly this reason, and `remote::is_auth_rejection` anchors on
///   "HTTP 401" with a test pinning the quoting case;
/// - `Parslee org lookup failed: HTTP 429 …` classified as `CredentialRejected`,
///   though the producer deliberately gates `note_credential_rejected()` on
///   401/403 because a 429 is not a dead credential;
/// - a locked keychain (`CredentialFailure::StoreUnreadable`) classified as
///   `CredentialAbsent`, whose remedy — configure a key — is wrong for a
///   credential that exists and cannot be read.
///
/// Only [`InferenceError::InferenceFailed`] falls through to a string sniff,
/// because it is the one variant carrying no structure, and that sniff is
/// status-anchored rather than substring-anchored.
pub fn classify_fallback_reason(error: &InferenceError) -> FallbackReason {
    use FallbackReason as R;
    match error {
        // 401/403 = the key was refused; 402 = the account is out of credit,
        // which is a "wait / top up" not a "your credential is wrong".
        InferenceError::ProviderAccount { status, .. } => match status {
            402 => R::QuotaExhausted,
            _ => R::CredentialRejected,
        },
        // Branch on the machine-readable classification, per its own contract.
        InferenceError::CredentialUnavailable { reason, .. } => match reason {
            // The account is fine; the run outlived the token.
            CredentialFailure::Expired { .. } => R::CredentialRejected,
            // Nothing was rejected — there is simply nothing there.
            CredentialFailure::SignedOut | CredentialFailure::EnvVarMissing { .. } => {
                R::CredentialAbsent
            }
            // Says NOTHING about whether a credential exists. Neither absent
            // nor rejected, so the honest bucket beats a wrong remedy.
            CredentialFailure::StoreUnreadable | CredentialFailure::RaceRetryable => R::Failed,
        },
        InferenceError::Transient {
            status: Some(429), ..
        } => R::RateLimited,
        // "Transport OR timeout", per the variant's own doc — and the two are
        // not distinguishable here. `reqwest_error_is_transient` admits
        // connect-refused, DNS, TLS and truncated-body errors alongside real
        // timeouts, and `TransportAttemptError` drops the `is_timeout` flag
        // that would separate them. Calling all of that `TimedOut` tells an
        // operator whose local runtime never started to raise a timeout.
        InferenceError::Transient { status: None, .. } => R::Failed,
        InferenceError::Transient { .. } => R::Failed,
        // The one case that IS unambiguously a deadline: the caller's own
        // armed `infer.deadline` elapsed, and the error says which one.
        InferenceError::DeadlineExceeded { .. } => R::TimedOut,
        InferenceError::InferenceFailed(msg) => classify_untyped_failure(msg),
        _ => R::Failed,
    }
}

/// The string fallback for [`InferenceError::InferenceFailed`], which carries
/// no structure.
///
/// Status-anchored wherever a status exists. A provider's error body is text we
/// did not write: it can quote any number or phrase, and
/// `apply_exhaustion_recovery_hint` already exempts `ContentRefused` from
/// substring hints for precisely that reason.
fn classify_untyped_failure(msg: &str) -> FallbackReason {
    use FallbackReason as R;
    // `API returned <status>: <verbatim provider body>` — trust the status,
    // never the body.
    if let Some(status) = parse_api_returned_status(msg) {
        return match status {
            401 | 403 => R::CredentialRejected,
            402 => R::QuotaExhausted,
            429 => R::RateLimited,
            408 | 504 => R::TimedOut,
            _ => R::Failed,
        };
    }
    let l = msg.to_ascii_lowercase();
    // `Parslee org lookup failed: HTTP <status>: <body>` is emitted for ANY
    // non-success status, so the phrase alone does not mean a dead credential.
    if l.contains("org lookup failed") {
        return if l.contains("http 401") || l.contains("http 403") {
            R::CredentialRejected
        } else if l.contains("http 429") {
            R::RateLimited
        } else {
            R::Failed
        };
    }
    if l.contains("authentication required")
        || l.contains("invalid_grant")
        || l.contains("token expired")
    {
        return R::CredentialRejected;
    }
    if l.contains("no credential for proprietary") || l.contains("no api key") {
        return R::CredentialAbsent;
    }
    if l.contains("too many requests") || l.contains("rate limit") {
        return R::RateLimited;
    }
    if l.contains("timed out") || l.contains("deadline exceeded") {
        return R::TimedOut;
    }
    R::Failed
}

/// Append `candidate` to the chain's hop list, with why it was skipped.
///
/// **Every hop, in order** — not first-wins. A chain that skips lanes 1, 2 and 3
/// before lane 4 serves made three transitions, and a single slot records one of
/// them while the journal downstream claims to hold every transition.
pub fn record_fallback_from(hops: &mut Vec<FallbackFrom>, candidate: &str, error: &InferenceError) {
    hops.push(FallbackFrom {
        candidate: candidate.to_string(),
        reason: classify_fallback_reason(error),
    });
}

/// 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>,
}

struct AbortOnDropTask<T>(Option<tokio::task::JoinHandle<T>>);

impl<T> AbortOnDropTask<T> {
    async fn join(mut self) -> Result<T, tokio::task::JoinError> {
        self.0.take().expect("owned task handle available").await
    }
}

impl<T> Drop for AbortOnDropTask<T> {
    fn drop(&mut self) {
        if let Some(task) = self.0.take() {
            task.abort();
        }
    }
}

fn bound_model_identity(
    snapshot: &CatalogSnapshot,
    requested_model_id: Option<&str>,
    resolved_model_id: &str,
) -> Result<InferenceModelIdentity, InferenceError> {
    let row = snapshot.model_by_exact_id(resolved_model_id).ok_or_else(|| {
        InferenceError::InferenceFailed(format!(
            "resolved model `{resolved_model_id}` was absent from the catalog snapshot bound to this request"
        ))
    })?;
    Ok(InferenceModelIdentity {
        requested_model_id: requested_model_id.map(str::to_string),
        resolved_model_id: row.model.id.clone(),
        row_digest: row.row_digest.clone(),
        catalog_revision: snapshot.catalog_revision.clone(),
    })
}

fn validate_expected_catalog_revision(
    req: &GenerateRequest,
    snapshot: &CatalogSnapshot,
) -> Result<(), InferenceError> {
    if let Some(expected) = req.expected_catalog_revision.as_deref() {
        if expected != snapshot.catalog_revision {
            return Err(InferenceError::CatalogPreconditionMismatch {
                detail: format!(
                    "expected catalog revision {expected}, got {}",
                    snapshot.catalog_revision
                ),
            });
        }
    }
    Ok(())
}

fn validate_expected_catalog_row(
    req: &GenerateRequest,
    snapshot: &CatalogSnapshot,
    resolved_model_id: &str,
) -> Result<(), InferenceError> {
    let Some(expected) = req.expected_row_digest.as_deref() else {
        return Ok(());
    };
    let row = snapshot
        .model_by_exact_id(resolved_model_id)
        .ok_or_else(|| InferenceError::CatalogPreconditionMismatch {
            detail: format!(
                "resolved model `{resolved_model_id}` is absent from the bound catalog snapshot"
            ),
        })?;
    if expected != row.row_digest {
        return Err(InferenceError::CatalogPreconditionMismatch {
            detail: format!(
                "expected row digest {expected} for `{resolved_model_id}`, got {}",
                row.row_digest
            ),
        });
    }
    Ok(())
}

const EXACT_MODEL_ID_PREFIX: &str = "\0car-exact-model-id:";

/// Mark a typed request as an exact immutable-id pin. The marker is consumed
/// before routing and never reaches a backend or delegated runner.
pub fn pin_exact_model_id(req: &mut GenerateRequest, model_id: String) -> Result<(), String> {
    if req.model.is_some() {
        return Err("`model` and `model_id` are mutually exclusive".to_string());
    }
    if model_id.trim().is_empty() {
        return Err("`model_id` must be a non-empty immutable id".to_string());
    }
    req.model = Some(format!("{EXACT_MODEL_ID_PREFIX}{model_id}"));
    req.params.strict_model = true;
    Ok(())
}

pub fn exact_pinned_model_id(req: &GenerateRequest) -> Option<&str> {
    req.model
        .as_deref()
        .and_then(|model| model.strip_prefix(EXACT_MODEL_ID_PREFIX))
}

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

/// The per-turn output budget for a resolved model.
///
/// When the caller left `max_tokens` at the library default we widen it to the
/// model's advertised output cap. That is what stops a long-horizon remote turn
/// from truncating a tool_use argument mid-object.
///
/// A model decoded **in-process** is the exception, and not a small one: its
/// token budget is a wall-clock budget. `mlx/qwen3-8b:4bit` advertises a 131072
/// context and no explicit output cap, so `effective_max_output()` widens 4096
/// to 32768 — about 24 minutes of decode at that catalog entry's own 22.4
/// tok/s, for one turn, and the empty result that a budget exhausted inside an
/// unclosed `<think>` block produces then trips the thinking-recovery retry in
/// [`InferenceEngine::generate_tracked`], which spends it a second time. That is
/// the reported hang: `car do --local` sat at ~39% CPU for 57 minutes with no
/// output. Such a model therefore keeps whatever budget the caller asked for.
/// `ModelSource::CodexCli` also keeps it: the CLI has no exact output-cap
/// option, so widening its best-effort instruction to a 128K catalog ceiling
/// would turn an ordinary default into a request for an enormous answer.
///
/// The local-model test is [`ModelSchema::decodes_in_process`], NOT `is_local` — vLLM-MLX
/// is local in the "runs on this machine" sense but is an HTTP server we do not
/// decode for, and it is precisely the local model whose tool_use JSON the
/// widening protects. (car#851)
fn resolved_max_tokens(requested: usize, schema: &ModelSchema) -> usize {
    if requested != crate::tasks::generate::DEFAULT_MAX_TOKENS
        || schema.decodes_in_process()
        || schema.is_codex_cli()
    {
        return requested;
    }
    schema.effective_max_output()
}

/// Wall-clock ceiling on ONE in-process decode pass, in seconds.
///
/// Deliberately generous: this is a runaway backstop, not a latency target. A
/// decode that reaches it has stopped being useful to its caller, and until it
/// existed the only bound on the loop was `max_tokens` — which on a large local
/// model is tens of minutes of silent CPU with no way to tell a slow model from
/// a wedged one. (car#851)
///
/// Scope: both loops that honor it (`drive_generation_with_timeout` and
/// `stream_local_mlx`) are MLX, i.e. Apple Silicon. The Candle in-process path
/// used on every other platform is NOT bounded by this — it only gets the
/// `max_tokens` rule in [`resolved_max_tokens`].
const DEFAULT_LOCAL_DECODE_TIMEOUT_SECS: u64 = 300;

/// `stop_reason` for a pass cut short by the ceiling above.
///
/// Deliberately not the bare `"timeout"`: a remote model's `stop_reason` is the
/// provider's raw `finish_reason` passed through with no allowlist, so a bare
/// spelling could collide with an endpoint that happens to emit it and hand a
/// remote caller an error naming a local wall clock. (car#851)
pub const LOCAL_DECODE_TIMEOUT_STOP_REASON: &str = "local_decode_timeout";

/// How often the decode loop reports progress. Time-based, not every-N-tokens:
/// the defect being fixed is *silence*, and a token-count interval still goes
/// quiet exactly when the model slows down. (car#851)
///
/// Both users — `drive_generation_with_timeout` and `stream_local_mlx` — are
/// MLX-only, so carry their cfg here too or this is dead code everywhere else
/// and `-D warnings` fails the build on Linux.
#[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
const LOCAL_DECODE_HEARTBEAT_SECS: u64 = 10;

/// Parse `CAR_LOCAL_DECODE_TIMEOUT_SECS`. `0` disables the ceiling; anything
/// unparseable falls back to the default rather than silently disabling it.
fn parse_decode_timeout(raw: Option<&str>) -> Option<std::time::Duration> {
    let secs = match raw {
        Some(v) => v
            .trim()
            .parse::<u64>()
            .unwrap_or(DEFAULT_LOCAL_DECODE_TIMEOUT_SECS),
        None => DEFAULT_LOCAL_DECODE_TIMEOUT_SECS,
    };
    (secs > 0).then(|| std::time::Duration::from_secs(secs))
}

/// Has this decode pass run past its wall-clock ceiling? `None` = no ceiling.
///
/// Shared by BOTH decode loops (`drive_generation_with_timeout` and
/// `stream_local_mlx`) so the comparison exists once. An inverted or
/// off-by-one comparison here is the difference between a bounded decode and
/// the car#851 hang, and the streaming loop cannot be unit-tested against a
/// real MLX backend — so the predicate is what gets tested.
///
/// Both callers are MLX-gated, so on every other target this has no caller.
/// It stays compiled (rather than carrying the loops' `cfg`) so its test still
/// runs on Linux CI — a regression net that only works on the author's Mac is
/// not a regression net.
#[cfg_attr(
    not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))),
    allow(dead_code)
)]
fn deadline_exceeded(elapsed: std::time::Duration, timeout: Option<std::time::Duration>) -> bool {
    timeout.is_some_and(|limit| elapsed >= limit)
}

/// Is another progress heartbeat due? Shared by both decode loops for the same
/// reason as [`deadline_exceeded`] — and because forgetting to advance
/// `last_heartbeat` turns the heartbeat into a per-token flood.
///
/// Ungated for the same reason as [`deadline_exceeded`].
#[cfg_attr(
    not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))),
    allow(dead_code)
)]
fn heartbeat_due(
    elapsed: std::time::Duration,
    last: std::time::Duration,
    interval: std::time::Duration,
) -> bool {
    elapsed.saturating_sub(last) >= interval
}

/// What [`InferenceEngine::generate_tracked`] should do with the pass it just
/// completed. Pulled out of the async fn so the decision — the highest-blast-
/// radius part of the car#851 change — is unit-testable without a live model.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum EmptyPassAction {
    /// Nothing usable, and reasoning is the plausible culprit: retry once with
    /// thinking suppressed (the pre-existing car-releases#60 recovery).
    RetryWithoutThinking,
    /// Nothing usable and the local wall-clock ceiling is why. Retrying spends
    /// the same ceiling a second time and cannot end differently — that is how
    /// car#851 turned a 24-minute turn into a 49-minute one — so fail loudly.
    FailDecodeCeiling,
    /// Usable output, or nothing usable for a reason neither branch owns.
    Accept,
}

/// Classify a completed pass. Order matters: the ceiling check comes FIRST,
/// because a ceiling stop looks exactly like a thinking truncation from here
/// (empty text, no tool calls — the model was still inside `<think>` when the
/// clock ran out) and the recovery retry would happily double the wall time.
///
/// A pass that produced *any* text or tool call is always accepted, ceiling or
/// not: a partial answer is worth more to the caller than an error.
fn classify_empty_pass(
    recover: bool,
    stop_reason: Option<&str>,
    text: &str,
    tool_calls_empty: bool,
) -> EmptyPassAction {
    if !text.trim().is_empty() || !tool_calls_empty {
        return EmptyPassAction::Accept;
    }
    if stop_reason == Some(LOCAL_DECODE_TIMEOUT_STOP_REASON) {
        return EmptyPassAction::FailDecodeCeiling;
    }
    if recover {
        return EmptyPassAction::RetryWithoutThinking;
    }
    EmptyPassAction::Accept
}

fn local_decode_timeout() -> Option<std::time::Duration> {
    parse_decode_timeout(
        std::env::var("CAR_LOCAL_DECODE_TIMEOUT_SECS")
            .ok()
            .as_deref(),
    )
}

impl InferenceResult {
    /// Canonical immutable id of the model that served this turn.
    ///
    /// Older/scripted payloads may not carry the flattened v3 identity fields;
    /// retain `model_used` as their compatibility fallback.
    pub fn served_model_id(&self) -> &str {
        if self.model_identity.resolved_model_id.is_empty() {
            &self.model_used
        } else {
            &self.model_identity.resolved_model_id
        }
    }

    /// 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 response was cut short rather than finished.
    /// Matches every provider spelling of an output-token cap: OpenAI chat
    /// `"length"`, OpenAI Responses `"max_output_tokens"`, Anthropic
    /// `"max_tokens"`, Google `"MAX_TOKENS"`, and the local MLX/Candle
    /// `"length"` — plus the local wall-clock ceiling
    /// (`"local_decode_timeout"`, car#851), which produces the same partial
    /// text for a different reason and would otherwise read as a complete
    /// answer. 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"
                    | crate::LOCAL_DECODE_TIMEOUT_STOP_REASON
            )
        )
    }

    /// 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(),
            model_id: Some(self.served_model_id().to_string()),
            local_last_resort: self.local_last_resort,
        });
    }
}

#[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,
    /// Durable ownership/tombstone records plus machine-shared activity locks
    /// for local model artifacts.
    model_management: model_management::ModelManagementStore,
    /// Shared admission service used by every CAR-owned local allocation.
    local_admission: Arc<resource_policy::LocalAdmissionCoordinator>,
    /// Keeps the state-root-scoped runtime composition alive. Engines pointed
    /// at the same CAR state root share every resident backend/cache/process;
    /// this prevents a second engine from loading peer-discounted duplicate
    /// weights or clearing another engine's residency accounting.
    _runtime_scope: Arc<ScopedInferenceRuntime>,
    resource_policy_generation: Arc<std::sync::atomic::AtomicU64>,
    /// Startup load source/warning paired with the active admission policy.
    /// The policy itself is refreshed from `local_admission` by the accessor,
    /// so independently constructed engines sharing one coordinator agree.
    resource_policy_evidence: Arc<std::sync::RwLock<resource_policy::ResourcePolicyLoadEvidence>>,
    /// Mutable cache ceiling paired with `local_admission` so a policy change
    /// affects both future reservations and retained idle weights.
    model_budget: Arc<backend_cache::SharedModelBudget>,
    /// 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<std::collections::HashMap<String, 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>,
}

enum SpeechCandidateAdmission {
    Proceed(Option<resource_policy::LocalLoadReservation>),
    SkipBlocked(InferenceError),
    FailBlocked(InferenceError),
}

struct ScopedInferenceRuntime {
    model_budget: Arc<backend_cache::SharedModelBudget>,
    resource_policy_generation: Arc<std::sync::atomic::AtomicU64>,
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    mlx_backends: Arc<backend_cache::BackendCache<backend::MlxBackend>>,
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    local_backends:
        Arc<backend_cache::BackendCache<Box<dyn backend::local::LocalInferenceBackend>>>,
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    flux_cache: Arc<backend_cache::BackendCache<backend::mlx_flux::FluxBackend>>,
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    ltx_cache: Arc<backend_cache::BackendCache<backend::mlx_ltx::LtxBackend>>,
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    kokoro_cache: Arc<backend_cache::BackendCache<backend::mlx_kokoro::KokoroBackend>>,
    #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
    backend: Arc<RwLock<std::collections::HashMap<String, 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>>>,
    vllm_pool: Arc<vllm_pool::VllmServerPool>,
    #[cfg(test)]
    load_probe: Arc<backend_cache::BackendCache<()>>,
}

fn scoped_inference_runtime_registry() -> &'static std::sync::Mutex<
    std::collections::HashMap<PathBuf, std::sync::Weak<ScopedInferenceRuntime>>,
> {
    static REGISTRY: std::sync::OnceLock<
        std::sync::Mutex<
            std::collections::HashMap<PathBuf, std::sync::Weak<ScopedInferenceRuntime>>,
        >,
    > = std::sync::OnceLock::new();
    REGISTRY.get_or_init(|| std::sync::Mutex::new(std::collections::HashMap::new()))
}

fn configured_cache_budget_mb(default_mb: u64) -> u64 {
    std::env::var("CAR_INFERENCE_MODEL_CACHE_MB")
        .ok()
        .and_then(|value| value.parse::<u64>().ok())
        .unwrap_or(default_mb)
}

fn scoped_inference_runtime(
    state_root: &Path,
    configured_ceiling_mb: u64,
    admission: Arc<resource_policy::LocalAdmissionCoordinator>,
) -> Arc<ScopedInferenceRuntime> {
    let state_root = resource_policy::normalized_state_root_key(state_root);
    let mut registry = scoped_inference_runtime_registry()
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    registry.retain(|_, runtime| runtime.strong_count() > 0);
    if let Some(runtime) = registry.get(&state_root).and_then(std::sync::Weak::upgrade) {
        runtime.model_budget.set_budget_bytes(
            configured_cache_budget_mb(configured_ceiling_mb).saturating_mul(1024 * 1024),
        );
        return runtime;
    }

    let model_budget = backend_cache::SharedModelBudget::from_env_or(configured_ceiling_mb);
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    let cache_idle = backend_cache::idle_ttl_from_env();
    let runtime = Arc::new(ScopedInferenceRuntime {
        model_budget: model_budget.clone(),
        resource_policy_generation: Arc::new(std::sync::atomic::AtomicU64::new(1)),
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        mlx_backends: Arc::new(backend_cache::BackendCache::from_shared_with_admission(
            model_budget.clone(),
            cache_idle,
            Some(admission.clone()),
        )),
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        local_backends: Arc::new(backend_cache::BackendCache::from_shared_with_admission(
            model_budget.clone(),
            cache_idle,
            Some(admission.clone()),
        )),
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        flux_cache: Arc::new(backend_cache::BackendCache::from_shared_with_admission(
            model_budget.clone(),
            cache_idle,
            Some(admission.clone()),
        )),
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        ltx_cache: Arc::new(backend_cache::BackendCache::from_shared_with_admission(
            model_budget.clone(),
            cache_idle,
            Some(admission.clone()),
        )),
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        kokoro_cache: Arc::new(backend_cache::BackendCache::from_shared_with_admission(
            model_budget,
            cache_idle,
            Some(admission.clone()),
        )),
        #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
        backend: Arc::new(RwLock::new(std::collections::HashMap::new())),
        #[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)),
        vllm_pool: Arc::new(vllm_pool::VllmServerPool::with_admission(
            std::time::Duration::from_secs(
                std::env::var("CAR_VLLM_IDLE_SECS")
                    .ok()
                    .and_then(|value| value.parse().ok())
                    .unwrap_or(300),
            ),
            admission,
        )),
        #[cfg(test)]
        load_probe: Arc::new(backend_cache::BackendCache::new(1024)),
    });
    registry.insert(state_root, Arc::downgrade(&runtime));
    runtime
}

/// A root-scoped Kokoro cache lease shared by the inference engine and
/// car-voice. The runtime is held only for as long as an actual voice owner
/// exists; merely importing car-voice cannot pin the default CAR runtime.
#[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
pub struct ScopedKokoroBackendCache {
    cache: Arc<backend_cache::BackendCache<backend::mlx_kokoro::KokoroBackend>>,
    _runtime: Arc<ScopedInferenceRuntime>,
    admission: Arc<resource_policy::LocalAdmissionCoordinator>,
}

#[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
impl ScopedKokoroBackendCache {
    pub fn cache(&self) -> &Arc<backend_cache::BackendCache<backend::mlx_kokoro::KokoroBackend>> {
        &self.cache
    }

    pub fn admission(&self) -> &Arc<resource_policy::LocalAdmissionCoordinator> {
        &self.admission
    }
}

#[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
pub fn scoped_kokoro_backend_cache(state_root: &Path) -> ScopedKokoroBackendCache {
    let state_root = resource_policy::normalized_state_root_key(state_root);
    let policy = resource_policy::FileResourcePolicyRepository::new(state_root.clone())
        .load()
        .unwrap_or_else(|_| resource_policy::ResourcePolicy::everyday());
    let hardware = HardwareInfo::detect();
    let admission = resource_policy::scoped_local_admission(&state_root, policy, hardware.clone());
    let ceiling_mb = admission
        .policy()
        .effective_budget(hardware.total_ram_mb)
        .configured_model_ceiling_mb;
    let runtime = scoped_inference_runtime(&state_root, ceiling_mb, admission.clone());
    ScopedKokoroBackendCache {
        cache: runtime.kokoro_cache.clone(),
        _runtime: runtime,
        admission,
    }
}

impl InferenceEngine {
    fn requires_local_admission(schema: &ModelSchema) -> bool {
        schema.is_car_managed_vllm_mlx() || Self::supports_worker_offload(schema)
    }

    /// Managed vLLM owns a wider startup transaction than ordinary local
    /// loaders: its reservation must be created only after the per-model
    /// dispatch gate is held. Reserving in the generic outer path lets a
    /// concurrent request observe the first startup's provisional process
    /// charge and fail before it can join the singleflight.
    fn reserve_in_outer_dispatch(schema: &ModelSchema) -> bool {
        Self::requires_local_admission(schema) && !schema.is_car_managed_vllm_mlx()
    }

    fn supports_worker_offload(schema: &ModelSchema) -> bool {
        matches!(
            schema.source,
            ModelSource::Local { .. } | ModelSource::Mlx { .. }
        )
    }

    /// Actual post-dispatch retention observed by worker/process owners.
    /// Success alone is insufficient: zero-cache loads remain transient.
    pub fn local_model_retention(&self, model_id: &str) -> backend_cache::BackendRetention {
        if self.local_admission.is_resident(model_id) {
            backend_cache::BackendRetention::Resident
        } else {
            backend_cache::BackendRetention::Transient
        }
    }
    /// Evaluate one local model without downloading or loading it.
    pub fn local_model_preflight(
        &self,
        model_id: &str,
        context_tokens: usize,
    ) -> Result<resource_policy::LocalLoadPreflight, InferenceError> {
        let schema = self
            .unified_registry
            .get(model_id)
            .or_else(|| self.unified_registry.find_by_name(model_id))
            .ok_or_else(|| InferenceError::ModelNotFound(model_id.to_string()))?;
        self.ensure_model_enabled(&schema.id)?;
        Ok(self.local_admission.preflight(schema, context_tokens))
    }

    /// The policy currently enforced by local-model admission, plus the load
    /// source/warning captured when this engine initialized it.
    ///
    /// Read-side model surfaces use this accessor rather than reopening the
    /// policy file, so a policy applied to the running engine is one atomic
    /// source of truth for preflight, fit annotations, and recommendations.
    pub fn active_local_resource_policy(&self) -> resource_policy::ResourcePolicyLoadEvidence {
        let mut evidence = self
            .resource_policy_evidence
            .read()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
            .clone();
        evidence.policy = self.local_admission.policy();
        evidence
    }

    /// Update the in-memory admission/cache ceiling after persistence succeeds.
    /// Idle entries are reclaimed by each cache's next sweep/access; active
    /// inference is never killed by a policy decrease.
    pub fn apply_local_resource_policy(&self, policy: resource_policy::ResourcePolicy) {
        let ceiling_mb = policy
            .effective_budget(HardwareInfo::detect().total_ram_mb)
            .configured_model_ceiling_mb;
        self.local_admission.set_policy(policy.clone());
        *self
            .resource_policy_evidence
            .write()
            .unwrap_or_else(|poisoned| poisoned.into_inner()) =
            resource_policy::ResourcePolicyLoadEvidence {
                policy,
                source: resource_policy::ResourcePolicyLoadSource::Loaded,
                warning: None,
            };
        let cache_ceiling_mb = configured_cache_budget_mb(ceiling_mb);
        self.model_budget
            .set_budget_bytes(cache_ceiling_mb.saturating_mul(1024 * 1024));
        let generation = self
            .resource_policy_generation
            .fetch_add(1, std::sync::atomic::Ordering::AcqRel)
            .saturating_add(1);
        if let Some(offload) = crate::offload::current_local_offload() {
            offload.refresh_resource_policy(generation);
        }
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        {
            self.mlx_backends.enforce_budget();
            self.local_backends.enforce_budget();
            self.flux_cache.enforce_budget();
            self.ltx_cache.enforce_budget();
            self.kokoro_cache.enforce_budget();
        }
    }

    pub fn begin_local_model_maintenance(
        &self,
        model_id: &str,
    ) -> Result<resource_policy::LocalModelMaintenanceGuard, resource_policy::ModelMaintenanceError>
    {
        self.local_admission.begin_model_maintenance(model_id)
    }

    pub async fn prepare_local_model_removal(
        &self,
        model_id: &str,
    ) -> Result<resource_policy::LocalModelMaintenanceGuard, resource_policy::ModelMaintenanceError>
    {
        let maintenance = self.local_admission.begin_model_maintenance(model_id)?;
        if let Some(offload) = crate::offload::current_local_offload() {
            if offload
                .resident_models()
                .await
                .iter()
                .any(|resident| resident == model_id)
            {
                let acknowledged = offload.release_model(model_id).await.map_err(|error| {
                    resource_policy::ModelMaintenanceError::ReleaseFailed(error.to_string())
                })?;
                if !acknowledged
                    || offload
                        .resident_models()
                        .await
                        .iter()
                        .any(|resident| resident == model_id)
                {
                    return Err(
                        resource_policy::ModelMaintenanceError::WorkerReleaseUnacknowledged(
                            model_id.to_string(),
                        ),
                    );
                }
            }
        }
        if self
            .vllm_pool
            .release_model_if_present(model_id)
            .await
            .is_err()
        {
            return Err(
                resource_policy::ModelMaintenanceError::ProcessReleaseUnacknowledged(
                    model_id.to_string(),
                ),
            );
        }
        if !self.evict_local_model_if_idle(model_id) {
            return Err(resource_policy::ModelMaintenanceError::CacheReleaseBlocked(
                model_id.to_string(),
            ));
        }
        let allocation_ids = self.local_admission.resident_allocation_ids(model_id);
        if !allocation_ids.is_empty() {
            return Err(resource_policy::ModelMaintenanceError::ResidualResidency {
                model_id: model_id.to_string(),
                allocation_ids,
            });
        }
        Ok(maintenance)
    }

    /// Targeted cache eviction for safe model removal. Callers must hold the
    /// per-model maintenance guard while invoking this and checking any
    /// worker/cross-process leases.
    pub fn evict_local_model_if_idle(&self, model_id: &str) -> bool {
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        {
            let mut allocation_ids = self.local_admission.resident_allocation_ids(model_id);
            if !allocation_ids.iter().any(|id| id == model_id) {
                allocation_ids.push(model_id.to_string());
            }
            allocation_ids.into_iter().all(|allocation_id| {
                [
                    self.mlx_backends.evict_if_idle(&allocation_id),
                    self.local_backends.evict_if_idle(&allocation_id),
                    self.flux_cache.evict_if_idle(&allocation_id),
                    self.ltx_cache.evict_if_idle(&allocation_id),
                    self.kokoro_cache.evict_if_idle(&allocation_id),
                ]
                .into_iter()
                .all(|evicted| evicted)
            })
        }
        #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
        {
            let _ = model_id;
            let backend_released = self.backend.try_write().is_ok_and(|mut backends| {
                if backends.remove(model_id).is_some() {
                    self.local_admission.mark_evicted(model_id);
                }
                true
            });
            // The embedding slot is still single-purpose. Fail closed when it
            // is populated or actively locked rather than unloading an
            // unrelated embedding model.
            backend_released
                && self
                    .embedding_backend
                    .try_write()
                    .is_ok_and(|slot| slot.is_none())
        }
    }

    fn reserve_local_request(
        &self,
        schema: &ModelSchema,
        context_tokens: usize,
    ) -> Result<resource_policy::LocalLoadReservation, InferenceError> {
        self.ensure_model_enabled(&schema.id)?;
        let activity_lease = self.model_management.acquire_lease(&schema.id)?;
        let mut reservation = self
            .local_admission
            .reserve(schema, context_tokens)
            .map_err(InferenceError::from)?;
        reservation.attach_activity_lease(activity_lease);
        Ok(reservation)
    }

    /// Recheck an installed allocation used only for the duration of one
    /// subprocess call. This deliberately never publishes resident weights;
    /// dropping the reservation after the subprocess exits releases the full
    /// measured allocation.
    #[cfg(any(
        test,
        all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))
    ))]
    fn reconcile_transient_local_allocation(
        reservation: &mut resource_policy::LocalLoadReservation,
        measured_weights_bytes: u64,
    ) -> Result<(), InferenceError> {
        reservation
            .reconcile_measured_weights(measured_weights_bytes)
            .map(|_| ())
            .map_err(InferenceError::from)
    }

    fn prepare_worker_admission(
        &self,
        schema: &ModelSchema,
        reservation: &mut resource_policy::LocalLoadReservation,
    ) -> Result<crate::offload::LocalWorkerAdmission, InferenceError> {
        let installed = self.config.models_dir.join(&schema.name);
        let installed_weights_bytes = backend_cache::estimate_model_size(&installed);
        // On a fresh machine the parent may dispatch before the worker has
        // downloaded the managed artifact. Zero is "not measured", not proof
        // that the model has no weights. Always re-run atomic admission after
        // binding the exact worker generation, using the larger of installed
        // evidence and the conservative catalog estimate; this prevents a new
        // worker from peer-discounting an older process still exiting.
        let measured_weights_bytes =
            installed_weights_bytes.max(reservation.reconciled_weights_bytes());
        reservation
            .reconcile_measured_weights(measured_weights_bytes)
            .map_err(InferenceError::from)?;
        Ok(crate::offload::LocalWorkerAdmission {
            policy: self.local_admission.policy(),
            policy_generation: self
                .resource_policy_generation
                .load(std::sync::atomic::Ordering::Acquire),
            state_root: resource_policy::normalized_state_root_key(&self.config.state_root),
            measured_weights_bytes,
        })
    }

    async fn reconcile_worker_residency(
        offload: &dyn crate::offload::LocalGenerationOffload,
        expected_model_id: &str,
        residency: &crate::offload::LocalWorkerResidency,
        retention: backend_cache::BackendRetention,
        reservation: &mut resource_policy::LocalLoadReservation,
    ) -> Result<(), InferenceError> {
        if residency.model_id != expected_model_id {
            if retention == backend_cache::BackendRetention::Resident {
                let released = offload
                    .release_model(&residency.model_id)
                    .await
                    .unwrap_or(false);
                if !released {
                    let allocation_id = offload
                        .resident_allocation_id(&residency.model_id)
                        .unwrap_or_else(|| {
                            resource_policy::worker_process_allocation_id(&residency.model_id)
                        });
                    reservation.publish_resident_weights_as(
                        &allocation_id,
                        residency.measured_weights_bytes,
                    );
                }
            }
            return Err(InferenceError::InferenceFailed(format!(
                "local worker acknowledged model '{}' for requested '{}'",
                residency.model_id, expected_model_id
            )));
        }
        if retention == backend_cache::BackendRetention::Resident {
            let allocation_id = offload
                .resident_allocation_id(expected_model_id)
                .unwrap_or_else(|| {
                    resource_policy::worker_process_allocation_id(expected_model_id)
                });
            reservation
                .publish_resident_weights_as(&allocation_id, residency.measured_weights_bytes);
        }
        Ok(())
    }

    fn admit_speech_candidate(
        &self,
        schema: &ModelSchema,
        explicit: bool,
    ) -> SpeechCandidateAdmission {
        if !schema.is_local()
            || matches!(
                schema.source,
                ModelSource::WindowsSpeech {} | ModelSource::AppleFoundationModels { .. }
            )
        {
            return SpeechCandidateAdmission::Proceed(None);
        }
        match self.reserve_local_request(schema, 0) {
            Ok(reservation) => SpeechCandidateAdmission::Proceed(Some(reservation)),
            Err(error) if explicit => SpeechCandidateAdmission::FailBlocked(error),
            Err(error) => SpeechCandidateAdmission::SkipBlocked(error),
        }
    }

    fn hold_local_reservation_for_stream(
        mut source: tokio::sync::mpsc::Receiver<stream::StreamEvent>,
        reservation: resource_policy::LocalLoadReservation,
    ) -> tokio::sync::mpsc::Receiver<stream::StreamEvent> {
        let (tx, rx) = tokio::sync::mpsc::channel(64);
        tokio::spawn(async move {
            let _reservation = reservation;
            while let Some(event) = source.recv().await {
                if tx.send(event).await.is_err() {
                    break;
                }
            }
        });
        rx
    }

    fn hold_optional_reservation_for_stream(
        source: tokio::sync::mpsc::Receiver<stream::StreamEvent>,
        reservation: Option<resource_policy::LocalLoadReservation>,
    ) -> tokio::sync::mpsc::Receiver<stream::StreamEvent> {
        match reservation {
            Some(reservation) => Self::hold_local_reservation_for_stream(source, reservation),
            None => source,
        }
    }

    /// 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();
        let policy_evidence =
            resource_policy::FileResourcePolicyRepository::new(config.state_root.clone())
                .load_with_evidence()
                .unwrap_or_else(|error| {
                    tracing::warn!(%error, "failed to read local model resource policy; using Everyday");
                    resource_policy::ResourcePolicyLoadEvidence {
                        policy: resource_policy::ResourcePolicy::everyday(),
                        source: resource_policy::ResourcePolicyLoadSource::CorruptDefault,
                        warning: Some(format!(
                            "The local-model resource policy could not be read ({error}); CAR used Everyday."
                        )),
                    }
                });
        let policy = policy_evidence.policy.clone();
        let effective_budget = policy.effective_budget(hw.total_ram_mb);
        let local_admission =
            resource_policy::scoped_local_admission(&config.state_root, policy, hw.clone());
        let runtime_scope = scoped_inference_runtime(
            &config.state_root,
            effective_budget.configured_model_ceiling_mb,
            local_admission.clone(),
        );
        let router = ModelRouter::new(hw.clone());
        let unified_registry = UnifiedRegistry::new_with_state_root(
            config.state_root.clone(),
            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.state_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.state_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();
        let model_management = model_management::ModelManagementStore::new(
            config.state_root.clone(),
            config.models_dir.clone(),
        );

        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,
            model_management,
            local_admission: local_admission.clone(),
            _runtime_scope: runtime_scope.clone(),
            resource_policy_generation: runtime_scope.resource_policy_generation.clone(),
            resource_policy_evidence: Arc::new(std::sync::RwLock::new(policy_evidence)),
            model_budget: runtime_scope.model_budget.clone(),
            #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
            mlx_backends: runtime_scope.mlx_backends.clone(),
            #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
            local_backends: runtime_scope.local_backends.clone(),
            #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
            flux_cache: runtime_scope.flux_cache.clone(),
            #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
            ltx_cache: runtime_scope.ltx_cache.clone(),
            #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
            kokoro_cache: runtime_scope.kokoro_cache.clone(),
            registry,
            router,
            #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
            backend: runtime_scope.backend.clone(),
            #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
            embedding_backend: runtime_scope.embedding_backend.clone(),
            speech_runtime: runtime_scope.speech_runtime.clone(),
            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: runtime_scope.vllm_pool.clone(),
        }
    }

    /// 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.state_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,
        schema: &ModelSchema,
        reservation: &mut resource_policy::LocalLoadReservation,
    ) -> Result<(), InferenceError> {
        let read = self.backend.read().await;
        if read.contains_key(&schema.id) {
            return Ok(());
        }
        drop(read);

        let mut write = self.backend.write().await;
        if write.contains_key(&schema.id) {
            return Ok(());
        }

        let model_path = self.registry.ensure_model(&schema.name).await?;
        let mut measured = backend_cache::estimate_model_size(&model_path);
        reservation
            .reconcile_measured_weights(measured)
            .map_err(InferenceError::from)?;
        let device = self.config.device.unwrap_or_else(Device::auto);
        // LOCAL_ADMISSION_BOUNDARY:adaptive-local-dispatch
        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 = %schema.id,
                    error = %load_err,
                    "candle backend load failed; purged corrupt cache files and re-pulling once"
                );
                let model_path = self.registry.ensure_model(&schema.name).await?;
                measured = backend_cache::estimate_model_size(&model_path);
                reservation
                    .reconcile_measured_weights(measured)
                    .map_err(InferenceError::from)?;
                CandleBackend::load(&model_path, device)?
            }
        };
        write.insert(schema.id.clone(), backend);
        reservation.publish_resident_weights(measured);
        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,
        reservation: &mut resource_policy::LocalLoadReservation,
    ) -> 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 mut measured = backend_cache::estimate_model_size(&model_path);
        reservation
            .reconcile_measured_weights(measured)
            .map_err(InferenceError::from)?;
        let device = self.config.device.unwrap_or_else(Device::auto);
        // LOCAL_ADMISSION_BOUNDARY:embedding-dispatch
        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?;
                measured = backend_cache::estimate_model_size(&model_path);
                reservation
                    .reconcile_measured_weights(measured)
                    .map_err(InferenceError::from)?;
                EmbeddingBackend::load(&model_path, device)?
            }
        };
        *write = Some(backend);
        reservation.publish_resident_weights(measured);
        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();
        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,
        reservation: &mut resource_policy::LocalLoadReservation,
        loader: F,
        repull: RF,
    ) -> Result<
        (
            backend_cache::CachedBackend<T>,
            backend_cache::BackendRetention,
        ),
        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_admitted(schema_id, size, reservation, || loader(&model_dir)) {
            Ok(admitted) => Ok(admitted),
            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?;
                let fresh_size = backend_cache::estimate_model_size(&fresh_dir);
                cache
                    .get_or_load_admitted(schema_id, fresh_size, reservation, || 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,
        reservation: &mut resource_policy::LocalLoadReservation,
    ) -> Result<
        (
            backend_cache::CachedBackend<backend::MlxBackend>,
            backend_cache::BackendRetention,
        ),
        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);
        if !reservation.authorizes_model(&schema.id) {
            return Err(InferenceError::InferenceFailed(format!(
                "local admission reservation does not authorize {}",
                schema.id
            )));
        }
        // 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(|| {
                // LOCAL_ADMISSION_BOUNDARY:adaptive-local-dispatch
                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,
            reservation,
            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,
        reservation: &mut resource_policy::LocalLoadReservation,
    ) -> Result<
        (
            backend_cache::CachedBackend<Box<dyn backend::local::LocalInferenceBackend>>,
            backend_cache::BackendRetention,
        ),
        InferenceError,
    > {
        let model_dir = self.unified_registry.ensure_local(&schema.id).await?;
        let size = backend_cache::estimate_model_size(&model_dir);
        if !reservation.authorizes_model(&schema.id) {
            return Err(InferenceError::InferenceFailed(format!(
                "local admission reservation does not authorize {}",
                schema.id
            )));
        }
        let loader = |dir: &Path| {
            let dir = dir.to_path_buf();
            std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
                // LOCAL_ADMISSION_BOUNDARY:adaptive-local-dispatch
                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,
            reservation,
            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;
            }
            // Reset is observational maintenance, not a load boundary. Never
            // turn a cache miss into a cold model allocation.
            if !self.local_backends.contains(&schema.id) {
                return;
            }
            let Ok(mut reservation) = self.reserve_local_request(&schema, 0) else {
                return;
            };
            if let Ok((handle, _retention)) =
                self.ensure_local_backend(&schema, &mut reservation).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}"))
                })?;
                // LOCAL_ADMISSION_BOUNDARY:warm-up
                let mut reservation = self.reserve_local_request(&schema, 0)?;
                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_admitted(
                            &schema.id,
                            size,
                            &mut reservation,
                            || 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_admitted(
                            &schema.id,
                            size,
                            &mut reservation,
                            || {
                                // LOCAL_ADMISSION_BOUNDARY:video-dispatch
                                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 cache_key = reservation.model_id().to_string();
                        let _ = self.kokoro_cache.get_or_load_admitted(
                            &cache_key,
                            size,
                            &mut reservation,
                            || backend::mlx_kokoro::KokoroBackend::load(&model_dir),
                        )?;
                    }
                    _ => {
                        let _ = self.ensure_mlx_backend(&schema, &mut reservation).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,
        reservation: Option<resource_policy::LocalLoadReservation>,
        context_tokens: usize,
    ) -> Result<(ModelSchema, Option<resource_policy::LocalLoadReservation>), InferenceError> {
        match &schema.source {
            ModelSource::ManagedVllmMlx { .. } => {}
            ModelSource::VllmMlx { .. } => return Ok((schema, None)),
            _ => return Ok((schema, None)),
        }
        // The gate begins before reaping/admission and ends only after the
        // ready process has been published resident. A concurrent request for
        // this model therefore waits, then reserves against the published
        // allocation instead of mistaking startup ownership for teardown.
        let _dispatch = self.vllm_pool.acquire_dispatch(&schema.id).await;
        self.vllm_pool
            .wait_for_teardown(&schema.id, std::time::Duration::from_secs(5))
            .await
            .map_err(InferenceError::InferenceFailed)?;
        // A dead leader may leave model-bearing descendants in its dedicated
        // process group. Reap/quarantine that group before taking a replacement
        // reservation; no new generation may peer-discount it while teardown
        // is pending.
        self.vllm_pool
            .reap_dead(&schema.id)
            .await
            .map_err(InferenceError::InferenceFailed)?;
        let mut reservation = match reservation {
            Some(reservation) if reservation.model_id() == schema.id => reservation,
            _ => self.reserve_local_request(&schema, context_tokens)?,
        };
        let model_dir = self.unified_registry.ensure_local(&schema.id).await?;
        let model_name = model_dir.display().to_string();
        let measured = backend_cache::estimate_model_size(&model_dir)
            .max(reservation.reconciled_weights_bytes());
        reservation
            .reconcile_measured_weights(measured)
            .map_err(InferenceError::from)?;
        // LOCAL_ADMISSION_BOUNDARY:supervised-vllm-mlx
        let endpoint = self
            .vllm_pool
            // `family` selects the server-side reasoning parser; without it a
            // reasoning model's chain-of-thought comes back as the answer.
            .ensure(&schema.id, &model_name, &reservation, &schema.family)
            .await
            .map_err(InferenceError::InferenceFailed)?;
        let allocation_id = resource_policy::vllm_process_allocation_id(&schema.id);
        reservation.publish_resident_weights_as(&allocation_id, measured);
        let mut schema = schema;
        schema.source = ModelSource::VllmMlx {
            endpoint,
            model_name,
        };
        Ok((schema, Some(reservation)))
    }

    /// 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.local_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 catalog_registry_snapshot(&self) -> UnifiedRegistry {
        let mut registry = self.unified_registry.clone();
        // Startup/list/setup/health refreshes physical runtimes and local
        // weights, but credential-backed rows use environment presence or the
        // non-secret authority hint only.
        registry.refresh_availability();
        self.filter_disabled_local_models(&mut registry);
        registry
    }

    fn filter_disabled_local_models(&self, registry: &mut UnifiedRegistry) {
        let disabled = registry
            .all()
            .filter(|schema| {
                schema.downloads_weights()
                    && !self
                        .model_management
                        .car_enabled(&schema.id)
                        .unwrap_or(false)
            })
            .map(|schema| schema.id.clone())
            .collect::<Vec<_>>();
        for model_id in disabled {
            registry.unregister(&model_id);
        }
    }

    async fn routing_registry_snapshot_with_credential_failure(
        &self,
    ) -> (UnifiedRegistry, Option<RouteCredentialFailure>) {
        // The first explicit route/use is allowed to establish credential
        // truth. Parslee goes through Task 2's process-owned coordinator;
        // denial/cooldown remains distinct from an authoritative signed-out
        // result so passive observations are never cleared by an unreadable
        // Keychain.
        let parslee = car_auth::resolve_credential(car_auth::CredentialReadMode::Use).await;
        let (parslee_api_base, parslee_signed_out, credential_failure) = match &parslee {
            Ok(Some(credential)) => (Some(credential.api_base.as_str()), false, None),
            Ok(None) => (None, true, Some(parslee_signed_out_route_failure())),
            Err(error) => {
                let source_error = error.to_string();
                (
                    None,
                    false,
                    Some(RouteCredentialFailure {
                        summary: format!(
                            "Parslee {AUTH_STORE_UNREADABLE_MARKER} — unlock or grant access to the credential store, then retry"
                        ),
                        source_error,
                    }),
                )
            }
        };
        let mut registry = self.unified_registry.clone();
        registry.refresh_routing_availability(parslee_api_base, parslee_signed_out);
        self.filter_disabled_local_models(&mut registry);
        (registry, credential_failure)
    }

    async fn routing_registry_snapshot(&self) -> UnifiedRegistry {
        self.routing_registry_snapshot_with_credential_failure()
            .await
            .0
    }

    /// An explicit model does not need a global provider-credential sweep to
    /// be routed. Its backend resolves only its own credential at dispatch;
    /// local and external-runtime models resolve none. This keeps unrelated OS
    /// keychain latency off the managed-runtime admission and startup path.
    async fn request_routing_registry_snapshot(
        &self,
        requested_model: Option<&str>,
    ) -> UnifiedRegistry {
        if requested_model.is_some() {
            self.catalog_registry_snapshot()
        } else {
            self.routing_registry_snapshot().await
        }
    }

    /// 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`] — 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 {
        if let Some(model) = self.preferred_model_for_capability(ModelCapability::Generate) {
            let exclude_set = self
                .adaptive_router
                .build_exclude_set(intent.as_ref(), &self.unified_registry);
            let overridden_is_excluded =
                Self::model_is_excluded(&exclude_set, &self.unified_registry, model);
            if !overridden_is_excluded {
                // Preferred-model routing never consulted refreshed
                // availability or credentials: it returned the configured
                // override either way. Read its context directly and avoid a
                // global credential/keychain sweep that cannot affect this
                // decision (and took ~182s in a scratch HOME).
                let ctx_len = self
                    .unified_registry
                    .get(model)
                    .or_else(|| self.unified_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 routing_registry = self.routing_registry_snapshot().await;
        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 passive catalog snapshot ONLY when there is an id to look
        // up (car-releases#75). It refreshes local weights/runtime readiness
        // plus non-secret environment/authority hints; it performs no secret
        // store reads. All three in-crate callers pass `model_id: None`, so
        // constructing and discarding even that snapshot would be unnecessary;
        // the `and_then` short-circuits on None and `context_window` is 0 either
        // way. Request-time routing establishes authoritative credential truth
        // separately through `routing_registry_snapshot`.
        let context_window = match model_id {
            Some(id) => {
                let routing_registry = self.catalog_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.catalog_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> {
        crate::offload::ensure_not_controlled_terminated()?;
        let catalog_snapshot = self
            .catalog_snapshot()
            .map_err(InferenceError::InferenceFailed)?;
        let recover = matches!(req.params.thinking, ThinkingMode::Auto);
        let mut result = self
            .generate_tracked_inner(req.clone(), &catalog_snapshot)
            .await?;

        let action = classify_empty_pass(
            recover,
            result.stop_reason.as_deref(),
            &result.text,
            result.tool_calls.is_empty(),
        );
        let hit_decode_ceiling = action == EmptyPassAction::FailDecodeCeiling;

        if action == EmptyPassAction::RetryWithoutThinking {
            result.stop_reason = Some("thinking_truncated".to_string());
            let mut retry = req;
            retry.params.thinking = ThinkingMode::Off;
            crate::offload::ensure_not_controlled_terminated()?;
            match self.generate_tracked_inner(retry, &catalog_snapshot).await {
                Ok(mut recovered) => {
                    if !recovered.text.trim().is_empty() || !recovered.tool_calls.is_empty() {
                        recovered.stop_reason = Some("thinking_recovered".to_string());
                        return Ok(recovered);
                    }
                }
                Err(error @ InferenceError::ControlledTermination) => return Err(error),
                Err(_) => {}
            }
        }

        // A ceiling stop that produced nothing usable is a FAILED turn, and it
        // has to read like one. Returning `Ok` with empty text hands the caller
        // a turn it cannot act on: `car do` printed nothing and exited 0, which
        // is the same silence car#851 was reported for, just bounded. Partial
        // text still comes back as `Ok` — it is worth something to the caller.
        if hit_decode_ceiling && result.text.trim().is_empty() && result.tool_calls.is_empty() {
            return Err(InferenceError::InferenceFailed(format!(
                "local generation hit its {}s wall-clock ceiling before producing any output. \
                 The `local prefill starting` / `local decode in progress` log lines show where \
                 the time went — a large prompt can spend most of it on prefill. Try a smaller \
                 model, shorten the prompt, check for another process contending for the GPU, \
                 or raise the ceiling with CAR_LOCAL_DECODE_TIMEOUT_SECS (0 disables it).",
                local_decode_timeout().map_or(0, |t| t.as_secs())
            )));
        }

        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,
        mut req: GenerateRequest,
        catalog_snapshot: &CatalogSnapshot,
    ) -> Result<InferenceResult, InferenceError> {
        crate::offload::ensure_not_controlled_terminated()?;
        validate_expected_catalog_revision(&req, catalog_snapshot)?;
        let requested_model_id = exact_pinned_model_id(&req).map(str::to_string);
        if let Some(model_id) = requested_model_id.as_ref() {
            req.model = Some(model_id.clone());
            req.params.strict_model = true;
        }
        let start = Instant::now();
        let has_requested_route = req.model.is_some();
        let (routing_registry, initial_route_credential_failure) = if has_requested_route {
            (self.catalog_registry_snapshot(), None)
        } else {
            self.routing_registry_snapshot_with_credential_failure()
                .await
        };
        if let Some(requested) = requested_model_id.as_deref() {
            if routing_registry.get(requested).is_none() {
                return Err(InferenceError::ModelNotFound(requested.to_string()));
            }
        } else 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 exclude_set = self
            .adaptive_router
            .build_exclude_set(req.intent.as_ref(), &routing_registry);
        let unpinned_override = self
            .lane_pin_for(&req, &routing_registry)
            .or(preferred_model)
            .filter(|model| !Self::model_is_excluded(&exclude_set, &routing_registry, model));
        let decision = match req.model.clone().or(unpinned_override) {
            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.model_id.is_empty() {
            let excluded_models = req
                .intent
                .as_ref()
                .map(|hint| hint.exclude_models.join(", "))
                .unwrap_or_default();
            return Err(InferenceError::NoEligibleModel { excluded_models });
        }

        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) —
        // except for models decoded in-process, where the budget is wall clock.
        // See `resolved_max_tokens` (car#851).
        if let Some(schema) = routing_registry
            .get(&decision.model_id)
            .or_else(|| routing_registry.find_by_name(&decision.model_id))
        {
            req.params.max_tokens = resolved_max_tokens(req.params.max_tokens, schema);
        }

        // 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)
        });
        let mut local_last_resort_id = None;
        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.clone());
                local_last_resort_id = Some(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;
        // The FIRST candidate whose credential was rejected (401/403/expired),
        // remembered so a later candidate's success can announce the degrade
        // rather than quietly serving a different model (Parslee-ai/car#888).
        // Only meaningful when the chain goes on to succeed — an exhausted
        // chain already surfaces `auth_expired_recovery_hint`.
        let mut auth_dead_lane: Option<String> = None;
        // Unlike `auth_dead_lane` (success-path degrade metadata), this holds
        // the human-actionable cause for an exhausted chain. Each later
        // configured/attempted credential failure replaces an earlier one;
        // ambient missing-variable noise from unconfigured fallback providers
        // is ignored. The routing snapshot's signed-out / store-unreadable
        // pre-seed only survives when a Parslee route is actually part of this
        // chain. Another provider's outage or a local OOM cannot be repaired
        // with the Parslee login; actual provider auth failures below still
        // replace this slot regardless of which providers were selected.
        let mut route_credential_failure = if chain_includes_parslee_route(
            |m| {
                routing_registry
                    .get(m)
                    .or_else(|| routing_registry.find_by_name(m))
            },
            &models_to_try,
        ) {
            initial_route_credential_failure
        } else {
            None
        };
        // Every skipped lane, not only the auth-rejected one. This ordered
        // history stays separate from both credential slots — see
        // `InferenceResult::fallback_from`.
        let mut fallback_hops: Vec<FallbackFrom> = Vec::new();

        // 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() {
            crate::offload::ensure_not_controlled_terminated()?;
            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 legacy explicit-model
            // path (`req.model` set), which bypasses the router entirely. An
            // exact immutable `model_id` pin must dispatch the named row and
            // therefore deliberately bypasses this compatibility substitution.
            #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
            if requested_model_id.is_none() {
                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());
                    }
                }
            }

            // Bound before the capability guard below so a candidate skipped
            // there can be named in the fallback hop list — that guard is the
            // one capability mismatch car#1351 calls out, and it is reachable
            // by the two paths its own comment names.
            let candidate_name = schema
                .as_ref()
                .map(|s| s.name.clone())
                .unwrap_or_else(|| candidate_id.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"
                );
                let unsupported = 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)",
                };
                // Recorded: this is the capability mismatch car#1351 names by
                // hand, and the guard's own comment above says it is reachable
                // — the explicit-model path bypasses the router's filter and
                // the cold-start last resort can hand back a default without
                // ToolUse.
                record_fallback_from(&mut fallback_hops, &candidate_name, &unsupported);
                last_error = Some(unsupported);
                continue;
            }

            // 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 reported_model_used = if requested_model_id.is_some() {
                resolved_id.clone()
            } else {
                candidate_name.clone()
            };
            validate_expected_catalog_row(&req, catalog_snapshot, &resolved_id)?;

            // An exact immutable id is an identity contract, not a request for
            // the nearest runnable implementation. Candle/GGUF execution is
            // disabled on Apple Silicon; fail before the worker boundary
            // instead of sending a legacy plain-model request that the worker
            // could silently redirect to the MLX twin.
            #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
            if requested_model_id.is_some()
                && schema
                    .as_ref()
                    .is_some_and(|schema| matches!(schema.source, ModelSource::Local { .. }))
            {
                let pinned = InferenceError::InferenceFailed(format!(
                    "exact model_id `{resolved_id}` names a GGUF/Candle row, but Candle is disabled on Apple Silicon; MLX-equivalent substitution is disabled for exact pins"
                ));
                record_fallback_from(&mut fallback_hops, &candidate_name, &pinned);
                last_error = Some(pinned);
                continue;
            }

            let is_remote = schema
                .as_ref()
                .map(|s| s.is_remote() || s.is_vllm_mlx())
                .unwrap_or(false);
            let is_codex_cli = schema.as_ref().map(|s| s.is_codex_cli()).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);
                        let unregistered = InferenceError::InferenceFailed(msg.into());
                        record_fallback_from(&mut fallback_hops, &candidate_name, &unregistered);
                        last_error = Some(unregistered);
                        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 = AbortOnDropTask(Some(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.join().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,
                            );
                        }
                        let local_last_resort = report_local_last_resort_served(
                            local_last_resort_id.as_deref(),
                            candidate_id,
                            &resolved_id,
                        );
                        return Ok(InferenceResult {
                            text: acc_text,
                            tool_calls: acc_tool_calls,
                            bounding_boxes: vec![],
                            trace_id: attempt_trace,
                            model_used: reported_model_used,
                            model_identity: bound_model_identity(
                                catalog_snapshot,
                                requested_model_id.as_deref(),
                                &resolved_id,
                            )?,
                            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,
                            auth_fallback_from: auth_dead_lane.clone(),
                            local_last_resort,
                            fallback_from: fallback_hops.clone(),
                        });
                    }
                    Ok(Err(e)) => {
                        self.outcome_tracker
                            .write()
                            .await
                            .record_failure(&attempt_trace, &e.to_string());
                        // Same bookkeeping as the main per-candidate failure arm
                        // below: a REJECTED credential here is a dead lane, and a
                        // later candidate's success must be able to say so.
                        // Classified from the SAME value that becomes
                        // `last_error`, so both failure records and the error
                        // the caller sees cannot describe different failures.
                        let failed = InferenceError::InferenceFailed(e.to_string());
                        record_auth_dead_lane(
                            &mut auth_dead_lane,
                            &candidate_name,
                            &failed.to_string(),
                        );
                        record_route_credential_failure(
                            &mut route_credential_failure,
                            &candidate_name,
                            &failed,
                            was_primary && has_requested_route,
                        );
                        record_fallback_from(&mut fallback_hops, &candidate_name, &failed);
                        last_error = Some(failed);
                        continue;
                    }
                    Err(join_err) => {
                        let msg = format!("runner task panicked: {join_err}");
                        self.outcome_tracker
                            .write()
                            .await
                            .record_failure(&attempt_trace, &msg);
                        // Recorded too: a panicked runner skips this candidate
                        // and the chain proceeds to a different backbone, which
                        // is a transition like any other. The arm above records
                        // and this one did not — two adjacent skips, one
                        // bookkeeping (linus review, car#1351).
                        let failed = InferenceError::InferenceFailed(msg);
                        record_fallback_from(&mut fallback_hops, &candidate_name, &failed);
                        last_error = Some(failed);
                        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();
            // LOCAL_ADMISSION_BOUNDARY:adaptive-local-dispatch
            // Reserve before either the in-process loader or the daemon-owned
            // worker receives the request. Explicit selections fail here and
            // never silently substitute another model; adaptive routing may
            // skip a blocked local candidate and records the reason.
            let mut local_reservation = if !is_delegated {
                match schema
                    .as_ref()
                    .filter(|schema| Self::reserve_in_outer_dispatch(schema))
                {
                    Some(local_schema) => {
                        match self.reserve_local_request(local_schema, estimated_footprint) {
                            Ok(reservation) => Some(reservation),
                            Err(error) if req.model.is_some() || req.params.strict_model => {
                                self.outcome_tracker
                                    .write()
                                    .await
                                    .record_capability_rejection(
                                        &attempt_trace,
                                        &error.to_string(),
                                    );
                                return Err(error);
                            }
                            Err(error) => {
                                tracing::warn!(
                                    model = %local_schema.id,
                                    error = %error,
                                    "adaptive local candidate blocked by resource policy; trying next route"
                                );
                                self.outcome_tracker
                                    .write()
                                    .await
                                    .record_capability_rejection(
                                        &attempt_trace,
                                        &error.to_string(),
                                    );
                                // A capability mismatch skips this candidate
                                // and the chain proceeds to a different
                                // backbone — a transition like any other, and
                                // one car#1351 names by hand.
                                record_fallback_from(&mut fallback_hops, &candidate_name, &error);
                                last_error = Some(error);
                                continue;
                            }
                        }
                    }
                    None => None,
                }
            } else {
                None
            };
            let result = if is_codex_cli {
                let schema_ref = schema
                    .as_ref()
                    .ok_or_else(|| InferenceError::ModelNotFound(candidate_id.clone()))?;
                if req.tools.as_ref().is_some_and(|tools| !tools.is_empty()) {
                    Err(InferenceError::UnsupportedMode {
                        mode: "tools",
                        backend: "codex-cli",
                        reason: "the subscription-backed Codex source is a side-effect-free text generator and does not accept tools",
                    })
                } else if req
                    .messages
                    .as_ref()
                    .is_some_and(|messages| !messages.is_empty())
                {
                    Err(InferenceError::UnsupportedMode {
                        mode: "multi-turn-messages",
                        backend: "codex-cli",
                        reason: "the subscription-backed Codex source accepts one prompt plus optional context; it does not resume or replay conversations",
                    })
                } else if req.images.as_ref().is_some_and(|images| !images.is_empty())
                    || Self::request_has_video(&req)
                    || Self::request_has_audio(&req)
                {
                    Err(InferenceError::UnsupportedMode {
                        mode: "multimodal-content",
                        backend: "codex-cli",
                        reason: "the subscription-backed Codex source is text-only",
                    })
                } else if req.response_format.is_some() {
                    Err(InferenceError::UnsupportedMode {
                        mode: "response-format",
                        backend: "codex-cli",
                        reason: "the subscription-backed Codex source returns plain text and does not expose provider-enforced schemas",
                    })
                } else {
                    let model = match &schema_ref.source {
                        ModelSource::CodexCli { model } => model,
                        _ => unreachable!("is_codex_cli matched a different source"),
                    };
                    crate::backend::codex_cli::generate(
                        model,
                        &req.prompt,
                        context.as_deref(),
                        req.params.max_tokens,
                        schema_ref.context_length,
                    )
                    .await
                    .map(|output| (output.text, vec![], Some(output.usage), None, None))
                }
            } else 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, _remote_request_reservation) = match self
                    .vllm_live_schema(
                        schema.unwrap(),
                        local_reservation.take(),
                        estimated_footprint,
                    )
                    .await
                {
                    Ok(pair) => pair,
                    Err(e) => {
                        self.outcome_tracker
                            .write()
                            .await
                            .record_failure(&attempt_trace, &e.to_string());
                        record_fallback_from(&mut fallback_hops, &candidate_name, &e);
                        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) = schema
                .as_ref()
                .filter(|schema| Self::supports_worker_offload(schema))
                .and_then(|_| 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());
                let schema_ref = schema
                    .as_ref()
                    .ok_or_else(|| InferenceError::ModelNotFound(resolved_id.clone()))?;
                let reservation = local_reservation.as_mut().ok_or_else(|| {
                    InferenceError::InferenceFailed(
                        "local worker dispatch missing admission reservation".into(),
                    )
                })?;
                if let Some(allocation_id) = offload.resident_allocation_id(&resolved_id) {
                    // A replacement offloader is a distinct process generation
                    // even when an older worker for the same logical model is
                    // still exiting. Reconcile against its exact owner before
                    // the child receives a load request so it cannot inherit a
                    // peer resident discount.
                    reservation.bind_allocation_id(&allocation_id);
                }
                let admission = self.prepare_worker_admission(schema_ref, reservation)?;
                match offload.generate_admitted(offload_req, admission).await {
                    Ok(outcome) => {
                        Self::reconcile_worker_residency(
                            offload.as_ref(),
                            &resolved_id,
                            &outcome.residency,
                            outcome.retention,
                            reservation,
                        )
                        .await?;
                        let ir = outcome.result;
                        // 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 model_dir = self.unified_registry.ensure_local(&schema_ref.id).await?;
                        let reservation = local_reservation
                            .as_mut()
                            .expect("local VLM branch has admission reservation");
                        Self::reconcile_transient_local_allocation(
                            reservation,
                            backend_cache::estimate_model_size(&model_dir),
                        )?;
                        let detached_lease = reservation.detached_lease();
                        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) = run_admitted_blocking(detached_lease, 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,
                            );
                        }
                        let local_last_resort = report_local_last_resort_served(
                            local_last_resort_id.as_deref(),
                            candidate_id,
                            &resolved_id,
                        );
                        return Ok(InferenceResult {
                            text,
                            tool_calls: vec![],
                            bounding_boxes,
                            trace_id: attempt_trace,
                            model_used: schema_ref.id.clone(),
                            model_identity: bound_model_identity(
                                catalog_snapshot,
                                requested_model_id.as_deref(),
                                &resolved_id,
                            )?,
                            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,
                            auth_fallback_from: auth_dead_lane.clone(),
                            local_last_resort,
                            fallback_from: fallback_hops.clone(),
                        });
                    } 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,
                            local_reservation
                                .as_mut()
                                .expect("local branch has admission reservation"),
                        )
                        .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, _retention) = self
                            .ensure_mlx_backend(
                                schema_ref,
                                local_reservation
                                    .as_mut()
                                    .expect("local branch has admission reservation"),
                            )
                            .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,
                            local_reservation
                                .as_mut()
                                .expect("local branch has admission reservation"),
                        )
                        .await
                        .map(|(text, usage, ttft, stop)| (text, vec![], usage, ttft, stop))
                    }
                }

                #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
                {
                    let schema_ref = schema
                        .as_ref()
                        .ok_or_else(|| InferenceError::ModelNotFound(candidate_id.clone()))?;
                    match self
                        .ensure_backend(
                            schema_ref,
                            local_reservation
                                .as_mut()
                                .expect("local branch has admission reservation"),
                        )
                        .await
                    {
                        Ok(()) => {
                            let mut write = self.backend.write().await;
                            let backend = write.get_mut(&schema_ref.id).ok_or_else(|| {
                                InferenceError::InferenceFailed(format!(
                                    "candle backend missing after ensure_backend for {}",
                                    schema_ref.id
                                ))
                            })?;
                            // 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);
                    let local_last_resort = report_local_last_resort_served(
                        local_last_resort_id.as_deref(),
                        candidate_id,
                        &resolved_id,
                    );
                    return Ok(InferenceResult {
                        text,
                        tool_calls,
                        bounding_boxes,
                        trace_id: attempt_trace,
                        model_used: reported_model_used,
                        model_identity: bound_model_identity(
                            catalog_snapshot,
                            requested_model_id.as_deref(),
                            &resolved_id,
                        )?,
                        latency_ms,
                        time_to_first_token_ms,
                        usage,
                        provider_output_items: captured_provider_output_items,
                        thinking: captured_thinking,
                        stop_reason,
                        auth_fallback_from: auth_dead_lane.clone(),
                        local_last_resort,
                        fallback_from: fallback_hops.clone(),
                    });
                }
                Err(e) => {
                    if matches!(e, InferenceError::ControlledTermination) {
                        self.outcome_tracker
                            .write()
                            .await
                            .record_capability_rejection(&attempt_trace, &e.to_string());
                        return Err(e);
                    }
                    tracing::warn!(
                        model = %candidate_name,
                        error = %e,
                        remaining = candidate_queue.len(),
                        "model failed, trying next fallback immediately"
                    );
                    // A candidate whose CREDENTIAL was rejected is a dead lane,
                    // not a flaky one: retrying cannot help and the human has to
                    // sign in. Remember the first such lane so a later
                    // candidate's success can announce that it degraded off it
                    // instead of silently serving a different model
                    // (Parslee-ai/car#888).
                    record_auth_dead_lane(&mut auth_dead_lane, &candidate_name, &e.to_string());
                    record_route_credential_failure(
                        &mut route_credential_failure,
                        &candidate_name,
                        &e,
                        was_primary && has_requested_route,
                    );
                    record_fallback_from(&mut fallback_hops, &candidate_name, &e);
                    // 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;
                        if write.remove(&resolved_id).is_some() {
                            self.local_admission.mark_evicted(&resolved_id);
                        }
                    }
                    // 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 error_ends_fallback_chain(&e) {
                        let dropped = candidate_queue.len();
                        candidate_queue.clear();
                        if dropped > 0 {
                            tracing::info!(
                                dropped,
                                "content refused for this request; ending the fallback chain \
                                 rather than answering with a different model"
                            );
                        }
                    }
                    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 e = apply_route_failure_context(underlying, route_credential_failure.as_ref());
        // 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
            .request_routing_registry_snapshot(req.model.as_deref())
            .await;
        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 exclude_set = self
            .adaptive_router
            .build_exclude_set(req.intent.as_ref(), &routing_registry);
        let unpinned_override = self
            .lane_pin_for(&req, &routing_registry)
            .or(preferred_model)
            .filter(|model| !Self::model_is_excluded(&exclude_set, &routing_registry, model));
        let decision = match req.model.clone().or(unpinned_override) {
            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,
                        )
                    })
            }
        };

        if decision.model_id.is_empty() {
            let excluded_models = req
                .intent
                .as_ref()
                .map(|hint| hint.exclude_models.join(", "))
                .unwrap_or_default();
            return Err(InferenceError::NoEligibleModel { excluded_models });
        }

        // `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, and so an in-process model does
        // not silently inherit a 32768-token (== tens of minutes) budget here
        // after that was fixed on the non-streaming path (car#851).
        let mut req = req;
        if let Some(schema) = schema.as_ref() {
            req.params.max_tokens = resolved_max_tokens(req.params.max_tokens, schema);
        }

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

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

        if is_codex_cli {
            return Err(InferenceError::UnsupportedMode {
                mode: "streaming",
                backend: "codex-cli",
                reason: "codex exec reports final answer items rather than token deltas; use non-streaming infer/generate_tracked",
            });
        }

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

        // LOCAL_ADMISSION_BOUNDARY:stream-local-dispatch
        let mut local_reservation =
            if !is_remote || schema.as_ref().is_some_and(ModelSchema::is_vllm_mlx) {
                schema
                    .as_ref()
                    .filter(|schema| Self::reserve_in_outer_dispatch(schema))
                    .map(|schema| self.reserve_local_request(schema, estimated_footprint))
                    .transpose()?
            } else {
                None
            };

        // 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 && schema.as_ref().is_some_and(Self::supports_worker_offload) {
            if let Some(offload) = crate::offload::current_local_offload() {
                let mut offload_req = req.clone();
                offload_req.model = Some(resolved_model_id.clone());
                let schema_ref = schema
                    .as_ref()
                    .ok_or_else(|| InferenceError::ModelNotFound(resolved_model_id.clone()))?;
                let reservation = local_reservation.as_mut().ok_or_else(|| {
                    InferenceError::InferenceFailed(
                        "local worker stream missing admission reservation".into(),
                    )
                })?;
                if let Some(allocation_id) = offload.resident_allocation_id(&resolved_model_id) {
                    reservation.bind_allocation_id(&allocation_id);
                }
                let admission = self.prepare_worker_admission(schema_ref, reservation)?;
                let offload_stream = offload.stream_admitted(offload_req, admission).await?;
                Self::reconcile_worker_residency(
                    offload.as_ref(),
                    &resolved_model_id,
                    &offload_stream.residency,
                    offload_stream.retention,
                    reservation,
                )
                .await?;
                let rx = offload_stream.events;
                let rx = match local_reservation {
                    Some(reservation) => Self::hold_local_reservation_for_stream(rx, reservation),
                    None => rx,
                };
                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, mut candidate_reservation) = match self
                    .vllm_live_schema(candidate, local_reservation.take(), estimated_footprint)
                    .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) => {
                        let receiver = Self::hold_optional_reservation_for_stream(
                            receiver,
                            candidate_reservation.take(),
                        );
                        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, _retention) = self
                    .ensure_mlx_backend(
                        &schema,
                        local_reservation
                            .as_mut()
                            .expect("local stream has admission reservation"),
                    )
                    .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);
                });
                let rx = match local_reservation {
                    Some(reservation) => Self::hold_local_reservation_for_stream(rx, reservation),
                    None => rx,
                };
                Ok((resolved_model_id, rx))
            }

            #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
            {
                self.ensure_backend(
                    &schema,
                    local_reservation
                        .as_mut()
                        .expect("local stream has admission reservation"),
                )
                .await?;
                let backend = self.backend.clone();
                let model_id = schema.id.clone();
                tokio::spawn(async move {
                    let _ = Self::stream_local_candle(backend, model_id, req, tx).await;
                });
                let rx = match local_reservation {
                    Some(reservation) => Self::hold_local_reservation_for_stream(rx, reservation),
                    None => rx,
                };
                Ok((resolved_model_id, rx))
            }
        }
    }

    /// Stream a generation and record an outcome when it finishes.
    ///
    /// Wraps [`generate_stream_raw`](crate::InferenceEngine::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<std::collections::HashMap<String, CandleBackend>>>,
        model_id: String,
        req: GenerateRequest,
        tx: tokio::sync::mpsc::Sender<stream::StreamEvent>,
    ) -> Result<(), InferenceError> {
        let mut write = backend_lock.write().await;
        let backend = write.get_mut(&model_id).ok_or_else(|| {
            InferenceError::InferenceFailed(format!("backend not initialized for {model_id}"))
        })?;
        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();

        // Same wall-clock ceiling and progress reporting the non-streaming loop
        // got in car#851. A streamed decode at least emits tokens as it goes,
        // so a client can tell it is alive — but it is reached by the daemon's
        // `infer_stream` RPC and by voice, and before this it had no bound at
        // all beyond `max_tokens`.
        let started = std::time::Instant::now();
        let timeout = local_decode_timeout();
        let heartbeat = std::time::Duration::from_secs(LOCAL_DECODE_HEARTBEAT_SECS);
        let mut last_heartbeat = std::time::Duration::ZERO;
        tracing::info!(
            prompt_tokens = tokens.len(),
            max_tokens = params.max_tokens,
            timeout_secs = timeout.map(|t| t.as_secs()),
            "local stream prefill starting"
        );

        // 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;
                }
            }

            // Deadline AFTER the push/send and the stop check, matching
            // `drive_generation_with_timeout` exactly. Checking it earlier drops
            // the token already sampled — the streamed and non-streamed partials
            // would then differ by one token for the same cut-off.
            let elapsed = started.elapsed();
            if deadline_exceeded(elapsed, timeout) {
                tracing::warn!(
                    elapsed_secs = elapsed.as_secs_f64(),
                    timeout_secs = timeout.map(|t| t.as_secs()),
                    completion_tokens = generated.len(),
                    max_tokens = params.max_tokens,
                    "local stream hit its wall-clock ceiling and was cut short; \
                     returning what was streamed so far. Raise or disable it with \
                     CAR_LOCAL_DECODE_TIMEOUT_SECS (0 disables)."
                );
                // Without this the consumer cannot tell a cut-off stream from a
                // finished one: `StreamAccumulator::was_truncated()` keys off
                // the stop reason, and the local streaming path never emitted
                // one. The daemon's `infer_stream` RPC and voice both read it.
                let _ = tx.blocking_send(stream::StreamEvent::StopReason(
                    LOCAL_DECODE_TIMEOUT_STOP_REASON.to_string(),
                ));
                break;
            }
            if heartbeat_due(elapsed, last_heartbeat, heartbeat) {
                last_heartbeat = elapsed;
                tracing::info!(
                    completion_tokens = generated.len(),
                    max_tokens = params.max_tokens,
                    elapsed_secs = elapsed.as_secs_f64(),
                    tokens_per_sec =
                        generated.len() as f64 / elapsed.as_secs_f64().max(f64::EPSILON),
                    "local stream in progress"
                );
            }

            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.catalog_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)?;
        let admission_schema = self
            .unified_registry
            .get(model)
            .or_else(|| self.unified_registry.find_by_name(model))
            .ok_or_else(|| InferenceError::ModelNotFound(model.to_string()))?
            .clone();
        // LOCAL_ADMISSION_BOUNDARY:tokenizer-encode
        let mut reservation =
            self.reserve_local_request(&admission_schema, text.len().div_ceil(4))?;

        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        {
            let schema = admission_schema;
            let (handle, _retention) = self.ensure_mlx_backend(&schema, &mut reservation).await?;
            let guard = handle.lock().map_err(|_| {
                InferenceError::InferenceFailed(format!(
                    "MLX backend mutex poisoned for {}",
                    schema.id
                ))
            })?;
            let tokens = guard.tokenize_raw(text)?;
            Ok(tokens)
        }

        #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
        {
            self.ensure_backend(&admission_schema, &mut reservation)
                .await?;
            let read = self.backend.read().await;
            let backend = read.get(&admission_schema.id).ok_or_else(|| {
                InferenceError::InferenceFailed(
                    "candle backend missing after ensure_backend".to_string(),
                )
            })?;
            let tokens = backend.tokenize_raw(text)?;
            Ok(tokens)
        }
    }

    /// 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)?;
        let admission_schema = self
            .unified_registry
            .get(model)
            .or_else(|| self.unified_registry.find_by_name(model))
            .ok_or_else(|| InferenceError::ModelNotFound(model.to_string()))?
            .clone();
        // LOCAL_ADMISSION_BOUNDARY:tokenizer-decode
        let mut reservation = self.reserve_local_request(&admission_schema, tokens.len())?;

        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        {
            let schema = admission_schema;
            let (handle, _retention) = self.ensure_mlx_backend(&schema, &mut reservation).await?;
            let guard = handle.lock().map_err(|_| {
                InferenceError::InferenceFailed(format!(
                    "MLX backend mutex poisoned for {}",
                    schema.id
                ))
            })?;
            let text = guard.detokenize_raw(tokens)?;
            Ok(text)
        }

        #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
        {
            self.ensure_backend(&admission_schema, &mut reservation)
                .await?;
            let read = self.backend.read().await;
            let backend = read.get(&admission_schema.id).ok_or_else(|| {
                InferenceError::InferenceFailed(
                    "candle backend missing after ensure_backend".to_string(),
                )
            })?;
            let text = backend.detokenize_raw(tokens)?;
            Ok(text)
        }
    }

    /// 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> {
        Self::drive_generation_with_timeout(backend, prompt, params, local_decode_timeout())
    }

    /// `drive_generation`(Self::drive_generation) with the wall-clock ceiling
    /// passed in rather than read from the environment, so the deadline is
    /// testable without mutating process-global state from a test thread.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    fn drive_generation_with_timeout(
        backend: &mut dyn backend::local::TextDecoder,
        prompt: &str,
        params: &GenerateParams,
        timeout: Option<std::time::Duration>,
    ) -> 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();

        // Announce BEFORE prefill, not after. Prefill is a single MLX forward
        // over the whole prompt and nothing can interrupt it — on a large model
        // with an agent's tools block it is tens of seconds on its own. Logging
        // only after it would leave exactly the window car#851 was reported for
        // still silent, and would let a prefill stall masquerade as a slow
        // decode.
        tracing::info!(
            prompt_tokens = tokens.len(),
            max_tokens = params.max_tokens,
            timeout_secs = timeout.map(|t| t.as_secs()),
            "local prefill starting"
        );

        // 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);

        // The loop below is silent for its whole duration, which is what made a
        // 24-minute decode indistinguishable from a wedged process in car#851.
        // This line alone would have exposed the real budget: the tracing span
        // records `max_tokens` at entry, BEFORE the routing layer widens it.
        tracing::info!(
            prompt_tokens = tokens.len(),
            max_tokens = params.max_tokens,
            prefill_ms = ttft_ms,
            timeout_secs = timeout.map(|t| t.as_secs()),
            "local decode starting"
        );

        // Track why the loop ended: a natural EOS / stop-sequence finish, the
        // max_tokens budget (truncation), or the wall-clock ceiling.
        let mut natural_stop = false;
        let mut timed_out = false;
        let heartbeat = std::time::Duration::from_secs(LOCAL_DECODE_HEARTBEAT_SECS);
        let mut last_heartbeat = std::time::Duration::ZERO;
        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 elapsed = start.elapsed();
            if deadline_exceeded(elapsed, timeout) {
                timed_out = true;
                break;
            }
            if heartbeat_due(elapsed, last_heartbeat, heartbeat) {
                last_heartbeat = elapsed;
                tracing::info!(
                    completion_tokens = generated.len(),
                    max_tokens = params.max_tokens,
                    elapsed_secs = elapsed.as_secs_f64(),
                    tokens_per_sec =
                        generated.len() as f64 / elapsed.as_secs_f64().max(f64::EPSILON),
                    "local decode in progress"
                );
            }

            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 elapsed = start.elapsed();
        let tokens_per_sec = generated.len() as f64 / elapsed.as_secs_f64().max(f64::EPSILON);
        if timed_out {
            tracing::warn!(
                elapsed_secs = elapsed.as_secs_f64(),
                timeout_secs = timeout.map(|t| t.as_secs()),
                completion_tokens = generated.len(),
                max_tokens = params.max_tokens,
                tokens_per_sec,
                "local decode hit its wall-clock ceiling and was cut short; \
                 returning the partial response. Raise or disable it with \
                 CAR_LOCAL_DECODE_TIMEOUT_SECS (0 disables)."
            );
        } else {
            tracing::info!(
                elapsed_secs = elapsed.as_secs_f64(),
                completion_tokens = generated.len(),
                max_tokens = params.max_tokens,
                tokens_per_sec,
                natural_stop,
                "local decode finished"
            );
        }

        let decoded = backend
            .decode(&generated)
            .map_err(DriveError::Recoverable)?;
        let text = tasks::generate::truncate_at_stop(&decoded, &params.stop);
        let stop_reason = Some(
            if timed_out {
                LOCAL_DECODE_TIMEOUT_STOP_REASON
            } else 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,
    /// `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) — and [`LOCAL_DECODE_TIMEOUT_STOP_REASON`]
    /// (`"local_decode_timeout"`) when the wall-clock decode ceiling cut it
    /// short (car#851).
    async fn generate_mlx(
        &self,
        req: GenerateRequest,
        model_id: &str,
        reservation: &mut resource_policy::LocalLoadReservation,
    ) -> 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, _retention) = self.ensure_mlx_backend(&schema, reservation).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 formatted = tasks::generate::render_chat_prompt(&req);
        let params = req.params.clone();
        let model_id = model_id.to_string();
        let cache = self.mlx_backends.clone();
        let device_guard = Self::mlx_device_lock().lock_owned().await;
        let detached_lease = reservation.detached_lease();

        // MLX prefill/decode is synchronous native work. Keep both the device
        // guard and the request's exact machine charge inside the blocking
        // closure: the Tokio runtime remains available for the raw WebSocket
        // cancel/deadline response, and abandoning that waiter cannot advertise
        // capacity while native work is still finishing.
        run_admitted_blocking(detached_lease, move || {
            let _device_guard = device_guard;
            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 ctx_window = backend.context_length() as u64;
            match Self::drive_generation(backend, &formatted, &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,
                        ..Default::default()
                    };
                    Ok((gen.text, Some(usage), gen.ttft_ms, gen.stop_reason))
                }
                Err(backend::local::DriveError::Recoverable(error)) => Err(error),
                Err(backend::local::DriveError::BackendCorrupted(error)) => {
                    drop(guard);
                    cache.invalidate(&model_id);
                    Err(error)
                }
            }
        })
        .await
        .map_err(|error| {
            InferenceError::InferenceFailed(format!("native MLX task panicked: {error}"))
        })?
    }

    /// 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,
        reservation: &mut resource_policy::LocalLoadReservation,
    ) -> 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, _retention) = self.ensure_local_backend(&schema, reservation).await?;
        let params = req.params.clone();
        let model_id = model_id.to_string();
        let cache = self.local_backends.clone();
        let device_guard = Self::mlx_device_lock().lock_owned().await;
        let detached_lease = reservation.detached_lease();

        run_admitted_blocking(detached_lease, move || {
            let _device_guard = device_guard;
            let mut guard = handle.lock().map_err(|_| {
                InferenceError::InferenceFailed(format!(
                    "local backend mutex poisoned for {model_id}"
                ))
            })?;
            let formatted = guard.render_prompt(&req)?;
            let backend: &mut dyn backend::local::TextDecoder = &mut **guard;
            let outcome = Self::drive_generation(backend, &formatted, &params);
            match outcome {
                Ok(gen) => {
                    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,
                        ..Default::default()
                    };
                    Ok((clean, tool_calls, Some(usage), gen.ttft_ms, gen.stop_reason))
                }
                Err(backend::local::DriveError::Recoverable(error)) => Err(error),
                Err(backend::local::DriveError::BackendCorrupted(error)) => {
                    drop(guard);
                    cache.invalidate(&model_id);
                    Err(error)
                }
            }
        })
        .await
        .map_err(|error| {
            InferenceError::InferenceFailed(format!("native local task panicked: {error}"))
        })?
    }

    /// 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");
        let embedding_model = self
            .preferred_model_for_capability(ModelCapability::Embed)
            .unwrap_or(&self.config.embedding_model);
        let admission_schema = self
            .unified_registry
            .get(embedding_model)
            .or_else(|| self.unified_registry.find_by_name(embedding_model))
            .ok_or_else(|| InferenceError::ModelNotFound(embedding_model.to_string()))?
            .clone();
        let estimated_tokens = req.texts.iter().map(|text| text.len().div_ceil(4)).sum();
        // LOCAL_ADMISSION_BOUNDARY:embedding-dispatch
        let mut reservation = self.reserve_local_request(&admission_schema, estimated_tokens)?;

        #[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, _retention) = self.ensure_mlx_backend(&schema, &mut reservation).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(&mut reservation).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,
                expected_row_digest: None,
                expected_catalog_revision: 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,
            expected_row_digest: None,
            expected_catalog_revision: 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
            }
        };
        let schema = self
            .unified_registry
            .get(&model)
            .or_else(|| self.unified_registry.find_by_name(&model))
            .ok_or_else(|| InferenceError::ModelNotFound(model.clone()))?
            .clone();

        if !schema.is_local() {
            return self.classify_via_generate(req, &schema.id).await;
        }

        // 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))))]
        {
            // LOCAL_ADMISSION_BOUNDARY:candle-classify
            let mut reservation =
                self.reserve_local_request(&schema, req.text.len().div_ceil(4))?;
            self.ensure_backend(&schema, &mut reservation).await?;
            let mut write = self.backend.write().await;
            let backend = write.get_mut(&schema.id).ok_or_else(|| {
                InferenceError::InferenceFailed(format!(
                    "candle backend missing after ensure_backend for {}",
                    schema.id
                ))
            })?;
            let result = tasks::classify::classify(backend, req).await?;
            Ok(result)
        }
    }

    /// Classify by routing through the main generate path (remote providers on
    /// every platform; native MLX on Apple Silicon).
    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,
            expected_row_digest: None,
            expected_catalog_revision: 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;
        let mut local_resource_block = None;

        for schema in candidates {
            // LOCAL_ADMISSION_BOUNDARY:speech-stt-dispatch
            let mut reservation = match self.admit_speech_candidate(&schema, req.model.is_some()) {
                SpeechCandidateAdmission::Proceed(reservation) => reservation,
                SpeechCandidateAdmission::SkipBlocked(error) => {
                    local_resource_block = Some(error.to_string());
                    last_error = Some(error);
                    continue;
                }
                SpeechCandidateAdmission::FailBlocked(error) => return Err(error),
            };
            let result = match &schema.source {
                ModelSource::Mlx { .. } => {
                    self.transcribe_local_mlx(&schema, &req, reservation.as_mut())
                        .await
                }
                ModelSource::WhisperCpp { model } => {
                    self.transcribe_whisper(&schema, model, &req, reservation.as_mut())
                        .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(mut result) => {
                    if matches!(schema.source, ModelSource::Proprietary { .. }) {
                        if let Some(reason) = local_resource_block.take() {
                            result.routing_explanation = Some(format!(
                                "Local speech recognition was blocked ({reason}); CAR routed to a remote provider, which may affect privacy and cost."
                            ));
                        }
                    }
                    return Ok(result);
                }
                Err(err) if req.model.is_some() => return Err(err),
                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;
        let mut local_resource_block = None;

        for schema in candidates {
            // LOCAL_ADMISSION_BOUNDARY:speech-tts-dispatch
            let mut reservation = match self.admit_speech_candidate(&schema, req.model.is_some()) {
                SpeechCandidateAdmission::Proceed(reservation) => reservation,
                SpeechCandidateAdmission::SkipBlocked(error) => {
                    local_resource_block = Some(error.to_string());
                    last_error = Some(error);
                    continue;
                }
                SpeechCandidateAdmission::FailBlocked(error) => return Err(error),
            };
            let result = match &schema.source {
                ModelSource::Mlx { .. } => {
                    self.synthesize_local_mlx(&schema, &req, reservation.as_mut())
                        .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(mut result) => {
                    if matches!(schema.source, ModelSource::Proprietary { .. }) {
                        if let Some(reason) = local_resource_block.take() {
                            result.routing_explanation = Some(format!(
                                "Local speech synthesis was blocked ({reason}); CAR routed to a remote provider, which may affect privacy and cost."
                            ));
                        }
                    }
                    return Ok(result);
                }
                Err(err) if req.model.is_some() => return Err(err),
                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(),
                routing_explanation: None,
            })
        }
        #[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 on what the native backend can actually load, not on an env
        // toggle. `mlx_flux` implements the Flux.1-lite architecture and reached
        // prompt-faithful parity with mflux (parity harness in
        // tools/parity/ref_flux.py + diff_flux_blocks.py), so it serves that
        // checkpoint. Every other architecture — FLUX.2, Krea 2, Qwen-Image,
        // Z-Image, Fibo — has no Rust implementation and goes to mflux.
        //
        // This is the same rule the text path uses (`backend::local::
        // has_native_backend`): the model decides the backend. The previous
        // `CAR_IMAGE_BACKEND` env toggle existed for A/B comparison *during* the
        // parity migration; that migration completed, and a toggle outliving its
        // purpose is exactly the "works for me but not for you" failure mode
        // CLAUDE.md's no-flags rule exists to prevent. It also defaulted to
        // native unconditionally, so asking for FLUX.2 silently got a backend
        // that cannot load it.
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        {
            use crate::backend::external_flux;
            let use_external = !external_flux::native_backend_serves(req.model.as_deref());
            if use_external {
                tracing::info!(
                    model = req.model.as_deref().unwrap_or("<default>"),
                    "no native Rust implementation for this image architecture; routing to mflux"
                );
                let schema = self
                    .media_generation_candidates(
                        ModelCapability::ImageGeneration,
                        req.model.as_deref(),
                    )?
                    .into_iter()
                    .next()
                    .ok_or_else(|| {
                        InferenceError::InferenceFailed(
                            "no image generation models available".into(),
                        )
                    })?;
                // LOCAL_ADMISSION_BOUNDARY:image-external-subprocess
                let mut reservation = self.reserve_local_request(&schema, 0)?;
                let model_dir = self.unified_registry.ensure_local(&schema.id).await?;
                reservation
                    .reconcile_measured_weights(backend_cache::estimate_model_size(&model_dir))
                    .map_err(InferenceError::from)?;
                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 {
            // LOCAL_ADMISSION_BOUNDARY:image-dispatch
            #[cfg_attr(
                not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))),
                allow(unused_mut, unused_variables)
            )]
            let mut reservation = self.reserve_local_request(&schema, 0)?;
            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, &mut reservation)
                        .await
                }
                _ => Err(InferenceError::InferenceFailed(format!(
                    "image generation not implemented for model source: {}",
                    schema.id
                ))),
            };

            match result {
                Ok(result) => return Ok(result),
                Err(err) if req.model.is_some() => return Err(err),
                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,
        reservation: &mut resource_policy::LocalLoadReservation,
    ) -> Result<GenerateImageResult, InferenceError> {
        let model_dir = self.unified_registry.ensure_local(&schema.id).await?;
        let size = backend_cache::estimate_model_size(&model_dir);
        // LOCAL_ADMISSION_BOUNDARY:image-dispatch
        let (handle, _retention) = Self::load_backend_healing(
            &schema.id,
            model_dir,
            &self.flux_cache,
            size,
            reservation,
            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,
        reservation: &mut resource_policy::LocalLoadReservation,
    ) -> Result<GenerateVideoResult, InferenceError> {
        let model_dir = self.unified_registry.ensure_local(&schema.id).await?;
        let size = backend_cache::estimate_model_size(&model_dir);
        // LOCAL_ADMISSION_BOUNDARY:video-dispatch
        let (handle, _retention) = Self::load_backend_healing(
            &schema.id,
            model_dir,
            &self.ltx_cache,
            size,
            reservation,
            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.
        let candidates = self
            .media_generation_candidates(ModelCapability::VideoGeneration, req.model.as_deref())?;
        let mut last_error = None;

        for schema in candidates {
            // LOCAL_ADMISSION_BOUNDARY:video-dispatch
            let mut reservation = self.reserve_local_request(&schema, 0)?;
            let model_dir = self.unified_registry.ensure_local(&schema.id).await?;
            reservation
                .reconcile_measured_weights(backend_cache::estimate_model_size(&model_dir))
                .map_err(InferenceError::from)?;
            let result = match &schema.source {
                #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
                ModelSource::Mlx { hf_repo, .. } => {
                    // The native Rust LTX port reaches quality parity with
                    // upstream `ltx-2-mlx` (#40 / #45), so it serves ordinary
                    // generation. The one thing it genuinely cannot do is
                    // audio-reference conditioning, which only the external
                    // `ltx-2-mlx a2v` CLI implements — that is a capability
                    // difference, not a preference, so it is what decides here.
                    //
                    // The former `CAR_VIDEO_BACKEND` toggle existed to A/B the
                    // port against the CLI while it reached parity. Parity
                    // landed and the toggle outlived it, leaving a runtime knob
                    // that silently changed which engine ran — the "works for
                    // me but not for you" failure mode CLAUDE.md's no-flags rule
                    // exists to prevent.
                    let 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, &mut reservation)
                            .await
                    }
                }
                _ => Err(InferenceError::InferenceFailed(format!(
                    "video generation not implemented for model source: {}",
                    schema.id
                ))),
            };

            match result {
                Ok(result) => return Ok(result),
                Err(err) if req.model.is_some() => return Err(err),
                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).
    /// Why `model` cannot honor a `response_format`, or `None` when it can
    /// (or is unknown here). Asks the SAME protocol handler the remote path
    /// consults (`ProtocolHandler::supports_response_format`) so a CLI can
    /// warn before a run rather than discover the `UnsupportedMode` on the
    /// repair turn. The Parslee gateway rejects every format separately in
    /// `execute_request`, so it is named here too.
    pub fn response_format_rejection_reason(
        &self,
        model: &str,
        rf: &crate::tasks::generate::ResponseFormat,
    ) -> Option<String> {
        let registry = self.unified_registry.clone();
        let schema = registry
            .list()
            .into_iter()
            .find(|s| s.id == model || s.name == model)?;
        match &schema.source {
            ModelSource::Proprietary { .. } => {
                Some("the Parslee gateway does not accept response_format".to_string())
            }
            ModelSource::RemoteApi { protocol, .. } => {
                let handler = crate::protocol::handler_for(*protocol);
                (!handler.supports_response_format(rf)).then(|| {
                    format!(
                        "the {} protocol rejects response_format",
                        handler.protocol_name()
                    )
                })
            }
            _ => None,
        }
    }

    /// The unified catalog, annotated for the machine this engine runs on
    /// under its active local-model resource policy — the same policy
    /// `models.preflight` admits against, kept in step with the persisted
    /// one by `apply_local_resource_policy`.
    pub fn list_models_unified(&self) -> Vec<ModelInfo> {
        let hardware = HardwareInfo::detect();
        let policy = self.active_local_resource_policy();
        self.list_models_unified_for(&hardware, &policy.policy)
    }

    /// The fit annotation for one schema on this machine under the active
    /// policy — `list_models_unified`'s verdict for a row built elsewhere
    /// (`models.search`), so every catalog surface publishes the same one.
    pub fn model_fit(&self, schema: &ModelSchema) -> recommend::ModelFit {
        recommend::model_fit(
            schema,
            &HardwareInfo::detect(),
            Some(&self.active_local_resource_policy().policy),
        )
    }

    /// [`Self::list_models_unified`] against explicit hardware and policy.
    /// Every row is returned in registry order with every existing field
    /// unchanged; the fit annotation is computed per call and never stored.
    pub fn list_models_unified_for(
        &self,
        hardware: &HardwareInfo,
        policy: &resource_policy::ResourcePolicy,
    ) -> Vec<ModelInfo> {
        let mut registry = self.unified_registry.clone();
        registry.refresh_availability();
        registry
            .list()
            .iter()
            .map(|schema| {
                let mut info = ModelInfo::from(*schema).with_fit(recommend::model_fit(
                    schema,
                    hardware,
                    Some(policy),
                ));
                if schema.downloads_weights() {
                    let enabled = self
                        .model_management
                        .car_enabled(&schema.id)
                        .unwrap_or(false);
                    if !enabled {
                        // `weights_ready` remains a physical diagnostic, but
                        // legacy clients route on `available`. Never advertise
                        // a tombstoned local model as routeable.
                        info.available = false;
                    }
                    if enabled
                        && self
                            .model_management
                            .load_receipt(&schema.id)
                            .is_ok_and(|receipt| receipt.is_none())
                    {
                        // Legacy CAR installs sometimes left only a managed
                        // symlink. That is safe to adopt automatically because
                        // deletion remains limited to the link and the exact
                        // shared target is captured in the receipt. Plain
                        // directories and shared-cache-only artifacts stay
                        // usable but unowned until explicit adoption.
                        if let Ok(_mutation) = self.model_management.begin_mutation(&schema.id) {
                            if let Some(path) = registry.existing_local_artifact(&schema.id) {
                                if std::fs::symlink_metadata(&path)
                                    .is_ok_and(|metadata| metadata.file_type().is_symlink())
                                {
                                    let generation = self
                                        .resource_policy_generation
                                        .load(std::sync::atomic::Ordering::Acquire);
                                    let _ = self.model_management.record_managed_artifact(
                                        &schema.id,
                                        model_source_identity(schema),
                                        None,
                                        generation,
                                        true,
                                        path,
                                    );
                                }
                            }
                        }
                    }
                    let receipt = self.model_management.load_receipt(&schema.id);
                    let directory_cleanup_unsupported =
                        !model_management::directory_removal_supported()
                            && receipt.as_ref().is_ok_and(|receipt| {
                                receipt.as_ref().is_some_and(|receipt| {
                                    receipt.artifact_kind
                                        == model_management::ManagedArtifactKind::Directory
                                })
                            });
                    info.car_enabled = enabled;
                    info.can_remove = enabled
                        && self
                            .model_management
                            .can_remove(&schema.id)
                            .unwrap_or(false);
                    info.in_use = self.local_admission.active_request_count(&schema.id) > 0
                        || self.local_admission.is_resident(&schema.id)
                        || self.local_admission.teardown_pending(&schema.id)
                        || self
                            .model_management
                            .model_in_use(&schema.id)
                            .unwrap_or(true);
                    info.management_evidence = if !enabled {
                        Some("disabled_tombstone".into())
                    } else if directory_cleanup_unsupported {
                        Some("install_receipt_directory_cleanup_unsupported".into())
                    } else if receipt.is_ok_and(|receipt| receipt.is_some()) {
                        Some("install_receipt".into())
                    } else if info.weights_ready {
                        Some("shared_or_hand_installed".into())
                    } else {
                        None
                    };
                }
                info
            })
            .collect()
    }

    pub fn model_management_store(&self) -> &model_management::ModelManagementStore {
        &self.model_management
    }

    fn ensure_model_enabled(&self, model_id: &str) -> Result<(), InferenceError> {
        if self.model_management.car_enabled(model_id)? {
            return Ok(());
        }
        Err(InferenceError::InferenceFailed(format!(
            "local model {model_id} was removed from CAR; reinstall it before use"
        )))
    }

    /// 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.state_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.state_root);
        // 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.state_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)
    }

    fn model_is_excluded(
        exclude_set: &std::collections::HashSet<String>,
        registry: &UnifiedRegistry,
        model: &str,
    ) -> bool {
        registry
            .get(model)
            .or_else(|| registry.find_by_name(model))
            .map(|schema| exclude_set.contains(&schema.id))
            .unwrap_or_else(|| exclude_set.contains(model))
    }

    /// 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`](crate::InferenceEngine::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`](crate::InferenceEngine::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`](crate::InferenceEngine::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.state_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.catalog_registry_snapshot()
            .list()
            .into_iter()
            .cloned()
            .collect()
    }

    /// Deterministic immutable catalog view used to bind inference routing to
    /// exact model rows. Runtime availability never participates in either
    /// row digests or the catalog revision.
    pub fn catalog_snapshot(&self) -> Result<CatalogSnapshot, String> {
        CatalogSnapshot::new(self.unified_registry.list().into_iter().cloned())
    }

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

    /// Whether a caller-supplied model name resolves to a registered schema.
    ///
    /// Answers the question generation asks, by the same two routes and in the
    /// same order: exact id, then the case-insensitive name lookup. It is
    /// deliberately NOT `list_models()`, which returns the on-device catalog —
    /// checking a remote model id against that set reports every cloud model as
    /// unknown.
    ///
    /// Exists so a caller that fans out to several named models can refuse a
    /// typo up front instead of discovering it as a generation error per
    /// request. Says nothing about whether the model is currently *reachable*
    /// (credentials, network) — only that the name is one CAR knows.
    pub fn knows_model(&self, name: &str) -> bool {
        self.model_schema(name).is_some()
    }

    /// The registered schema behind a model name or id, resolved exactly as
    /// [`Self::knows_model`] resolves it — exact id first, then the
    /// case-insensitive name lookup.
    ///
    /// Defined together with `knows_model` so the two cannot drift into
    /// disagreeing about which names exist, and it resolves in the SAME order
    /// generation does (`get(id).or_else(find_by_name(id))`, as at the routing
    /// sites) — so a caller asking "will these two names reach the same model?"
    /// gets the answer that will actually hold at generation time, including
    /// `find_by_name`'s MLX-variant redirect on Apple silicon.
    ///
    /// That fidelity is the point, and it is NOT a canonical identity oracle.
    /// The lookup is over a `HashMap`, so if two rows share a display name the
    /// one returned is arbitrary — stable within a process, not across
    /// restarts. Generation has the same property, so a caller comparing what
    /// will run stays correct; a caller needing a stable identity for storage
    /// wants the exact id via `registered_schema`.
    pub fn model_schema(&self, name: &str) -> Option<&ModelSchema> {
        self.unified_registry
            .get(name)
            .or_else(|| self.unified_registry.find_by_name(name))
    }

    /// 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.model_management.car_enabled(&s.id).unwrap_or(false))
            .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()))?;
        let _mutation = self.model_management.begin_mutation(&schema.id)?;
        if let Some(receipt) = self.model_management.load_receipt(&schema.id)? {
            // `can_remove=false` can mean a valid receipt-backed directory
            // whose recursive cleanup is deliberately unsupported. Removal
            // capability must never gate reuse/re-enable of valid weights.
            let _ = self.model_management.can_remove(&schema.id)?;
            self.model_management.clear_tombstone(&schema.id)?;
            return Ok(receipt.managed_path);
        }
        if let Some(receipt) = self.model_management.resume_install_intent(&schema.id)? {
            return Ok(receipt.managed_path);
        }
        let expected_managed = self.model_management.models_dir().join(&schema.name);
        if std::fs::symlink_metadata(&expected_managed).is_ok() {
            return Err(InferenceError::InferenceFailed(format!(
                "model {} has a pre-existing unreceipted artifact at {}; use models.adopt or move it before pulling",
                schema.id,
                expected_managed.display()
            )));
        }
        let staging = self.model_management.create_install_staging(&schema.id)?;
        let installed = match self
            .unified_registry
            .ensure_local_with_progress_staged(&schema.id, sink, &staging)
            .await
        {
            Ok(installed) => installed,
            Err(error) => {
                self.model_management.discard_install_staging(&staging);
                return Err(error);
            }
        };
        let installed_is_staging = match (installed.canonicalize(), staging.canonicalize()) {
            (Ok(installed), Ok(staging)) => installed == staging,
            _ => false,
        };
        let generation = self
            .resource_policy_generation
            .load(std::sync::atomic::Ordering::Acquire);
        let managed_path = self.model_management.models_dir().join(&schema.name);
        let managed = if installed_is_staging {
            let receipt = self.model_management.install_receipt_for_publication(
                &schema.id,
                model_source_identity(schema),
                generation,
                false,
                managed_path,
                model_management::ManagedArtifactKind::Directory,
                &staging,
            )?;
            self.model_management
                .begin_install_intent(receipt, Some(&staging))?;
            self.model_management
                .publish_install_staging(&schema.id, &staging, &schema.name)?
        } else {
            self.model_management.discard_install_staging(&staging);
            let receipt = self.model_management.install_receipt_for_publication(
                &schema.id,
                model_source_identity(schema),
                generation,
                false,
                managed_path,
                model_management::ManagedArtifactKind::Symlink,
                &installed,
            )?;
            self.model_management.begin_install_intent(receipt, None)?;
            self.model_management
                .materialize_managed_projection(&schema.name, &installed)?
        };
        let receipt = self
            .model_management
            .resume_install_intent(&schema.id)?
            .ok_or_else(|| {
                InferenceError::InferenceFailed(format!(
                    "model {} publication completed without a durable install intent",
                    schema.id
                ))
            })?;
        debug_assert_eq!(receipt.managed_path, managed);
        Ok(receipt.managed_path)
    }

    /// Explicitly adopt an already-usable local artifact into CAR ownership.
    /// The source path is resolved from the registry; callers cannot nominate
    /// an arbitrary deletion target.
    pub async fn adopt_model_into_car(
        &self,
        model_id: &str,
    ) -> Result<model_management::InstallReceipt, InferenceError> {
        let schema = self
            .unified_registry
            .get(model_id)
            .or_else(|| self.unified_registry.find_by_name(model_id))
            .ok_or_else(|| InferenceError::ModelNotFound(model_id.to_string()))?;
        if !schema.is_local() || !schema.downloads_weights() {
            return Err(InferenceError::InferenceFailed(format!(
                "model {} is not a CAR-manageable local artifact",
                schema.id
            )));
        }
        let existing = self
            .unified_registry
            .existing_local_artifact(&schema.id)
            .ok_or_else(|| {
                InferenceError::InferenceFailed(format!(
                    "model {} has no usable local artifact to adopt",
                    schema.id
                ))
            })?;
        let _mutation = self.model_management.begin_mutation(&schema.id)?;
        let existing_is_managed_symlink = std::fs::symlink_metadata(&existing)
            .is_ok_and(|metadata| metadata.file_type().is_symlink())
            && existing.parent().is_some_and(|parent| {
                parent.canonicalize().ok() == self.model_management.models_dir().canonicalize().ok()
            });
        if let Some(receipt) = self.model_management.resume_install_intent(&schema.id)? {
            return Ok(receipt);
        }
        let generation = self
            .resource_policy_generation
            .load(std::sync::atomic::Ordering::Acquire);
        let managed = if existing_is_managed_symlink {
            existing
        } else {
            let managed = self.model_management.adopted_projection_path(&schema.id)?;
            let receipt = self.model_management.install_receipt_for_publication(
                &schema.id,
                model_source_identity(schema),
                generation,
                true,
                managed,
                model_management::ManagedArtifactKind::Symlink,
                &existing,
            )?;
            self.model_management.begin_install_intent(receipt, None)?;
            self.model_management
                .materialize_adopted_projection(&schema.id, &existing)?
        };
        if existing_is_managed_symlink {
            self.model_management
                .record_managed_artifact(
                    &schema.id,
                    model_source_identity(schema),
                    None,
                    generation,
                    true,
                    managed,
                )
                .map_err(InferenceError::from)
        } else {
            self.model_management
                .resume_install_intent(&schema.id)?
                .ok_or_else(|| {
                    InferenceError::InferenceFailed(format!(
                        "model {} adoption completed without a durable install intent",
                        schema.id
                    ))
                })
        }
    }

    /// Safely remove only CAR-owned linkage after every Task 3 runtime owner
    /// acknowledges release. Shared Hugging Face blobs remain untouched.
    pub async fn remove_model_from_car(
        &self,
        model_id: &str,
    ) -> Result<model_management::RemoveFromCarResult, InferenceError> {
        let schema = self
            .unified_registry
            .get(model_id)
            .or_else(|| self.unified_registry.find_by_name(model_id))
            .ok_or_else(|| InferenceError::ModelNotFound(model_id.to_string()))?;
        if !schema.is_local() || !schema.downloads_weights() {
            return Err(InferenceError::InferenceFailed(format!(
                "model {} is not a CAR-owned local artifact",
                schema.id
            )));
        }
        if self.model_management.load_receipt(&schema.id)?.is_none() {
            if self.model_management.car_enabled(&schema.id)? {
                return Err(model_management::ModelManagementError::MissingReceipt {
                    model_id: schema.id.clone(),
                }
                .into());
            }
            // A prior request may have completed removal and lost its response.
            // Resume the durable tombstone result without re-running runtime
            // maintenance against an artifact that no longer exists.
            let generation = self
                .resource_policy_generation
                .load(std::sync::atomic::Ordering::Acquire)
                .saturating_add(1);
            return self
                .model_management
                .begin_mutation(&schema.id)?
                .remove(generation)
                .map_err(InferenceError::from);
        }
        let mutation = self.model_management.begin_mutation(&schema.id)?;
        let _maintenance = self
            .prepare_local_model_removal(&schema.id)
            .await
            .map_err(|error| InferenceError::InferenceFailed(error.to_string()))?;
        let generation = self
            .resource_policy_generation
            .load(std::sync::atomic::Ordering::Acquire)
            .saturating_add(1);
        mutation.remove(generation).map_err(InferenceError::from)
    }

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

    /// Legacy synchronous removal is intentionally disabled because it cannot
    /// coordinate active workers, cross-process leases, or receipt ownership.
    /// Use [`Self::remove_model_from_car`] instead.
    #[deprecated(note = "use async remove_model_from_car for receipt-backed safe removal")]
    pub fn remove_model(&self, name: &str) -> Result<(), InferenceError> {
        Err(InferenceError::InferenceFailed(format!(
            "legacy removal for {name} is disabled; use async receipt-backed remove_model_from_car"
        )))
    }

    /// 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.state_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.state_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`](crate::InferenceEngine::flush_outcomes) for shutdown / periodic flushes; the
    /// per-call path uses [`auto_save_outcomes`](crate::InferenceEngine::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.state_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.state_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.state_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.state_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,
            // Passive doctor/health state may report explicit environment
            // presence, but must not query the OS credential store. A pasted
            // Keychain value remains unknown until an explicit use/status.
            elevenlabs_configured: crate::tasks::transcribe::provider_configured_for_passive_status(
                "ELEVENLABS_API_KEY",
            )
                || crate::tasks::synthesize::provider_configured_for_passive_status(
                    "ELEVENLABS_API_KEY",
                ),
            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.state_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.catalog_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,
        reservation: Option<&mut resource_policy::LocalLoadReservation>,
    ) -> Result<TranscribeResult, InferenceError> {
        let model = model.to_string();
        let model_path = car_whisper::ensure_model(&model)
            .map_err(|e| InferenceError::InferenceFailed(format!("whisper download: {e}")))?;
        let measured_bytes = backend_cache::estimate_model_size(&model_path);
        let reservation = reservation.ok_or_else(|| {
            InferenceError::InferenceFailed("local Whisper path missing admission".into())
        })?;
        reservation
            .reconcile_measured_weights(measured_bytes)
            .map_err(InferenceError::from)?;
        let detached_lease = reservation.detached_lease();
        // 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 =
            run_admitted_blocking(detached_lease, move || -> Result<String, InferenceError> {
                // LOCAL_ADMISSION_BOUNDARY:speech-stt-dispatch
                let stt = car_whisper::WhisperStt::load_from_path(&model_path, &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,
        reservation: Option<&mut resource_policy::LocalLoadReservation>,
    ) -> Result<TranscribeResult, InferenceError> {
        let model_dir = self.unified_registry.ensure_local(&schema.id).await?;
        let reservation = reservation.ok_or_else(|| {
            InferenceError::InferenceFailed("local STT path missing admission".into())
        })?;
        reservation
            .reconcile_measured_weights(backend_cache::estimate_model_size(&model_dir))
            .map_err(InferenceError::from)?;
        // Native MLX transcription via Parakeet backend (no Python shelling).
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        {
            // 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).
            // LOCAL_ADMISSION_BOUNDARY:speech-stt-dispatch
            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, reservation.detached_lease())
                        .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,
                routing_explanation: None,
            })
        }

        // 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, reservation.detached_lease())
                .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,
        detached_lease: resource_policy::DetachedLocalLease,
    ) -> 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, detached_lease).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(),
                routing_explanation: None,
            })
        }
    }

    async fn synthesize_local_mlx(
        &self,
        schema: &ModelSchema,
        req: &SynthesizeRequest,
        reservation: Option<&mut resource_policy::LocalLoadReservation>,
    ) -> 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)"
            );
        }

        let model_dir = self.unified_registry.ensure_local(&schema.id).await?;
        let reservation = reservation.ok_or_else(|| {
            InferenceError::InferenceFailed("local TTS path missing admission".into())
        })?;
        reservation
            .reconcile_measured_weights(backend_cache::estimate_model_size(&model_dir))
            .map_err(InferenceError::from)?;

        // 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 size = backend_cache::estimate_model_size(&model_dir);
            let cache_key = reservation.model_id().to_string();
            // LOCAL_ADMISSION_BOUNDARY:speech-tts-dispatch
            let (handle, retention) = match Self::load_backend_healing(
                &cache_key,
                model_dir,
                &self.kokoro_cache,
                size,
                reservation,
                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, reservation.detached_lease())
                        .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();
            let detached_lease = (retention == backend_cache::BackendRetention::Transient)
                .then(|| reservation.detached_lease());
            // 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 _detached_lease = detached_lease;
                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(),
                routing_explanation: None,
            })
        }

        // 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, reservation.detached_lease())
                .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,
        detached_lease: resource_policy::DetachedLocalLease,
    ) -> 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,
                detached_lease.clone(),
            )
            .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,
                        detached_lease.clone(),
                    )
                    .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(),
            routing_explanation: None,
        })
    }

    async fn synthesize_local_mlx_repo(
        &self,
        runtime: &SpeechRuntime,
        hf_repo: &str,
        model_name: &str,
        req: &SynthesizeRequest,
        detached_lease: resource_policy::DetachedLocalLease,
    ) -> 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,
                detached_lease,
            )
            .await?
        } else {
            run_mlx_audio_command(runtime, "tts.generate", &args, detached_lease).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,
            crate::tasks::transcribe::resolve_provider_credential_for_request,
        )?;
        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(),
            routing_explanation: None,
        })
    }

    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,
            crate::tasks::synthesize::resolve_provider_credential_for_request,
        )?;
        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),
            routing_explanation: None,
        })
    }
}

#[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 python = managed_venv::interpreter(&root);
        let stt_program = managed_venv::venv_program(&root, "mlx_audio.stt.generate");
        let tts_program = managed_venv::venv_program(&root, "mlx_audio.tts.generate");
        Self {
            root,
            python,
            stt_program,
            tts_program,
        }
    }

    fn is_ready(&self) -> bool {
        // `interpreter_healthy` runs the interpreter rather than stat-ing it.
        // A venv whose Python was rotated away by a Homebrew upgrade still has
        // every console script sitting on disk, so a pure existence check
        // reports "ready" for a runtime where all of them die at their shebang.
        managed_venv::interpreter_healthy(&self.root)
            && 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],
    detached_lease: resource_policy::DetachedLocalLease,
) -> Result<CommandOutput, InferenceError> {
    run_mlx_audio_command_with_env(runtime, subcommand, args, &[], detached_lease).await
}

/// Run synchronous native model work with an owned machine-budget charge.
/// Tokio cannot cancel a started `spawn_blocking` closure, so the lease must
/// live inside the closure rather than in the awaiting request future.
async fn run_admitted_blocking<F, T>(
    detached_lease: resource_policy::DetachedLocalLease,
    operation: F,
) -> Result<T, tokio::task::JoinError>
where
    F: FnOnce() -> T + Send + 'static,
    T: Send + 'static,
{
    tokio::task::spawn_blocking(move || {
        let _detached_lease = detached_lease;
        operation()
    })
    .await
}

struct DetachedSpeechProcess {
    child: Option<tokio::process::Child>,
    lease: Option<resource_policy::DetachedLocalLease>,
}

impl Drop for DetachedSpeechProcess {
    fn drop(&mut self) {
        let Some(mut child) = self.child.take() else {
            return;
        };
        let lease = self.lease.take();
        let _ = child.start_kill();
        if tokio::runtime::Handle::try_current().is_ok() {
            tokio::spawn(async move {
                let _ = child.wait().await;
                drop(lease);
            });
        } else {
            // Without an executor we cannot confirm OS exit. Preserve both
            // ownership and charge rather than advertise unsafe headroom.
            std::mem::forget((child, lease));
        }
    }
}

async fn run_mlx_audio_command_with_env(
    runtime: &SpeechRuntime,
    subcommand: &str,
    args: &[String],
    envs: &[(String, String)],
    detached_lease: resource_policy::DetachedLocalLease,
) -> 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);
    }
    command
        .stdout(std::process::Stdio::piped())
        .stderr(std::process::Stdio::piped())
        .kill_on_drop(true);
    let child = command
        .spawn()
        .map_err(|err| InferenceError::InferenceFailed(format!("{}: {err}", program.display())))?;
    let mut owned = DetachedSpeechProcess {
        child: Some(child),
        lease: Some(detached_lease),
    };
    let mut stdout = owned
        .child
        .as_mut()
        .expect("speech child owned")
        .stdout
        .take()
        .ok_or_else(|| {
            InferenceError::InferenceFailed(format!("{} stdout unavailable", program.display()))
        })?;
    let mut stderr = owned
        .child
        .as_mut()
        .expect("speech child owned")
        .stderr
        .take()
        .ok_or_else(|| {
            InferenceError::InferenceFailed(format!("{} stderr unavailable", program.display()))
        })?;
    let stdout_reader = tokio::spawn(async move {
        let mut bytes = Vec::new();
        stdout.read_to_end(&mut bytes).await.map(|_| bytes)
    });
    let stderr_reader = tokio::spawn(async move {
        let mut bytes = Vec::new();
        stderr.read_to_end(&mut bytes).await.map(|_| bytes)
    });
    let status = owned
        .child
        .as_mut()
        .expect("speech child owned")
        .wait()
        .await
        .map_err(|err| InferenceError::InferenceFailed(format!("{}: {err}", program.display())))?;
    owned.child.take();
    owned.lease.take();
    let stdout = stdout_reader
        .await
        .map_err(|err| InferenceError::InferenceFailed(format!("speech stdout join: {err}")))?
        .map_err(|err| InferenceError::InferenceFailed(format!("speech stdout: {err}")))?;
    let stderr = stderr_reader
        .await
        .map_err(|err| InferenceError::InferenceFailed(format!("speech stderr join: {err}")))?
        .map_err(|err| InferenceError::InferenceFailed(format!("speech stderr: {err}")))?;

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

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

    // A bare `uv venv` hard-fails against an existing directory, so this used to
    // abort on every machine that had already provisioned the runtime once —
    // including the case this bootstrap exists to handle, where the venv is
    // present but its interpreter was rotated away by a Homebrew upgrade.
    // `managed_venv` reuses a healthy venv and rebuilds a broken one.
    let outcome = managed_venv::ensure_venv(&runtime.root, &python)
        .await
        .map_err(|err| InferenceError::InferenceFailed(err.to_string()))?;
    if outcome == managed_venv::VenvOutcome::Recreated {
        tracing::warn!(
            root = %runtime.root.display(),
            "managed speech runtime had an unusable interpreter; rebuilt it \
             (installed packages were discarded and are being reinstalled)"
        );
    }

    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"),
        // A remote credential is configuration, not a cached model artifact.
        // Credential truth is established only at explicit request time.
        ModelSource::Proprietary { .. } => false,
        _ => false,
    }
}

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,
            ..
        } => {
            std::env::var(api_key_env).is_ok_and(|value| !value.trim().is_empty())
                || api_key_envs.iter().any(|env_var| {
                    std::env::var(env_var).is_ok_and(|value| !value.trim().is_empty())
                })
        }
        ModelSource::Proprietary { auth, .. } => match auth {
            ProprietaryAuth::ApiKeyEnv { env_var } => {
                std::env::var(env_var).is_ok_and(|value| !value.trim().is_empty())
            }
            ProprietaryAuth::BearerTokenEnv { env_var } => {
                std::env::var(env_var).is_ok_and(|value| !value.trim().is_empty())
            }
            ProprietaryAuth::OAuth2Pkce { .. } => matches!(
                car_auth::credential_authority_hint().state,
                car_auth::CredentialAuthorityState::Configured
            ),
        },
        ModelSource::VllmMlx { .. } => {
            std::env::var("VLLM_MLX_ENDPOINT").is_ok() || schema.available
        }
        ModelSource::Ollama { .. } => schema.available,
        ModelSource::CodexCli { .. } => crate::backend::codex_cli::is_available(),
        ModelSource::Mlx { .. }
        | ModelSource::ManagedVllmMlx { .. }
        | 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::ManagedVllmMlx { hf_repo, .. } => {
            format!("managed-vllm-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::CodexCli { model } => format!("codex-cli:{model}"),
        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})"
    ))
}

/// Whether an error message means **the credential was rejected** — the remedy
/// is for a human to sign in again (`car auth login`), not for the machinery to
/// retry.
///
/// This is the single definition of that question in the workspace.
/// [`auth_expired_recovery_hint`] consumes it to decide whether to print re-auth
/// guidance, and `car_server_core::coder::native_loop::is_auth_failure` consumes
/// it so the coder loop pauses for sign-in instead of burning inference strikes
/// (three of which throw away the worktree) on a credential that cannot possibly
/// succeed on retry — Parslee-ai/car#888, where the real expired-token error
/// (`Parslee org lookup failed: HTTP 401 Unauthorized: Authentication required`)
/// matched none of that loop's hand-rolled substrings.
///
/// It deliberately does **not** match transient failures — 5xx, timeouts, reset
/// connections. Those are worth retrying and must keep flowing down the normal
/// failure path; classifying one as "sign in again" would tell an operator to
/// fix something that is not broken.
pub fn is_auth_rejection_message(underlying: &str) -> bool {
    let l = underlying.to_ascii_lowercase();
    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")
}

/// Whether a rendered inference failure needs credential repair rather than an
/// infrastructure retry.
///
/// Route summaries and consumers such as the coder loop share
/// `AUTH_FAILURE_MESSAGE_MARKERS` instead of maintaining independent phrase
/// lists that can disagree when a summary is added or reworded.
pub fn is_auth_failure_message(message: &str) -> bool {
    let lower = message.to_ascii_lowercase();
    AUTH_FAILURE_MESSAGE_MARKERS
        .iter()
        .any(|marker| lower.contains(marker))
        || is_auth_rejection_message(message)
}

/// Record `candidate` as the dead lane if `error` is a credential rejection and
/// no dead lane has been recorded yet.
///
/// FIRST-wins, not last: the chain is walked in preference order, so the first
/// rejected lane is the one the operator actually configured and the one worth
/// naming. Non-auth failures (5xx, timeouts) leave the slot untouched — they are
/// not a sign-in problem. Extracted from the fallback loop so the rule is
/// directly testable (Parslee-ai/car#888).
fn record_auth_dead_lane(slot: &mut Option<String>, candidate: &str, error: &str) {
    if slot.is_none() && is_auth_rejection_message(error) {
        *slot = Some(candidate.to_string());
    }
}

/// Whether the candidate that served was the on-device model appended behind
/// an otherwise remote-only chain. Comparing the attempted ids (rather than
/// display names) keeps aliases from turning ordinary local routing into a
/// false fallback marker.
fn is_local_last_resort(appended_id: Option<&str>, candidate_id: &str) -> bool {
    appended_id == Some(candidate_id)
}

/// Mark and announce the moment the appended model actually serves. The INFO
/// at append time reports only that fallback was available; this WARN reports
/// the materially different fact that the turn degraded onto it.
fn report_local_last_resort_served(
    appended_id: Option<&str>,
    candidate_id: &str,
    resolved_id: &str,
) -> bool {
    let served = is_local_last_resort(appended_id, candidate_id);
    if served {
        tracing::warn!(
            local_model = %resolved_id,
            "on-device last-resort model served inference turn"
        );
    }
    served
}

/// 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> {
    if !is_auth_rejection_message(underlying) {
        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,
    resolve_credential: fn(&str) -> Option<String>,
) -> Result<(String, String), InferenceError> {
    match &schema.source {
        ModelSource::Proprietary {
            endpoint,
            auth: schema::ProprietaryAuth::ApiKeyEnv { env_var },
            ..
        } => {
            let key = resolve_credential(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",
    }
}

/// Benchmark-prior files to merge, in order: `<state models dir>/`, its parent
/// (the state root), and an explicit `CAR_BENCHMARK_PRIORS_PATH`. Takes the
/// *state* models dir ([`InferenceConfig::state_models_dir`]), not the shared
/// weights dir, so a relocated daemon reads its own priors.
fn benchmark_priors_paths(state_models_dir: &Path) -> Vec<PathBuf> {
    let mut paths = Vec::new();

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

    if let Some(parent) = state_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(
    state_models_dir: &Path,
    schemas: &[ModelSchema],
) -> Vec<ModelBenchmarkPriorHealth> {
    let mut priors = std::collections::BTreeMap::new();
    for path in benchmark_priors_paths(state_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)]
pub(crate) fn run_in_isolated_test_process(test_name: &str, sentinel: &str) -> bool {
    static CHILD_PROCESS_MUTEX: std::sync::Mutex<()> = std::sync::Mutex::new(());

    if std::env::var_os(sentinel).is_some() {
        return true;
    }

    let _child_process = CHILD_PROCESS_MUTEX
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    let mut command = std::process::Command::new(std::env::current_exe().unwrap());
    command
        .arg("--exact")
        .arg(test_name)
        .arg("--nocapture")
        .arg("--test-threads=1")
        .env(sentinel, "1");
    for name in [
        car_home::ENV_VAR,
        "CAR_SECRETS_FILE_DIR",
        "CAR_AUTH_LOCK_PATH",
        car_auth::PARSLEE_ACCESS_TOKEN_KEY,
        car_auth::PARSLEE_API_BASE_KEY,
        crate::openrouter::API_KEY_ENV,
        "OPENAI_API_KEY",
        "ANTHROPIC_API_KEY",
        "GOOGLE_API_KEY",
        "ELEVENLABS_API_KEY",
        "SSL_CERT_FILE",
        "SSL_CERT_DIR",
    ] {
        command.env_remove(name);
    }
    let output = command.output().expect("spawn isolated inference test");
    assert!(
        output.status.success(),
        "isolated {test_name} failed\nstdout:\n{}\nstderr:\n{}",
        String::from_utf8_lossy(&output.stdout),
        String::from_utf8_lossy(&output.stderr),
    );
    false
}

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

    /// car#851: `car do --local --model mlx/qwen3-8b:4bit` hung for 57 minutes.
    /// The caller asked for the default 4096-token budget and the routing layer
    /// silently widened it to the model's advertised 32768 — which for a model
    /// decoded in-process is not a token budget, it is ~24 minutes of wall
    /// clock. Remote models still get the widening; that is what keeps a
    /// long-horizon tool_use argument from truncating mid-object.
    #[test]
    fn local_models_keep_the_callers_default_output_budget() {
        use crate::tasks::generate::DEFAULT_MAX_TOKENS;

        let catalog = crate::registry::builtin_catalog();
        let local = catalog
            .iter()
            .find(|s| s.id == "mlx/qwen3-8b:4bit")
            .expect("mlx/qwen3-8b:4bit is a builtin catalog entry");

        assert!(local.is_local(), "mlx/* is decoded in-process");
        assert_eq!(
            local.effective_max_output(),
            32_768,
            "the budget that made the reported turn ~24 minutes long"
        );
        assert_eq!(
            resolved_max_tokens(DEFAULT_MAX_TOKENS, local),
            DEFAULT_MAX_TOKENS,
            "a local model must keep the budget the caller actually asked for"
        );

        // Same numbers, only the locality differs — so the widening below can
        // only be attributable to the model being remote.
        let mut remote = catalog
            .iter()
            .find(|s| !s.is_local())
            .expect("the builtin catalog ships remote models")
            .clone();
        remote.context_length = local.context_length;
        remote.max_output_tokens = local.max_output_tokens;
        assert!(!remote.is_local());
        assert_eq!(
            resolved_max_tokens(DEFAULT_MAX_TOKENS, &remote),
            32_768,
            "remote models still get their advertised output budget"
        );

        // An explicit budget is a caller decision; never second-guess it.
        assert_eq!(resolved_max_tokens(512, local), 512);
        assert_eq!(resolved_max_tokens(512, &remote), 512);

        let codex = catalog
            .iter()
            .find(|s| s.id == "openai/gpt-5.6-sol:high")
            .expect("subscription-backed Codex row is builtin");
        assert_eq!(
            resolved_max_tokens(DEFAULT_MAX_TOKENS, codex),
            DEFAULT_MAX_TOKENS,
            "an approximate instruction must not widen the default to 128K tokens"
        );

        // vLLM-MLX is `is_local()` but we do not decode it — it is an HTTP
        // server on this machine, and it is the documented route to structured
        // tool calls from a local model, so it must KEEP the widening. Gating
        // this helper on `is_local` instead of `decodes_in_process` silently
        // reintroduces the tool_use truncation the widening exists to prevent.
        if let Some(vllm) = catalog.iter().find(|s| s.is_vllm_mlx()) {
            assert!(vllm.is_local(), "vLLM-MLX runs on this machine");
            assert!(
                !vllm.decodes_in_process(),
                "but CAR does not decode it token by token"
            );
            assert_eq!(
                resolved_max_tokens(DEFAULT_MAX_TOKENS, vllm),
                vllm.effective_max_output(),
            );
        }
    }

    /// The decision that stops car#851 from paying its ceiling twice, and the
    /// one that stops a dead turn from reading as a successful empty one.
    #[test]
    fn a_ceiling_stop_fails_instead_of_retrying() {
        use EmptyPassAction::*;
        const CEILING: Option<&str> = Some(LOCAL_DECODE_TIMEOUT_STOP_REASON);

        // The car#851 doubling: empty text + Auto looks exactly like a thinking
        // truncation, and retrying would spend the same ceiling again.
        assert_eq!(
            classify_empty_pass(true, CEILING, "", true),
            FailDecodeCeiling
        );
        assert_eq!(
            classify_empty_pass(false, CEILING, "", true),
            FailDecodeCeiling
        );
        // Whitespace is not output.
        assert_eq!(
            classify_empty_pass(true, CEILING, "  \n ", true),
            FailDecodeCeiling
        );

        // The pre-existing car-releases#60 recovery still fires when the
        // ceiling is NOT the reason.
        assert_eq!(
            classify_empty_pass(true, Some("length"), "", true),
            RetryWithoutThinking
        );
        assert_eq!(
            classify_empty_pass(true, None, "", true),
            RetryWithoutThinking
        );

        // Caller opted out of recovery and no ceiling: accept the empty result
        // rather than inventing a retry or an error.
        assert_eq!(classify_empty_pass(false, Some("stop"), "", true), Accept);

        // A partial answer beats an error — a ceiling stop that produced text
        // or a tool call is still usable output.
        assert_eq!(classify_empty_pass(true, CEILING, "partial", true), Accept);
        assert_eq!(classify_empty_pass(true, CEILING, "", false), Accept);

        // Collision guard: a remote provider's raw finish_reason of "timeout"
        // must NOT be mistaken for the local ceiling and converted into an
        // error naming a local wall clock and a local env var.
        assert_ne!(LOCAL_DECODE_TIMEOUT_STOP_REASON, "timeout");
        assert_eq!(
            classify_empty_pass(true, Some("timeout"), "", true),
            RetryWithoutThinking
        );
    }

    /// Both decode loops share these two predicates. The streaming loop runs
    /// only against a real MLX backend, so this is the regression net for an
    /// inverted comparison or a heartbeat that forgets to advance. (car#851)
    #[test]
    fn decode_deadline_and_heartbeat_predicates() {
        use std::time::Duration;
        let limit = Duration::from_secs(300);

        // No ceiling configured: never fires, however long it runs.
        assert!(!deadline_exceeded(Duration::from_secs(86_400), None));

        assert!(!deadline_exceeded(Duration::from_secs(299), Some(limit)));
        // Inclusive at the boundary — `>`, not `>=`, would let an exactly-at-
        // limit decode run one more forward.
        assert!(deadline_exceeded(limit, Some(limit)));
        assert!(deadline_exceeded(Duration::from_secs(301), Some(limit)));

        let every = Duration::from_secs(10);
        // First heartbeat: `last` starts at ZERO.
        assert!(!heartbeat_due(
            Duration::from_secs(9),
            Duration::ZERO,
            every
        ));
        assert!(heartbeat_due(
            Duration::from_secs(10),
            Duration::ZERO,
            every
        ));
        // After firing, `last` advances — no flood on the next token.
        assert!(!heartbeat_due(
            Duration::from_secs(11),
            Duration::from_secs(10),
            every
        ));
        assert!(heartbeat_due(
            Duration::from_secs(20),
            Duration::from_secs(10),
            every
        ));
        // saturating_sub: a `last` ahead of `elapsed` must not panic.
        assert!(!heartbeat_due(
            Duration::from_secs(5),
            Duration::from_secs(10),
            every
        ));
    }

    #[test]
    fn decode_timeout_parses_with_a_safe_fallback() {
        let default = std::time::Duration::from_secs(DEFAULT_LOCAL_DECODE_TIMEOUT_SECS);
        assert_eq!(parse_decode_timeout(None), Some(default));
        assert_eq!(
            parse_decode_timeout(Some(" 45 ")),
            Some(std::time::Duration::from_secs(45))
        );
        assert_eq!(
            parse_decode_timeout(Some("0")),
            None,
            "0 disables the ceiling"
        );
        assert_eq!(
            parse_decode_timeout(Some("banana")),
            Some(default),
            "garbage must fall back to the default, never silently disable it"
        );
    }

    /// The other half of car#851: even with a sane budget, the decode loop's
    /// only bound was `max_tokens`, and it logged nothing for its whole
    /// duration — so a runaway was indistinguishable from a wedged process.
    /// A decoder that never emits an eos id must now come back on the clock.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    #[test]
    fn local_decode_stops_at_the_wall_clock_ceiling() {
        /// Always samples token 7; 0 is the only eos id, so this never stops
        /// on its own. 5 ms per forward stands in for a large slow model.
        struct NeverStops;

        impl crate::backend::local::TextDecoder for NeverStops {
            fn encode(&self, _text: &str) -> Result<Vec<u32>, InferenceError> {
                Ok(vec![1, 2, 3])
            }
            fn decode(&self, tokens: &[u32]) -> Result<String, InferenceError> {
                Ok("x".repeat(tokens.len()))
            }
            fn forward(
                &mut self,
                _tokens: &[u32],
                _pos: usize,
            ) -> Result<Vec<f32>, InferenceError> {
                std::thread::sleep(std::time::Duration::from_millis(5));
                let mut logits = vec![0.0f32; 16];
                logits[7] = 10.0;
                Ok(logits)
            }
            fn eos_ids(&self) -> Vec<u32> {
                vec![0]
            }
            fn context_length(&self) -> usize {
                4096
            }
            fn clear_kv_cache(&mut self) {}
        }

        // 100_000 tokens at 5 ms each is over eight minutes of decode if the
        // budget is the only thing bounding the loop.
        let params = GenerateParams {
            max_tokens: 100_000,
            temperature: 0.0,
            ..Default::default()
        };
        let ceiling = std::time::Duration::from_millis(300);

        let mut backend = NeverStops;
        let started = std::time::Instant::now();
        let generated = match InferenceEngine::drive_generation_with_timeout(
            &mut backend,
            "anything",
            &params,
            Some(ceiling),
        ) {
            Ok(generated) => generated,
            // `DriveError` is not `Debug`, so unwrap the inner error by hand.
            Err(e) => panic!(
                "a decode cut short by the ceiling returns its partial text, not an error: {}",
                e.into_inner()
            ),
        };
        let elapsed = started.elapsed();

        assert_eq!(
            generated.stop_reason.as_deref(),
            Some(LOCAL_DECODE_TIMEOUT_STOP_REASON),
            "the caller must be able to tell a deadline stop from a clean finish"
        );
        assert!(
            InferenceResult {
                text: generated.text.clone(),
                bounding_boxes: Vec::new(),
                tool_calls: vec![],
                trace_id: String::new(),
                model_used: String::new(),
                model_identity: Default::default(),
                latency_ms: 0,
                time_to_first_token_ms: None,
                usage: None,
                provider_output_items: Vec::new(),
                thinking: Vec::new(),
                stop_reason: generated.stop_reason.clone(),
                auth_fallback_from: None,
                local_last_resort: false,
                fallback_from: Vec::new(),
            }
            .was_truncated(),
            "a ceiling stop is a cut-short answer, not a complete one"
        );
        assert!(
            generated.completion_tokens > 0,
            "the partial response is kept, not discarded"
        );
        assert!(
            generated.completion_tokens < params.max_tokens,
            "the loop stopped on the clock, not by exhausting the budget"
        );
        assert!(
            elapsed < std::time::Duration::from_secs(30),
            "bounded in wall clock; took {elapsed:?}"
        );
    }

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

    // Gated to match its only consumer,
    // `exact_model_id_nonstream_bypasses_mlx_equivalent_substitution`. Ungated,
    // this whole cluster is dead code everywhere the MLX test is compiled out,
    // which `-D warnings` turns into a build failure on the Linux runner.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    struct ExactPinCaptureOffload {
        dispatched_models: std::sync::Mutex<Vec<String>>,
    }

    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    impl ExactPinCaptureOffload {
        fn new() -> Self {
            Self {
                dispatched_models: std::sync::Mutex::new(Vec::new()),
            }
        }

        fn dispatched_models(&self) -> Vec<String> {
            self.dispatched_models.lock().unwrap().clone()
        }
    }

    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    #[async_trait::async_trait]
    impl crate::offload::LocalGenerationOffload for ExactPinCaptureOffload {
        async fn generate(
            &self,
            request: GenerateRequest,
        ) -> Result<InferenceResult, InferenceError> {
            let model_id = request.model.expect("resolved worker model");
            self.dispatched_models
                .lock()
                .unwrap()
                .push(model_id.clone());
            Ok(InferenceResult {
                text: "exact pin".into(),
                tool_calls: vec![],
                bounding_boxes: vec![],
                trace_id: "worker-trace".into(),
                model_used: model_id,
                model_identity: Default::default(),
                latency_ms: 0,
                time_to_first_token_ms: None,
                usage: None,
                provider_output_items: vec![],
                thinking: vec![],
                stop_reason: Some("stop".into()),
                auth_fallback_from: None,
                local_last_resort: false,
                fallback_from: Vec::new(),
            })
        }

        async fn stream(
            &self,
            request: GenerateRequest,
        ) -> Result<tokio::sync::mpsc::Receiver<StreamEvent>, InferenceError> {
            let model_id = request.model.expect("resolved worker model");
            self.dispatched_models.lock().unwrap().push(model_id);
            let (tx, rx) = tokio::sync::mpsc::channel(2);
            tx.send(StreamEvent::Done {
                text: "exact pin".into(),
                tool_calls: vec![],
            })
            .await
            .unwrap();
            Ok(rx)
        }
    }

    struct ReconcileOffload {
        calls: std::sync::Mutex<Vec<String>>,
        release_acknowledged: bool,
    }

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

        async fn stream(
            &self,
            _request: GenerateRequest,
        ) -> Result<tokio::sync::mpsc::Receiver<StreamEvent>, InferenceError> {
            unreachable!("residency reconciliation fixture")
        }

        fn resident_allocation_id(&self, model_id: &str) -> Option<String> {
            self.calls
                .lock()
                .unwrap()
                .push(format!("allocation:{model_id}"));
            Some(format!("worker:{model_id}:generation-7"))
        }

        async fn release_model(&self, model_id: &str) -> Result<bool, InferenceError> {
            self.calls
                .lock()
                .unwrap()
                .push(format!("release:{model_id}"));
            Ok(self.release_acknowledged)
        }
    }

    fn reconciliation_reservation() -> (
        Arc<crate::resource_policy::LocalAdmissionCoordinator>,
        crate::resource_policy::LocalLoadReservation,
    ) {
        struct FixedProbe;
        impl crate::resource_policy::LiveMemoryProbe for FixedProbe {
            fn available_memory_mb(
                &self,
            ) -> Result<Option<u64>, crate::resource_policy::ResourcePolicyError> {
                Ok(Some(24_000))
            }
        }
        let coordinator = Arc::new(
            crate::resource_policy::LocalAdmissionCoordinator::with_probe(
                crate::resource_policy::ResourcePolicy::custom_gb(8.0).unwrap(),
                crate::hardware::HardwareInfo {
                    total_ram_mb: 32 * 1024,
                    ..crate::hardware::HardwareInfo::detect()
                },
                Arc::new(FixedProbe),
            ),
        );
        let reservation = coordinator
            .reserve_measured_host_allocation(
                "expected/model",
                "expected/model#request",
                1024 * 1024,
                0,
            )
            .unwrap();
        (coordinator, reservation)
    }

    #[tokio::test]
    async fn worker_residency_reconciliation_releases_mismatched_ack_before_returning_error() {
        let offload = ReconcileOffload {
            calls: std::sync::Mutex::new(Vec::new()),
            release_acknowledged: true,
        };
        let (_coordinator, mut reservation) = reconciliation_reservation();
        let error = InferenceEngine::reconcile_worker_residency(
            &offload,
            "expected/model",
            &crate::offload::LocalWorkerResidency {
                model_id: "wrong/model".into(),
                measured_weights_bytes: 2 * 1024 * 1024,
            },
            backend_cache::BackendRetention::Resident,
            &mut reservation,
        )
        .await
        .unwrap_err();
        assert!(error.to_string().contains("wrong/model"));
        assert_eq!(
            *offload.calls.lock().unwrap(),
            vec!["release:wrong/model".to_string()]
        );
    }

    #[tokio::test]
    async fn worker_residency_reconciliation_publishes_exact_owner_for_matching_ack() {
        let offload = ReconcileOffload {
            calls: std::sync::Mutex::new(Vec::new()),
            release_acknowledged: false,
        };
        let (coordinator, mut reservation) = reconciliation_reservation();
        InferenceEngine::reconcile_worker_residency(
            &offload,
            "expected/model",
            &crate::offload::LocalWorkerResidency {
                model_id: "expected/model".into(),
                measured_weights_bytes: 2 * 1024 * 1024,
            },
            backend_cache::BackendRetention::Resident,
            &mut reservation,
        )
        .await
        .unwrap();
        drop(reservation);
        assert_eq!(
            *offload.calls.lock().unwrap(),
            vec!["allocation:expected/model".to_string()]
        );
        assert!(coordinator.is_resident("expected/model"));
    }

    #[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> {
            unreachable!("admission-aware streaming fixture")
        }

        async fn stream_admitted(
            &self,
            request: GenerateRequest,
            admission: crate::offload::LocalWorkerAdmission,
        ) -> Result<crate::offload::LocalOffloadStream, 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(crate::offload::LocalOffloadStream {
                events: rx,
                residency: crate::offload::LocalWorkerResidency {
                    model_id: request.model.unwrap_or_else(|| "fixture/local".into()),
                    measured_weights_bytes: admission.measured_weights_bytes,
                },
                retention: backend_cache::BackendRetention::Resident,
            })
        }
    }

    /// Pin the engine's local-admission live-memory probe to a fixed, ample
    /// value. Tests that stream through a LOCAL fixture model are exercising
    /// stream/outcome mechanics, not host admission — with the real
    /// SystemLiveMemoryProbe, a concurrent cargo build's rustc processes can
    /// push live free memory under the emergency reserve and turn the setup
    /// into LocalResourceBlocked/InsufficientLiveMemory (car-sap7: measured
    /// under a parallel build with 8326 MB live against a 6553 MB reserve
    /// plus a 2037 MB estimate). Policy and hardware stay exactly as the
    /// engine built them; only the live probe is pinned.
    fn pin_test_live_memory(engine: &mut InferenceEngine) {
        let policy = engine.local_admission.policy();
        engine.local_admission = Arc::new(resource_policy::LocalAdmissionCoordinator::with_probe(
            policy,
            HardwareInfo::detect(),
            Arc::new(resource_policy::FixedLiveMemoryProbe::known(1_048_576)),
        ));
    }

    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
    }

    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    fn install_exact_pin_equivalent_fixture(engine: &InferenceEngine) -> String {
        let gguf = engine
            .unified_registry
            .get("qwen/qwen3-0.6b:q8_0")
            .expect("GGUF fixture row")
            .clone();
        let mlx = engine
            .unified_registry
            .get("mlx/qwen3-0.6b:6bit")
            .expect("MLX equivalent fixture row")
            .clone();

        let gguf_dir = engine.config.models_dir.join(&gguf.name);
        std::fs::create_dir_all(&gguf_dir).unwrap();
        std::fs::write(gguf_dir.join("model.gguf"), b"fixture").unwrap();
        std::fs::write(gguf_dir.join("tokenizer.json"), b"{}").unwrap();

        let mlx_dir = engine.config.models_dir.join(&mlx.name);
        std::fs::create_dir_all(&mlx_dir).unwrap();
        std::fs::write(mlx_dir.join("config.json"), b"{}").unwrap();
        std::fs::write(mlx_dir.join("model.safetensors"), b"fixture").unwrap();

        gguf.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,
        }
    }

    async fn assert_remote_model_identity_contract(
        protocol: schema::ApiProtocol,
        model_id: &str,
        provider_model: &str,
        api_key_env: &str,
    ) {
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let server = MockServer::start().await;
        let (endpoint_path, response) = match protocol {
            schema::ApiProtocol::OpenAiCompat => (
                "/v1/chat/completions",
                serde_json::json!({
                    "choices": [{
                        "message": {"content": "openai exact"},
                        "finish_reason": "stop"
                    }],
                    "usage": {"prompt_tokens": 2, "completion_tokens": 2, "total_tokens": 4}
                }),
            ),
            schema::ApiProtocol::Anthropic => (
                "/v1/messages",
                serde_json::json!({
                    "content": [{"type": "text", "text": "anthropic exact"}],
                    "stop_reason": "end_turn",
                    "usage": {"input_tokens": 2, "output_tokens": 2}
                }),
            ),
            _ => unreachable!("identity regression covers the newsroom's two remote providers"),
        };
        Mock::given(method("POST"))
            .and(path(endpoint_path))
            .respond_with(ResponseTemplate::new(200).set_body_json(response))
            .mount(&server)
            .await;
        unsafe { std::env::set_var(api_key_env, "fixture") };

        let tmp = TempDir::new().unwrap();
        let mut engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let mut schema =
            remote_stream_fixture_schema(model_id, server.uri(), protocol, api_key_env);
        schema.name = provider_model.into();
        engine.register_model(schema);

        let mut exact_request = GenerateRequest {
            prompt: "return the exact identity".into(),
            ..Default::default()
        };
        pin_exact_model_id(&mut exact_request, model_id.into()).unwrap();
        let exact = engine.generate_tracked(exact_request).await.unwrap();
        assert_eq!(exact.model_used, model_id);
        assert_eq!(
            exact.model_identity.requested_model_id.as_deref(),
            Some(model_id)
        );
        assert_eq!(exact.model_identity.resolved_model_id, model_id);
        let exact_envelope = serde_json::to_value(&exact).unwrap();
        assert_eq!(exact_envelope["model_used"], model_id);
        assert_eq!(exact_envelope["requested_model_id"], model_id);
        assert_eq!(exact_envelope["resolved_model_id"], model_id);
        assert!(exact_envelope["row_digest"].is_string());
        assert!(exact_envelope["catalog_revision"].is_string());

        let loose = engine
            .generate_tracked(GenerateRequest {
                prompt: "keep legacy display-name routing".into(),
                model: Some(provider_model.into()),
                params: GenerateParams {
                    strict_model: true,
                    ..Default::default()
                },
                ..Default::default()
            })
            .await
            .unwrap();
        assert_eq!(loose.model_used, provider_model);
        assert_eq!(loose.model_identity.requested_model_id, None);
        assert_eq!(loose.model_identity.resolved_model_id, model_id);

        let requests = server.received_requests().await.unwrap();
        assert_eq!(requests.len(), 2);
        for request in requests {
            let body: serde_json::Value = serde_json::from_slice(&request.body).unwrap();
            assert_eq!(body["model"], provider_model);
        }

        unsafe { std::env::remove_var(api_key_env) };
    }

    /// 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());
    }

    /// The single public definition of "the credential was rejected". Pinned to
    /// the LITERAL error an expired Parslee session produces (Parslee-ai/car#888):
    /// the coder loop's own matcher missed this exact string, so an expired
    /// token burned inference strikes instead of asking for a sign-in.
    #[test]
    fn auth_rejection_classifier_matches_the_real_expired_token_error() {
        assert!(is_auth_rejection_message(
            "inference failed: Parslee org lookup failed: HTTP 401 Unauthorized: \
             Authentication required"
        ));
        // A transient is NOT a sign-in problem — telling an operator to
        // re-authenticate through a 503 sends them to fix what isn't broken.
        for transient in [
            "API returned 503: service unavailable",
            "request timed out",
            "connection reset by peer",
        ] {
            assert!(
                !is_auth_rejection_message(transient),
                "transient wrongly classified as an auth rejection: {transient:?}"
            );
        }
    }

    /// Fixtures built from the real `InferenceError` values these paths
    /// produce, not invented to match the arms.
    ///
    /// The first version of this test hand-wrote eleven plausible strings and
    /// passed, while `ProviderAccount`'s actual Display — the one a refused API
    /// key produces — classified as `Failed`. A test whose vocabulary comes
    /// from the implementation agrees with it by construction.
    #[test]
    fn typed_errors_classify_by_their_structure_not_their_prose() {
        use FallbackReason as R;
        let cases: Vec<(InferenceError, R)> = vec![
            // The single most actionable degrade there is. Its Display carries
            // no "unauthorized" token, which is what the string rule missed.
            (
                InferenceError::ProviderAccount {
                    provider: "openai".into(),
                    status: 401,
                    message: "provider rejected the API key — check the configured credential"
                        .into(),
                },
                R::CredentialRejected,
            ),
            // Out of credits is a billing wait, not a wrong credential.
            (
                InferenceError::ProviderAccount {
                    provider: "openrouter".into(),
                    status: 402,
                    message: "OpenRouter account is out of credits".into(),
                },
                // NOT RateLimited: an empty balance does not clear by waiting.
                R::QuotaExhausted,
            ),
            (
                InferenceError::CredentialUnavailable {
                    provider: "parslee".into(),
                    model: "parslee/reasoning".into(),
                    reason: CredentialFailure::Expired { expires_at: 0 },
                    detail: "session expired".into(),
                },
                R::CredentialRejected,
            ),
            (
                InferenceError::CredentialUnavailable {
                    provider: "openai".into(),
                    model: "openai/gpt-5.6".into(),
                    reason: CredentialFailure::EnvVarMissing {
                        env_var: "OPENAI_API_KEY".into(),
                    },
                    detail: "not set".into(),
                },
                R::CredentialAbsent,
            ),
            // A locked keychain says NOTHING about whether a credential
            // exists, so neither absent nor rejected is honest.
            (
                InferenceError::CredentialUnavailable {
                    provider: "parslee".into(),
                    model: "parslee/reasoning".into(),
                    reason: CredentialFailure::StoreUnreadable,
                    detail: "the bounded Keychain helper timed out".into(),
                },
                R::Failed,
            ),
            (
                InferenceError::Transient {
                    status: Some(429),
                    message: "slow down".into(),
                },
                R::RateLimited,
            ),
            // A statusless transport error is NOT a timeout: the same variant
            // carries connection-refused, DNS and TLS failures, and telling
            // someone their call timed out when the endpoint was never up
            // sends them to raise a timeout instead of starting the runtime.
            (
                InferenceError::Transient {
                    status: None,
                    message: "connection reset by peer".into(),
                },
                R::Failed,
            ),
            (
                InferenceError::Transient {
                    status: Some(503),
                    message: "upstream down".into(),
                },
                R::Failed,
            ),
        ];
        for (err, want) in cases {
            assert_eq!(classify_fallback_reason(&err), want, "{err}");
        }
    }

    /// A provider's error body is text we did not write. It can quote any
    /// status or phrase, and the status line is the only part we control.
    ///
    /// Both cases below are lifted from defects this workspace already fixed
    /// elsewhere: `remote::is_auth_rejection` has a test pinning the 400-that-
    /// quotes-401, and `is_provider_transient` anchors on the parsed status
    /// because of the 400-whose-message-says-timeout.
    #[test]
    fn a_quoted_status_in_a_provider_body_does_not_decide_the_bucket() {
        use FallbackReason as R;
        for (msg, want) in [
            (
                "API returned 400 Bad Request: your last request 401'd upstream and was unauthorized",
                R::Failed,
            ),
            ("API returned 400 Bad Request: timeout param invalid", R::Failed),
            ("API returned 429 Too Many Requests: slow down", R::RateLimited),
            ("API returned 401 Unauthorized: bad key", R::CredentialRejected),
        ] {
            assert_eq!(
                classify_fallback_reason(&InferenceError::InferenceFailed(msg.into())),
                want,
                "{msg}"
            );
        }
    }

    /// `Parslee org lookup failed: HTTP <status>` is emitted for ANY non-success
    /// status, so the phrase alone is not a dead credential — the producer
    /// itself gates `note_credential_rejected()` on 401/403 for this reason.
    #[test]
    fn a_parslee_org_lookup_failure_is_classified_by_its_status() {
        use FallbackReason as R;
        for (msg, want) in [
            (
                "Parslee org lookup failed: HTTP 401 Unauthorized: Authentication required",
                R::CredentialRejected,
            ),
            (
                "Parslee org lookup failed: HTTP 429 Too Many Requests: slow down",
                R::RateLimited,
            ),
            (
                "Parslee org lookup failed: HTTP 500 Internal Server Error: boom",
                R::Failed,
            ),
        ] {
            assert_eq!(
                classify_fallback_reason(&InferenceError::InferenceFailed(msg.into())),
                want,
                "{msg}"
            );
        }
    }

    /// EVERY hop, in order — a chain that skips three lanes made three
    /// transitions, and a single first-wins slot records one while the journal
    /// downstream claims to hold them all.
    #[test]
    fn every_skipped_lane_is_recorded_in_order() {
        let mut hops = Vec::new();
        for (cand, err) in [
            (
                "lane-one",
                InferenceError::Transient {
                    status: Some(429),
                    message: "x".into(),
                },
            ),
            // Statusless transport: `Failed`, not `TimedOut` — the runtime
            // cannot tell a refused connection from a real deadline here.
            (
                "lane-two",
                InferenceError::Transient {
                    status: None,
                    message: "connection refused".into(),
                },
            ),
            (
                "lane-three",
                InferenceError::ProviderAccount {
                    provider: "openai".into(),
                    status: 401,
                    message: "rejected".into(),
                },
            ),
        ] {
            record_fallback_from(&mut hops, cand, &err);
        }
        assert_eq!(
            hops.iter()
                .map(|h| h.candidate.as_str())
                .collect::<Vec<_>>(),
            ["lane-one", "lane-two", "lane-three"]
        );
        assert_eq!(
            hops.iter().map(|h| h.reason).collect::<Vec<_>>(),
            [
                FallbackReason::RateLimited,
                FallbackReason::Failed,
                FallbackReason::CredentialRejected
            ]
        );
    }

    /// `CredentialRejected` is BROADER than `auth_fallback_from`'s predicate,
    /// which is why the two are recorded independently rather than one being
    /// projected from the other.
    ///
    /// A provider refusing an API key is a rejected credential, and the journal
    /// should say so. It is NOT something `car auth login` fixes, so it must
    /// not drive the announcement that says to run it.
    #[test]
    fn a_refused_api_key_is_journaled_but_does_not_claim_sign_in_fixes_it() {
        let refused = InferenceError::ProviderAccount {
            provider: "openai".into(),
            status: 401,
            message: "provider rejected the API key — check the configured credential".into(),
        };
        let mut hops = Vec::new();
        record_fallback_from(&mut hops, "openai/gpt-5.6", &refused);
        assert_eq!(hops[0].reason, FallbackReason::CredentialRejected);

        // The sign-in slot stays empty: this is not a lapsed session.
        let mut auth = None;
        record_auth_dead_lane(&mut auth, "openai/gpt-5.6", &refused.to_string());
        assert_eq!(auth, None, "car auth login does not fix a bad OpenAI key");
    }

    #[test]
    fn auth_dead_lane_records_first_rejected_candidate_only() {
        // Nothing auth-failed → the field stays None, which is the common path.
        let mut slot: Option<String> = None;
        record_auth_dead_lane(
            &mut slot,
            "parslee/reasoning",
            "API returned 503: unavailable",
        );
        record_auth_dead_lane(&mut slot, "openai/gpt-5.6", "request timed out");
        assert_eq!(slot, None);

        // An auth rejection names the lane...
        record_auth_dead_lane(
            &mut slot,
            "parslee/reasoning",
            "Parslee org lookup failed: HTTP 401 Unauthorized: Authentication required",
        );
        assert_eq!(slot.as_deref(), Some("parslee/reasoning"));

        // ...and a LATER rejection does not overwrite it: the first one is the
        // lane the operator configured.
        record_auth_dead_lane(&mut slot, "anthropic/claude", "HTTP 403: forbidden");
        assert_eq!(slot.as_deref(), Some("parslee/reasoning"));
    }

    #[test]
    fn configured_provider_with_expired_token_is_named_before_a_local_oom() {
        let expired = InferenceError::CredentialUnavailable {
            provider: "parslee".into(),
            model: "parslee/reasoning".into(),
            reason: CredentialFailure::Expired { expires_at: 42 },
            detail: "access token expired".into(),
        };
        let mut credential = None;
        record_route_credential_failure(&mut credential, "parslee/reasoning", &expired, false);

        let error = apply_route_failure_context(
            InferenceError::InferenceFailed(
                "This model needs about 9059 MB, beyond the configured 6553 MB local-model allocation"
                    .into(),
            ),
            credential.as_ref(),
        )
        .to_string();

        let auth_pos = error
            .find("Parslee login expired")
            .expect("expired login must be named");
        let remedy_pos = error
            .find("car auth login")
            .expect("credential remedy must be named");
        let oom_pos = error
            .find("9059 MB")
            .expect("fallback error must remain as secondary detail");
        assert!(auth_pos < remedy_pos && remedy_pos < oom_pos, "{error}");
        assert!(is_auth_failure_message(&error), "{error}");
    }

    #[test]
    fn absent_login_is_named_before_a_local_oom() {
        let failure = parslee_signed_out_route_failure();
        let error = apply_route_failure_context(
            InferenceError::InferenceFailed("local fallback needs 9059 MB".into()),
            Some(&failure),
        )
        .to_string();

        let absent_pos = error
            .find("Parslee login is absent")
            .expect("missing login must be named");
        let remedy_pos = error
            .find("car auth login")
            .expect("credential remedy must be named");
        let oom_pos = error
            .find("9059 MB")
            .expect("fallback OOM must remain as secondary detail");
        assert!(absent_pos < remedy_pos && remedy_pos < oom_pos, "{error}");
    }

    #[test]
    fn genuine_local_oom_is_not_reclassified_as_auth() {
        let oom = InferenceError::InferenceFailed(
            "This model needs about 9059 MB, beyond the configured 6553 MB local-model allocation"
                .into(),
        );
        let error = apply_route_failure_context(oom, None);
        assert!(matches!(error, InferenceError::InferenceFailed(ref message)
            if message.starts_with("This model needs about 9059 MB")));
    }

    #[test]
    fn unconfigured_provider_is_not_surfaced_over_the_terminal_failure() {
        let mut credential = None;
        record_route_credential_failure(
            &mut credential,
            "openai/gpt-5.6",
            &InferenceError::CredentialUnavailable {
                provider: "openai".into(),
                model: "openai/gpt-5.6".into(),
                reason: CredentialFailure::EnvVarMissing {
                    env_var: "OPENAI_API_KEY".into(),
                },
                detail: "set OPENAI_API_KEY".into(),
            },
            false,
        );

        let terminal = InferenceError::InferenceFailed(
            "This model needs about 9059 MB, beyond the configured 6553 MB local-model allocation"
                .into(),
        );
        let error = apply_route_failure_context(terminal, credential.as_ref()).to_string();
        assert!(
            credential.is_none(),
            "an unconfigured fallback is ambient noise"
        );
        assert!(error.contains("9059 MB"), "{error}");
        assert!(!error.contains("OPENAI_API_KEY"), "{error}");
        assert!(!is_auth_failure_message(&error), "{error}");
    }

    #[test]
    fn explicitly_requested_missing_credential_uses_the_shared_auth_table() {
        let mut credential = None;
        record_route_credential_failure(
            &mut credential,
            "openai/gpt-5.6",
            &InferenceError::CredentialUnavailable {
                provider: "openai".into(),
                model: "openai/gpt-5.6".into(),
                reason: CredentialFailure::EnvVarMissing {
                    env_var: "OPENAI_API_KEY".into(),
                },
                detail: "set OPENAI_API_KEY".into(),
            },
            true,
        );
        let summary = credential
            .expect("an explicitly requested provider must surface its missing key")
            .summary;
        assert!(summary.contains(AUTH_ENV_MISSING_MARKER), "{summary}");
        assert!(is_auth_failure_message(&summary), "{summary}");
    }

    #[test]
    fn latest_actionable_credential_failure_wins() {
        let mut credential = None;
        record_route_credential_failure(
            &mut credential,
            "parslee/reasoning",
            &InferenceError::ProviderAccount {
                provider: "parslee".into(),
                status: 401,
                message: "Unauthorized".into(),
            },
            false,
        );
        record_route_credential_failure(
            &mut credential,
            "anthropic/claude",
            &InferenceError::CredentialUnavailable {
                provider: "anthropic".into(),
                model: "anthropic/claude".into(),
                reason: CredentialFailure::Expired { expires_at: 43 },
                detail: "configured token expired".into(),
            },
            false,
        );

        assert_eq!(
            credential
                .expect("latest actionable credential cause must be retained")
                .summary,
            "anthropic login expired for `anthropic/claude` — run `car auth login`"
        );
    }

    #[test]
    fn store_unreadable_summary_uses_the_shared_auth_table() {
        let summary = route_credential_failure(
            "parslee/reasoning",
            &InferenceError::CredentialUnavailable {
                provider: "parslee".into(),
                model: "parslee/reasoning".into(),
                reason: CredentialFailure::StoreUnreadable,
                detail: "keychain helper timed out".into(),
            },
            false,
        )
        .expect("an unreadable configured credential store is actionable");
        assert!(summary.contains(AUTH_STORE_UNREADABLE_MARKER), "{summary}");
        assert!(is_auth_failure_message(&summary), "{summary}");
    }

    fn chain_gate_fixture_schema(id: &str, provider: &str, source: ModelSource) -> ModelSchema {
        ModelSchema {
            id: id.into(),
            name: id.into(),
            provider: provider.into(),
            family: "test".into(),
            version: "1".into(),
            capabilities: vec![ModelCapability::Generate],
            context_length: 32_768,
            max_output_tokens: Some(4_096),
            param_count: String::new(),
            quantization: None,
            performance: Default::default(),
            cost: Default::default(),
            source,
            tags: vec![],
            supported_params: vec![],
            public_benchmarks: vec![],
            trust_tier: TrustTier::Community,
            deprecated: false,
            available: true,
            weights_ready: true,
        }
    }

    #[test]
    fn signed_out_pre_seed_is_gated_on_a_parslee_route_in_the_chain() {
        let local = chain_gate_fixture_schema(
            "qwen/qwen3-4b:q4_k_m",
            "qwen",
            ModelSource::Mlx {
                hf_repo: "mlx-community/Qwen3-4B-4bit".into(),
                hf_weight_file: None,
            },
        );
        let ollama = chain_gate_fixture_schema(
            "ollama/llama3",
            "ollama",
            ModelSource::Ollama {
                model_tag: "llama3".into(),
                host: "http://localhost:11434".into(),
            },
        );
        let parslee = chain_gate_fixture_schema(
            "parslee/reasoning",
            "parslee",
            ModelSource::Proprietary {
                provider: "parslee".into(),
                endpoint: "https://api.parslee.ai".into(),
                auth: ProprietaryAuth::OAuth2Pkce {
                    authority: "https://login.example".into(),
                    client_id: "client".into(),
                    scopes: vec![],
                },
                protocol: Default::default(),
            },
        );
        let cloud = chain_gate_fixture_schema(
            "openai/gpt-5.6",
            "openai",
            ModelSource::RemoteApi {
                endpoint: "https://api.openai.com".into(),
                api_key_env: "OPENAI_API_KEY".into(),
                api_key_envs: vec![],
                api_version: None,
                protocol: schema::ApiProtocol::OpenAiCompat,
            },
        );
        let schemas: std::collections::HashMap<&str, &ModelSchema> = [
            ("qwen/qwen3-4b:q4_k_m", &local),
            ("ollama/llama3", &ollama),
            ("parslee/reasoning", &parslee),
            ("openai/gpt-5.6", &cloud),
        ]
        .into_iter()
        .collect();
        let resolve = |m: &str| schemas.get(m).copied();

        // Local weights and local servers resolve no credential: no pre-seed.
        let local_only = vec![
            "qwen/qwen3-4b:q4_k_m".to_string(),
            "ollama/llama3".to_string(),
        ];
        assert!(!chain_includes_parslee_route(resolve, &local_only));

        // Only a Parslee route keeps the Parslee-specific snapshot failure.
        let with_parslee = vec![
            "parslee/reasoning".to_string(),
            "qwen/qwen3-4b:q4_k_m".to_string(),
        ];
        assert!(chain_includes_parslee_route(resolve, &with_parslee));
        let with_cloud = vec![
            "openai/gpt-5.6".to_string(),
            "qwen/qwen3-4b:q4_k_m".to_string(),
        ];
        // An adaptive request with no explicit model can select a configured
        // preferred OpenAI route, then append a local fallback. Neither uses
        // the missing Parslee credential from the routing snapshot.
        assert!(!chain_includes_parslee_route(resolve, &with_cloud));
        let mut credential = chain_includes_parslee_route(resolve, &with_cloud)
            .then(parslee_signed_out_route_failure);
        let outage = InferenceError::Transient {
            status: Some(500),
            message: "OpenAI HTTP 500 Internal Server Error".into(),
        };
        record_route_credential_failure(&mut credential, &with_cloud[0], &outage, false);
        let terminal = apply_route_failure_context(outage, credential.as_ref());
        assert!(matches!(terminal, InferenceError::Transient { .. }));
        assert!(!is_auth_failure_message(&terminal.to_string()));
        let oom = InferenceError::InferenceFailed("local model out of memory".into());
        record_route_credential_failure(&mut credential, &with_cloud[1], &oom, false);
        let terminal = apply_route_failure_context(oom, credential.as_ref()).to_string();
        assert!(!terminal.contains("Parslee"), "{terminal}");
        assert!(!is_auth_failure_message(&terminal), "{terminal}");

        // Discarding the unrelated pre-seed must not discard observed auth.
        record_route_credential_failure(
            &mut credential,
            &with_cloud[0],
            &InferenceError::ProviderAccount {
                provider: "openai".into(),
                status: 401,
                message: "invalid API key".into(),
            },
            false,
        );
        let terminal = apply_route_failure_context(
            InferenceError::InferenceFailed("local model out of memory".into()),
            credential.as_ref(),
        )
        .to_string();
        assert!(terminal.contains("openai"), "{terminal}");
        assert!(!terminal.contains("Parslee"), "{terminal}");
        assert!(is_auth_failure_message(&terminal), "{terminal}");

        // An unknown candidate proves nothing and must not keep the pre-seed.
        let unknown = vec!["missing/model".to_string()];
        assert!(!chain_includes_parslee_route(resolve, &unknown));
    }

    /// The four terminal failures from the review: with the pre-seed gated out
    /// of a local-only chain, none of them may render as a Parslee auth
    /// failure or classify as one.
    #[test]
    fn local_only_terminal_failures_are_not_relabeled_as_auth() {
        let cases = [
            // Local OOM.
            InferenceError::InferenceFailed(
                "This model needs about 9059 MB, beyond the configured 6553 MB local-model allocation"
                    .into(),
            ),
            // HTTP 500 from a local server.
            InferenceError::Transient {
                status: Some(500),
                message: "HTTP 500 Internal Server Error".into(),
            },
            // Crashed llama runner.
            InferenceError::InferenceFailed("llama runner process has terminated".into()),
        ];
        for case in cases {
            let error = apply_route_failure_context(case, None).to_string();
            assert!(!error.contains("Parslee login is absent"), "{error}");
            assert!(!is_auth_failure_message(&error), "{error}");
        }

        // ModelNotFound keeps the pre-existing setup guidance (which names
        // `car auth login` as one of two legitimate remedies) but must not
        // open with a fabricated Parslee sign-out.
        let error = apply_route_failure_context(
            InferenceError::ModelNotFound("qwen/qwen3-4b:q4_k_m".into()),
            None,
        )
        .to_string();
        assert!(!error.contains("Parslee login is absent"), "{error}");
        assert!(error.contains("car models pull"), "{error}");
    }

    /// The credential context wraps the terminal error without flattening its
    /// type — downstream retry/account logic branches on the variant.
    #[test]
    fn credential_context_preserves_the_typed_terminal_variant() {
        let credential = parslee_signed_out_route_failure();

        let transient = apply_route_failure_context(
            InferenceError::Transient {
                status: Some(500),
                message: "HTTP 500 Internal Server Error".into(),
            },
            Some(&credential),
        );
        match &transient {
            InferenceError::Transient { status, message } => {
                assert_eq!(*status, Some(500));
                assert!(message.starts_with("Parslee login is absent"), "{message}");
                assert!(message.contains("HTTP 500"), "{message}");
            }
            other => panic!("Transient must stay Transient, got {other:?}"),
        }

        let account = apply_route_failure_context(
            InferenceError::ProviderAccount {
                provider: "openai".into(),
                status: 402,
                message: "insufficient credits".into(),
            },
            Some(&credential),
        );
        assert!(
            matches!(
                &account,
                InferenceError::ProviderAccount {
                    provider,
                    status: 402,
                    ..
                } if provider == "openai"
            ),
            "ProviderAccount must stay ProviderAccount, got {account:?}"
        );

        let unavailable = apply_route_failure_context(
            InferenceError::CredentialUnavailable {
                provider: "parslee".into(),
                model: "parslee/reasoning".into(),
                reason: CredentialFailure::Expired { expires_at: 42 },
                detail: "access token expired".into(),
            },
            Some(&credential),
        );
        match &unavailable {
            InferenceError::CredentialUnavailable { reason, detail, .. } => {
                assert_eq!(*reason, CredentialFailure::Expired { expires_at: 42 });
                assert!(detail.contains("Parslee login is absent"), "{detail}");
            }
            other => panic!("CredentialUnavailable must keep its reason data, got {other:?}"),
        }
        assert!(is_auth_failure_message(&unavailable.to_string()));
    }

    /// The two non-Parslee summaries introduced by the route aggregation must
    /// classify through the one shared marker table.
    #[test]
    fn non_parslee_rejection_summaries_match_the_shared_classifier() {
        let rejected = route_credential_failure(
            "openai/gpt-5.6",
            &InferenceError::ProviderAccount {
                provider: "openai".into(),
                status: 403,
                message: "key revoked".into(),
            },
            false,
        )
        .expect("a 403 from a configured provider is actionable");
        assert!(rejected.contains("credential was rejected"), "{rejected}");
        assert!(is_auth_failure_message(&rejected), "{rejected}");

        let generic = route_credential_failure(
            "openai/gpt-5.6",
            &InferenceError::InferenceFailed("upstream said: token expired".into()),
            false,
        )
        .expect("an auth-rejection message from a non-Parslee route is actionable");
        assert!(generic.contains("repair its provider login"), "{generic}");
        assert!(is_auth_failure_message(&generic), "{generic}");
    }

    /// A signed-out fresh install exhausts with a no-backend error; the
    /// credential cause must not displace the `car models pull` setup path.
    #[test]
    fn fresh_install_exhaustion_keeps_the_models_pull_guidance() {
        let credential = parslee_signed_out_route_failure();
        let error = apply_route_failure_context(
            InferenceError::InferenceFailed("no models available for generate".into()),
            Some(&credential),
        )
        .to_string();
        assert!(error.contains("Parslee login is absent"), "{error}");
        assert!(
            error.contains("car models pull qwen/qwen3-4b:q4_k_m"),
            "{error}"
        );
        assert!(error.contains("car auth login"), "{error}");
    }

    /// The field is absent from the wire on the common path (so no existing
    /// client sees a new key) and present when a lane was skipped.
    #[test]
    fn auth_fallback_from_round_trips_and_defaults_to_none() {
        let mut result: InferenceResult = serde_json::from_value(serde_json::json!({
            "text": "hi",
            "tool_calls": [],
            "trace_id": "t",
            "model_used": "openai/gpt-5.6",
            "latency_ms": 1,
        }))
        .expect("a payload without the field still deserializes");
        assert_eq!(result.auth_fallback_from, None);
        let json = serde_json::to_value(&result).unwrap();
        assert!(json.get("auth_fallback_from").is_none());

        result.auth_fallback_from = Some("parslee/reasoning".to_string());
        let json = serde_json::to_value(&result).unwrap();
        assert_eq!(json["auth_fallback_from"], "parslee/reasoning");
        let back: InferenceResult = serde_json::from_value(json).unwrap();
        assert_eq!(
            back.auth_fallback_from.as_deref(),
            Some("parslee/reasoning")
        );
    }

    /// A successful turn carries both the exact model that served it and an
    /// explicit marker when that model was the appended on-device last resort.
    /// The marker defaults false for older payloads, so this is additive on the
    /// wire rather than making old clients invent attribution.
    #[test]
    fn local_last_resort_turn_carries_model_id_and_flag() {
        let ordinary: InferenceResult = serde_json::from_value(serde_json::json!({
            "text": "hi",
            "tool_calls": [],
            "trace_id": "ordinary",
            "model_used": "anthropic/claude-haiku-4-5:latest",
            "latency_ms": 1,
        }))
        .expect("older payloads default the marker");
        assert!(!ordinary.local_last_resort);

        let fallback: InferenceResult = serde_json::from_value(serde_json::json!({
            "text": "offline answer",
            "tool_calls": [],
            "trace_id": "fallback",
            "model_used": "Qwen3 4B MLX",
            "resolved_model_id": "mlx/qwen3-4b:4bit",
            "latency_ms": 1,
            "local_last_resort": true,
        }))
        .expect("fallback attribution payload");
        assert_eq!(fallback.served_model_id(), "mlx/qwen3-4b:4bit");
        assert!(fallback.local_last_resort);

        assert!(!is_local_last_resort(None, "mlx/qwen3-4b:4bit"));
        assert!(report_local_last_resort_served(
            Some("mlx/qwen3-4b:4bit"),
            "mlx/qwen3-4b:4bit",
            "mlx/qwen3-4b:4bit"
        ));
        assert!(!is_local_last_resort(
            Some("mlx/qwen3-4b:4bit"),
            "anthropic/claude-haiku-4-5:latest"
        ));
    }

    #[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(());

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

        let _environment = ENV_MUTEX.lock().await;
        let _restore = RestoredEnvironment::capture(&["CAR_CODEX_BIN", "OPENAI_API_KEY"]);
        let tmp = TempDir::new().unwrap();
        let fixture = tmp.path().join("codex-fixture.sh");
        std::fs::write(
            &fixture,
            r#"#!/bin/sh
if [ -n "${OPENAI_API_KEY-}" ]; then
  echo 'OPENAI_API_KEY leaked' >&2
  exit 91
fi
cat >/dev/null
printf '%s\n' '{"type":"turn.started"}'
printf '%s\n' '{"type":"item.completed","item":{"type":"agent_message","text":"fixture newsroom answer"}}'
printf '%s\n' '{"type":"turn.completed","usage":{"input_tokens":17,"output_tokens":5}}'
"#,
        )
        .unwrap();
        std::fs::set_permissions(&fixture, std::fs::Permissions::from_mode(0o700)).unwrap();
        unsafe {
            std::env::set_var("CAR_CODEX_BIN", &fixture);
            std::env::set_var("OPENAI_API_KEY", "must-not-reach-codex");
        }

        let engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let mut request = GenerateRequest {
            prompt: "write a brief".into(),
            params: GenerateParams {
                max_tokens: 1056,
                strict_model: true,
                ..Default::default()
            },
            ..Default::default()
        };
        pin_exact_model_id(&mut request, "openai/gpt-5.6-sol:high".into()).unwrap();
        let result = engine.generate_tracked(request).await.unwrap();

        assert_eq!(result.model_used, "openai/gpt-5.6-sol:high");
        assert_eq!(result.text, "fixture newsroom answer");
        assert_eq!(result.usage.as_ref().unwrap().total_tokens, 22);
        assert_eq!(result.stop_reason, None, "Codex reports no finish reason");
        assert!(result.tool_calls.is_empty());
    }

    #[tokio::test]
    async fn isolated_test_child_removes_parent_auth_lock_override() {
        const CHILD_SENTINEL: &str = "CAR_AUTH_LOCK_SANITIZER_CHILD";
        if std::env::var_os(CHILD_SENTINEL).is_some() {
            assert!(
                std::env::var_os("CAR_AUTH_LOCK_PATH").is_none(),
                "an isolated credential test must not inherit the invoking process's auth lock"
            );
            return;
        }

        let _environment = ENV_MUTEX.lock().await;
        let _restore = RestoredEnvironment::capture(&["CAR_AUTH_LOCK_PATH"]);
        unsafe {
            std::env::set_var(
                "CAR_AUTH_LOCK_PATH",
                "/sentinel/must-not-reach-isolated-child.lock",
            );
        }
        assert!(!crate::run_in_isolated_test_process(
            "tests::isolated_test_child_removes_parent_auth_lock_override",
            CHILD_SENTINEL,
        ));
    }

    fn test_config(models_dir: PathBuf) -> InferenceConfig {
        // Keep every state file inside the test's own tree: the state root is
        // the models dir's parent, so `state_models_dir()` lands back on
        // `models_dir` exactly as it did before the root was split out.
        let state_root = models_dir
            .parent()
            .map(Path::to_path_buf)
            .unwrap_or_else(|| models_dir.clone());
        InferenceConfig {
            models_dir,
            state_root,
            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,
        }
    }

    fn metal_mac_for_fit(ram_gb: u64) -> HardwareInfo {
        HardwareInfo {
            os: "macos".into(),
            arch: "aarch64".into(),
            cpu_cores: 8,
            total_ram_mb: ram_gb * 1024,
            gpu_backend: crate::hardware::GpuBackend::Metal,
            gpu_memory_mb: None,
            gpu_devices: vec![],
            recommended_model: String::new(),
            recommended_context: 8_192,
            max_model_mb: 0,
        }
    }

    /// car#1399: the unified catalog is annotated for the machine it is
    /// asked about, without any row being dropped, reordered, or otherwise
    /// changed. Under Everyday (40% of unified memory) the builtin
    /// `mlx/qwen3-8b:4bit` (~6.3 GB at the recommendation context) is too
    /// big for an 8 GB Mac and fits a 32 GB one; a deprecated row stays
    /// listed and says so.
    #[test]
    fn unified_rows_carry_fit_per_machine_and_keep_deprecated_rows() {
        // Pin OpenRouter credential availability for BOTH snapshots below.
        // The remote-row set depends on whether a credential resolves, and
        // that resolution is process-global — a parallel test flipping the
        // override between the at_8 and at_32 listings made the two id sets
        // differ with nothing wrong in the catalog (car-sap7, and the trace
        // on the bead: availability differed between two snapshots).
        let _credential_scope = crate::openrouter::test_credential_scope();
        crate::openrouter::set_test_credential(Some("unified-rows-fit-test-key"));
        let root = tempfile::tempdir().unwrap();
        let config = test_config(root.path().join("weights"));
        let mut engine = InferenceEngine::new(config);
        let mut retired = engine
            .list_schemas()
            .into_iter()
            .find(|schema| schema.id == "mlx/qwen3-4b:4bit")
            .expect("builtin 4B MLX row");
        retired.id = "test/retired-4b:4bit".into();
        retired.name = "Retired 4B".into();
        retired.deprecated = true;
        engine.register_model(retired);
        let policy = resource_policy::ResourcePolicy::everyday();

        let at_8 = engine.list_models_unified_for(&metal_mac_for_fit(8), &policy);
        let at_32 = engine.list_models_unified_for(&metal_mac_for_fit(32), &policy);
        let ids = |rows: &[ModelInfo]| rows.iter().map(|row| row.id.clone()).collect::<Vec<_>>();
        assert_eq!(
            ids(&at_8),
            ids(&at_32),
            "the machine never removes or reorders a row"
        );
        let row = |rows: &[ModelInfo], id: &str| {
            rows.iter()
                .find(|row| row.id == id)
                .unwrap_or_else(|| panic!("{id} missing"))
                .clone()
        };

        let eight_b_small = row(&at_8, "mlx/qwen3-8b:4bit");
        let eight_b_large = row(&at_32, "mlx/qwen3-8b:4bit");
        assert_eq!(eight_b_small.fit, ModelFitStatus::TooBig);
        assert_eq!(eight_b_large.fit, ModelFitStatus::Fits);
        assert!(eight_b_small.platform_compatible && eight_b_large.platform_compatible);
        assert_eq!(
            eight_b_small.estimated_peak_mb, eight_b_large.estimated_peak_mb,
            "the estimate is the model's; only the budget differs"
        );
        assert!(eight_b_small.estimated_peak_mb.is_some_and(|mb| mb > 4_800));
        assert_eq!(eight_b_small.family.as_deref(), Some("qwen3"));
        assert!(eight_b_small.version.is_some());

        let retired = row(&at_8, "test/retired-4b:4bit");
        assert!(retired.deprecated, "deprecated rows stay listed, flagged");
        assert!(!eight_b_small.deprecated);

        let mut saw_remote = false;
        for remote in at_8.iter().filter(|row| !row.is_local) {
            saw_remote = true;
            assert_eq!(remote.fit, ModelFitStatus::Fits, "{}", remote.id);
            assert!(remote.platform_compatible, "{}", remote.id);
            assert_eq!(remote.estimated_peak_mb, None, "{}", remote.id);
            assert_eq!(
                remote.family, None,
                "{}: no upstream identifier here",
                remote.id
            );
            assert_eq!(remote.version, None, "{}", remote.id);
        }
        assert!(saw_remote);

        // Every existing field is byte-identical across machines: strip the
        // three fit keys and the rows must serialize the same.
        for (small, large) in at_8.iter().zip(&at_32) {
            let strip = |row: &ModelInfo| {
                let mut value = serde_json::to_value(row).unwrap();
                let object = value.as_object_mut().unwrap();
                for key in ["fit", "estimated_peak_mb", "platform_compatible"] {
                    object.remove(key);
                }
                value
            };
            assert_eq!(strip(small), strip(large), "{}", small.id);
        }
    }

    #[tokio::test]
    async fn explicit_model_blocked_by_zero_budget_does_not_substitute_or_download() {
        let root = tempfile::tempdir().unwrap();
        let models_dir = root.path().join("weights");
        let config = test_config(models_dir.clone());
        let repository =
            crate::resource_policy::FileResourcePolicyRepository::new(config.state_root.clone());
        crate::resource_policy::ResourcePolicyRepository::save(
            &repository,
            &crate::resource_policy::ResourcePolicy::custom_gb(0.0).unwrap(),
        )
        .unwrap();
        let engine = InferenceEngine::new(config);

        let error = engine
            .generate_tracked(GenerateRequest {
                prompt: "hello".into(),
                model: Some("mlx/qwen3-4b:4bit".into()),
                ..Default::default()
            })
            .await
            .unwrap_err();

        assert!(matches!(
            error,
            InferenceError::LocalResourceBlocked {
                preflight: crate::resource_policy::LocalLoadPreflight {
                    verdict: crate::resource_policy::LocalLoadVerdict::DisabledByPolicy,
                    ..
                },
                ..
            }
        ));
        assert!(
            !models_dir.exists() || std::fs::read_dir(models_dir).unwrap().next().is_none(),
            "admission must happen before download/load"
        );
    }

    #[tokio::test]
    async fn external_vllm_mlx_bypasses_local_admission_while_managed_artifact_does_not() {
        let schema = crate::vllm_mlx::to_model_schema(
            &crate::vllm_mlx::DiscoveredModel {
                id: "mlx-community/Qwen3-4B-4bit".into(),
                owned_by: None,
            },
            "http://localhost:8000",
        );
        assert!(!InferenceEngine::requires_local_admission(&schema));

        let root = tempfile::tempdir().unwrap();
        let config = test_config(root.path().join("weights"));
        let repository =
            crate::resource_policy::FileResourcePolicyRepository::new(config.state_root.clone());
        crate::resource_policy::ResourcePolicyRepository::save(
            &repository,
            &crate::resource_policy::ResourcePolicy::custom_gb(0.0).unwrap(),
        )
        .unwrap();
        let engine = InferenceEngine::new(config);
        let (external, reservation) = engine
            .vllm_live_schema(schema.clone(), None, 0)
            .await
            .unwrap();
        assert!(matches!(
            external.source,
            ModelSource::VllmMlx { ref endpoint, .. } if endpoint == "http://localhost:8000"
        ));
        assert!(reservation.is_none());

        let mut managed = schema;
        managed.source = ModelSource::ManagedVllmMlx {
            hf_repo: "mlx-community/Qwen3-4B-4bit".into(),
            hf_weight_file: None,
        };
        assert!(InferenceEngine::requires_local_admission(&managed));
        let error = engine
            .reserve_local_request(&managed, 0)
            .expect_err("zero-GB policy must reject before vllm runtime/download/spawn");
        assert!(matches!(
            error,
            InferenceError::LocalResourceBlocked {
                preflight: crate::resource_policy::LocalLoadPreflight {
                    verdict: crate::resource_policy::LocalLoadVerdict::DisabledByPolicy,
                    ..
                },
                ..
            }
        ));
    }

    #[cfg(unix)]
    async fn assert_concurrent_managed_vllm_dispatch_waits_before_outer_reservation(
        streaming: bool,
        cancel_first: bool,
    ) {
        struct FixedProbe;
        impl crate::resource_policy::LiveMemoryProbe for FixedProbe {
            fn available_memory_mb(
                &self,
            ) -> Result<Option<u64>, crate::resource_policy::ResourcePolicyError> {
                Ok(Some(24_000))
            }
        }

        let Some(python) = crate::vllm_runtime::test_python_interpreter() else {
            panic!("a real Python interpreter is required for the managed-vllm dispatch fixture");
        };
        let root = tempfile::tempdir().unwrap();
        let script = root.path().join("fake-vllm-mlx");
        let spawned = root.path().join("spawned");
        let release = root.path().join("release");
        std::fs::write(
            &script,
            format!(
                "#!{}\n\
                 import http.server, os, sys, time\n\
                 marker = {:?}\n\
                 release = {:?}\n\
                 open(marker, 'w').close()\n\
                 while not os.path.exists(release): time.sleep(0.01)\n\
                 port = int(sys.argv[sys.argv.index('--port') + 1])\n\
                 class H(http.server.BaseHTTPRequestHandler):\n\
                 \x20   def do_GET(self):\n\
                 \x20       self.send_response(200); self.end_headers(); self.wfile.write(b'ok')\n\
                 \x20   def do_POST(self):\n\
                 \x20       length = int(self.headers.get('content-length', '0'))\n\
                 \x20       request = self.rfile.read(length).replace(b' ', b'')\n\
                 \x20       if b'\"stream\":true' in request:\n\
                 \x20           body = b'data: {{\"id\":\"fixture\",\"object\":\"chat.completion.chunk\",\"created\":0,\"model\":\"fixture\",\"choices\":[{{\"index\":0,\"delta\":{{\"content\":\"round13-stream\"}},\"finish_reason\":null}}]}}\\n\\ndata: {{\"id\":\"fixture\",\"object\":\"chat.completion.chunk\",\"created\":0,\"model\":\"fixture\",\"choices\":[{{\"index\":0,\"delta\":{{}},\"finish_reason\":\"stop\"}}]}}\\n\\ndata: [DONE]\\n\\n'\n\
                 \x20           content_type = 'text/event-stream'\n\
                 \x20       else:\n\
                 \x20           body = b'{{\"id\":\"fixture\",\"object\":\"chat.completion\",\"created\":0,\"model\":\"fixture\",\"choices\":[{{\"index\":0,\"message\":{{\"role\":\"assistant\",\"content\":\"round13-ok\"}},\"finish_reason\":\"stop\"}}],\"usage\":{{\"prompt_tokens\":1,\"completion_tokens\":1,\"total_tokens\":2}}}}'\n\
                 \x20           content_type = 'application/json'\n\
                 \x20       self.send_response(200); self.send_header('content-type', content_type); self.send_header('content-length', str(len(body))); self.end_headers(); self.wfile.write(body)\n\
                 \x20   def log_message(self, *args): pass\n\
                 http.server.HTTPServer(('127.0.0.1', port), H).serve_forever()\n",
                python.display(),
                spawned.display().to_string(),
                release.display().to_string(),
            ),
        )
        .unwrap();
        use std::os::unix::fs::PermissionsExt;
        std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();

        let models_dir = root.path().join("models");
        let mut engine = InferenceEngine::new(test_config(models_dir.clone()));
        let mut schema = crate::registry::builtin_catalog()
            .into_iter()
            .find(ModelSchema::is_car_managed_vllm_mlx)
            .expect("managed vllm fixture schema");
        schema.id = "vllm-mlx/round12-singleflight".into();
        schema.name = "round12-singleflight".into();
        schema.cost.size_mb = Some(1);
        schema.cost.ram_mb = Some(1);
        schema.source = ModelSource::ManagedVllmMlx {
            hf_repo: "fixture/round12-singleflight".into(),
            hf_weight_file: None,
        };
        let model_dir = models_dir.join(&schema.name);
        std::fs::create_dir_all(&model_dir).unwrap();
        std::fs::write(model_dir.join("config.json"), b"{}").unwrap();
        std::fs::write(model_dir.join("model.safetensors"), b"fixture").unwrap();
        engine
            .unified_registry
            .register_project_model(schema.clone());

        let coordinator = Arc::new(
            crate::resource_policy::LocalAdmissionCoordinator::with_probe(
                // Two concurrent Linux requests each carry 1 GiB of runtime
                // overhead plus context/transient headroom. Keep the fixture
                // above that platform-specific total so this test exercises
                // dispatch singleflight rather than an unrelated ceiling.
                crate::resource_policy::ResourcePolicy::custom_gb(8.0).unwrap(),
                crate::hardware::HardwareInfo::detect(),
                Arc::new(FixedProbe),
            ),
        );
        engine.local_admission = coordinator.clone();
        engine.vllm_pool = Arc::new(crate::vllm_pool::VllmServerPool::with_test_runtime(
            std::time::Duration::from_secs(300),
            coordinator,
            script,
        ));
        let engine = Arc::new(engine);
        let model_id = schema.id.clone();
        let mut request = GenerateRequest {
            prompt: "hello from round 13".into(),
            model: Some(model_id.clone()),
            ..Default::default()
        };
        // A fixture failure must stay a fixture failure. Without strict model
        // routing, the streaming case escaped to a configured provider and
        // returned real, nondeterministic prose instead of exercising this
        // managed-vLLM singleflight path.
        request.params.strict_model = true;
        let (estimated_input, _, _) = engine.estimated_tokens(&request, Some(&model_id));
        let expected_footprint = estimated_input.saturating_add(request.params.max_tokens);
        let expected_estimate = engine
            .local_model_preflight(&model_id, expected_footprint)
            .unwrap()
            .estimate;
        let expected_request_overhead_mb = expected_estimate
            .runtime_overhead_mb
            .saturating_add(expected_estimate.context_overhead_mb)
            .saturating_add(expected_estimate.transient_margin_mb);

        async fn execute(
            engine: Arc<InferenceEngine>,
            request: GenerateRequest,
            streaming: bool,
            direct_vllm: bool,
        ) -> Result<String, InferenceError> {
            if direct_vllm {
                let model_id = request.model.as_deref().expect("explicit fixture model");
                let schema = engine
                    .unified_registry
                    .get(model_id)
                    .cloned()
                    .expect("fixture schema");
                let (schema, _) = engine.vllm_live_schema(schema, None, 0).await?;
                return match schema.source {
                    ModelSource::VllmMlx { endpoint, .. } => Ok(endpoint),
                    source => Err(InferenceError::InferenceFailed(format!(
                        "fixture did not resolve to a vllm endpoint: {source:?}"
                    ))),
                };
            }
            if !streaming {
                return engine
                    .generate_tracked(request)
                    .await
                    .map(|result| result.text);
            }
            let mut tracked = engine.generate_tracked_stream(request).await?;
            let mut accumulator = crate::stream::StreamAccumulator::default();
            while let Some(event) = tracked.events.recv().await {
                let done = matches!(event, crate::stream::StreamEvent::Done { .. });
                accumulator.push(&event);
                if done {
                    break;
                }
            }
            Ok(accumulator.finish().0)
        }

        let first_engine = engine.clone();
        let first_request = request.clone();
        let mut first = tokio::spawn(async move {
            execute(first_engine, first_request, streaming, cancel_first).await
        });
        tokio::time::timeout(std::time::Duration::from_secs(5), async {
            while !spawned.exists() {
                if first.is_finished() {
                    let result = (&mut first).await;
                    panic!("first dispatch ended before spawn: {result:?}");
                }
                tokio::time::sleep(std::time::Duration::from_millis(5)).await;
            }
        })
        .await
        .expect("first request must spawn before publication");
        if !cancel_first {
            let during_startup = engine.local_model_preflight(&model_id, 0).unwrap();
            assert_eq!(
                during_startup.active_reservations_mb, expected_request_overhead_mb,
                "the cold-to-pending transfer must retain all request context/KV overhead"
            );
            assert_eq!(
                during_startup.resident_model_mb, expected_estimate.weights_mb,
                "the pending allocation must replace the exact cold-weight charge"
            );
            assert_eq!(
                during_startup
                    .active_reservations_mb
                    .saturating_add(during_startup.resident_model_mb),
                expected_estimate.estimated_peak_mb,
                "active request overhead plus pending weights must preserve the full admitted footprint"
            );
        }

        let second_engine = engine.clone();
        let mut second =
            tokio::spawn(
                async move { execute(second_engine, request, streaming, cancel_first).await },
            );
        assert!(
            tokio::time::timeout(std::time::Duration::from_millis(100), &mut second)
                .await
                .is_err(),
            "request 2 must wait for request 1 to publish instead of failing on startup state"
        );

        let first_result = if cancel_first {
            std::fs::remove_file(&spawned).unwrap();
            first.abort();
            let _ = first.await;
            tokio::time::timeout(std::time::Duration::from_secs(5), async {
                while !spawned.exists() {
                    if second.is_finished() {
                        let result = (&mut second).await;
                        panic!("waiter ended before replacement spawn: {result:?}");
                    }
                    tokio::time::sleep(std::time::Duration::from_millis(5)).await;
                }
            })
            .await
            .expect("waiter must continue after cancelled owner teardown");
            None
        } else {
            std::fs::write(&release, b"release").unwrap();
            Some(
                tokio::time::timeout(std::time::Duration::from_secs(5), first)
                    .await
                    .expect("first dispatch completes")
                    .unwrap()
                    .unwrap(),
            )
        };
        std::fs::write(&release, b"release").unwrap();
        let second_result = tokio::time::timeout(std::time::Duration::from_secs(5), second)
            .await
            .expect("second dispatch completes")
            .unwrap()
            .unwrap();
        let expected = if cancel_first {
            None
        } else if streaming {
            Some("round13-stream")
        } else {
            Some("round13-ok")
        };
        if let (Some(first_result), Some(expected)) = (first_result, expected) {
            assert_eq!(first_result, expected);
        }
        if let Some(expected) = expected {
            assert_eq!(second_result, expected);
        } else {
            assert!(second_result.starts_with("http://127.0.0.1:"));
        }
        assert_eq!(engine.vllm_pool.len().await, 1);
        assert!(engine
            .vllm_pool
            .release_model_if_present(&model_id)
            .await
            .unwrap());
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn concurrent_managed_vllm_generate_waits_before_outer_reservation() {
        assert_concurrent_managed_vllm_dispatch_waits_before_outer_reservation(false, false).await;
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn concurrent_managed_vllm_stream_waits_before_outer_reservation() {
        assert_concurrent_managed_vllm_dispatch_waits_before_outer_reservation(true, false).await;
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn managed_vllm_waiter_continues_after_startup_owner_cancellation() {
        assert_concurrent_managed_vllm_dispatch_waits_before_outer_reservation(false, true).await;
    }

    #[tokio::test]
    async fn same_state_root_engines_share_runtime_components() {
        const CHILD_ENV: &str = "CAR_TWO_ENGINE_RUNTIME_TEST_CHILD";
        if std::env::var_os(CHILD_ENV).is_some() {
            tokio::time::sleep(std::time::Duration::from_secs(60)).await;
            return;
        }
        let root = tempfile::tempdir().unwrap();
        let first = InferenceEngine::new(test_config(root.path().join("weights")));
        let second = InferenceEngine::new(test_config(root.path().join("weights")));

        assert!(Arc::ptr_eq(&first.model_budget, &second.model_budget));
        assert!(Arc::ptr_eq(&first.vllm_pool, &second.vllm_pool));
        assert!(Arc::ptr_eq(
            &first.resource_policy_generation,
            &second.resource_policy_generation
        ));
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        {
            assert!(Arc::ptr_eq(&first.mlx_backends, &second.mlx_backends));
            assert!(Arc::ptr_eq(&first.local_backends, &second.local_backends));
            assert!(Arc::ptr_eq(&first.flux_cache, &second.flux_cache));
            assert!(Arc::ptr_eq(&first.ltx_cache, &second.ltx_cache));
            assert!(Arc::ptr_eq(&first.kokoro_cache, &second.kokoro_cache));
        }
        #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
        {
            assert!(Arc::ptr_eq(&first.backend, &second.backend));
            assert!(Arc::ptr_eq(
                &first.embedding_backend,
                &second.embedding_backend
            ));
        }

        let loads = Arc::new(std::sync::atomic::AtomicU64::new(0));
        let first_cache = first._runtime_scope.load_probe.clone();
        let second_cache = second._runtime_scope.load_probe.clone();
        let mut threads = Vec::new();
        for cache in [first_cache, second_cache] {
            let loads = loads.clone();
            threads.push(std::thread::spawn(move || {
                cache
                    .get_or_load::<()>("same/model", 1, || {
                        loads.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
                        std::thread::sleep(std::time::Duration::from_millis(20));
                        Ok(())
                    })
                    .unwrap()
            }));
        }
        let handles = threads
            .into_iter()
            .map(|thread| thread.join().unwrap())
            .collect::<Vec<_>>();
        assert_eq!(loads.load(std::sync::atomic::Ordering::SeqCst), 1);
        assert!(Arc::ptr_eq(&handles[0], &handles[1]));

        let child = tokio::process::Command::new(std::env::current_exe().unwrap())
            .arg("--exact")
            .arg("tests::same_state_root_engines_share_runtime_components")
            .env(CHILD_ENV, "1")
            .stdin(std::process::Stdio::null())
            .stdout(std::process::Stdio::null())
            .stderr(std::process::Stdio::null())
            .kill_on_drop(true)
            .spawn()
            .unwrap();
        first
            .vllm_pool
            .insert_test_process("vllm-mlx/two-engine", child)
            .await;
        first.local_admission.mark_resident_allocation(
            "vllm-mlx/two-engine",
            &resource_policy::vllm_process_allocation_id("vllm-mlx/two-engine"),
            1,
        );
        assert!(second.vllm_pool.contains("vllm-mlx/two-engine").await);
        drop(first);
        assert!(second.vllm_pool.contains("vllm-mlx/two-engine").await);
        assert!(second.local_admission.is_resident("vllm-mlx/two-engine"));
        assert!(second.vllm_pool.evict_model("vllm-mlx/two-engine").await);
        assert!(!second.local_admission.is_resident("vllm-mlx/two-engine"));
    }

    #[tokio::test]
    async fn last_engine_drop_reaps_vllm_before_new_runtime_admission() {
        const CHILD_ENV: &str = "CAR_LAST_ENGINE_VLLM_DROP_TEST_CHILD";
        if std::env::var_os(CHILD_ENV).is_some() {
            tokio::time::sleep(std::time::Duration::from_secs(60)).await;
            return;
        }
        let root = tempfile::tempdir().unwrap();
        let config = test_config(root.path().join("weights"));
        let engine = InferenceEngine::new(config.clone());
        let coordinator = engine.local_admission.clone();
        let schema = engine
            .unified_registry
            .all()
            .find(|schema| schema.is_vllm_mlx())
            .cloned()
            .expect("supervised vllm schema");
        let child = tokio::process::Command::new(std::env::current_exe().unwrap())
            .arg("--exact")
            .arg("tests::last_engine_drop_reaps_vllm_before_new_runtime_admission")
            .env(CHILD_ENV, "1")
            .stdin(std::process::Stdio::null())
            .stdout(std::process::Stdio::null())
            .stderr(std::process::Stdio::null())
            .kill_on_drop(true)
            .spawn()
            .unwrap();
        engine
            .vllm_pool
            .insert_test_process(&schema.id, child)
            .await;
        coordinator.mark_resident_allocation(
            &schema.id,
            &resource_policy::vllm_process_allocation_id(&schema.id),
            1,
        );

        drop(engine);

        tokio::time::timeout(std::time::Duration::from_secs(2), async {
            while coordinator.teardown_pending(&schema.id) {
                tokio::time::sleep(std::time::Duration::from_millis(10)).await;
            }
        })
        .await
        .expect("last runtime drop must eventually confirm supervised child exit");
        assert!(!coordinator.is_resident(&schema.id));
        let next = InferenceEngine::new(config);
        assert!(Arc::ptr_eq(&coordinator, &next.local_admission));
        let preflight = next.local_model_preflight(&schema.id, 0).unwrap();
        assert_eq!(preflight.resident_model_mb, 0);
        assert!(preflight.estimated_incremental_mb >= preflight.estimate.weights_mb);
    }

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

        let fixture = tempfile::tempdir().unwrap();
        let real = fixture.path().join("real-state");
        std::fs::create_dir(&real).unwrap();
        let alias = fixture.path().join("state-alias");
        symlink(&real, &alias).unwrap();

        let first = InferenceEngine::new(test_config(real.join("weights")));
        let second = InferenceEngine::new(test_config(alias.join("weights")));
        assert!(Arc::ptr_eq(&first.local_admission, &second.local_admission));
        assert!(Arc::ptr_eq(&first._runtime_scope, &second._runtime_scope));
        assert!(Arc::ptr_eq(&first.model_budget, &second.model_budget));
    }

    #[tokio::test]
    async fn stream_reservation_lives_until_returned_receiver_is_released() {
        let root = tempfile::tempdir().unwrap();
        let engine = InferenceEngine::new(test_config(root.path().join("weights")));
        let schema = crate::registry::builtin_catalog()
            .into_iter()
            .find(|schema| schema.is_local() && !schema.is_vllm_mlx())
            .expect("local model schema");
        engine.local_admission.mark_resident(&schema.id, 1);
        let reservation = engine.reserve_local_request(&schema, 64).unwrap();
        assert_eq!(engine.local_admission.active_request_count(&schema.id), 1);
        let (source_tx, source_rx) = tokio::sync::mpsc::channel(1);
        let returned =
            InferenceEngine::hold_optional_reservation_for_stream(source_rx, Some(reservation));

        drop(returned);
        source_tx
            .send(stream::StreamEvent::TextDelta("release".into()))
            .await
            .unwrap();
        for _ in 0..20 {
            if engine.local_admission.active_request_count(&schema.id) == 0 {
                break;
            }
            tokio::task::yield_now().await;
        }
        assert_eq!(engine.local_admission.active_request_count(&schema.id), 0);

        let compact_source = include_str!("lib.rs")
            .split_whitespace()
            .collect::<String>();
        let remote_handoff = [
            "Self::hold_optional_reservation_for_stream",
            "(receiver,",
            "candidate_reservation.take(),",
            ");",
        ]
        .concat();
        assert!(compact_source.contains(&remote_handoff));
    }

    #[tokio::test]
    async fn residual_voice_allocation_blocks_removal_with_typed_error() {
        let root = tempfile::tempdir().unwrap();
        let engine = InferenceEngine::new(test_config(root.path().join("weights")));
        engine
            .local_admission
            .mark_resident("voice/removal-fixture", 1);

        let error = match engine
            .prepare_local_model_removal("voice/removal-fixture")
            .await
        {
            Err(error) => error,
            Ok(_) => panic!("voice allocation must be released by its owner first"),
        };
        assert!(matches!(
            error,
            crate::resource_policy::ModelMaintenanceError::ResidualResidency {
                model_id,
                allocation_ids,
            } if model_id == "voice/removal-fixture"
                && allocation_ids == vec!["voice/removal-fixture"]
        ));
    }

    #[tokio::test]
    async fn catalog_voice_id_blocks_removal_of_live_provider_alias() {
        let root = tempfile::tempdir().unwrap();
        let engine = InferenceEngine::new(test_config(root.path().join("weights")));
        engine.local_admission.register_model_aliases(
            "voice/parakeet-tdt-0.6b",
            ["mlx/parakeet-tdt-0.6b-v3:default"],
        );
        let mut reservation = engine
            .local_admission
            .reserve_measured_host_allocation(
                "voice/parakeet-tdt-0.6b",
                "voice/parakeet-tdt-0.6b#voice-allocation-0",
                1024 * 1024,
                0,
            )
            .unwrap();
        reservation.publish_resident_weights(1024 * 1024);
        drop(reservation);

        let result = engine
            .prepare_local_model_removal("mlx/parakeet-tdt-0.6b-v3:default")
            .await;
        assert!(matches!(
            result,
            Err(crate::resource_policy::ModelMaintenanceError::ResidualResidency { .. })
        ));
    }

    struct RefusingRemovalOffload;

    #[async_trait::async_trait]
    impl crate::offload::LocalGenerationOffload for RefusingRemovalOffload {
        async fn generate(
            &self,
            _request: GenerateRequest,
        ) -> Result<InferenceResult, InferenceError> {
            unreachable!("removal test does not generate")
        }

        async fn stream(
            &self,
            _request: GenerateRequest,
        ) -> Result<tokio::sync::mpsc::Receiver<StreamEvent>, InferenceError> {
            unreachable!("removal test does not stream")
        }

        async fn resident_models(&self) -> Vec<String> {
            vec!["worker/refuses-release".into()]
        }

        async fn release_model(&self, _model_id: &str) -> Result<bool, InferenceError> {
            Ok(false)
        }
    }

    #[tokio::test]
    async fn worker_release_boolean_is_required_for_model_removal() {
        let _offload_guard = crate::offload::test_offload_lock().lock().await;
        crate::offload::set_local_offload(Some(Arc::new(RefusingRemovalOffload)));
        let root = tempfile::tempdir().unwrap();
        let engine = InferenceEngine::new(test_config(root.path().join("weights")));
        let result = engine
            .prepare_local_model_removal("worker/refuses-release")
            .await;
        crate::offload::set_local_offload(None);

        assert!(matches!(
            result,
            Err(crate::resource_policy::ModelMaintenanceError::WorkerReleaseUnacknowledged(
                model_id
            )) if model_id == "worker/refuses-release"
        ));
    }

    #[test]
    fn transient_mlx_vlm_allocation_never_becomes_resident() {
        struct FixedProbe;
        impl crate::resource_policy::LiveMemoryProbe for FixedProbe {
            fn available_memory_mb(
                &self,
            ) -> Result<Option<u64>, crate::resource_policy::ResourcePolicyError> {
                Ok(Some(24_000))
            }
        }

        let root = tempfile::tempdir().unwrap();
        let mut engine = InferenceEngine::new(test_config(root.path().join("weights")));
        engine.local_admission = Arc::new(
            crate::resource_policy::LocalAdmissionCoordinator::with_probe(
                crate::resource_policy::ResourcePolicy::custom_gb(8.0).unwrap(),
                crate::hardware::HardwareInfo {
                    total_ram_mb: 32 * 1024,
                    ..crate::hardware::HardwareInfo::detect()
                },
                Arc::new(FixedProbe),
            ),
        );
        let mut schema = crate::registry::builtin_catalog()
            .into_iter()
            .find(|schema| schema.tags.iter().any(|tag| tag == "mlx-vlm-cli"))
            .expect("one-shot mlx-vlm schema");
        schema.param_count = "1M".into();
        schema.quantization = Some(Quantization::parse("Q4"));
        let mut reservation = engine.reserve_local_request(&schema, 64).unwrap();
        InferenceEngine::reconcile_transient_local_allocation(&mut reservation, 1024 * 1024)
            .unwrap();
        drop(reservation);
        assert!(!engine.local_admission.is_resident(&schema.id));
    }

    #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
    #[test]
    fn non_apple_backend_map_keeps_two_local_model_identities_exact() {
        let mut backends = std::collections::HashMap::<String, u32>::new();
        backends.insert("local/model-a".into(), 1);
        backends.insert("local/model-b".into(), 2);
        assert_eq!(backends.get("local/model-a"), Some(&1));
        assert_eq!(backends.get("local/model-b"), Some(&2));
        assert_eq!(backends.remove("local/model-a"), Some(1));
        assert!(!backends.contains_key("local/model-a"));
        assert_eq!(backends.get("local/model-b"), Some(&2));
    }

    #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
    #[tokio::test]
    async fn non_apple_remote_classification_at_zero_gb_routes_without_local_allocation() {
        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_json(serde_json::json!({
                "choices": [{
                    "message": {"role": "assistant", "content": "positive"},
                    "finish_reason": "stop"
                }],
                "usage": {"prompt_tokens": 16, "completion_tokens": 1}
            })))
            .mount(&server)
            .await;

        let fixture = tempfile::tempdir().unwrap();
        let config = test_config(fixture.path().join("weights"));
        let repository =
            crate::resource_policy::FileResourcePolicyRepository::new(config.state_root.clone());
        crate::resource_policy::ResourcePolicyRepository::save(
            &repository,
            &crate::resource_policy::ResourcePolicy::custom_gb(0.0).unwrap(),
        )
        .unwrap();
        let mut engine = InferenceEngine::new(config);
        let mut remote = crate::openrouter::curated_schemas()
            .into_iter()
            .next()
            .expect("OpenRouter schema");
        remote.id = "openrouter/test/classifier".into();
        remote.name = remote.id.clone();
        if let ModelSource::RemoteApi { endpoint, .. } = &mut remote.source {
            *endpoint = server.uri();
        }
        let remote_id = remote.id.clone();
        engine.unified_registry.register_project_model(remote);

        let result = engine
            .classify(ClassifyRequest {
                text: "a good outcome".into(),
                labels: vec!["positive".into(), "negative".into()],
                model: Some(remote_id),
            })
            .await
            .unwrap();
        assert_eq!(
            result.first().map(|item| item.label.as_str()),
            Some("positive")
        );
        assert_eq!(engine.local_admission.resident_model_mb(), 0);
        assert!(
            !engine.config.models_dir.exists()
                || std::fs::read_dir(&engine.config.models_dir)
                    .unwrap()
                    .next()
                    .is_none(),
            "remote classification must not download local weights"
        );
    }

    #[test]
    fn adaptive_speech_skips_blocked_local_but_explicit_speech_fails() {
        let fixture = TempDir::new().unwrap();
        let config = InferenceConfig {
            models_dir: fixture.path().join("weights"),
            state_root: fixture.path().join("state"),
            ..Default::default()
        };
        let repository =
            crate::resource_policy::FileResourcePolicyRepository::new(config.state_root.clone());
        crate::resource_policy::ResourcePolicyRepository::save(
            &repository,
            &crate::resource_policy::ResourcePolicy::custom_gb(0.0).unwrap(),
        )
        .unwrap();
        let engine = InferenceEngine::new(config);
        let local = engine
            .unified_registry
            .all()
            .find(|schema| {
                schema.is_local() && schema.has_capability(ModelCapability::SpeechToText)
            })
            .cloned()
            .expect("built-in local STT model");

        assert!(matches!(
            engine.admit_speech_candidate(&local, false),
            SpeechCandidateAdmission::SkipBlocked(_)
        ));
        assert!(matches!(
            engine.admit_speech_candidate(&local, true),
            SpeechCandidateAdmission::FailBlocked(InferenceError::LocalResourceBlocked { .. })
        ));

        let mut os_owned = local;
        os_owned.id = "windows/speech-synthesis:test".into();
        os_owned.source = ModelSource::WindowsSpeech {};
        assert!(matches!(
            engine.admit_speech_candidate(&os_owned, true),
            SpeechCandidateAdmission::Proceed(None)
        ));
    }

    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn cancelled_native_blocking_work_keeps_its_exact_charge_until_completion() {
        let coordinator = std::sync::Arc::new(resource_policy::LocalAdmissionCoordinator::new(
            resource_policy::ResourcePolicy::custom_gb(1.0).unwrap(),
            crate::hardware::HardwareInfo {
                os: "test".into(),
                arch: "test".into(),
                cpu_cores: 8,
                total_ram_mb: 32 * 1024,
                gpu_backend: crate::hardware::GpuBackend::Cpu,
                gpu_memory_mb: None,
                gpu_devices: Vec::new(),
                recommended_model: "fixture".into(),
                recommended_context: 4096,
                max_model_mb: 32 * 1024,
            },
        ));
        let reservation = coordinator
            .reserve_measured_host("detached-native-a", 512 * 1024 * 1024, 0)
            .unwrap();
        let lease = reservation.detached_lease();
        let (started_tx, started_rx) = tokio::sync::oneshot::channel();
        let release =
            std::sync::Arc::new((std::sync::Mutex::new(false), std::sync::Condvar::new()));
        let release_worker = release.clone();
        let operation = tokio::spawn(async move {
            let _request_reservation = reservation;
            run_admitted_blocking(lease, move || {
                let _ = started_tx.send(());
                let (lock, ready) = &*release_worker;
                let mut released = lock
                    .lock()
                    .unwrap_or_else(std::sync::PoisonError::into_inner);
                while !*released {
                    released = ready
                        .wait(released)
                        .unwrap_or_else(std::sync::PoisonError::into_inner);
                }
            })
            .await
        });
        started_rx.await.unwrap();
        operation.abort();
        let _ = operation.await;

        let blocked = coordinator.reserve_measured_host("different-model-b", 768 * 1024 * 1024, 0);
        assert!(
            blocked.is_err(),
            "cancelling the await must not advertise memory still owned by spawn_blocking"
        );

        let (lock, ready) = &*release;
        *lock
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner) = true;
        ready.notify_one();
        tokio::time::timeout(std::time::Duration::from_secs(2), async {
            loop {
                if coordinator
                    .reserve_measured_host("different-model-b", 768 * 1024 * 1024, 0)
                    .is_ok()
                {
                    break;
                }
                tokio::time::sleep(std::time::Duration::from_millis(10)).await;
            }
        })
        .await
        .expect("the detached charge must clear after native work really exits");
    }

    #[test]
    fn nonstream_native_text_generation_uses_cancellable_blocking_boundary() {
        let source = include_str!("lib.rs");
        let mlx = source
            .split("async fn generate_mlx(")
            .nth(1)
            .and_then(|tail| tail.split("async fn generate_local(").next())
            .expect("generate_mlx source");
        let local = source
            .split("async fn generate_local(")
            .nth(1)
            .and_then(|tail| tail.split("fn apply_top_k_top_p").next())
            .expect("generate_local source");

        assert!(
            mlx.contains("run_admitted_blocking"),
            "native MLX decode must yield the Tokio runtime so a WS timeout/cancel can preempt its response waiter"
        );
        assert!(
            local.contains("run_admitted_blocking"),
            "polymorphic local decode must yield the Tokio runtime so a WS timeout/cancel can preempt its response waiter"
        );
    }

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

        let fixture = TempDir::new().unwrap();
        let runtime = SpeechRuntime::new(fixture.path().join("speech-runtime"));
        std::fs::create_dir_all(runtime.stt_program.parent().unwrap()).unwrap();
        std::fs::write(
            &runtime.stt_program,
            b"#!/bin/sh\necho started > \"$1\"\nsleep 1\necho continued > \"$2\"\n",
        )
        .unwrap();
        let mut permissions = std::fs::metadata(&runtime.stt_program)
            .unwrap()
            .permissions();
        permissions.set_mode(0o755);
        std::fs::set_permissions(&runtime.stt_program, permissions).unwrap();

        let coordinator = std::sync::Arc::new(resource_policy::LocalAdmissionCoordinator::new(
            resource_policy::ResourcePolicy::custom_gb(1.0).unwrap(),
            crate::hardware::HardwareInfo {
                total_ram_mb: 32 * 1024,
                ..crate::hardware::HardwareInfo::detect()
            },
        ));
        let reservation = coordinator
            .reserve_measured_host("mlx-audio-a", 512 * 1024 * 1024, 0)
            .unwrap();
        let lease = reservation.detached_lease();
        let started = fixture.path().join("started");
        let continued = fixture.path().join("continued");
        let args = vec![
            started.display().to_string(),
            continued.display().to_string(),
        ];
        let command = tokio::spawn(async move {
            let _request_reservation = reservation;
            run_mlx_audio_command(&runtime, "stt.generate", &args, lease).await
        });
        tokio::time::timeout(std::time::Duration::from_secs(2), async {
            while !started.exists() {
                tokio::time::sleep(std::time::Duration::from_millis(10)).await;
            }
        })
        .await
        .expect("speech fixture child must start");
        command.abort();
        let _ = command.await;

        tokio::time::timeout(std::time::Duration::from_secs(2), async {
            loop {
                if coordinator
                    .reserve_measured_host("different-model-b", 768 * 1024 * 1024, 0)
                    .is_ok()
                {
                    break;
                }
                tokio::time::sleep(std::time::Duration::from_millis(10)).await;
            }
        })
        .await
        .expect("charge clears only after the cancelled child is reaped");
        tokio::time::sleep(std::time::Duration::from_millis(1100)).await;
        assert!(
            !continued.exists(),
            "the cancelled local speech process must not keep allocating in the background"
        );
    }

    #[test]
    fn local_model_eviction_surface_includes_every_in_process_cache() {
        let source = include_str!("lib.rs");
        for cache in [
            "self.mlx_backends.evict_if_idle(model_id)",
            "self.local_backends.evict_if_idle(model_id)",
            "self.flux_cache.evict_if_idle(model_id)",
            "self.ltx_cache.evict_if_idle(model_id)",
            "self.kokoro_cache.evict_if_idle(model_id)",
            "self.local_backends.evict_idle()",
        ] {
            assert!(source.contains(cache), "missing eviction seam: {cache}");
        }
    }

    /// Demand-driven credentials: constructing the real builtin catalog and
    /// rendering passive Home/Models/setup/speech/health surfaces must not
    /// touch any secret backend. The process-wide counter is the proof seam;
    /// a registry-local fake would miss provider helpers that construct their
    /// own `SecretStore`.
    #[tokio::test]
    async fn catalog_refresh_uses_authority_hints_without_secret_reads() {
        if !crate::run_in_isolated_test_process(
            "tests::catalog_refresh_uses_authority_hints_without_secret_reads",
            "CAR_CATALOG_ZERO_SECRET_READ_CHILD",
        ) {
            return;
        }
        let _environment = ENV_MUTEX.lock().await;
        let fixture = TempDir::new().unwrap();
        let credential_envs = [
            car_auth::PARSLEE_ACCESS_TOKEN_KEY,
            car_auth::PARSLEE_API_BASE_KEY,
            crate::openrouter::API_KEY_ENV,
            "OPENAI_API_KEY",
            "ANTHROPIC_API_KEY",
            "GOOGLE_API_KEY",
            "ELEVENLABS_API_KEY",
        ];
        let mut restored_names = vec![car_home::ENV_VAR, "CAR_SECRETS_FILE_DIR"];
        restored_names.extend(credential_envs);
        let _restore = RestoredEnvironment::capture(&restored_names);
        unsafe {
            std::env::set_var(car_home::ENV_VAR, fixture.path().join("car-home"));
            std::env::set_var(
                "CAR_SECRETS_FILE_DIR",
                fixture.path().join("isolated-secrets"),
            );
            for name in credential_envs {
                std::env::remove_var(name);
            }
        }

        let before = car_secrets::secret_store_activity();
        let engine = InferenceEngine::new(test_config(fixture.path().join("models")));

        // Home / Models catalog.
        let listed = engine.list_models_unified();
        let schemas = engine.list_schemas();
        for provider in ["parslee", "openai", "anthropic", "google", "elevenlabs"] {
            assert!(
                schemas.iter().any(|schema| schema.provider == provider),
                "real builtin catalog lost the credential-bearing {provider} rows"
            );
        }
        assert!(
            schemas.iter().any(|schema| matches!(
                schema.source,
                ModelSource::RemoteApi {
                    protocol: ApiProtocol::OpenRouter,
                    ..
                }
            )),
            "real builtin catalog lost the reviewed OpenRouter rows"
        );
        assert_eq!(listed.len(), schemas.len());

        // `models.setup_plan` delegates to this exact list + recommender path.
        let schema_refs: Vec<&ModelSchema> = schemas.iter().collect();
        let _setup_plan = crate::recommend(
            &schema_refs,
            &HardwareInfo::detect(),
            UseCase::default(),
            QualityTier::default(),
            Privacy::OnDevice,
        );

        // Cached speech state plus Home/health status entry points.
        let _speech = engine.speech_health();
        let _concierge = engine.concierge_status(false).await;
        let _health = engine.model_health().await;

        let after = car_secrets::secret_store_activity();
        assert_eq!(
            after, before,
            "passive builtin catalog surfaces performed secret-store operations"
        );
    }

    #[tokio::test]
    async fn list_models_unified_and_model_health_are_zero_secret_store_probes() {
        if !crate::run_in_isolated_test_process(
            "tests::list_models_unified_and_model_health_are_zero_secret_store_probes",
            "CAR_DIRECT_MODEL_SURFACES_ZERO_SECRET_CHILD",
        ) {
            return;
        }
        let _environment = ENV_MUTEX.lock().await;
        let fixture = TempDir::new().unwrap();
        let _restore = RestoredEnvironment::capture(&[
            car_home::ENV_VAR,
            "CAR_SECRETS_FILE_DIR",
            crate::openrouter::API_KEY_ENV,
        ]);
        unsafe {
            std::env::set_var(car_home::ENV_VAR, fixture.path().join("car-home"));
            std::env::set_var(
                "CAR_SECRETS_FILE_DIR",
                fixture.path().join("isolated-secrets"),
            );
            std::env::remove_var(crate::openrouter::API_KEY_ENV);
        }
        let engine = InferenceEngine::new(test_config(fixture.path().join("models")));
        let before = car_secrets::secret_store_activity();

        let rows = engine.list_models_unified();
        let health = engine.model_health().await;

        assert!(!rows.is_empty(), "the unified catalog fixture must exist");
        assert!(health.total_models > 0, "the health fixture must exist");
        let after = car_secrets::secret_store_activity();
        assert_eq!(after.status_attempts, before.status_attempts);
        assert_eq!(after.get_attempts, before.get_attempts);
    }

    /// The signed-catalog cache holds an anti-rollback version counter and the
    /// discovery cache holds a provider model list — both are per-daemon
    /// bookkeeping, and both were derived from the *weights* dir, which
    /// deliberately stays machine-shared. A relocated daemon therefore kept
    /// writing them into the primary's `~/.car`, which is precisely the
    /// shared-state clobber `CAR_HOME` exists to prevent.
    ///
    /// The weights themselves must still NOT move, or every isolated daemon
    /// re-downloads tens of gigabytes to end up with identical bytes.
    #[test]
    fn car_home_moves_the_catalog_and_discovery_caches_but_never_the_weights() {
        let _environment = crate::openrouter::test_environment_scope();
        let prior = std::env::var_os(car_home::ENV_VAR);

        unsafe { std::env::remove_var(car_home::ENV_VAR) };
        let shared = InferenceConfig::default();
        let default_catalog = crate::catalog::cache_path(&shared.state_root);
        let default_discovery = crate::discovery::cache_path(&shared.state_models_dir());

        let alt = Path::new("/tmp/car-home-inference-cache-test");
        unsafe { std::env::set_var(car_home::ENV_VAR, alt) };
        let relocated = InferenceConfig::default();
        let catalog = crate::catalog::cache_path(&relocated.state_root);
        let discovery = crate::discovery::cache_path(&relocated.state_models_dir());

        match prior {
            Some(value) => unsafe { std::env::set_var(car_home::ENV_VAR, value) },
            None => unsafe { std::env::remove_var(car_home::ENV_VAR) },
        }

        assert_eq!(catalog, alt.join(crate::catalog::CATALOG_CACHE_FILE));
        assert_eq!(
            discovery,
            alt.join("models")
                .join(crate::discovery::DISCOVERED_MODELS_FILE)
        );
        assert_ne!(
            catalog, default_catalog,
            "the catalog cache must not resolve back into the shared root",
        );
        assert_ne!(
            discovery, default_discovery,
            "the discovery cache must not resolve back into the shared root",
        );

        assert_eq!(
            relocated.models_dir, shared.models_dir,
            "the weights cache is machine-global and must not follow CAR_HOME",
        );
        assert!(
            !relocated.models_dir.starts_with(alt),
            "the weights cache must not be dragged under the override",
        );
    }

    #[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() {
        if !crate::run_in_isolated_test_process(
            "tests::v2_parslee_auth_drives_managed_registration_routing_lane_and_logout",
            "CAR_V2_ROUTING_AUTH_CHILD",
        ) {
            return;
        }
        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,
        ]);
        // Same reason as the legacy sibling below: the managed-row assertions
        // read the durable gateway (Parslee-ai/car#786) and credential
        // (Parslee-ai/car#887) verdicts out of the CAR state root, and a live
        // one left there by any other process suppresses every `parslee/*` row
        // no matter what this test seeds. Pin the root and forget the
        // in-process copies rather than inheriting whatever the machine holds.
        let _home = crate::openrouter::StateRootScope::new();
        crate::openrouter::clear_gateway_unconfigured();
        crate::parslee_credential::clear_credential_rejected();
        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(),
            );
        }
        registry.refresh_routing_availability(Some("https://api.parslee.ai"), false);
        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_routing_availability(Some("https://api.parslee.ai"), false);
        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().await),
            Some(managed_lane_id.to_string()),
            "a managed lane default must resolve from authoritative V2 auth"
        );

        car_auth::logout()
            .await
            .expect("production logout must publish a signed-out tombstone");
        let persisted_logout: serde_json::Value =
            serde_json::from_str(&store.get(&state_ref).unwrap()).unwrap();
        assert_eq!(persisted_logout["tombstone"], true);
        assert_eq!(persisted_logout["accounts"], serde_json::json!([]));
        assert!(persisted_logout.get("active").is_none());
        assert_eq!(car_auth::access_token(), None);

        registry.refresh_routing_availability(None, true);
        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().await;
        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() {
        if !crate::run_in_isolated_test_process(
            "tests::legacy_parslee_auth_is_routable_only_until_v2_tombstone_then_migrates",
            "CAR_LEGACY_V2_MIGRATION_CHILD",
        ) {
            return;
        }
        let tmp = TempDir::new().unwrap();
        let _provider_env = crate::openrouter::test_environment_scope_async().await;
        let _restore = RestoredEnvironment::capture(&[
            "CAR_SECRETS_FILE_DIR",
            car_home::ENV_VAR,
            car_auth::PARSLEE_ACCESS_TOKEN_KEY,
        ]);
        // The managed-alias assertions below also read two DURABLE
        // session-scoped verdicts — `gateway-state.json` (Parslee-ai/car#786)
        // and `parslee-credential-state.json` (Parslee-ai/car#887) — either of
        // which suppresses every `parslee/openrouter/*` row regardless of what
        // this test seeded into its secret store.
        //
        // Until Parslee-ai/car#986 this test was repaired by a side effect it
        // never asked for: the tombstoned half's `refresh_availability` ran
        // signed out and cleared BOTH verdicts, in memory and on disk, before
        // the legacy half looked at them. Construction is not a statement about
        // the session, so that clear is gone — and with it the accidental
        // repair. Isolate the state root into this test's own temp dir and
        // forget the in-process copies, so the only verdicts in play are the
        // ones this test set itself.
        let _home = crate::openrouter::StateRootScope::new();
        crate::openrouter::clear_gateway_unconfigured();
        crate::parslee_credential::clear_credential_rejected();
        unsafe {
            std::env::remove_var(car_auth::PARSLEE_ACCESS_TOKEN_KEY);
            std::env::set_var(car_home::ENV_VAR, tmp.path().join("car-home"));
        }

        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(),
            "passive catalog registration must remain disabled without a configured hint"
        );
        let tombstoned = car_auth::resolve_credential(car_auth::CredentialReadMode::Use)
            .await
            .unwrap();
        assert!(tombstoned.is_none(), "the V2 tombstone is authoritative");
        tombstoned_registry.refresh_routing_availability(None, true);
        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(),
            "passive registration must not inspect attributable legacy slots"
        );
        registry.refresh_availability();
        assert!(
            !registry.get(&managed.id).unwrap().available_now(),
            "passive refresh must remain secret-store free until request-time migration"
        );
        let resolved = car_auth::resolve_credential(car_auth::CredentialReadMode::Use)
            .await
            .unwrap()
            .expect("request-time auth reconciliation must migrate attributable legacy state");
        registry.refresh_routing_availability(Some(&resolved.api_base), false);
        assert!(registry.get(&managed.id).unwrap().available_now());
        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"
        );
    }

    #[tokio::test]
    async 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().await),
            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().await),
            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}"
        );
    }

    #[tokio::test]
    async 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().await;
        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().await;
        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 mut engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        pin_test_live_memory(&mut engine);
        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")));
        pin_test_live_memory(&mut engine);
        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 exact_model_id_rejects_display_name_without_dispatch() {
        let tmp = TempDir::new().unwrap();
        let mut engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let mut first = remote_stream_fixture_schema(
            "test/ambiguous-a:1",
            "http://127.0.0.1:9".into(),
            schema::ApiProtocol::OpenAiCompat,
            "CAR_AMBIGUOUS_EXACT_KEY",
        );
        first.name = "Shared Alias".into();
        let mut second = first.clone();
        second.id = "test/ambiguous-b:1".into();
        engine.register_model(first);
        engine.register_model(second);
        let mut request = GenerateRequest {
            prompt: "must not dispatch".into(),
            ..Default::default()
        };
        pin_exact_model_id(&mut request, "Shared Alias".into()).unwrap();

        let error = engine
            .generate_tracked(request)
            .await
            .expect_err("an exact-id pin must never resolve a display name");
        assert!(matches!(error, InferenceError::ModelNotFound(_)));
    }

    #[tokio::test(flavor = "current_thread")]
    async fn exact_openai_pin_reports_catalog_id_and_loose_request_keeps_provider_name() {
        let _env = ENV_MUTEX.lock().await;
        assert_remote_model_identity_contract(
            schema::ApiProtocol::OpenAiCompat,
            "openai/newsroom-gpt-5.5-2026-04-23:test",
            "newsroom-gpt-5.5-2026-04-23-test",
            "CAR_OPENAI_IDENTITY_TEST_KEY",
        )
        .await;
    }

    #[tokio::test(flavor = "current_thread")]
    async fn exact_anthropic_pin_reports_catalog_id_and_loose_request_keeps_provider_name() {
        let _env = ENV_MUTEX.lock().await;
        assert_remote_model_identity_contract(
            schema::ApiProtocol::Anthropic,
            "anthropic/newsroom-claude-opus-4-8:test",
            "newsroom-claude-opus-4-8-test",
            "CAR_ANTHROPIC_IDENTITY_TEST_KEY",
        )
        .await;
    }

    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    #[tokio::test(flavor = "current_thread")]
    async fn exact_model_id_nonstream_bypasses_mlx_equivalent_substitution() {
        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 exact_id = install_exact_pin_equivalent_fixture(&engine);
        let offload = Arc::new(ExactPinCaptureOffload::new());
        crate::offload::set_local_offload(Some(offload.clone()));

        let mut request = GenerateRequest {
            prompt: "use only the immutable row I selected".into(),
            ..Default::default()
        };
        pin_exact_model_id(&mut request, exact_id.clone()).unwrap();
        let error = engine.generate_tracked(request).await.unwrap_err();

        assert!(offload.dispatched_models().is_empty());
        assert!(error.to_string().contains(&exact_id), "{error}");
        assert!(
            error
                .to_string()
                .contains("MLX-equivalent substitution is disabled for exact pins"),
            "{error}"
        );
        crate::offload::set_local_offload(None);
    }

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

        let _env = ENV_MUTEX.lock().await;
        let server = MockServer::start().await;
        Mock::given(method("POST"))
            .and(path("/v1/chat/completions"))
            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
                "choices": [{"message": {"content": "must not run"}, "finish_reason": "stop"}],
            })))
            .mount(&server)
            .await;
        unsafe { std::env::set_var("CAR_PRECONDITION_TEST_KEY", "fixture") };

        let tmp = TempDir::new().unwrap();
        let mut engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let model_id = "test/catalog-precondition:1";
        engine.register_model(remote_stream_fixture_schema(
            model_id,
            server.uri(),
            schema::ApiProtocol::OpenAiCompat,
            "CAR_PRECONDITION_TEST_KEY",
        ));
        let snapshot = engine.catalog_snapshot().unwrap();
        let row_digest = snapshot
            .model_by_exact_id(model_id)
            .unwrap()
            .row_digest
            .clone();

        for (expected_row_digest, expected_catalog_revision) in [
            (
                Some("0".repeat(64)),
                Some(snapshot.catalog_revision.clone()),
            ),
            (Some(row_digest.clone()), Some("f".repeat(64))),
        ] {
            let mut request = GenerateRequest {
                prompt: "must not dispatch".into(),
                expected_row_digest,
                expected_catalog_revision,
                ..Default::default()
            };
            pin_exact_model_id(&mut request, model_id.into()).unwrap();
            let error = engine.generate_tracked(request).await.unwrap_err();
            assert!(matches!(
                error,
                InferenceError::CatalogPreconditionMismatch { .. }
            ));
        }
        assert!(
            server.received_requests().await.unwrap().is_empty(),
            "catalog identity mismatches must fail before provider dispatch"
        );

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

    #[tokio::test(flavor = "current_thread")]
    async fn exact_nonstream_identity_survives_thinking_retry() {
        use std::sync::atomic::{AtomicUsize, Ordering};
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let _env = ENV_MUTEX.lock().await;
        let server = MockServer::start().await;
        let calls = Arc::new(AtomicUsize::new(0));
        let response_calls = calls.clone();
        Mock::given(method("POST"))
            .and(path("/v1/chat/completions"))
            .respond_with(move |_request: &wiremock::Request| {
                let attempt = response_calls.fetch_add(1, Ordering::SeqCst);
                let content = if attempt == 0 { "" } else { "recovered" };
                ResponseTemplate::new(200).set_body_json(serde_json::json!({
                    "choices": [{
                        "message": {"content": content},
                        "finish_reason": if attempt == 0 { "length" } else { "stop" },
                    }],
                    "usage": {"prompt_tokens": 2, "completion_tokens": 1, "total_tokens": 3},
                }))
            })
            .mount(&server)
            .await;
        unsafe { std::env::set_var("CAR_IDENTITY_RETRY_KEY", "fixture") };

        let tmp = TempDir::new().unwrap();
        let mut engine = InferenceEngine::new(test_config(tmp.path().join("models")));
        let model_id = "test/identity-retry:1";
        engine.register_model(remote_stream_fixture_schema(
            model_id,
            server.uri(),
            schema::ApiProtocol::OpenAiCompat,
            "CAR_IDENTITY_RETRY_KEY",
        ));
        let snapshot = engine.catalog_snapshot().unwrap();
        let expected_row = snapshot.model_by_exact_id(model_id).unwrap();
        let mut request = GenerateRequest {
            prompt: "retry once".into(),
            expected_row_digest: Some(expected_row.row_digest.clone()),
            expected_catalog_revision: Some(snapshot.catalog_revision.clone()),
            ..Default::default()
        };
        pin_exact_model_id(&mut request, model_id.into()).unwrap();

        let result = engine.generate_tracked(request).await.unwrap();
        assert_eq!(calls.load(Ordering::SeqCst), 2, "must exercise retry path");
        assert_eq!(result.stop_reason.as_deref(), Some("thinking_recovered"));
        assert_eq!(
            result.model_identity.requested_model_id.as_deref(),
            Some(model_id)
        );
        assert_eq!(result.model_identity.resolved_model_id, model_id);
        assert_eq!(result.model_identity.row_digest, expected_row.row_digest);
        assert_eq!(
            result.model_identity.catalog_revision,
            snapshot.catalog_revision
        );

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

    #[tokio::test(flavor = "current_thread")]
    async fn managed_openrouter_reasoning_items_roundtrip_verbatim_across_two_turns() {
        if !crate::run_in_isolated_test_process(
            "tests::managed_openrouter_reasoning_items_roundtrip_verbatim_across_two_turns",
            "CAR_MANAGED_REASONING_ROUNDTRIP_CHILD",
        ) {
            return;
        }
        let _home = crate::openrouter::StateRootScope::new();
        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() {
        if !crate::run_in_isolated_test_process(
            "tests::managed_partial_eof_fails_buffered_and_streamed_turns_and_records_only_failures",
            "CAR_MANAGED_PARTIAL_EOF_CHILD",
        ) {
            return;
        }
        let _home = crate::openrouter::StateRootScope::new();
        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#796 — a content refusal ENDS the chain rather than being
    /// answered by the next candidate.
    ///
    /// The chain cannot vary the request, so every remaining candidate replays
    /// the payload the filter just declined — and the tail of a remote-only
    /// chain is an appended on-device model with no filter in front of it. Left
    /// to fall through, a refused `parslee/reasoning` call returns a *local*
    /// model's answer under the requested model's name, which is what makes an
    /// adversarial-safety benchmark's counts move run to run.
    #[test]
    fn a_content_refusal_ends_the_fallback_chain() {
        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_ends_fallback_chain(&refused));

        // Narrow, and in the safe direction: every condition that IS about a
        // lane keeps advancing the chain, or a single dead credential would
        // start failing calls that a fallback would have served.
        for still_advances in [
            InferenceError::InferenceFailed("managed inference failed".into()),
            InferenceError::InferenceFailed("API returned 503".into()),
            InferenceError::ModelNotFound("parslee/reasoning".into()),
            InferenceError::UnsupportedMode {
                mode: "json_schema",
                backend: "anthropic",
                reason: "structured output is not supported by this protocol",
            },
            InferenceError::GatewayUnconfigured {
                provider: "parslee".into(),
                namespace: "parslee/openrouter/".into(),
                status: 503,
                message: "not configured".into(),
            },
        ] {
            assert!(
                !error_ends_fallback_chain(&still_advances),
                "must keep advancing the chain: {still_advances}"
            );
        }
    }

    /// Parslee-ai/car#796 — the exhausted-chain recovery hints must not launder
    /// a content refusal back into a generic failure.
    ///
    /// Both hints match SUBSTRINGS of the Display text, and a refusal embeds the
    /// gateway's own message verbatim. A gateway that says "403 forbidden" while
    /// refusing on content grounds would otherwise be rewritten to
    /// `InferenceFailed` and lose the classification one layer after it was
    /// finally earned.
    #[test]
    fn recovery_hints_do_not_rewrite_a_content_refusal() {
        let refused = InferenceError::ContentRefused {
            provider: "parslee".into(),
            kind: Some("invalid_request_error".into()),
            code: Some("content_policy_violation".into()),
            // Deliberately quotes a phrase the auth-expired hint matches on.
            message: "blocked: 403 forbidden by the content filter".into(),
        };
        let out = apply_exhaustion_recovery_hint(refused);
        assert!(
            matches!(out, InferenceError::ContentRefused { .. }),
            "{out:?}"
        );

        // The hints still fire for the cases they were written for.
        let signed_out = apply_exhaustion_recovery_hint(InferenceError::InferenceFailed(
            "no credential for proprietary provider 'parslee'".into(),
        ));
        assert!(
            matches!(signed_out, InferenceError::InferenceFailed(ref m) if m.contains("car auth")),
            "{signed_out:?}"
        );

        // ...and an unrelated failure still passes through untouched.
        let transient = apply_exhaustion_recovery_hint(InferenceError::InferenceFailed(
            "API returned 500".into(),
        ));
        assert_eq!(transient.to_string(), "inference failed: API returned 500");
    }

    /// 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 mut 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()
        };
        req.params.strict_model = true;

        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.
    ///
    /// The interpreter half comes from [`managed_venv::seed_ready_venv`] — one
    /// definition, shared with `car-cli`'s CLI tests — because readiness
    /// *executes* the interpreter and the runnable-stub trick differs per
    /// platform. The console scripts are only stat-ed, so empty files at the
    /// paths `SpeechRuntime` itself computes are enough; taking them from the
    /// struct is what keeps fixture and probe from drifting apart again.
    fn fake_ready_speech_runtime(root: &Path) {
        managed_venv::seed_ready_venv(root);
        let runtime = SpeechRuntime::new(root.to_path_buf());
        for program in [&runtime.stt_program, &runtime.tts_program] {
            std::fs::create_dir_all(program.parent().expect("program has a parent")).unwrap();
            std::fs::write(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.
    ///
    /// Keeping it unscoped is also what caught the Windows layout bug. When the
    /// probe read `<root>/bin/python` on every platform, this test's pre-seeded
    /// runtime went unrecognised on Windows, prepare fell through to a real
    /// `uv` bootstrap, and CI panicked with "`uv` … was not found on PATH".
    ///
    /// #953 gated this `#[cfg(unix)]` to unbreak the Windows leg, and named the
    /// real repair in the same breath: "Making it spawn means teaching
    /// `interpreter` the Windows `Scripts\\python.exe` layout … That is a
    /// product change, not a test fix." That product change is now made, so the
    /// gate comes back off. It has to: `managed_venv`'s claim that these Python
    /// stacks are Apple-Silicon-only holds for the *visual* runtime and is
    /// backwards for the speech one, which exists precisely for machines
    /// without Apple's MLX backends. Gate this and the runtime loses coverage
    /// on its own target platform.
    #[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(),
            model_identity: InferenceModelIdentity {
                requested_model_id: Some("test/model:1".into()),
                resolved_model_id: "test/model:1".into(),
                row_digest: "a".repeat(64),
                catalog_revision: "b".repeat(64),
            },
            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()),
            auth_fallback_from: None,
            local_last_resort: false,
            fallback_from: Vec::new(),
        };

        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["requested_model_id"].as_str(), Some("test/model:1"));
        assert_eq!(json["resolved_model_id"].as_str(), Some("test/model:1"));
        assert_eq!(json["row_digest"].as_str().unwrap(), "a".repeat(64));
        assert_eq!(json["catalog_revision"].as_str().unwrap(), "b".repeat(64));
        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(),
            model_identity: InferenceModelIdentity::default(),
            latency_ms: 0,
            time_to_first_token_ms: None,
            usage: None,
            provider_output_items: Vec::new(),
            thinking: Vec::new(),
            stop_reason: None,
            auth_fallback_from: None,
            local_last_resort: false,
            fallback_from: Vec::new(),
        };

        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",
            "requested_model_id",
            "resolved_model_id",
            "row_digest",
            "catalog_revision",
            "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(),
            model_identity: InferenceModelIdentity::default(),
            latency_ms: 42,
            time_to_first_token_ms: None,
            usage: None,
            provider_output_items: Vec::new(),
            thinking: Vec::new(),
            stop_reason: None,
            auth_fallback_from: None,
            local_last_resort: false,
            fallback_from: Vec::new(),
        };

        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": "gateway-alias",
            "resolved_model_id": "openrouter/anthropic/claude-sonnet-4.5",
            "local_last_resort": true,
            "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,
                model_id,
                local_last_resort,
                ..
            } if content == "calling"
                && tool_calls[0].id.as_deref() == Some("call_1")
                && model_id.as_deref() == Some("openrouter/anthropic/claude-sonnet-4.5")
                && *local_last_resort
        ));
    }

    #[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);
    }

    #[tokio::test]
    async fn pull_reuses_a_valid_directory_receipt_and_reports_removability() {
        let root = tempfile::tempdir().unwrap();
        let models_dir = root.path().join("models");
        std::fs::create_dir_all(&models_dir).unwrap();
        let engine = InferenceEngine::new(InferenceConfig {
            state_root: root.path().join("state"),
            models_dir: models_dir.clone(),
            ..InferenceConfig::default()
        });
        let schema = engine
            .unified_registry
            .all()
            .find(|schema| matches!(schema.source, ModelSource::Local { .. }))
            .unwrap()
            .clone();
        let managed = models_dir.join(&schema.name);
        std::fs::create_dir_all(&managed).unwrap();
        std::fs::write(managed.join("model.gguf"), b"owned").unwrap();
        std::fs::write(managed.join("tokenizer.json"), b"{}").unwrap();
        engine
            .model_management
            .record_managed_artifact(
                &schema.id,
                model_source_identity(&schema),
                None,
                1,
                false,
                managed.clone(),
            )
            .unwrap();
        let row = engine
            .list_models_unified()
            .into_iter()
            .find(|row| row.id == schema.id)
            .unwrap();
        if model_management::directory_removal_supported() {
            assert!(engine.model_management.can_remove(&schema.id).unwrap());
            assert!(row.can_remove);
            assert_eq!(row.management_evidence.as_deref(), Some("install_receipt"));
        } else {
            assert!(!engine.model_management.can_remove(&schema.id).unwrap());
            assert!(!row.can_remove);
            assert_eq!(
                row.management_evidence.as_deref(),
                Some("install_receipt_directory_cleanup_unsupported")
            );
        }

        let reused = engine.pull_model(&schema.id).await.unwrap();
        assert_eq!(reused, managed);
    }

    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    #[test]
    fn kokoro_cache_is_explicitly_state_root_scoped_and_does_not_pin_runtime() {
        let first_root = tempfile::tempdir().unwrap();
        let second_root = tempfile::tempdir().unwrap();
        let first = scoped_kokoro_backend_cache(first_root.path());
        let second = scoped_kokoro_backend_cache(second_root.path());
        assert!(!Arc::ptr_eq(first.cache(), second.cache()));
        assert!(!Arc::ptr_eq(first.admission(), second.admission()));

        let runtime = Arc::downgrade(&first._runtime);
        drop(first);
        assert!(
            runtime.upgrade().is_none(),
            "an unused Kokoro accessor must not process-pin the scoped runtime"
        );
    }
}

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

    /// The CLI's startup warning asks the engine, and the engine asks the
    /// SAME protocol handler the remote path consults — so the answer cannot
    /// drift from what a real request would hit.
    #[test]
    fn rejection_reason_tracks_the_protocol_handler() {
        let engine = InferenceEngine::new(Default::default());
        let rf = crate::tasks::generate::ResponseFormat::JsonObject;
        let models = engine.list_models_unified();
        let anthropic = models
            .iter()
            .find(|m| m.provider.eq_ignore_ascii_case("anthropic"));
        if let Some(m) = anthropic {
            let reason = engine
                .response_format_rejection_reason(&m.id, &rf)
                .expect("the Anthropic protocol rejects response_format");
            assert!(reason.contains("protocol rejects"), "{reason}");
        }
        let openrouter = models
            .iter()
            .find(|m| m.provider.eq_ignore_ascii_case("openrouter"));
        if let Some(m) = openrouter {
            assert_eq!(
                engine.response_format_rejection_reason(&m.id, &rf),
                None,
                "OpenRouter forwards the format upstream"
            );
        }
        assert!(
            anthropic.is_some() || openrouter.is_some(),
            "the builtin catalog should list at least one of the two providers this pins"
        );
        assert_eq!(
            engine.response_format_rejection_reason("no/such-model", &rf),
            None,
            "an unknown model is not a rejection"
        );
    }
}