cera-cli 0.3.0

use std::io::{IsTerminal, Write};
use std::path::{Path, PathBuf};
use std::str::FromStr;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex};

use anyhow::{Context, Result};
use cera::tokenizer::BpeTokenizer;
use cera::{BackendPreference, CeraEngine, CeraError, EngineConfig, FinishReason, ModalitySink};
use clap::{Parser, Subcommand};

mod chat_tui;
mod image_source;
mod signal;
mod thermal;

/// Decode tokens to stdout as they stream. Used by the `run` command.
///
/// Holds a clone of the session's cancel flag so we can trigger a clean
/// shutdown when stdout closes (e.g. `cera run ... | head` detaches). Using
/// `print!` there would panic on `BrokenPipe`; we write manually and flip
/// cancel on any write error, letting the decode loop exit gracefully.
struct StdoutSink<'a> {
    tokenizer: &'a BpeTokenizer,
    cancel: Arc<AtomicBool>,
}

impl<'a> StdoutSink<'a> {
    fn new(tokenizer: &'a BpeTokenizer, cancel: Arc<AtomicBool>) -> Self {
        Self { tokenizer, cancel }
    }
}

impl ModalitySink for StdoutSink<'_> {
    fn on_text_tokens(&mut self, tokens: &[u32]) {
        if self.cancel.load(Ordering::Relaxed) {
            return;
        }
        let piece = self.tokenizer.decode(tokens);
        let mut out = std::io::stdout().lock();
        if out.write_all(piece.as_bytes()).is_err() || out.flush().is_err() {
            // Downstream closed (BrokenPipe). Signal the session to stop
            // decoding on the next iteration.
            self.cancel.store(true, Ordering::Relaxed);
        }
    }
    fn on_done(&mut self, _reason: FinishReason) {}
}

/// Swallows every event. Used by `bench` to avoid stdout inside the timed loop.
struct NoopSink;

impl ModalitySink for NoopSink {
    fn on_done(&mut self, _reason: FinishReason) {}
}

/// Streams decoded tokens to stdout *and* accumulates them into a
/// `String` buffer so the chat REPL can capture the full assistant
/// reply for the next turn's history. Otherwise mirrors `StdoutSink`'s
/// BrokenPipe-aware write behavior.
struct ChatSink<'a> {
    tokenizer: &'a BpeTokenizer,
    cancel: Arc<AtomicBool>,
    buffer: String,
    /// Stream decoded pieces to stderr instead of stdout. Used by the
    /// tool-calling path so stdout carries only the machine-readable tool-call
    /// JSON, uncorrupted by the raw reply stream.
    to_stderr: bool,
}

impl<'a> ChatSink<'a> {
    fn new(tokenizer: &'a BpeTokenizer, cancel: Arc<AtomicBool>) -> Self {
        Self {
            tokenizer,
            cancel,
            buffer: String::new(),
            to_stderr: false,
        }
    }
    /// Like [`Self::new`], but streams the reply to stderr, leaving stdout for
    /// structured output.
    fn new_stderr(tokenizer: &'a BpeTokenizer, cancel: Arc<AtomicBool>) -> Self {
        Self {
            tokenizer,
            cancel,
            buffer: String::new(),
            to_stderr: true,
        }
    }
    fn into_text(self) -> String {
        self.buffer
    }
}

impl ModalitySink for ChatSink<'_> {
    fn on_text_tokens(&mut self, tokens: &[u32]) {
        if self.cancel.load(Ordering::Relaxed) {
            return;
        }
        let piece = self.tokenizer.decode(tokens);
        let write_err = if self.to_stderr {
            let mut out = std::io::stderr().lock();
            out.write_all(piece.as_bytes()).is_err() || out.flush().is_err()
        } else {
            let mut out = std::io::stdout().lock();
            out.write_all(piece.as_bytes()).is_err() || out.flush().is_err()
        };
        if write_err {
            self.cancel.store(true, Ordering::Relaxed);
            return;
        }
        self.buffer.push_str(&piece);
    }
    fn on_done(&mut self, _reason: FinishReason) {}
}

/// `BundleRepo` progress callback that renders a single-line live status to
/// stderr while bundle files stream in. Prevents a multi-MB cache-miss
/// download from looking like a hung process when `cera chat --bundle-id`
/// runs the first time.
///
/// Trait throttling is handled by the library (~1 call per 256 KB written +
/// once at end-of-stream) so this just formats and rewrites the line.
/// Multiple files in one resolve (manifest.json then the GGUF) are
/// distinguished by `url`; on a URL change we emit a newline first so the
/// previous file's final progress line stays visible.
#[derive(Debug, Default)]
struct CliDownloadProgress {
    last_url: Mutex<Option<String>>,
}

impl CliDownloadProgress {
    fn reset(&self) {
        let mut guard = self
            .last_url
            .lock()
            .expect("CliDownloadProgress lock poisoned");
        *guard = None;
    }

    fn finish_line(&self) {
        let mut guard = self
            .last_url
            .lock()
            .expect("CliDownloadProgress lock poisoned");
        if guard.take().is_some() {
            eprintln!();
        }
    }
}

impl cera::bundle::DownloadProgress for CliDownloadProgress {
    fn on_progress(&self, url: &str, bytes: u64, total: Option<u64>) {
        // URL transition → seal the prior line with a newline so it stays
        // legible after the next file's progress overwrites the position.
        {
            let mut guard = self
                .last_url
                .lock()
                .expect("CliDownloadProgress lock poisoned");
            let new_file = guard.as_deref() != Some(url);
            if new_file {
                if guard.is_some() {
                    eprintln!();
                }
                *guard = Some(url.to_string());
            }
        }

        let filename = url.rsplit('/').next().unwrap_or(url);
        let mb = bytes as f64 / (1024.0 * 1024.0);
        let line = match total {
            Some(t) if t > 0 => {
                let total_mb = t as f64 / (1024.0 * 1024.0);
                let pct = ((bytes * 100) / t).min(100);
                format!("\rDownloading {filename}: {pct:>3}% ({mb:>6.1} / {total_mb:.1} MiB)")
            }
            // No Content-Length — chunked-transfer or HEAD-less stream.
            // Show bytes downloaded only.
            _ => format!("\rDownloading {filename}: {mb:>6.1} MiB"),
        };
        let mut err = std::io::stderr().lock();
        let _ = err.write_all(line.as_bytes());
        let _ = err.flush();
    }
}

#[derive(Parser)]
#[command(name = "cera", version, about = "Rust-native LLM inference engine")]
struct Cli {
    #[command(subcommand)]
    command: Command,
}

#[derive(Subcommand)]
// Clap subcommand args live inline in each variant; `Run`/`Chat`/`Embed` carry
// many flags so the variants differ in size. Boxing fields to equalize them
// would fight the derive for no runtime benefit (the enum is built once at
// startup), so allow the size disparity here.
#[allow(clippy::large_enum_variant)]
enum Command {
    /// Run inference on a prompt.
    Run {
        /// Path to the model: a `.gguf` file, a `.json` LeapBundles
        /// manifest, or a directory containing exactly one `.json`
        /// manifest. Mutually exclusive with `--bundle-id` /
        /// `--quant`; one of the two source forms must be set.
        #[arg(
            short,
            long,
            conflicts_with_all = ["bundle_id", "quant"],
        )]
        model: Option<String>,

        /// LeapBundles bundle id (e.g. `LFM2.5-1.2B-Instruct` or
        /// `LFM2.5-1.2B-Instruct-GGUF` — `-GGUF` is appended
        /// automatically if missing). Pairs with `--quant` for
        /// auto-download from
        /// `huggingface.co/LiquidAI/LeapBundles`. Cached under
        /// `--cache-dir` (default `$HOME/.cache/cera`). Use
        /// `cera list-bundles` to discover available IDs.
        #[arg(long, requires = "quant")]
        bundle_id: Option<String>,

        /// Quantization label for `--bundle-id` (e.g. `Q4_0`,
        /// `Q8_0`). Pairs with `--bundle-id`: clap rejects
        /// either flag without the other.
        #[arg(long, requires = "bundle_id")]
        quant: Option<String>,

        /// The prompt to generate from. Required for text mode; optional
        /// when `--audio-in` is set (in which case it becomes a leading
        /// text instruction before the audio).
        #[arg(short, long)]
        prompt: Option<String>,

        /// Maximum number of tokens to generate.
        #[arg(long, default_value_t = 256)]
        max_tokens: usize,

        /// Sampling temperature.
        #[arg(long, default_value_t = 0.7)]
        temperature: f32,

        /// Constrain output to a GBNF grammar. Pass an inline grammar string, or
        /// `@path/to/file.gbnf` to read it from a file.
        #[arg(long)]
        grammar: Option<String>,

        /// Shorthand: constrain output to valid JSON (a bundled JSON grammar).
        #[arg(long, conflicts_with = "grammar")]
        json: bool,

        /// Enable tool calling. Pass an inline JSON array of tool schemas
        /// (OpenAI "function" shape: `[{"name":..,"description":..,
        /// "parameters":{JSON Schema}}]`), or `@path/to/tools.json` to read it
        /// from a file. The tools are rendered into the model's chat template
        /// and any tool call in the reply is parsed and printed. Text-only:
        /// conflicts with the image / audio / vocoder / raw-token-ids modes,
        /// which have their own generation paths.
        #[arg(long, conflicts_with_all = ["image", "audio_in", "vocoder", "token_ids"])]
        tools: Option<String>,

        /// With `--tools`, constrain the reply to a valid tool call for the
        /// declared tools (grammar + lazy trigger). Off by default: the model
        /// decides freely whether/how to call a tool.
        #[arg(long, requires = "tools")]
        constrain_tools: bool,

        /// Device to use: cpu, gpu, or auto.
        #[arg(long, default_value = "auto")]
        device: String,

        /// Raw token IDs (comma-separated). Overrides --prompt when set.
        #[arg(long)]
        token_ids: Option<String>,

        /// Max context window size (KV cache). Default 4096. Larger values use more
        /// memory. Context >4096 auto-switches to flash attention (~14% slower).
        #[arg(long, default_value_t = 4096)]
        context_size: usize,

        /// Path to vocoder GGUF for audio generation. Enables audio output.
        #[arg(long)]
        vocoder: Option<String>,

        /// Path to a PCM16 WAV file to feed as audio input. Any
        /// sample rate accepted — non-16 kHz inputs are resampled
        /// with linear interpolation before encoding. Multi-channel
        /// inputs are down-mixed to mono by averaging across
        /// channels. For studio-quality conversion, pre-resample
        /// and down-mix externally (sox/ffmpeg) and pass 16 kHz
        /// mono PCM16 to bypass both steps. Encoded via the
        /// bundle's mmproj (`AudioEncoderWeights`) and prefilled
        /// into the LLM as soft tokens via `Session::append_audio`.
        ///
        /// Combinations:
        /// - With `--prompt` alone: a leading text prefix (after BOS)
        ///   then audio. Plain mode, no chat template.
        /// - With `--system` (and optionally `--prompt`): renders the
        ///   model's chat template and inserts audio at the end of
        ///   the user turn (e.g. `--system "Perform ASR."` for
        ///   transcription). Requires the tokenizer to expose a
        ///   reserved special token (`<|reserved_4|>` or similar) to
        ///   mark the audio insertion point in the rendered prompt.
        ///
        /// Mutually exclusive with `--vocoder` (audio output),
        /// `--audio-out` (output WAV writer — not produced in
        /// audio-in mode), and `--token-ids` (audio-in builds its
        /// own KV from the encoder, not raw tokens).
        #[arg(long, conflicts_with_all = ["vocoder", "audio_out", "token_ids", "image"])]
        audio_in: Option<String>,

        /// Image source for one or more inputs (PNG or JPEG).
        /// Each value is either a filesystem path or an
        /// `http(s)://` URL — URLs are downloaded over HTTPS with
        /// a 30s timeout and the same 50 MB cap as filesystem
        /// inputs. When set, renders the model's chat template
        /// with multimodal content (image(s) plus optional
        /// `--prompt`) and prefills via
        /// `Session::append_chat_with_images`. Repeat the flag for
        /// multi-image inputs:
        ///
        ///   cera run -m foo.gguf --image pug.jpg --prompt "describe what you see"
        ///   cera run -m foo.gguf --image a.jpg --image b.jpg --prompt "compare"
        ///   cera run -m foo.gguf --image https://example.com/a.jpg --prompt "describe"
        ///
        /// `--prompt` is optional in image mode (image-only inputs
        /// are allowed). `--system` is allowed and renders as a
        /// system turn before the user turn carrying the image(s).
        ///
        /// Mutually exclusive with `--audio-in` (audio-input
        /// pipeline), `--vocoder` / `--audio-out` (audio-output
        /// pipeline), and `--token-ids` (raw token mode bypasses
        /// the chat template the helper renders).
        // The doc above shows a literal `--image https://…` example; a markdown
        // autolink or code fence would leak into clap's `--help` output, so
        // suppress the bare-url rustdoc lint here rather than mangling the help.
        #[allow(rustdoc::bare_urls)]
        #[arg(
            long,
            value_name = "PATH-OR-URL",
            conflicts_with_all = ["audio_in", "vocoder", "audio_out", "token_ids"],
        )]
        image: Vec<String>,

        /// Cap the longest side (in pixels) of each `--image` input's
        /// *encoded* resolution. Smaller = fewer image tokens, faster
        /// prefill, less detail; larger (or unset) = full model
        /// resolution. The cap only shrinks and takes precedence over
        /// the model's minimum-resolution floor. Applies to every image
        /// in the turn via `Session::set_image_max_long_size`.
        #[arg(long, value_name = "PIXELS")]
        max_long_size: Option<u32>,

        /// Output WAV file for generated audio.
        #[arg(long)]
        audio_out: Option<String>,

        /// System prompt (used with --vocoder for audio mode selection).
        /// E.g. "Perform TTS." or "Respond with interleaved text and audio."
        #[arg(long)]
        system: Option<String>,

        /// Audio sampling temperature (0.0 = greedy, >0 = stochastic).
        #[arg(long, default_value_t = 0.8)]
        audio_temperature: f32,

        /// Audio top-k for stochastic sampling.
        #[arg(long, default_value_t = 4)]
        audio_top_k: usize,

        /// Cache root, shared between KV prefix cache files
        /// (under `<dir>/kv/`, enables disk caching for prompt
        /// reuse) AND the `BundleRepo` download store when
        /// `--bundle-id` is set (downloads under
        /// `<dir>/huggingface.co/...`). Default: `$HOME/.cache/cera`.
        #[arg(long)]
        cache_dir: Option<String>,

        /// Max warm (memory) cache size in MB. Default 256.
        #[arg(long, default_value_t = 256)]
        cache_warm_mb: u64,

        /// Max disk cache size in GB. Default 10.
        #[arg(long, default_value_t = 10)]
        cache_disk_gb: u64,

        /// Disable KV prefix caching entirely.
        #[arg(long)]
        no_cache: bool,

        /// KV cache key compression: f32 (default) or tq3 (TurboQuant 3-bit).
        #[arg(long, default_value = "f32")]
        kv_cache_keys: String,

        /// Prefill chunk size (ubatch). Long prompts split into chunks of
        /// this many tokens so `cancel()` can interrupt within one chunk.
        /// Default 512 matches the Phase 1.4 sweep on LFM2; values under
        /// 256 lose ≥5% prefill throughput. 0 disables chunking (monolithic).
        #[arg(long, default_value_t = 512)]
        ubatch_size: u32,

        /// Tokens to pin at the front when the KV window fills up. 0
        /// disables shifting — overflow returns ContextOverflow. A
        /// positive value lets the session drop a middle range to make
        /// room, but ONLY if (a) the pinned prefix plus incoming tokens
        /// leave real space in the context window (so setting
        /// `--n-keep` >= `--context-size` is a no-op) and (b) the prompt
        /// itself fits (overflow still occurs if the raw prompt is
        /// larger than the window). Not supported with any TurboQuant
        /// KV-cache mode (`tq3`, `tq3-keys`, `tq3-values`) — shifting
        /// compressed caches lands in a follow-up.
        #[arg(long, default_value_t = 0)]
        n_keep: u32,

        /// Attach a LoRA adapter (.gguf or PEFT .safetensors) for this session.
        #[arg(long, value_name = "PATH")]
        lora: Option<String>,

        /// LoRA `alpha` for a PEFT `.safetensors` adapter (`scale = alpha /
        /// rank`); defaults to `alpha = rank` (scale = 1). Ignored for `.gguf`
        /// adapters, which carry alpha in their own metadata.
        #[arg(long, value_name = "ALPHA", requires = "lora")]
        lora_alpha: Option<f32>,
    },

    /// Inspect a GGUF model file.
    Inspect {
        /// Path to the GGUF model file.
        #[arg(short, long)]
        model: String,
    },

    /// Print the resolved CPU backend tier + detected SIMD features for this
    /// host (no model required). Same line `inspect` shows under "CPU Backend".
    Cpu,

    /// Interactive multi-turn chat REPL.
    ///
    /// Reads user messages from stdin one line at a time, renders
    /// the model's chat template per turn, and streams the assistant
    /// reply to stdout. The Session is kept alive across turns so
    /// the engine's prefix cache accelerates each successive prefill.
    ///
    /// Slash commands (a line starting with `/` is interpreted as a
    /// command, not sent to the model):
    /// - `/help` — list available commands.
    /// - `/clear` — reset history; the system prompt (if any) is
    ///   preserved.
    /// - `/exit`, `/quit`, EOF (Ctrl+D) — leave the REPL.
    Chat {
        /// Path to the model: a `.gguf` file, a `.json` LeapBundles
        /// manifest, or a directory containing exactly one `.json`
        /// manifest. Mutually exclusive with `--bundle-id` /
        /// `--quant`; one of the two source forms must be set.
        #[arg(
            short,
            long,
            conflicts_with_all = ["bundle_id", "quant"],
        )]
        model: Option<String>,

        /// LeapBundles bundle id (e.g. `LFM2.5-1.2B-Instruct` or
        /// `LFM2.5-1.2B-Instruct-GGUF` — `-GGUF` is appended
        /// automatically if missing). Pairs with `--quant` for
        /// auto-download from
        /// `huggingface.co/LiquidAI/LeapBundles`. Cached under
        /// `--cache-dir` (default `$HOME/.cache/cera`). Use
        /// `cera list-bundles` to discover available IDs.
        #[arg(long, requires = "quant")]
        bundle_id: Option<String>,

        /// Quantization label for `--bundle-id` (e.g. `Q4_0`,
        /// `Q8_0`). Required when `--bundle-id` is set.
        #[arg(long, requires = "bundle_id")]
        quant: Option<String>,

        /// Cache root: shared between `--bundle-id` downloads
        /// (under `<dir>/huggingface.co/...`) and the KV prefix
        /// cache (under `<dir>/kv/`). Default: `$HOME/.cache/cera`.
        /// The disk-tier prefix cache survives process restarts —
        /// useful for mobile / FFI consumers that get killed and
        /// resumed; on next launch the historical conversation
        /// prefix rehydrates instead of re-prefilling cold.
        #[arg(long)]
        cache_dir: Option<String>,

        /// Max warm (in-memory) prefix-cache size in MB. Default 256.
        #[arg(long, default_value_t = 256)]
        cache_warm_mb: u64,

        /// Max cold (disk) prefix-cache size in GB. Default 10.
        /// Only consumed when `--cache-dir` (or default) is writable.
        #[arg(long, default_value_t = 10)]
        cache_disk_gb: u64,

        /// Disable the KV prefix cache entirely. Bundle downloads
        /// still use `--cache-dir` (this flag only gates the KV
        /// prefix cache, not the bundle store).
        #[arg(long)]
        no_cache: bool,

        /// Optional system prompt pinned at the head of the
        /// conversation. Carried through every turn unchanged.
        #[arg(long)]
        system: Option<String>,

        /// Device to use: cpu, gpu, metal, or auto.
        #[arg(long, default_value = "auto")]
        device: String,

        /// Max KV context window size. Default 4096.
        #[arg(long, default_value_t = 4096)]
        context_size: usize,

        /// Max tokens generated per assistant turn.
        #[arg(long, default_value_t = 512)]
        max_tokens: usize,

        /// Sampling temperature. `<= 0` selects greedy decoding
        /// (reproducible). Default 0 so chat output is deterministic
        /// without a seed.
        #[arg(long, default_value_t = 0.0)]
        temperature: f32,

        /// RNG seed for sampling. Only meaningful when
        /// `--temperature > 0`; ignored under greedy decoding.
        #[arg(long)]
        seed: Option<u64>,

        /// Disable the inline TUI even when stdin/stdout are TTYs.
        /// Falls back to the line-based REPL — useful for shell
        /// scripting, log capture, or terminals that don't speak
        /// the ratatui control sequences cleanly. Auto-detection
        /// also falls back to the line REPL when either stdin or
        /// stdout is redirected.
        #[arg(long)]
        no_tui: bool,

        /// Attach a LoRA adapter (.gguf or PEFT .safetensors) for this session.
        #[arg(long, value_name = "PATH")]
        lora: Option<String>,

        /// LoRA `alpha` for a PEFT `.safetensors` adapter (`scale = alpha /
        /// rank`); defaults to `alpha = rank` (scale = 1). Ignored for `.gguf`
        /// adapters, which carry alpha in their own metadata.
        #[arg(long, value_name = "ALPHA", requires = "lora")]
        lora_alpha: Option<f32>,
    },

    /// Extract hidden-state embeddings for a prompt.
    ///
    /// Runs a side-effect-free prefill and prints the model's last-layer
    /// hidden states — post-final-RMSNorm, the same vector llama.cpp returns
    /// under `--pooling none`. By default the per-token states are mean-pooled
    /// into a single `[hidden_size]` vector (the common classifier / retrieval
    /// embedding); `--per-token` emits the full `[T*hidden_size]` matrix, one
    /// row per token. Requires a model whose backend implements hidden-state
    /// extraction.
    ///
    /// The prompt is raw-encoded — no BOS token and no chat template — matching
    /// the library's `hidden_states_for_text`, so the CLI and the SDK produce
    /// identical vectors for the same text. (llama.cpp's embedding CLI prepends
    /// BOS by default, so add it to your prompt if you need that exact parity.)
    Embed {
        /// Path to the model: a `.gguf` file, a `.json` LeapBundles
        /// manifest, or a directory containing exactly one `.json`
        /// manifest. Mutually exclusive with `--bundle-id` /
        /// `--quant`; one of the two source forms must be set.
        #[arg(
            short,
            long,
            conflicts_with_all = ["bundle_id", "quant"],
        )]
        model: Option<String>,

        /// LeapBundles bundle id (e.g. `LFM2.5-1.2B-Instruct` or
        /// `LFM2.5-1.2B-Instruct-GGUF` — `-GGUF` is appended
        /// automatically if missing). Pairs with `--quant` for
        /// auto-download from `huggingface.co/LiquidAI/LeapBundles`.
        #[arg(long, requires = "quant")]
        bundle_id: Option<String>,

        /// Quantization label for `--bundle-id` (e.g. `Q4_0`, `Q8_0`).
        #[arg(long, requires = "bundle_id")]
        quant: Option<String>,

        /// Cache root for `--bundle-id` downloads. Default: `$HOME/.cache/cera`.
        #[arg(long)]
        cache_dir: Option<String>,

        /// The prompt to embed.
        #[arg(short, long)]
        prompt: String,

        /// Device to use: cpu, gpu, metal, or auto.
        #[arg(long, default_value = "auto")]
        device: String,

        /// Max context window size. Default 4096.
        #[arg(long, default_value_t = 4096)]
        context_size: usize,

        /// Emit per-token hidden states (`[T*hidden_size]`, one line per
        /// token) instead of the default mean-pooled `[hidden_size]` vector.
        #[arg(long)]
        per_token: bool,

        /// Output as a JSON array (`[[..], ..]` per-token, or `[..]` pooled)
        /// instead of space-separated floats.
        #[arg(long)]
        json: bool,

        /// Attach a LoRA adapter (.gguf or PEFT .safetensors) for this session.
        #[arg(long, value_name = "PATH")]
        lora: Option<String>,

        /// LoRA `alpha` for a PEFT `.safetensors` adapter (`scale = alpha /
        /// rank`); defaults to `alpha = rank` (scale = 1). Ignored for `.gguf`
        /// adapters, which carry alpha in their own metadata.
        #[arg(long, value_name = "ALPHA", requires = "lora")]
        lora_alpha: Option<f32>,

        /// Prepend the model's BOS token before pooling — matches
        /// `add_bos_token=true` classifier/embedder heads (and llama.cpp's
        /// embedding CLI, which prepends BOS by default). Off by default so the
        /// CLI stays byte-identical to `hidden_states_for_text`.
        #[arg(long)]
        add_bos: bool,
    },

    /// Dump the next-token logits over the full vocabulary for a prompt.
    ///
    /// Runs a single prefill and prints the `[vocab_size]` logit vector for the
    /// last token (the distribution the sampler would draw from). Useful for
    /// cross-backend parity checks — diff the same prompt's logits across
    /// `--device cpu` and `--device metal`. `--top-k` prints the K
    /// highest-scoring `(token_id, logit)` pairs instead of the whole vector.
    Logits {
        /// Path to the model: a `.gguf` file, a `.json` LeapBundles manifest, or
        /// a directory containing exactly one `.json` manifest. Mutually
        /// exclusive with `--bundle-id` / `--quant`.
        #[arg(short, long, conflicts_with_all = ["bundle_id", "quant"])]
        model: Option<String>,

        /// LeapBundles bundle id (pairs with `--quant`). See `cera list-bundles`.
        #[arg(long, requires = "quant")]
        bundle_id: Option<String>,

        /// Quantization label for `--bundle-id` (e.g. `Q4_0`, `Q8_0`).
        #[arg(long, requires = "bundle_id")]
        quant: Option<String>,

        /// Cache root for `--bundle-id` downloads. Default: `$HOME/.cache/cera`.
        #[arg(long)]
        cache_dir: Option<String>,

        /// The prompt to score. Overridden by `--token-ids` when set.
        #[arg(short, long)]
        prompt: Option<String>,

        /// Raw token IDs (comma-separated). Overrides `--prompt` when set — use
        /// to score an exact token sequence without tokenizer ambiguity.
        #[arg(long)]
        token_ids: Option<String>,

        /// Prepend the model's BOS token to the tokenized `--prompt` (ignored for
        /// `--token-ids`, which is taken verbatim). Match llama.cpp, which
        /// prepends BOS by default, when diffing distributions against it.
        #[arg(long)]
        add_bos: bool,

        /// Device to use: cpu, gpu, metal, or auto.
        #[arg(long, default_value = "auto")]
        device: String,

        /// Max context window size. Default 4096.
        #[arg(long, default_value_t = 4096)]
        context_size: usize,

        /// Print only the top-K `(token_id, logit)` pairs (descending) instead
        /// of the full vocab vector. `0` (default) dumps the whole vector.
        #[arg(long, default_value_t = 0)]
        top_k: usize,

        /// Output as a JSON array (`[..]` full vector, or `[[id,logit],..]` for
        /// `--top-k`) instead of space-separated / tabular text.
        #[arg(long)]
        json: bool,
    },

    /// Tokenize text and print token IDs (for comparison with HuggingFace).
    Tokenize {
        /// Path to the GGUF model file.
        #[arg(short, long)]
        model: String,

        /// Text to tokenize.
        #[arg(short, long)]
        text: String,
    },

    /// Benchmark decode throughput with stable in-process measurements.
    ///
    /// Loads the model once, runs a short warmup, then measures decode tok/s
    /// over N runs and reports p10/p50/p90/mean/stddev. Production mode only
    /// (CERA_PROFILE must be unset) — profile-mode timings are diagnostic and
    /// don't predict real decode throughput.
    Bench {
        /// Path to the model: a `.gguf` file, a `.json` LeapBundles
        /// manifest, or a directory containing exactly one `.json`
        /// manifest. Mutually exclusive with `--bundle-id` /
        /// `--quant`; one of the two source forms must be set.
        #[arg(
            short,
            long,
            conflicts_with_all = ["bundle_id", "quant"],
        )]
        model: Option<String>,

        /// LeapBundles bundle id (e.g. `LFM2.5-1.2B-Instruct` or
        /// `LFM2.5-1.2B-Instruct-GGUF` — `-GGUF` is appended
        /// automatically if missing). Pairs with `--quant` for
        /// auto-download from
        /// `huggingface.co/LiquidAI/LeapBundles`. Cached under
        /// `--cache-dir` (default `$HOME/.cache/cera`). Use
        /// `cera list-bundles` to discover available IDs.
        #[arg(long, requires = "quant")]
        bundle_id: Option<String>,

        /// Quantization label for `--bundle-id` (e.g. `Q4_0`,
        /// `Q8_0`). Pairs with `--bundle-id`: clap rejects
        /// either flag without the other.
        #[arg(long, requires = "bundle_id")]
        quant: Option<String>,

        /// Cache root for `--bundle-id` downloads. Default:
        /// `$HOME/.cache/cera`. Used only for bundle download
        /// caching; bench's KV prefix cache is the engine default
        /// (warm-only, in-memory) regardless of this flag —
        /// `cera run --cache-dir <d>` is the right entrypoint
        /// for KV-cache-aware benchmarks. No-op when `--model`
        /// is used.
        #[arg(long)]
        cache_dir: Option<String>,

        /// The prompt to benchmark on.
        #[arg(short, long, default_value = "The capital of France is")]
        prompt: String,

        /// Number of tokens to use for the prompt (ignores --prompt if set).
        #[arg(long)]
        prompt_tokens: Option<usize>,

        /// Number of measured runs.
        #[arg(long, default_value_t = 20)]
        runs: usize,

        /// Warmup runs (discarded). Primes Metal shader cache and GPU clock.
        #[arg(long, default_value_t = 2)]
        warmup: usize,

        /// Max tokens to decode per run.
        #[arg(long, default_value_t = 128)]
        max_tokens: usize,

        /// Device to use: cpu, gpu, metal, or auto.
        #[arg(long, default_value = "auto")]
        device: String,

        /// Max context window size (KV cache). Default 4096.
        #[arg(long, default_value_t = 4096)]
        context_size: usize,

        /// Disable KV prefix caching entirely.
        #[arg(long)]
        no_cache: bool,

        /// KV cache key compression: f32 (default) or tq3 (TurboQuant 3-bit).
        #[arg(long, default_value = "f32")]
        kv_cache_keys: String,

        /// Prefill chunk size (ubatch). Lower = more cancel-responsive
        /// but slower prefill. 0 disables chunking (monolithic).
        #[arg(long, default_value_t = 512)]
        ubatch_size: u32,
    },

    /// List bundles published on `huggingface.co/LiquidAI/LeapBundles`.
    ///
    /// Discovery surface for the `--bundle-id` / `--quant` flags on
    /// `cera run` / `cera chat` / `cera bench`. Hits the HF
    /// model-info API once and prints sorted bundle names; pass
    /// `--quants` to also surface available quantization labels per
    /// bundle.
    ListBundles {
        /// Also print available quantizations under each bundle,
        /// space-separated and indented.
        #[arg(long)]
        quants: bool,
    },

    /// Download LeapBundles manifests and model files without loading them.
    ///
    /// Accepts one or more `ID:QUANT` pairs. Bare bundle IDs are normalized
    /// the same way as `run` / `chat` / `bench`, so both
    /// `LFM2.5-350M:Q4_0` and `LFM2.5-350M-GGUF:Q4_0` are valid.
    DownloadBundles {
        /// Bundle and quant pair to download, shaped `ID:QUANT`.
        /// Repeat the flag to prefetch a spread of models:
        /// `--bundle LFM2.5-350M:Q4_0 --bundle LFM2-700M:Q8_0`.
        #[arg(long = "bundle", value_name = "ID:QUANT", required = true)]
        bundles: Vec<BundleQuantPair>,

        /// Cache root for downloads. Default: `$HOME/.cache/cera`.
        #[arg(long)]
        cache_dir: Option<String>,
    },
}

#[derive(Debug, Clone, PartialEq, Eq)]
struct BundleQuantPair {
    bundle_id: String,
    quant: String,
}

impl FromStr for BundleQuantPair {
    type Err = String;

    fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
        let (bundle_id, quant) = s
            .split_once(':')
            .ok_or_else(|| "expected ID:QUANT, for example LFM2.5-350M:Q4_0".to_string())?;
        let bundle_id = bundle_id.trim();
        let quant = quant.trim();
        if bundle_id.is_empty() {
            return Err("bundle id before `:` must not be empty".to_string());
        }
        if quant.is_empty() {
            return Err("quant after `:` must not be empty".to_string());
        }
        Ok(Self {
            bundle_id: bundle_id.to_string(),
            quant: quant.to_string(),
        })
    }
}

impl std::fmt::Display for BundleQuantPair {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}:{}", self.bundle_id, self.quant)
    }
}

/// Load a `CeraEngine` from a path that may be a bare `.gguf`, a `.json`
/// manifest, or a directory containing one `.json` manifest. The engine
/// owns the model + tokenizer for the CLI's lifetime; callers get
/// `engine.new_session(...)` for text and `engine.model()` / `engine.tokenizer()`
/// handles for the audio pipeline.
///
/// Either a local file/manifest path or a LeapBundles `bundle_id`+`quant` pair.
/// The bundle path constructs a `BundleRepo` rooted at `cache_dir` so the
/// downloaded manifest + GGUFs land under a stable location and turn-2+ runs
/// hit the cache.
enum ModelSpec<'a> {
    Path(&'a Path),
    Bundle {
        id: &'a str,
        quant: &'a str,
        cache_dir: PathBuf,
    },
}

/// Suffix appended to bare bundle IDs so users can type
/// `--bundle-id LFM2.5-1.2B-Instruct` instead of
/// `--bundle-id LFM2.5-1.2B-Instruct-GGUF`. Every entry in
/// `LiquidAI/LeapBundles` today ends in `-GGUF` (the directory
/// names are derived from the upstream model + format pair). When
/// other formats land we'll revisit, but for the present catalog
/// this is a pure UX win.
const LEAP_BUNDLE_GGUF_SUFFIX: &str = "-GGUF";

/// Append `-GGUF` to `input` if it isn't already present. The
/// canonical bundle ID on `LiquidAI/LeapBundles` is the HF
/// directory name (always `<base>-GGUF` today), and the library
/// `cera::bundle::leap_bundles_manifest_url` interpolates that
/// verbatim into the URL — so normalization belongs at the CLI
/// boundary where the typo-friendly bare form is accepted.
///
/// Idempotent: passing `LFM2-1.2B-GGUF` returns the same string.
fn normalize_bundle_id(input: &str) -> String {
    if input.ends_with(LEAP_BUNDLE_GGUF_SUFFIX) {
        input.to_string()
    } else {
        format!("{input}{LEAP_BUNDLE_GGUF_SUFFIX}")
    }
}

/// Inverse of [`normalize_bundle_id`] for display: strip a trailing
/// `-GGUF` so `cera list-bundles` shows the same form users type.
/// `strip_suffix` returns `None` when the suffix isn't present,
/// preserving the original name (a future non-GGUF bundle would
/// just display verbatim).
fn display_bundle_id(name: &str) -> &str {
    name.strip_suffix(LEAP_BUNDLE_GGUF_SUFFIX).unwrap_or(name)
}

fn strip_file_scheme(s: &str) -> Option<&str> {
    if s.len() >= 7 && s[..7].eq_ignore_ascii_case("file://") {
        Some(&s[7..])
    } else {
        None
    }
}

fn resolve_manifest_file_for_download(
    repo: &cera::bundle::BundleRepo,
    progress: &CliDownloadProgress,
    value: &str,
    manifest_dir: Option<&Path>,
) -> Result<PathBuf> {
    if image_source::looks_like_url(value) {
        let result = repo.resolve_url(value, None);
        progress.finish_line();
        return Ok(result?);
    }
    if let Some(rest) = strip_file_scheme(value) {
        anyhow::bail!(
            "manifest references `file://` URI `{value}`; pass the local path directly, e.g. `{rest}`"
        );
    }
    let path = Path::new(value);
    if path.is_absolute() {
        Ok(path.to_path_buf())
    } else if let Some(dir) = manifest_dir {
        Ok(dir.join(path))
    } else {
        Ok(path.to_path_buf())
    }
}

fn download_bundle_pair(
    repo: &cera::bundle::BundleRepo,
    pair: &BundleQuantPair,
    progress: &CliDownloadProgress,
) -> Result<()> {
    let normalized = normalize_bundle_id(&pair.bundle_id);
    let manifest_url = cera::bundle::leap_bundles_manifest_url(&normalized, &pair.quant)?;
    eprintln!("Resolving bundle `{normalized}` (quant `{}`)", pair.quant);
    let manifest_result = repo.resolve_url(&manifest_url, None);
    progress.finish_line();
    let manifest_path =
        manifest_result.with_context(|| format!("downloading manifest `{manifest_url}`"))?;
    let manifest = cera::manifest::Manifest::from_file(&manifest_path)?;
    let manifest_dir = manifest_path.parent();
    eprintln!("  manifest: {}", manifest_path.display());
    for (role, value) in manifest.files_in_order() {
        let path = resolve_manifest_file_for_download(repo, progress, value, manifest_dir)
            .with_context(|| {
                format!("resolving `{role}` file for `{normalized}:{}`", pair.quant)
            })?;
        eprintln!("  {role}: {}", path.display());
    }
    progress.finish_line();
    Ok(())
}

/// Write the chat history to `path` as a plain-text transcript:
/// one block per message shaped `<role>: <content>\n`, separated
/// by a blank line. Multi-line content is written verbatim (no
/// escaping) so it round-trips through `cat` / `less` cleanly.
///
/// **Format is for human reading, not round-trip parsing.** Content
/// containing a literal `\nassistant: …` line would render as a
/// fake turn header on read-back. A future `/load` command would
/// need a structured format (JSON Lines) instead — out of scope
/// for this v1 dump.
///
/// Used by both the line REPL and the inline TUI's `/save` command.
/// I/O errors propagate; the caller surfaces them as a status line
/// without killing the REPL.
fn write_transcript(history: &[cera::tokenizer::ChatMessage], path: &Path) -> std::io::Result<()> {
    use std::io::{BufWriter, Write};
    // Buffer the writes so a long conversation doesn't pay one
    // syscall per `writeln!` (each turn issues up to two: the
    // blank separator and the role+content line). `BufWriter`
    // flushes on drop, but we call `flush()` explicitly so any
    // late I/O error surfaces here instead of being silently
    // swallowed by the destructor.
    let f = std::fs::File::create(path)?;
    let mut w = BufWriter::new(f);
    for (i, msg) in history.iter().enumerate() {
        if i > 0 {
            // Blank line between turns.
            writeln!(w)?;
        }
        writeln!(w, "{}: {}", msg.role, msg.content)?;
    }
    w.flush()?;
    Ok(())
}

/// Drop the oldest user+assistant pair from `history` (and the matching
/// entries in `history_images`), preserving any system message at index 0
/// and never touching the most recent entry (which is the user turn the
/// caller is about to prefill). Used by the chat REPL to shrink history
/// on `CeraError::ContextOverflow` and retry, instead of bubbling overflow
/// up as a hard error and forcing the user to `/clear`.
///
/// Pairs are dropped together so the chat-template's alternating
/// user/assistant invariant stays intact. Returns `false` when there's
/// nothing left to drop without touching the system entry or the current
/// turn — caller surfaces "prompt too large for context window even with
/// empty history".
pub(crate) fn truncate_oldest_turn_pair(
    history: &mut Vec<cera::tokenizer::ChatMessage>,
    history_images: &mut Vec<Vec<Arc<Vec<u8>>>>,
) -> bool {
    debug_assert_eq!(history.len(), history_images.len());
    // Index of the first non-system entry. System lives at index 0 when
    // present (or there's no system at all).
    let start = if history.first().map(|m| m.role.as_str()) == Some("system") {
        1
    } else {
        0
    };
    // Need at least 2 non-system entries to drop ONE pair without touching
    // the just-pushed user turn at the tail. (1 means only the current
    // user turn exists past the system; nothing older to drop.)
    if history.len() <= start + 1 {
        return false;
    }
    history.remove(start);
    history_images.remove(start);
    // If the next entry is the matching assistant reply, drop it too. The
    // length check stays bounded by `start + 1` (the original user-turn
    // tail is now at `start` after the first remove if there's no
    // assistant in between). Without this guard a malformed history
    // (interrupted turn with no assistant reply) would still drop one
    // entry safely.
    if history.len() > start + 1 && history[start].role == "assistant" {
        history.remove(start);
        history_images.remove(start);
    }
    true
}

/// Simulate `n_pairs` consecutive `truncate_oldest_turn_pair` calls without
/// actually mutating anything. Returns `(start, end, applied)` describing
/// the slice that would remain after the truncations:
///
/// * `start` — index 0 unless a system message lives at index 0 (then 1).
/// * `end` — index just past the last dropped entry; the kept entries are
///   `history[..start]` (system prefix, possibly empty) and
///   `history[end..]`.
/// * `applied` — number of pairs actually dropped, capped by what the
///   real helper would have done. Equal to `n_pairs` in the common case;
///   less when fewer than `n_pairs` pairs exist past the system prefix
///   without touching the just-pushed user turn at the tail.
///
/// Lets the TUI build the per-turn channel send by chaining the kept
/// slices without paying the O(N) `Vec::remove` shift inside a loop.
pub(crate) fn simulate_truncate_oldest_turn_pairs(
    history: &[cera::tokenizer::ChatMessage],
    n_pairs: usize,
) -> (usize, usize, usize) {
    let start = if history.first().map(|m| m.role.as_str()) == Some("system") {
        1
    } else {
        0
    };
    let mut end = start;
    let mut applied = 0;
    while applied < n_pairs {
        // Mirror the helper's "need at least 2 entries past `end` (incl.
        // the tail) to drop one pair without touching the just-pushed
        // user turn" precondition.
        if history.len() <= end + 1 {
            break;
        }
        // Drop the user-or-orphan entry at `end`.
        end += 1;
        // Helper drops the next entry too iff it is the matching
        // assistant reply. Keep the same predicate so simulation
        // matches mutation byte-for-byte.
        if end < history.len() && history[end].role == "assistant" {
            end += 1;
        }
        applied += 1;
    }
    (start, end, applied)
}

/// Default cache root, used by the bundle-id flow when `--cache-dir` is
/// unset: `$HOME/.cache/cera` when `$HOME` is set, otherwise
/// `<TMPDIR>/.cache/cera`. Shared between the `BundleRepo` (downloads land
/// under `<root>/huggingface.co/...`) and the KV prefix cache (under
/// `<root>/kv`), so a single `--cache-dir` flag covers both — unify the
/// user's cache footprint instead of fragmenting it.
fn default_cache_dir() -> PathBuf {
    let base = std::env::var_os("HOME")
        .map(PathBuf::from)
        .unwrap_or_else(std::env::temp_dir);
    base.join(".cache/cera")
}

/// Take the four CLI flags `(--model, --bundle-id, --quant, --cache-dir)` and
/// validate "exactly one source set". Then build a `ModelSpec` and load
/// through [`load_engine_from_spec`]. Errors before any I/O so a flag-misuse
/// surfaces fast with a clear message rather than a downstream HTTP/file
/// error.
fn resolve_engine(
    model: Option<&str>,
    bundle_id: Option<&str>,
    quant: Option<&str>,
    cache_dir: Option<&str>,
    device: &str,
    context_size: usize,
) -> Result<CeraEngine> {
    match (model, bundle_id, quant) {
        (Some(p), None, None) => {
            load_engine_from_spec(ModelSpec::Path(Path::new(p)), device, context_size)
        }
        (None, Some(id), Some(q)) => {
            let cache = cache_dir
                .map(PathBuf::from)
                .unwrap_or_else(default_cache_dir);
            // Append `-GGUF` if the user didn't include it. Keeps
            // `--bundle-id LFM2.5-1.2B-Instruct` and the explicit
            // `--bundle-id LFM2.5-1.2B-Instruct-GGUF` both valid;
            // the URL Liquid actually publishes always has the
            // suffix.
            let normalized = normalize_bundle_id(id);
            load_engine_from_spec(
                ModelSpec::Bundle {
                    id: &normalized,
                    quant: q,
                    cache_dir: cache,
                },
                device,
                context_size,
            )
        }
        (None, Some(_), None) | (None, None, Some(_)) => {
            anyhow::bail!(
                "`--bundle-id` and `--quant` must be passed together \
                 (e.g. `--bundle-id LFM2-1.2B-GGUF --quant Q4_0`)"
            )
        }
        (Some(_), Some(_), _) | (Some(_), None, Some(_)) => anyhow::bail!(
            "`--model` and `--bundle-id`/`--quant` are mutually exclusive — \
             pick one source"
        ),
        (None, None, None) => anyhow::bail!(
            "no model source: pass either `--model <path>` or \
             `--bundle-id <id> --quant <quant>`"
        ),
    }
}

fn load_engine_from_spec(
    spec: ModelSpec<'_>,
    device: &str,
    context_size: usize,
) -> Result<CeraEngine> {
    let backend = BackendPreference::parse_str(device).map_err(|e| anyhow::anyhow!("{e}"))?;
    let engine = match spec {
        ModelSpec::Path(path) => {
            // `..Default::default()` picks up optional fields (e.g.
            // `bundle_repo`, which is gated behind the `remote` feature
            // — cera-cli now enables it unconditionally to power
            // `--bundle-id`).
            CeraEngine::from_path(
                path,
                EngineConfig {
                    context_size,
                    backend,
                    ..Default::default()
                },
            )?
        }
        ModelSpec::Bundle {
            id,
            quant,
            cache_dir,
        } => {
            eprintln!(
                "Resolving bundle `{id}` (quant `{quant}`) into cache `{}`…",
                cache_dir.display()
            );
            // Concrete `Arc<CliDownloadProgress>` first so we can seal the
            // progress line after the resolve; coerce to `Arc<dyn ...>` only
            // at the BundleRepo call site.
            let progress = Arc::new(CliDownloadProgress::default());
            let repo = cera::bundle::BundleRepo::with_progress(
                cache_dir,
                progress.clone() as Arc<dyn cera::bundle::DownloadProgress>,
            );
            let engine = CeraEngine::from_bundle_id(
                id,
                quant,
                EngineConfig {
                    context_size,
                    backend,
                    bundle_repo: Some(repo),
                },
            )?;
            progress.finish_line();
            engine
        }
    };
    eprintln!(
        "Using {} backend ({})",
        match backend {
            BackendPreference::Auto => "auto-selected",
            BackendPreference::Cpu => "CPU",
            BackendPreference::Gpu => "wgpu",
            BackendPreference::Metal => "native Metal",
        },
        engine.metadata().architecture,
    );
    Ok(engine)
}

/// Attach a LoRA adapter to a freshly-created session when `--lora <PATH>` is
/// set. Shared by `Run`, `Chat`, and `Embed` so every session-creation site
/// applies the adapter identically. The file extension selects the loader:
/// `.safetensors` → PEFT (`scale = alpha / rank`, where `alpha` comes from
/// `--lora-alpha`; without it `alpha` defaults to the rank, i.e. `scale = 1` —
/// the loader does not read `adapter_config.json`); anything else → llama.cpp
/// GGUF (`alpha` from the adapter's own metadata). Dimensions are validated by
/// `attach_lora_adapters`, so a mismatched adapter errors clearly rather than
/// corrupting output.
fn attach_lora(
    session: &mut cera::Session,
    lora: &Option<String>,
    lora_alpha: Option<f32>,
) -> Result<()> {
    if let Some(p) = lora {
        let path = Path::new(p);
        let is_safetensors = path
            .extension()
            .and_then(|e| e.to_str())
            .is_some_and(|e| e.eq_ignore_ascii_case("safetensors"));
        let adapters = if is_safetensors {
            cera::lora::LoraAdapterWeights::from_safetensors(path, lora_alpha)
        } else {
            cera::lora::LoraAdapterWeights::from_gguf(path)
        }
        .with_context(|| format!("loading LoRA adapter {p}"))?;
        session.attach_lora_adapters(adapters)?;
        eprintln!("attached LoRA adapter: {p}");
    }
    Ok(())
}

/// Format an `f32` for `embed --json` output. Non-finite values (`NaN` / `inf`)
/// become `null` so the emitted array stays valid JSON.
/// Write one `[hidden_size]` row of an `embed` result to `w` — comma-separated
/// (`json`, non-finite → `null`) or space-separated. Streams value-by-value,
/// formatting each float straight into `w` (no per-element `String`), so a long
/// `--per-token` result never materializes the whole matrix.
fn write_embed_row<W: std::io::Write>(w: &mut W, row: &[f32], json: bool) -> std::io::Result<()> {
    for (j, v) in row.iter().enumerate() {
        if j > 0 {
            write!(w, "{}", if json { "," } else { " " })?;
        }
        // JSON has no NaN/inf literal — emit `null` so the array stays valid.
        if json && !v.is_finite() {
            write!(w, "null")?;
        } else {
            write!(w, "{v}")?;
        }
    }
    Ok(())
}

/// Write one logit straight into `w` (no intermediate `String` — the full-vocab
/// dump is ~152k values). In JSON mode a non-finite value becomes `null` (JSON
/// has no NaN/inf literal); otherwise the native `{v}` rendering (`NaN`/`inf`)
/// is kept for human/plain-text output.
fn write_logit<W: std::io::Write>(w: &mut W, v: f32, json: bool) -> std::io::Result<()> {
    if json && !v.is_finite() {
        write!(w, "null")
    } else {
        write!(w, "{v}")
    }
}

/// Configure the engine's KV prefix cache from the four CLI flags shared by
/// `Run` and `Chat`. Encapsulates the `<root>/kv` derivation rule + the
/// `--no-cache` short-circuit so both subcommands stay in sync.
///
/// Behavior:
/// - `no_cache == true` → all-zeros config (warm + cold both disabled).
/// - explicit `--cache-dir foo` → KV files under `foo/kv` (peer of
///   `foo/huggingface.co/...` for bundle downloads).
/// - default `$HOME/.cache/cera/kv` when `$HOME` is set.
/// - no `$HOME` and no `--cache-dir` → KV stays disabled (TMPDIR fallback
///   in `default_cache_dir()` is bundle-only).
fn configure_prefix_cache(
    engine: &CeraEngine,
    cache_dir: Option<&str>,
    no_cache: bool,
    cache_warm_mb: u64,
    cache_disk_gb: u64,
) {
    if no_cache {
        engine.configure_cache(cera::kv_cache::KvCacheConfig {
            cache_dir: None,
            max_warm_entries: 0,
            max_warm_bytes: 0,
            max_cold_bytes: 0,
        });
        return;
    }
    let kv_dir: Option<PathBuf> = if let Some(d) = cache_dir {
        Some(PathBuf::from(d).join("kv"))
    } else if std::env::var_os("HOME").is_some() {
        Some(default_cache_dir().join("kv"))
    } else {
        None
    };
    engine.configure_cache(cera::kv_cache::KvCacheConfig {
        cache_dir: kv_dir,
        max_warm_entries: 32,
        max_warm_bytes: cache_warm_mb * 1024 * 1024,
        max_cold_bytes: cache_disk_gb * 1024 * 1024 * 1024,
    });
}

/// (p10, p50, p90, mean, stddev)
fn summarize(mut xs: Vec<f64>) -> (f64, f64, f64, f64, f64) {
    assert!(!xs.is_empty());
    xs.sort_by(|a, b| a.total_cmp(b));
    let n = xs.len();
    let p = |q: f64| {
        let idx = ((n as f64 - 1.0) * q).round() as usize;
        xs[idx]
    };
    let mean = xs.iter().sum::<f64>() / n as f64;
    let var = xs.iter().map(|x| (x - mean).powi(2)).sum::<f64>() / n as f64;
    (p(0.1), p(0.5), p(0.9), mean, var.sqrt())
}

/// Read a PCM16 WAV file and return (samples_f32_in_minus1_to_1,
/// sample_rate). Output is always mono: multi-channel inputs are
/// down-mixed by averaging across channels per frame. Sample rate
/// is returned untouched — resampling happens at the call site.
///
/// Constraints: `audio_format == 1` (PCM), `bits_per_sample == 16`,
/// `channels >= 1`. Anything else errors with a typed message
/// pointing at the offending field.
///
/// Skips unknown subchunks (LIST, JUNK, etc.) between fmt and data
/// per the RIFF spec. Emits a `note:` line on stderr when down-mix
/// happens so the user can see why the channel count dropped.
fn read_wav_pcm16_mono(path: &str) -> Result<(Vec<f32>, u32)> {
    use anyhow::{Context, anyhow, bail};
    use std::io::Read;
    let mut f = std::fs::File::open(path).with_context(|| format!("opening WAV `{path}`"))?;
    let mut buf = Vec::new();
    f.read_to_end(&mut buf)
        .with_context(|| format!("reading WAV `{path}`"))?;

    let read_u16 = |o: usize| -> Result<u16> {
        let end = o.checked_add(2).ok_or_else(|| anyhow!("offset overflow"))?;
        if end > buf.len() {
            bail!(
                "WAV `{path}` truncated: needed u16 at offset {o}, file is {} bytes",
                buf.len()
            );
        }
        Ok(u16::from_le_bytes(buf[o..end].try_into().unwrap()))
    };
    let read_u32 = |o: usize| -> Result<u32> {
        let end = o.checked_add(4).ok_or_else(|| anyhow!("offset overflow"))?;
        if end > buf.len() {
            bail!(
                "WAV `{path}` truncated: needed u32 at offset {o}, file is {} bytes",
                buf.len()
            );
        }
        Ok(u32::from_le_bytes(buf[o..end].try_into().unwrap()))
    };

    if buf.len() < 12 || &buf[0..4] != b"RIFF" || &buf[8..12] != b"WAVE" {
        bail!("WAV `{path}`: missing RIFF/WAVE header");
    }

    // Walk subchunks starting at offset 12. Find "fmt " then "data".
    let mut o = 12usize;
    let mut fmt_off: Option<usize> = None;
    let mut data: Option<(usize, usize)> = None;
    while o + 8 <= buf.len() {
        let id = &buf[o..o + 4];
        let sz = read_u32(o + 4)? as usize;
        let body = o + 8;
        if id == b"fmt " {
            fmt_off = Some(body);
        } else if id == b"data" {
            if body + sz > buf.len() {
                bail!(
                    "WAV `{path}`: data chunk size {sz} exceeds file (body+sz={} > len={})",
                    body + sz,
                    buf.len()
                );
            }
            data = Some((body, sz));
        }
        // Subchunks are word-aligned: pad odd sizes by 1.
        o = body + sz + (sz & 1);
    }
    let fmt = fmt_off.ok_or_else(|| anyhow!("WAV `{path}`: no `fmt ` chunk"))?;
    let (data_off, data_sz) = data.ok_or_else(|| anyhow!("WAV `{path}`: no `data` chunk"))?;

    let audio_format = read_u16(fmt)?;
    let channels = read_u16(fmt + 2)?;
    let sample_rate = read_u32(fmt + 4)?;
    let bits = read_u16(fmt + 14)?;
    if audio_format != 1 {
        bail!(
            "WAV `{path}`: audio_format {audio_format} (expected 1=PCM). Re-encode as 16-bit PCM."
        );
    }
    if channels == 0 {
        bail!("WAV `{path}`: channels=0 in fmt header (must be >= 1)");
    }
    if bits != 16 {
        bail!("WAV `{path}`: {bits} bits/sample (expected 16). Re-encode as 16-bit PCM.");
    }

    // PCM16 frame = `channels` samples × 2 bytes.
    let frame_bytes = 2usize * channels as usize;
    if data_sz % frame_bytes != 0 {
        bail!(
            "WAV `{path}`: data chunk size {data_sz} is not a multiple of frame size \
             {frame_bytes} ({channels} channels × 2 bytes)"
        );
    }
    let n_frames = data_sz / frame_bytes;

    // Symmetric scale: i16::MIN -> -1.0, i16::MAX -> ~1.0. Using 32768
    // (vs 32767) keeps zero exactly at zero and avoids the asymmetric
    // off-by-one when round-tripping through `write_wav` (which clamps
    // before scaling by 32767).
    let read_sample = |frame_idx: usize, ch: usize| -> f32 {
        let o = data_off + (frame_idx * channels as usize + ch) * 2;
        let s = i16::from_le_bytes([buf[o], buf[o + 1]]);
        s as f32 / 32768.0
    };

    let mut samples = Vec::with_capacity(n_frames);
    if channels == 1 {
        for f in 0..n_frames {
            samples.push(read_sample(f, 0));
        }
    } else {
        // Down-mix by averaging across channels. Average (vs sum) keeps
        // amplitudes inside [-1, 1] when each channel is in range; a
        // sum could clip a stereo input where both channels are at full
        // scale.
        let inv = 1.0_f32 / channels as f32;
        for f in 0..n_frames {
            let mut acc = 0.0_f32;
            for c in 0..channels as usize {
                acc += read_sample(f, c);
            }
            samples.push(acc * inv);
        }
        eprintln!(
            "note: down-mixing {channels}-channel WAV `{path}` to mono \
             by averaging across channels. To skip this step, pass mono \
             PCM16 directly — e.g. `sox in.wav -c 1 out.wav` or \
             `ffmpeg -i in.wav -ac 1 out.wav`."
        );
    }
    Ok((samples, sample_rate))
}

/// Linearly resample `samples` from `sr_in` to `sr_out` Hz.
/// Returns `samples` unchanged when `sr_in == sr_out`.
///
/// Linear interpolation is the simplest viable resampler:
/// - Upsample (e.g. 8 kHz → 16 kHz): introduces a smoothed
///   high-frequency rolloff but no aliasing — adequate for ASR.
/// - Downsample (e.g. 44.1 kHz → 16 kHz): does NOT apply an
///   anti-aliasing low-pass filter, so frequencies above the
///   output Nyquist (8 kHz here) fold back as aliasing artifacts.
///   Speech energy is mostly under 8 kHz so this is tolerable for
///   ASR but not studio-quality. Users who care can pre-resample
///   externally with `sox` / `ffmpeg` and pass a 16 kHz WAV
///   directly to bypass this path.
///
/// Time complexity: O(n_out). Space: one allocation of size
/// `n_out * 4 bytes`. No SIMD; the audio path is dwarfed by
/// model inference so the linear scan isn't a bottleneck.
///
/// Empty input or zero rates return an empty `Vec` — these are
/// degenerate but cheap to handle here so the caller doesn't
/// have to special-case them.
fn resample_linear(samples: &[f32], sr_in: u32, sr_out: u32) -> Vec<f32> {
    if samples.is_empty() || sr_in == 0 || sr_out == 0 {
        return Vec::new();
    }
    if sr_in == sr_out {
        return samples.to_vec();
    }
    let n_in = samples.len();
    // Output length scales by the rate ratio. Use f64 to avoid
    // precision loss on long inputs (a 60s @ 44.1kHz clip is
    // 2.6M samples — f32 mantissa starts losing integer fidelity
    // around 16M, so f32 would be fine here, but f64 is free).
    let ratio = sr_out as f64 / sr_in as f64;
    // Clamp to ≥ 1 for non-empty input. Without this a tiny input
    // (e.g. `n_in=1` with `sr_in=48_000, sr_out=16_000`) would
    // round `n_in * ratio = 0.333 → 0` and the resampler would
    // hand back an empty buffer, which `Session::append_audio`
    // surfaces as `EmptyInput`. The empty-input early return
    // above handles `n_in == 0`; this handles the round-to-zero
    // edge case for non-empty input.
    let n_out = ((n_in as f64) * ratio).round().max(1.0) as usize;
    let mut out = Vec::with_capacity(n_out);
    let step = sr_in as f64 / sr_out as f64;
    for i in 0..n_out {
        let pos = i as f64 * step;
        let idx = pos.floor() as usize;
        let frac = (pos - idx as f64) as f32;
        // Clamp to [0, n_in - 1]. The last interval (idx == n_in - 1,
        // frac > 0) interpolates against itself — equivalent to
        // hold-the-last-sample, which is the standard end-of-buffer
        // handling for linear resampling.
        let a = samples[idx.min(n_in - 1)];
        let b = samples[(idx + 1).min(n_in - 1)];
        out.push(a + (b - a) * frac);
    }
    out
}

/// Pick a vocab-resident special token to use as the audio
/// insertion marker in chat-template renders. The token must
/// (1) tokenize as a single ID regardless of context (i.e. be a
/// real special token, not a unicode placeholder), and (2) never
/// appear in real user content so we don't false-match it.
///
/// Tries the LFM2-family reserved slots in order. Returns
/// `(token_id, token_name_for_template_substitution)`. Errors
/// when none are present — without a marker we can't split the
/// rendered token stream deterministically; the caller should
/// drop `--system` to fall back to plain audio-in mode.
fn pick_audio_marker_token(tok: &BpeTokenizer) -> Result<(u32, &'static str)> {
    // Candidate list lives in `cera` core so this path and `CeraEngine::transcribe`
    // can't drift apart.
    for name in CeraEngine::AUDIO_MARKER_CANDIDATES {
        if let Some(id) = tok.special_token_id(name) {
            return Ok((id, name));
        }
    }
    anyhow::bail!(
        "no suitable special token for audio chat-template insertion. \
         Tried <|reserved_4|>..<|reserved_7|>. Drop --system to use \
         plain audio-in mode (text prefix → audio, no template)."
    );
}

/// Find the unique index of `marker_id` in `tokens`. Returns the
/// zero-based position; the caller slices `tokens[..idx]` and
/// `tokens[idx + 1..]` for the prefix and suffix around the marker.
/// Single-pass scan — no allocation.
///
/// Errors include `marker_name` (the human-readable special-token
/// string, not just the numeric id) so users hitting these cases
/// know which literal to inspect / remove from `--prompt` or
/// `--system`. The two failures:
///
/// - **Marker not found**: chat template stripped the placeholder
///   (e.g. an aggressive escape filter), OR rendering mismatched
///   the user content. Caller should drop `--system` to fall back
///   to plain audio-in.
/// - **Marker appears more than once**: user-supplied
///   `--prompt`/`--system` text contains a literal occurrence of
///   the marker token name, making the insertion point ambiguous.
///   Caller should remove that literal.
fn split_at_marker(tokens: &[u32], marker_id: u32, marker_name: &str) -> Result<usize> {
    // Delegates to the shared core scanner so the marker-splitting logic lives in
    // one place. Append CLI-specific recovery hints (flag names) to the core error.
    CeraEngine::split_tokens_at_marker(tokens, marker_id, marker_name).map_err(|e| {
        anyhow::anyhow!(
            "{e}. Drop `--system` to fall back to plain audio-in, or remove any literal \
             marker text from `--prompt` / `--system`."
        )
    })
}

/// Write PCM float32 samples as a WAV file (16-bit PCM, mono).
fn write_wav(path: &str, samples: &[f32], sample_rate: u32) -> Result<()> {
    use std::io::Write;
    let mut f = std::fs::File::create(path)?;
    let n = samples.len() as u32;
    let data_size = n * 2;
    let file_size = 36 + data_size;
    f.write_all(b"RIFF")?;
    f.write_all(&file_size.to_le_bytes())?;
    f.write_all(b"WAVE")?;
    f.write_all(b"fmt ")?;
    f.write_all(&16u32.to_le_bytes())?;
    f.write_all(&1u16.to_le_bytes())?;
    f.write_all(&1u16.to_le_bytes())?;
    f.write_all(&sample_rate.to_le_bytes())?;
    f.write_all(&(sample_rate * 2).to_le_bytes())?;
    f.write_all(&2u16.to_le_bytes())?;
    f.write_all(&16u16.to_le_bytes())?;
    f.write_all(b"data")?;
    f.write_all(&data_size.to_le_bytes())?;
    for &s in samples {
        let i16_val = (s.clamp(-1.0, 1.0) * 32767.0) as i16;
        f.write_all(&i16_val.to_le_bytes())?;
    }
    Ok(())
}

/// Parse a CLI KV-cache-compression flag value into a `KvCompression`.
///
/// Modes:
/// - `f32` / `none`: uncompressed (default)
/// - `tq3` / `turboquant`: TurboQuant on both keys (3-bit) and values (2-bit)
/// - `tq3-keys`: TurboQuant keys only (values stay f32) — debugging
/// - `tq3-values`: TurboQuant values only (keys stay f32) — debugging
fn setup_kv_compression(
    model: &dyn cera::model::Model,
    kv_cache_mode: &str,
) -> Result<cera::kv_cache::KvCompression> {
    use cera::kv_cache::KvCompression;
    let seed: u64 = 42; // deterministic default seed

    let (keys, values) = match kv_cache_mode {
        "f32" | "none" => return Ok(KvCompression::None),
        "tq3" | "turboquant" => (true, true),
        "tq3-keys" => (true, false),
        "tq3-values" => (false, true),
        other => anyhow::bail!(
            "unknown --kv-cache-keys mode: {other} (use f32, tq3, tq3-keys, or tq3-values)"
        ),
    };

    if model.turboquant_supported() {
        eprintln!(
            "TurboQuant KV compression enabled (keys: {}, values: {})",
            if keys { "3-bit" } else { "f32" },
            if values { "2-bit" } else { "f32" }
        );
        Ok(KvCompression::TurboQuant { seed, keys, values })
    } else {
        eprintln!(
            "warning: TurboQuant not supported by this model/backend; falling back to f32 KV"
        );
        Ok(KvCompression::None)
    }
}

fn main() -> Result<()> {
    tracing_subscriber::fmt()
        .with_env_filter(tracing_subscriber::EnvFilter::from_default_env())
        .init();

    let cli = Cli::parse();

    // Warm the compute pools + size rayon to P-cores. After `Cli::parse()` so
    // `--help` / parse errors don't pay the pool spawn.
    cera::backend::cpu::configure_thread_pool();

    match cli.command {
        Command::Run {
            model,
            bundle_id,
            quant,
            prompt,
            max_tokens,
            temperature,
            grammar,
            json,
            tools,
            constrain_tools,
            device,
            token_ids,
            context_size,
            vocoder,
            audio_in,
            image,
            max_long_size,
            audio_out,
            system,
            audio_temperature,
            audio_top_k,
            cache_dir,
            cache_warm_mb,
            cache_disk_gb,
            no_cache,
            kv_cache_keys,
            ubatch_size,
            n_keep,
            lora,
            lora_alpha,
        } => {
            // Compile the grammar (if any) up front so a malformed GBNF fails fast,
            // before the engine loads ~1 GB of weights. `--json` uses a bundled grammar;
            // `--grammar` takes an inline string or `@path` to a file.
            let grammar_compiled: Option<std::sync::Arc<cera::grammar::Grammar>> = {
                let src: Option<String> = if json {
                    Some(include_str!("../grammars/json.gbnf").to_string())
                } else if let Some(g) = &grammar {
                    Some(match g.strip_prefix('@') {
                        Some(path) => std::fs::read_to_string(path)
                            .with_context(|| format!("reading grammar file `{path}`"))?,
                        None => g.clone(),
                    })
                } else {
                    None
                };
                match src {
                    Some(s) => Some(std::sync::Arc::new(
                        cera::grammar::Grammar::parse(&s).context("parsing GBNF grammar")?,
                    )),
                    None => None,
                }
            };

            // Parse `--tools` up front (fail fast, before weights load). Accepts
            // an inline JSON array or `@path/to/tools.json`.
            let tool_defs: Vec<cera::tools::ToolDef> = match &tools {
                Some(spec) => {
                    let raw = match spec.strip_prefix('@') {
                        Some(path) => std::fs::read_to_string(path)
                            .with_context(|| format!("reading tools file `{path}`"))?,
                        None => spec.clone(),
                    };
                    let defs: Vec<cera::tools::ToolDef> = serde_json::from_str(&raw).context(
                        "parsing --tools JSON (expected an array of \
                         {name, description?, parameters} objects)",
                    )?;
                    // Each tool's `parameters` must be a JSON Schema object.
                    // A non-object (e.g. `"parameters": null`) breaks chat
                    // templates that read `tool.parameters.properties` and
                    // yields a zero-property grammar — fail fast with the
                    // offending tool named. Mirrors the FFI-layer check.
                    for def in &defs {
                        anyhow::ensure!(
                            def.parameters.is_object(),
                            "tool `{}` has non-object `parameters` \
                             (expected a JSON Schema object)",
                            def.name
                        );
                    }
                    defs
                }
                None => Vec::new(),
            };

            // Resolve `--image` arguments BEFORE engine load so a missing
            // file / unreachable URL fails fast — engine load can spend
            // ~1 GB of RAM on Q4_0 weights and a typo'd `--image
            // not_a_path.jpg` shouldn't pay that cost. Each arg may be a
            // filesystem path or an `http(s)://` URL; the 50 MB cap rejects
            // unbounded inputs uniformly across both branches. Empty vec
            // when the flag isn't set; the image branch later checks
            // `image_bytes.is_empty()`.
            let image_bytes: Vec<Vec<u8>> = image
                .iter()
                .map(|arg| {
                    if image_source::looks_like_url(arg) {
                        eprintln!("Downloading image: {arg}");
                    }
                    let bytes = image_source::load(arg, image_source::MAX_IMAGE_BYTES)
                        .with_context(|| format!("--image {arg}"))?;
                    eprintln!("Loaded image: {arg} ({} bytes)", bytes.len());
                    Ok::<_, anyhow::Error>(bytes)
                })
                .collect::<Result<_>>()?;

            // `cache_dir` is shared between bundle downloads (when
            // `--bundle-id` is set) and the KV prefix cache below.
            let engine = resolve_engine(
                model.as_deref(),
                bundle_id.as_deref(),
                quant.as_deref(),
                cache_dir.as_deref(),
                &device,
                context_size,
            )?;
            let tokenizer = engine.tokenizer();
            let add_bos = engine.metadata().add_bos_token;

            let kv_compression = setup_kv_compression(engine.model(), &kv_cache_keys)?;

            // Configure KV prefix cache (shared logic with `Chat`).
            configure_prefix_cache(
                &engine,
                cache_dir.as_deref(),
                no_cache,
                cache_warm_mb,
                cache_disk_gb,
            );

            // Image-input path (mutually exclusive with --audio-in,
            // --vocoder, --audio-out, --token-ids via clap
            // `conflicts_with`). Renders the chat template with
            // multimodal content and feeds image embeddings through
            // `Session::append_chat_with_images` (PR #134), which
            // walks `<image>` markers and splices in the model-
            // specific `<|image_start|>` / `<|image_end|>` envelope.
            // Image bytes were read above (pre-engine-load) so this
            // branch starts with files known to be valid.
            if !image_bytes.is_empty() {
                eprintln!(
                    "Model: {} | {} layers | hidden={}",
                    engine.model().config().architecture,
                    engine.model().config().n_layers,
                    engine.model().config().hidden_size
                );

                let mut session = engine.new_session(cera::SessionConfig {
                    kv_compression,
                    seed: None,
                    ubatch_size,
                    n_keep,
                    ..Default::default()
                })?;
                attach_lora(&mut session, &lora, lora_alpha)?;
                // Honored by `append_chat_with_images` below (and any
                // later append) — bounds each image's encoded long side.
                session.set_image_max_long_size(max_long_size);

                // Build messages: optional system turn (single text
                // item) + a user turn with N image items followed by
                // the optional --prompt as text. `[Image, …, Text]`
                // is the order LFM2-VL was trained on (matches
                // mtmd-cli's `<image> Describe<|im_end|>` shape).
                let mut content: Vec<cera::tokenizer::ContentItem> =
                    vec![cera::tokenizer::ContentItem::Image; image_bytes.len()];
                if let Some(p) = &prompt
                    && !p.is_empty()
                {
                    content.push(cera::tokenizer::ContentItem::Text { text: p.clone() });
                }
                let mut messages = Vec::new();
                if let Some(sys) = &system {
                    messages.push(cera::tokenizer::ChatMessageMultimodal {
                        role: "system".into(),
                        content: vec![cera::tokenizer::ContentItem::Text { text: sys.clone() }],
                    });
                }
                messages.push(cera::tokenizer::ChatMessageMultimodal {
                    role: "user".into(),
                    content,
                });
                let images_refs: Vec<&[u8]> = image_bytes.iter().map(|v| v.as_slice()).collect();

                let prefill_start = std::time::Instant::now();
                session.append_chat_with_images(&messages, &images_refs, true)?;
                let prefill_elapsed = prefill_start.elapsed();
                let kv_after_prefill = session.position();
                eprintln!(
                    "Image prefill: {kv_after_prefill} KV tokens, {:.1} ms",
                    prefill_elapsed.as_secs_f64() * 1000.0
                );

                let opts = cera::GenerateOpts {
                    max_tokens: max_tokens as u32,
                    temperature,
                    grammar: grammar_compiled.clone(),
                    ..Default::default()
                };
                let mut sink = StdoutSink::new(tokenizer, session.cancel_handle());
                let summary = session.generate(&opts, &mut sink)?;

                let decode_tps = if summary.decode_ms > 0 {
                    summary.tokens_generated as f64 / (summary.decode_ms as f64 / 1000.0)
                } else {
                    0.0
                };
                eprintln!();
                eprintln!("---");
                eprintln!("Generated tokens: {}", summary.tokens_generated);
                eprintln!("Decode: {:.1} tok/s", decode_tps);
                return Ok(());
            }

            // Audio-input path (mutually exclusive with --vocoder via clap
            // `conflicts_with`). Skips the chat-template / token-building
            // dance entirely — the audio is fed in as soft tokens via
            // `Session::append_audio`, which uses the engine's
            // auto-attached `AudioEncoderWeights` (PR #106).
            if let Some(wav_path) = &audio_in {
                let (pcm_in, sr_in) = read_wav_pcm16_mono(wav_path)?;
                eprintln!(
                    "Loaded {} samples ({:.2}s @ {sr_in} Hz) from {wav_path}",
                    pcm_in.len(),
                    pcm_in.len() as f32 / sr_in as f32
                );
                // LFM2A's audio encoder expects 16 kHz mono PCM. If the
                // WAV is at any other rate, resample with linear
                // interpolation. Quality is adequate for ASR speech
                // (no anti-aliasing on downsample, but speech energy
                // is mostly under 8 kHz so the worst aliasing folds
                // outside the recognized band). For studio quality on
                // long clips, pre-resample externally with sox/ffmpeg.
                const TARGET_SR: u32 = 16_000;
                let (pcm, sr) = if sr_in == TARGET_SR {
                    (pcm_in, sr_in)
                } else {
                    let resampled = resample_linear(&pcm_in, sr_in, TARGET_SR);
                    eprintln!(
                        "note: resampling {sr_in} Hz → {TARGET_SR} Hz \
                         ({} → {} samples, linear interpolation). \
                         For best quality and performance pass \
                         16 kHz mono PCM16 directly — e.g. \
                         `sox in.wav -r 16000 -c 1 -b 16 out.wav` \
                         or `ffmpeg -i in.wav -ar 16000 -ac 1 -sample_fmt s16 out.wav` \
                         — to skip this step.",
                        pcm_in.len(),
                        resampled.len()
                    );
                    (resampled, TARGET_SR)
                };
                eprintln!(
                    "Model: {} | {} layers | hidden={}",
                    engine.model().config().architecture,
                    engine.model().config().n_layers,
                    engine.model().config().hidden_size
                );

                // ASR fast path: dogfood the shared `CeraEngine::transcribe` helper (also exposed
                // via cera-ffi for Kotlin/Swift). `transcribe` is a fixed greedy decode with the
                // default token budget (256) and no `--prompt`/KV-compression knobs — so only take
                // it when the user's flags are compatible with that exact behavior. Otherwise fall
                // through to the chat-template flow below, which honors `--max-tokens`,
                // `--temperature`, `--kv-cache-keys`, and appends `--prompt` before the marker.
                // (256 / "f32" mirror the `Run` clap defaults; `transcribe` uses the same budget.)
                let prompt_is_empty = prompt.as_deref().unwrap_or("").trim().is_empty();
                let transcribe_compatible = prompt_is_empty
                    && temperature <= 0.0
                    && max_tokens == 256
                    && kv_cache_keys == "f32"
                    // `engine.transcribe` bypasses the session, so a LoRA adapter
                    // could never be attached — fall through to the session path.
                    && lora.is_none();
                if system.as_deref() == Some("Perform ASR.") && transcribe_compatible {
                    let text = engine.transcribe(&pcm, sr)?;
                    println!("{text}");
                    return Ok(());
                }

                let mut session = engine.new_session(cera::SessionConfig {
                    kv_compression,
                    seed: None,
                    ubatch_size,
                    n_keep,
                    ..Default::default()
                })?;
                attach_lora(&mut session, &lora, lora_alpha)?;

                let prefill_start = std::time::Instant::now();
                if let Some(sys) = &system {
                    // Chat-template flow: render the model's template
                    // with a placeholder marker where audio should land
                    // (end of user content). Split the rendered tokens
                    // at the marker and feed prefix → audio → suffix so
                    // audio sits inside the user turn, before <im_end>.
                    // The template's `{{ bos_token }}` already adds
                    // BOS — don't add it again.
                    let (marker_id, marker_name) = pick_audio_marker_token(tokenizer)?;
                    let user_text = prompt.as_deref().unwrap_or("");
                    let user_content = format!("{user_text}{marker_name}");
                    let messages = vec![
                        cera::tokenizer::ChatMessage {
                            role: "system".into(),
                            content: sys.clone(),
                        },
                        cera::tokenizer::ChatMessage {
                            role: "user".into(),
                            content: user_content,
                        },
                    ];
                    let formatted =
                        cera::tokenizer::apply_chat_template(tokenizer, &messages, true)?;
                    let toks = tokenizer.encode(&formatted);
                    let split = split_at_marker(&toks, marker_id, marker_name)?;
                    let (prefix, suffix) = (&toks[..split], &toks[split + 1..]);
                    eprintln!(
                        "Chat template: {} prefix tokens, audio, {} suffix tokens",
                        prefix.len(),
                        suffix.len()
                    );
                    if !prefix.is_empty() {
                        session.append_tokens(prefix)?;
                    }
                    session.append_audio(&pcm, sr)?;
                    if !suffix.is_empty() {
                        session.append_tokens(suffix)?;
                    }
                } else {
                    // Plain audio-in: BOS (when the model wants it),
                    // optional --prompt as a leading text prefix, then
                    // audio. No template, no system role.
                    if add_bos {
                        if let Some(bos) = tokenizer.bos_token() {
                            session.append_tokens(&[bos])?;
                        }
                    }
                    if let Some(p) = &prompt {
                        if !p.is_empty() {
                            session.append_text(p)?;
                        }
                    }
                    session.append_audio(&pcm, sr)?;
                }
                let prefill_elapsed = prefill_start.elapsed();
                // Snapshot KV size before generate(): that call advances
                // `position` by every emitted token, so reading it after
                // would overreport the prefill frame count.
                let kv_after_prefill = session.position();

                let opts = cera::GenerateOpts {
                    max_tokens: max_tokens as u32,
                    temperature,
                    grammar: grammar_compiled.clone(),
                    ..Default::default()
                };

                let mut sink = StdoutSink::new(tokenizer, session.cancel_handle());
                let summary = session.generate(&opts, &mut sink)?;

                let decode_tps = if summary.decode_ms > 0 {
                    summary.tokens_generated as f64 / (summary.decode_ms as f64 / 1000.0)
                } else {
                    0.0
                };

                eprintln!();
                eprintln!("---");
                eprintln!("Frames in KV after prefill: {kv_after_prefill}");
                eprintln!("Generated tokens: {}", summary.tokens_generated);
                eprintln!(
                    "Prefill (encode + LLM): {:.2}s",
                    prefill_elapsed.as_secs_f64()
                );
                eprintln!("Decode: {:.1} tok/s", decode_tps);
                return Ok(());
            }

            // Text mode (audio-in path returned above). `--prompt` is
            // required here — the audio-in branch is the only context
            // where it's optional. Treat absence as an explicit usage
            // error rather than silently prefilling an empty/BOS-only
            // prefix that would surprise the caller.
            let prompt = match &prompt {
                Some(p) => p,
                None => anyhow::bail!(
                    "--prompt is required for text mode. Use `cera run --prompt <text> ...` \
                     or pass `--audio-in <wav>` for the audio-input path."
                ),
            };

            // Build token sequence.
            let mut tokens = Vec::new();
            if !tool_defs.is_empty() {
                // Tool calling: render the chat template with a `tools` array so
                // the model's tool-definition block appears. `--system` is
                // honored as a leading system turn if given.
                let mut messages = Vec::new();
                if let Some(sys) = system.as_deref() {
                    messages.push(cera::tokenizer::ChatMessage {
                        role: "system".into(),
                        content: sys.into(),
                    });
                }
                messages.push(cera::tokenizer::ChatMessage {
                    role: "user".into(),
                    content: prompt.clone(),
                });
                let formatted = cera::tokenizer::apply_chat_template_with_tools(
                    tokenizer, &messages, &tool_defs, true,
                )?;
                eprintln!(
                    "Chat template applied with {} tool(s) ({} chars)",
                    tool_defs.len(),
                    formatted.len()
                );
                tokens = tokenizer.encode(&formatted);
            } else if system.is_some() || vocoder.is_some() {
                // Use chat template when --system or --vocoder is set.
                anyhow::ensure!(
                    system.is_some(),
                    "--system is required with --vocoder. Supported:\n  \
                     \"Respond with interleaved text and audio.\"\n  \
                     \"Perform TTS. <voice description>\"\n  \
                     \"Perform ASR.\" (not yet supported — requires audio encoder)"
                );
                let sys = system.as_deref().unwrap();
                let messages = vec![
                    cera::tokenizer::ChatMessage {
                        role: "system".into(),
                        content: sys.into(),
                    },
                    cera::tokenizer::ChatMessage {
                        role: "user".into(),
                        content: prompt.clone(),
                    },
                ];
                let formatted = cera::tokenizer::apply_chat_template(tokenizer, &messages, true)?;
                eprintln!("Chat template applied ({} chars)", formatted.len());
                tokens = tokenizer.encode(&formatted);
            } else if let Some(ids) = &token_ids {
                tokens = ids
                    .split(',')
                    .map(|s| s.trim().parse::<u32>())
                    .collect::<Result<Vec<_>, _>>()?;
            } else {
                if add_bos {
                    if let Some(bos) = tokenizer.bos_token() {
                        tokens.push(bos);
                    }
                }
                tokens.extend_from_slice(&tokenizer.encode(prompt));
            }

            eprintln!(
                "Model: {} | {} layers | hidden={}",
                engine.model().config().architecture,
                engine.model().config().n_layers,
                engine.model().config().hidden_size
            );
            eprintln!("Prompt tokens: {}", tokens.len());

            if let Some(vocoder_path) = &vocoder {
                // Audio generation mode. The audio decoder weight
                // loaders take `&Arc<GgufFile>` (mmap-backed weight
                // handles hold their own Arc clones to keep the
                // GGUF alive — see `cera::model::weights::MmapWeight`);
                // `open_arc` is the convenience opener that wraps in
                // `Arc` for us.
                let voc_gguf = cera::gguf::GgufFile::open_arc(Path::new(vocoder_path))?;
                let decoder_weights =
                    cera::model::audio_decoder::AudioDecoderWeights::from_gguf(&voc_gguf)?;
                {
                    let dc = &decoder_weights.depthformer_config;
                    let cc = &decoder_weights.decoder_config;
                    eprintln!(
                        "Audio decoder loaded: depthformer {}L×{}, decoder {}cb×{} vocab, LLM embd={}",
                        dc.n_layer, dc.n_embd, cc.n_codebook, cc.n_vocab, cc.n_embd
                    );
                }
                let detok_weights =
                    cera::model::audio_decoder::DetokenizerWeights::from_gguf(&voc_gguf)?;
                {
                    let cfg = &detok_weights.config;
                    eprintln!(
                        "Detokenizer loaded: {}L, embd={}, head={}/{}, ffn={}, conv_layers={}",
                        cfg.n_layer,
                        cfg.n_embd,
                        cfg.n_head,
                        cfg.n_head_kv,
                        cfg.ffn_dim,
                        cfg.layer_is_conv.iter().filter(|&&c| c).count()
                    );
                }
                let gpu_df_requested = std::env::var("CERA_GPU_DF").as_deref() == Ok("1");
                #[cfg(all(feature = "metal", target_os = "macos"))]
                if gpu_df_requested {
                    eprintln!(
                        "warning: CERA_GPU_DF=1 enables an experimental Metal depthformer that \
                         currently produces incorrect codes (frame-1 immediate-end with \
                         --audio-temperature 0; NaN-logit panic with default sampling). \
                         The CPU depthformer is the supported path."
                    );
                }

                #[cfg(all(feature = "metal", target_os = "macos"))]
                let gpu_detok = {
                    match cera::model::metal_audio_decoder::MetalAudioDecoder::from_gguf(
                        &voc_gguf,
                        Path::new(vocoder_path),
                    ) {
                        Ok(d) => {
                            eprintln!("Metal detokenizer loaded");
                            Some(d)
                        }
                        Err(e) => {
                            eprintln!("Metal detokenizer failed: {e}, using CPU");
                            None
                        }
                    }
                };
                #[cfg(not(all(feature = "metal", target_os = "macos")))]
                let _gpu_detok: Option<()> = None;

                let mut all_pcm = Vec::new();
                let sys = system.as_deref().unwrap();
                let mode = if sys == "Respond with interleaved text and audio." {
                    cera::audio_engine::AudioMode::Interleaved
                } else {
                    cera::audio_engine::AudioMode::Sequential
                };
                let audio_config = cera::audio_engine::AudioGenerateConfig {
                    max_tokens,
                    sampler: cera::sampler::SamplerConfig {
                        temperature,
                        ..Default::default()
                    },
                    audio_temperature,
                    audio_top_k,
                    mode,
                    gpu_depthformer: gpu_df_requested,
                };

                #[cfg(all(feature = "metal", target_os = "macos"))]
                let gpu_ref: Option<&dyn cera::model::audio_decoder::AudioGpu> = gpu_detok
                    .as_ref()
                    .map(|d| d as &dyn cera::model::audio_decoder::AudioGpu);
                #[cfg(not(all(feature = "metal", target_os = "macos")))]
                let gpu_ref: Option<&dyn cera::model::audio_decoder::AudioGpu> = None;

                let result = cera::audio_engine::generate_audio(
                    engine.model(),
                    &decoder_weights,
                    &detok_weights,
                    tokenizer,
                    &tokens,
                    &audio_config,
                    gpu_ref,
                    |text| {
                        print!("{text}");
                    },
                    |pcm, _sr| {
                        all_pcm.extend_from_slice(pcm);
                    },
                )?;

                eprintln!();
                eprintln!("---");
                eprintln!("Text tokens: {}", result.text_tokens);
                eprintln!("Audio frames: {}", result.audio_frames);
                eprintln!(
                    "Audio: {} samples ({:.1}s at 24kHz)",
                    all_pcm.len(),
                    all_pcm.len() as f64 / 24000.0
                );
                eprintln!("Elapsed: {:.1}s", result.elapsed_secs);
                eprintln!(
                    "Breakdown: depthformer {}ms ({:.1}ms/frame), detokenizer {}ms ({:.1}ms/frame), other {}ms",
                    (result.depthformer_secs * 1000.0) as u64,
                    if result.audio_frames > 0 {
                        result.depthformer_secs * 1000.0 / result.audio_frames as f64
                    } else {
                        0.0
                    },
                    (result.detokenizer_secs * 1000.0) as u64,
                    if result.audio_frames > 0 {
                        result.detokenizer_secs * 1000.0 / result.audio_frames as f64
                    } else {
                        0.0
                    },
                    (result.elapsed_secs * 1000.0
                        - result.depthformer_secs * 1000.0
                        - result.detokenizer_secs * 1000.0) as u64,
                );
                eprintln!(
                    "Throughput: {:.1} tok/s (text+audio)",
                    (result.text_tokens + result.audio_frames * 12) as f64 / result.elapsed_secs
                );

                if let Some(wav_path) = &audio_out {
                    write_wav(wav_path, &all_pcm, 24000)?;
                    eprintln!("Wrote {wav_path}");
                } else if !all_pcm.is_empty() {
                    let default_path = "/tmp/cera_audio.wav";
                    write_wav(default_path, &all_pcm, 24000)?;
                    eprintln!("Wrote {default_path}");
                }
            } else {
                // Text-only generation via Session + StdoutSink.
                let mut session = engine.new_session(cera::SessionConfig {
                    kv_compression,
                    seed: None,
                    ubatch_size,
                    n_keep,
                    ..Default::default()
                })?;
                attach_lora(&mut session, &lora, lora_alpha)?;

                let prefill_start = std::time::Instant::now();
                session.append_tokens(&tokens)?;
                let prefill_elapsed = prefill_start.elapsed();

                // Tool calling: pick the wire format for this model and, when
                // `--constrain-tools` is set, compile the tool grammar + resolve
                // the lazy start-marker trigger. Otherwise fall back to any
                // `--grammar`/`--json` grammar.
                let tool_format = (!tool_defs.is_empty()).then(|| {
                    let arch = &engine.model().config().architecture;
                    cera::tools::ToolFormat::detect(arch).unwrap_or_else(|| {
                        // No known convention for this architecture — parsing
                        // could well be wrong, so warn rather than silently
                        // guessing. LFM2 Pythonic is the fallback.
                        eprintln!(
                            "warning: no known tool-call format for architecture '{arch}'; \
                             assuming LFM2 Pythonic. Tool-call parsing may be incorrect."
                        );
                        cera::tools::ToolFormat::Lfm2Pythonic
                    })
                });
                // `--constrain-tools` with an empty `--tools` (e.g. `[]`) passes
                // clap's `requires = "tools"` but has nothing to constrain to,
                // so it would silently no-op. Fail fast instead.
                if constrain_tools && tool_format.is_none() {
                    anyhow::bail!(
                        "--constrain-tools requires at least one tool in --tools \
                         (the tool list is empty)"
                    );
                }
                let (effective_grammar, trigger_tokens) =
                    if constrain_tools && let Some(fmt) = tool_format {
                        let gbnf = cera::tools::tool_grammar(&tool_defs, fmt)?;
                        let g = std::sync::Arc::new(
                            cera::grammar::Grammar::parse(&gbnf)
                                .context("compiling generated tool grammar")?,
                        );
                        // The lazy trigger needs the start marker as a single
                        // special token. Without it the grammar would run
                        // eagerly from token 0 and force an *unmarked* call the
                        // parser can't recover — so fail fast rather than
                        // silently degrade.
                        let marker = fmt.call_start_marker();
                        let Some(trig_id) = tokenizer.special_token_id(marker) else {
                            anyhow::bail!(
                                "--constrain-tools: this model's tokenizer has no `{marker}` \
                                 special token (required for the {fmt:?} tool-call format), so \
                                 the lazy grammar trigger can't be set. This model likely does \
                                 not support constrained tool calling."
                            );
                        };
                        (Some(g), vec![trig_id])
                    } else {
                        (grammar_compiled.clone(), Vec::new())
                    };

                let opts = cera::GenerateOpts {
                    max_tokens: max_tokens as u32,
                    temperature,
                    grammar: effective_grammar,
                    grammar_trigger_tokens: trigger_tokens,
                    ..Default::default()
                };

                // With tools, collect the reply (ChatSink streams + buffers) so
                // tool calls can be parsed out afterward. Stream it to stderr so
                // stdout carries only the machine-readable tool-call JSON.
                let summary;
                let reply_text;
                if tool_format.is_some() {
                    let mut sink = ChatSink::new_stderr(tokenizer, session.cancel_handle());
                    summary = session.generate(&opts, &mut sink)?;
                    reply_text = Some(sink.into_text());
                } else {
                    let mut sink = StdoutSink::new(tokenizer, session.cancel_handle());
                    summary = session.generate(&opts, &mut sink)?;
                    reply_text = None;
                }

                let prefill_tps = if prefill_elapsed.as_secs_f64() > 0.0 {
                    tokens.len() as f64 / prefill_elapsed.as_secs_f64()
                } else {
                    0.0
                };
                let decode_tps = if summary.decode_ms > 0 {
                    summary.tokens_generated as f64 / (summary.decode_ms as f64 / 1000.0)
                } else {
                    0.0
                };

                eprintln!();
                eprintln!("---");
                eprintln!("Prompt tokens: {}", tokens.len());
                eprintln!("Generated tokens: {}", summary.tokens_generated);
                eprintln!("Prefill: {:.1} tok/s", prefill_tps);
                eprintln!("Decode: {:.1} tok/s", decode_tps);

                // Parse and report any tool calls in the reply. Three distinct
                // outcomes so automation can tell them apart:
                //   - calls found → stdout gets `[{…}]`, exit 0
                //   - no call     → stdout gets `[]`,    exit 0
                //   - parse error → stdout gets nothing, non-zero exit (the
                //                   error propagates), so a *malformed* tool-call
                //                   section is distinct from "the model didn't
                //                   call a tool".
                // The human summary goes to stderr. `writeln!` (not `println!`)
                // so a closed pipe surfaces as an ignored error, not a panic.
                if let (Some(fmt), Some(text)) = (tool_format, reply_text) {
                    let calls = cera::tools::parse_tool_calls(&text, fmt)
                        .context("parsing tool calls from model reply")?;
                    if calls.is_empty() {
                        eprintln!("--- (no tool calls in reply)");
                    } else {
                        eprintln!("---");
                        eprintln!("Tool calls ({}):", calls.len());
                        for (i, c) in calls.iter().enumerate() {
                            let args = serde_json::to_string(&c.arguments)
                                .unwrap_or_else(|_| "<unserializable>".into());
                            eprintln!("  [{i}] {}({args})", c.name);
                        }
                    }
                    let json = serde_json::to_string(&calls).unwrap_or_else(|_| "[]".into());
                    let mut out = std::io::stdout().lock();
                    let _ = writeln!(out, "{json}");
                }
            }
        }
        Command::Inspect { model } => {
            let gguf = cera::gguf::GgufFile::open(Path::new(&model))?;
            gguf.print_inspect();
            println!();
            println!("=== CPU Backend ===");
            // Host capability + the SIMD tier the runtime resolved for it.
            // Useful in bug reports to know which kernel path actually ran.
            println!("{}", cera::cpu_features().report());
        }
        Command::Cpu => {
            println!("{}", cera::cpu_features().report());
        }
        Command::Tokenize { model, text } => {
            let gguf = cera::gguf::GgufFile::open(Path::new(&model))?;
            let tok = cera::tokenizer::BpeTokenizer::from_gguf(&gguf)?;
            let ids = tok.encode(&text);
            println!("{ids:?}");
        }
        Command::Embed {
            model,
            bundle_id,
            quant,
            cache_dir,
            prompt,
            device,
            context_size,
            per_token,
            json,
            lora,
            lora_alpha,
            add_bos,
        } => {
            let engine = resolve_engine(
                model.as_deref(),
                bundle_id.as_deref(),
                quant.as_deref(),
                cache_dir.as_deref(),
                &device,
                context_size,
            )?;

            // Fail clearly before prefill if the resolved backend can't extract
            // hidden states (rather than surfacing an opaque UnsupportedModality
            // from deep inside `hidden_states_*`).
            if !engine.model().supports_hidden_states() {
                anyhow::bail!(
                    "hidden-state extraction is not implemented for the `{}` model on \
                     this backend; try `--device cpu`",
                    engine.metadata().architecture
                );
            }

            let mut session = engine.new_session(cera::SessionConfig::default())?;
            attach_lora(&mut session, &lora, lora_alpha)?;

            // Tokenize with the session's tokenizer so the ids match the model's
            // vocab exactly (same path `hidden_states_for_text` would take).
            let encoded = session.tokenizer().encode(&prompt);
            // Prepend BOS (if requested and the model declares one) so the pooled
            // vector matches a head trained with `add_bos_token=true` (BOS is
            // included in the mean). Build the vec with BOS first rather than an
            // O(n) `insert(0, …)` that shifts the whole prompt.
            let bos = if add_bos {
                session.tokenizer().bos_token()
            } else {
                None
            };
            let mut tokens = Vec::with_capacity(encoded.len() + usize::from(bos.is_some()));
            tokens.extend(bos);
            tokens.extend_from_slice(&encoded);
            if tokens.is_empty() {
                anyhow::bail!("prompt tokenized to zero tokens; nothing to embed");
            }
            let hidden_size = session.hidden_size();

            use std::io::Write;
            let stdout = std::io::stdout();
            let mut w = std::io::BufWriter::new(stdout.lock());

            if per_token {
                let flat = session.hidden_states_for_tokens(&tokens)?;
                // The backend must return exactly [tokens × hidden_size]; a
                // mismatch would let `chunks_exact` silently drop a remainder.
                anyhow::ensure!(
                    flat.len() == tokens.len() * hidden_size,
                    "hidden-state buffer length {} != tokens ({}) × hidden_size ({})",
                    flat.len(),
                    tokens.len(),
                    hidden_size
                );
                if json {
                    // Stream row-by-row so a long prompt never materializes the
                    // whole [T*hidden_size] output as strings at once.
                    write!(w, "[")?;
                    for (i, row) in flat.chunks_exact(hidden_size).enumerate() {
                        if i > 0 {
                            write!(w, ",")?;
                        }
                        write!(w, "[")?;
                        write_embed_row(&mut w, row, true)?;
                        write!(w, "]")?;
                    }
                    writeln!(w, "]")?;
                } else {
                    for row in flat.chunks_exact(hidden_size) {
                        write_embed_row(&mut w, row, false)?;
                        writeln!(w)?;
                    }
                }
            } else {
                let pooled = session.hidden_states_mean_pooled(&tokens)?;
                anyhow::ensure!(
                    pooled.len() == hidden_size,
                    "pooled hidden-state length {} != hidden_size {}",
                    pooled.len(),
                    hidden_size
                );
                if json {
                    write!(w, "[")?;
                    write_embed_row(&mut w, &pooled, true)?;
                    writeln!(w, "]")?;
                } else {
                    write_embed_row(&mut w, &pooled, false)?;
                    writeln!(w)?;
                }
            }
            w.flush()?;
        }
        Command::Logits {
            model,
            bundle_id,
            quant,
            cache_dir,
            prompt,
            token_ids,
            add_bos,
            device,
            context_size,
            top_k,
            json,
        } => {
            let engine = resolve_engine(
                model.as_deref(),
                bundle_id.as_deref(),
                quant.as_deref(),
                cache_dir.as_deref(),
                &device,
                context_size,
            )?;
            let mut session = engine.new_session(cera::SessionConfig::default())?;

            // `--token-ids` scores an exact sequence (no tokenizer ambiguity);
            // otherwise tokenize the prompt with the model's own vocab, optionally
            // prepending BOS (`--add-bos`) so distributions line up with llama.cpp.
            let tokens: Vec<u32> = if let Some(ids) = token_ids.as_deref() {
                ids.split(',')
                    .map(|s| s.trim())
                    .filter(|s| !s.is_empty())
                    .map(|s| s.parse::<u32>())
                    .collect::<Result<_, _>>()
                    .context("parsing --token-ids as comma-separated u32")?
            } else {
                let p = prompt
                    .as_deref()
                    .context("provide --prompt or --token-ids")?;
                let encoded = session.tokenizer().encode(p);
                let bos = if add_bos {
                    session.tokenizer().bos_token()
                } else {
                    None
                };
                let mut t = Vec::with_capacity(encoded.len() + usize::from(bos.is_some()));
                t.extend(bos);
                t.extend_from_slice(&encoded);
                t
            };
            anyhow::ensure!(!tokens.is_empty(), "no tokens to score");
            // `--token-ids` is the only path that injects raw ids (tokenizer
            // output is always in-vocab). Bound-check before prefill: an
            // out-of-vocab id otherwise indexes the embedding table past its
            // end — a clean panic on CPU but a silent out-of-bounds mmap read
            // (garbage logits) on Metal.
            let vocab = session.model().config().vocab_size;
            if let Some(&bad) = tokens.iter().find(|&&t| (t as usize) >= vocab) {
                anyhow::bail!("token id {bad} is out of range for vocab_size {vocab}");
            }

            // Prefill; `last_logits` then holds the next-token distribution for
            // the final token.
            session.append_tokens(&tokens)?;
            let logits = session
                .last_logits()
                .context("no logits produced (prefill was cancelled or empty)")?;

            use std::io::Write;
            let stdout = std::io::stdout();
            let mut w = std::io::BufWriter::new(stdout.lock());
            if top_k > 0 {
                // Partial top-K by logit, descending. Ties broken by lower id.
                // `total_cmp` is a strict total order (required by the unstable
                // sorts); a NaN logit is sunk to -inf so it can never spuriously
                // rank as a top prediction.
                let mut idx: Vec<usize> = (0..logits.len()).collect();
                let k = top_k.min(idx.len());
                let cmp = |a: &usize, b: &usize| {
                    let la = if logits[*a].is_nan() {
                        f32::NEG_INFINITY
                    } else {
                        logits[*a]
                    };
                    let lb = if logits[*b].is_nan() {
                        f32::NEG_INFINITY
                    } else {
                        logits[*b]
                    };
                    lb.total_cmp(&la).then(a.cmp(b))
                };
                idx.select_nth_unstable_by(k.saturating_sub(1), cmp);
                idx.truncate(k);
                idx.sort_unstable_by(cmp);
                if json {
                    write!(w, "[")?;
                    for (i, &id) in idx.iter().enumerate() {
                        if i > 0 {
                            write!(w, ",")?;
                        }
                        write!(w, "[{},", id)?;
                        write_logit(&mut w, logits[id], true)?;
                        write!(w, "]")?;
                    }
                    writeln!(w, "]")?;
                } else {
                    for &id in &idx {
                        write!(w, "{}\t", id)?;
                        write_logit(&mut w, logits[id], false)?;
                        writeln!(w)?;
                    }
                }
            } else if json {
                write!(w, "[")?;
                for (i, &v) in logits.iter().enumerate() {
                    if i > 0 {
                        write!(w, ",")?;
                    }
                    write_logit(&mut w, v, true)?;
                }
                writeln!(w, "]")?;
            } else {
                for (i, &v) in logits.iter().enumerate() {
                    if i > 0 {
                        write!(w, " ")?;
                    }
                    write_logit(&mut w, v, false)?;
                }
                writeln!(w)?;
            }
            w.flush()?;
        }
        Command::ListBundles { quants } => {
            // One HTTP round-trip; sorted output. Quants are
            // space-joined on a single indented line per bundle —
            // compact enough to fit in a terminal width even for
            // bundles with several quant variants, and grep-able.
            //
            // Display strip: every entry in the live catalog ends
            // in `-GGUF`. Trim the suffix on output so what's
            // shown matches what users type at `--bundle-id`
            // (`normalize_bundle_id` re-appends the suffix on the
            // way back in). `display_bundle_id` is a no-op for
            // any future non-GGUF entry that ships.
            let entries = cera::bundle::list_leap_bundles()?;
            for entry in entries {
                println!("{}", display_bundle_id(&entry.name));
                if quants {
                    println!("  {}", entry.quants.join("  "));
                }
            }
        }
        Command::DownloadBundles { bundles, cache_dir } => {
            let cache = cache_dir
                .map(PathBuf::from)
                .unwrap_or_else(default_cache_dir);
            eprintln!("Cache: {}", cache.display());
            let progress = Arc::new(CliDownloadProgress::default());
            let repo = cera::bundle::BundleRepo::with_progress(
                cache,
                progress.clone() as Arc<dyn cera::bundle::DownloadProgress>,
            );
            let mut failures = Vec::new();
            for pair in &bundles {
                progress.reset();
                if let Err(err) = download_bundle_pair(&repo, pair, &progress) {
                    progress.finish_line();
                    eprintln!("error: {pair}: {err:#}");
                    failures.push(pair.to_string());
                }
            }
            if !failures.is_empty() {
                anyhow::bail!(
                    "failed to download {} bundle(s): {}",
                    failures.len(),
                    failures.join(", ")
                );
            }
        }
        Command::Chat {
            model,
            bundle_id,
            quant,
            cache_dir,
            cache_warm_mb,
            cache_disk_gb,
            no_cache,
            system,
            device,
            context_size,
            max_tokens,
            temperature,
            seed,
            no_tui,
            lora,
            lora_alpha,
        } => {
            use std::io::BufRead;

            let engine = resolve_engine(
                model.as_deref(),
                bundle_id.as_deref(),
                quant.as_deref(),
                cache_dir.as_deref(),
                &device,
                context_size,
            )?;
            let tokenizer = engine.tokenizer();

            // Configure the KV prefix cache (shared logic with `Run`).
            // Cross-restart disk-tier caching is the win for mobile / FFI
            // consumers whose process can be killed and resumed.
            configure_prefix_cache(
                &engine,
                cache_dir.as_deref(),
                no_cache,
                cache_warm_mb,
                cache_disk_gb,
            );

            // Up-front chat-template probe: fail before the user types
            // anything if the model has no template metadata. Without this,
            // the first per-turn `apply_chat_template` would `?`-return
            // through the entire CLI after the user already typed a
            // message — confusing UX.
            if tokenizer.chat_template().is_none() {
                anyhow::bail!(
                    "model has no chat template metadata; \
                     `cera chat` requires a chat-tuned model. \
                     Use `cera run --prompt <text>` for plain completion instead."
                );
            }

            let mut session = engine.new_session(cera::SessionConfig {
                seed,
                ..Default::default()
            })?;
            attach_lora(&mut session, &lora, lora_alpha)?;

            let mut history: Vec<cera::tokenizer::ChatMessage> = Vec::new();
            // Parallel to `history`: each entry holds the images
            // attached to the corresponding turn (empty for
            // system / assistant / text-only user). Used to
            // re-render the conversation as multimodal on every
            // turn so the model has actual pixel access for
            // multi-turn fine-grained follow-ups, not just its
            // own turn-1 description. `Arc<Vec<u8>>` keeps the
            // per-turn re-flatten cheap.
            let mut history_images: Vec<Vec<std::sync::Arc<Vec<u8>>>> = Vec::new();
            if let Some(sys) = system {
                history.push(cera::tokenizer::ChatMessage {
                    role: "system".into(),
                    content: sys,
                });
                history_images.push(Vec::new());
            }

            // Image attachments collected via `/image <path-or-url>` for the
            // NEXT user turn. On send, a clone of this vec moves
            // into `history_images[user_idx]` so every subsequent
            // turn re-feeds the same images through the encoder.
            // `pending_images` itself drains on a successful turn
            // AND on `/clear`. `Arc<Vec<u8>>` keeps the
            // pending → history_images copy cheap (refcount bump,
            // not memcpy).
            let mut pending_images: Vec<std::sync::Arc<Vec<u8>>> = Vec::new();

            let opts = cera::GenerateOpts {
                max_tokens: max_tokens as u32,
                temperature,
                ..Default::default()
            };

            // Dispatch: inline TUI when both stdin AND stdout are TTYs
            // (so cursor positioning + raw-mode keystroke reads behave
            // sensibly) and the user didn't opt out via `--no-tui`.
            // Otherwise fall back to the line-based REPL — works for
            // pipes, log capture, dumb terminals, scripted tests.
            let use_tui =
                !no_tui && std::io::stdin().is_terminal() && std::io::stdout().is_terminal();
            if use_tui {
                // `tokenizer_arc()` shares the engine's existing
                // `Arc<BpeTokenizer>` with the worker thread instead
                // of deep-cloning the vocab + merge tables.
                let _final_history = chat_tui::run(session, engine.tokenizer_arc(), history, opts)?;
                return Ok(());
            }

            // Line-based REPL fallback below.
            let mut session = session;
            // The actual backend choice is reported by `load_engine` via
            // its own "Using ... backend" line above; don't echo `device`
            // here since under `--device auto` it'd misrepresent the
            // resolved backend.
            eprintln!(
                "cera chat (ctx={context_size}, max_tokens/turn={max_tokens}). \
                 Type `/help` for commands, `/exit` or EOF (Ctrl+D) to quit."
            );
            if !history.is_empty() {
                eprintln!("(system prompt active)");
            }

            let stdin = std::io::stdin();
            let cancel = session.cancel_handle();
            // SIGINT during a turn → flip the session's cancel atomic so
            // prefill / generate unwind cleanly; SIGINT at the prompt →
            // exit the process. `intercepting` distinguishes the two and
            // is toggled around every prefill / generate call below.
            // `sigint_fired` is set IN ADDITION to `cancel` so the REPL
            // can tell "user pressed Ctrl+C" (stay alive) from "ChatSink
            // self-cancelled because stdout went away" (exit) — both
            // flip the session's cancel flag.
            // The TUI path takes a different branch above and never
            // reaches this code; raw mode handles Ctrl+C as a key event.
            let intercepting = Arc::new(AtomicBool::new(false));
            let sigint_fired = Arc::new(AtomicBool::new(false));
            signal::install_line_repl_handler(
                Arc::clone(&cancel),
                Arc::clone(&intercepting),
                Arc::clone(&sigint_fired),
            )?;
            loop {
                // Defense against a leak from the previous turn's
                // swap→store window: a SIGINT that arrived between
                // `sigint_fired.swap(false)` and
                // `intercepting.store(false)` would have re-set
                // `sigint_fired` while intercepting was still true; the
                // outer cleanup already saved its own snapshot, so any
                // late set must NOT carry into the next turn or the
                // user sees a spurious "(cancelled)".
                sigint_fired.store(false, Ordering::Relaxed);
                eprint!("user> ");
                std::io::stderr().flush().ok();
                let mut line = String::new();
                let n = stdin.lock().read_line(&mut line)?;
                if n == 0 {
                    eprintln!();
                    break; // EOF
                }
                // Strip line terminators only; preserve any meaningful
                // leading/trailing whitespace the user actually typed
                // (e.g. indented code in a prompt).
                let user = line.trim_end_matches(['\r', '\n']).to_string();
                if user.trim().is_empty() {
                    continue;
                }
                // Slash-command dispatch. A leading `/` puts the line
                // into command mode; we never send it to the model.
                // Trade-off: legit user messages that genuinely start
                // with `/` (e.g. a Unix path) are unreachable today.
                // Mitigations would be `\\` escape or a `/say <text>`
                // form; not worth the complexity for v1.
                if user.starts_with('/') {
                    // Trim trailing whitespace so commands like "/help "
                    // or "/exit\t" still dispatch correctly. The user's
                    // line preserves leading/trailing spaces inside a
                    // chat message (intentional for indented prompts),
                    // but a bare command shouldn't be defeated by a
                    // stray space that's hard to see.
                    //
                    // Split on the first whitespace so commands with
                    // arguments (`/save out.txt`, `/system You are ...`)
                    // dispatch on the verb only — `rest.trim()` covers
                    // any extra whitespace between verb and argument.
                    let trimmed = user.trim_end();
                    let (cmd, rest) = match trimmed.split_once(char::is_whitespace) {
                        Some((c, r)) => (c, r.trim()),
                        None => (trimmed, ""),
                    };
                    // Trailing-arg policy: commands that don't take
                    // an argument reject extras strictly so a typo
                    // like `/clear save` doesn't silently wipe the
                    // conversation when the user meant `/save`.
                    let reject_extra_args = |verb: &str| -> bool {
                        if !rest.is_empty() {
                            eprintln!(
                                "{verb} takes no arguments. Type /help for available commands."
                            );
                            true
                        } else {
                            false
                        }
                    };
                    match cmd {
                        "/exit" | "/quit" => {
                            if reject_extra_args(cmd) {
                                continue;
                            }
                            break;
                        }
                        "/help" => {
                            if reject_extra_args(cmd) {
                                continue;
                            }
                            eprintln!("Commands:");
                            eprintln!(
                                "  /clear           Clear conversation history (system prompt preserved)"
                            );
                            eprintln!(
                                "  /system <text>   Replace (or set) the system prompt; empty arg removes it"
                            );
                            eprintln!(
                                "  /save <path>     Save the conversation transcript to a file"
                            );
                            eprintln!(
                                "  /image <path-or-url>    Attach an image (file path or http(s):// URL) to the next user turn (repeat for multi-image)"
                            );
                            eprintln!("  /help            Show this help");
                            eprintln!("  /exit, /quit     Exit the REPL");
                            continue;
                        }
                        "/clear" => {
                            if reject_extra_args(cmd) {
                                continue;
                            }
                            // Reset history but preserve the initial
                            // system message if one was set via
                            // `--system`. The per-turn loop calls
                            // `session.reset()` itself before the next
                            // prefill, so we don't need an explicit
                            // reset here — the next turn will see the
                            // truncated history and start clean.
                            let had_system = history.first().is_some_and(|m| m.role == "system");
                            if had_system {
                                history.truncate(1);
                                history_images.truncate(1);
                            } else {
                                history.clear();
                                history_images.clear();
                            }
                            // `/clear` also drops any pending image
                            // attachments — staying-attached across a
                            // history wipe would surprise the user
                            // (the next message would attach to a
                            // brand-new conversation).
                            let pending_dropped = !pending_images.is_empty();
                            pending_images.clear();
                            eprintln!(
                                "(history cleared{}{})",
                                if had_system {
                                    "; system prompt preserved"
                                } else {
                                    ""
                                },
                                if pending_dropped {
                                    "; pending images dropped"
                                } else {
                                    ""
                                },
                            );
                            continue;
                        }
                        "/save" => {
                            if rest.is_empty() {
                                eprintln!("usage: /save <path>");
                                continue;
                            }
                            // `len()` counts the system message as
                            // one of the saved entries; "messages"
                            // is the honest label (a "turn" is
                            // colloquially user+assistant).
                            match write_transcript(&history, Path::new(rest)) {
                                Ok(()) => eprintln!(
                                    "(saved {} message{} to {rest})",
                                    history.len(),
                                    if history.len() == 1 { "" } else { "s" }
                                ),
                                Err(e) => eprintln!("error: /save failed: {e}"),
                            }
                            continue;
                        }
                        "/system" => {
                            // Empty arg removes the system message
                            // (the user-facing off-switch). Non-empty
                            // arg replaces or inserts at index 0.
                            // Either way, the per-turn loop's own
                            // `session.reset()` will flush KV state
                            // before the next prefill.
                            if rest.is_empty() {
                                let removed = history.first().is_some_and(|m| m.role == "system");
                                if removed {
                                    history.remove(0);
                                    history_images.remove(0);
                                    eprintln!("(system prompt removed)");
                                } else {
                                    eprintln!("(no system prompt was set)");
                                }
                                continue;
                            }
                            let new_msg = cera::tokenizer::ChatMessage {
                                role: "system".into(),
                                content: rest.to_string(),
                            };
                            if history.first().is_some_and(|m| m.role == "system") {
                                history[0] = new_msg;
                                // history_images[0] stays as empty
                                // Vec — system messages never have
                                // image attachments.
                            } else {
                                history.insert(0, new_msg);
                                history_images.insert(0, Vec::new());
                            }
                            eprintln!("(system prompt updated)");
                            continue;
                        }
                        "/image" => {
                            // Attach an image to the NEXT user turn. The
                            // arg is a filesystem path or an `http(s)://`
                            // URL — `image_source::load` resolves both with
                            // the same 50 MB cap and the same special-file
                            // rejection. Multi-image: re-issue the command:
                            //   /image a.jpg
                            //   /image https://.../b.jpg
                            //   compare these two
                            // Pending state drains after the next successful
                            // turn OR on `/clear`.
                            if rest.is_empty() {
                                eprintln!("usage: /image <path-or-url>");
                                continue;
                            }
                            // Path branch: synchronous fs read; this arm is
                            // intentionally not cancellable. SIGINT during
                            // a path read falls to the at-prompt handler
                            // branch and exits — fine for the typical
                            // sub-second local read; less ideal for a slow
                            // network mount or a 50 MB max-size read where
                            // the read itself could take long enough to
                            // matter, but the threading machinery isn't
                            // worth it for a path that's blocking-by-design.
                            if !image_source::looks_like_url(rest) {
                                match image_source::load(rest, image_source::MAX_IMAGE_BYTES) {
                                    Ok(bytes) => {
                                        eprintln!(
                                            "(image attached: {rest}, {} bytes; sends with next message)",
                                            bytes.len()
                                        );
                                        pending_images.push(std::sync::Arc::new(bytes));
                                    }
                                    Err(e) => {
                                        eprintln!("error: /image {rest}: {e:#}");
                                    }
                                }
                                continue;
                            }
                            // URL branch: spawn the fetch on a background
                            // thread and poll for the result with short
                            // timeouts so SIGINT during the wait can flip
                            // the cancel atomic and break us out.
                            // `intercepting=true` for the wait span — same
                            // discipline as around prefill / generate
                            // (PR #140) so the SIGINT handler routes
                            // Ctrl+C to cancel instead of process-exit. The
                            // orphan fetch thread continues until reqwest
                            // resolves the request (≤30s timeout); its
                            // eventual `tx.send` returns SendError silently
                            // when the receiver is dropped.
                            //
                            // Hoist `intercepting=true` BEFORE any URL-
                            // branch work (eprintln, channel setup, thread
                            // spawn) — a SIGINT in the gap between branch
                            // entry and the store would otherwise route to
                            // the at-prompt handler branch and exit. Same
                            // race PR #140's review caught for the
                            // prefill/generate span.
                            intercepting.store(true, Ordering::Relaxed);
                            eprintln!("(downloading {rest}...)");
                            let url = rest.to_string();
                            let url_for_thread = url.clone();
                            let (tx, rx) =
                                std::sync::mpsc::channel::<std::result::Result<Vec<u8>, String>>();
                            std::thread::spawn(move || {
                                // catch_unwind so a panic inside rustls /
                                // tokio (rare but possible) becomes a
                                // surfaced error instead of dropping the
                                // sender silently and stranding the REPL
                                // forever waiting on `rx`.
                                let result = std::panic::catch_unwind(|| {
                                    image_source::load(
                                        &url_for_thread,
                                        image_source::MAX_IMAGE_BYTES,
                                    )
                                });
                                let payload = match result {
                                    Ok(Ok(bytes)) => Ok(bytes),
                                    Ok(Err(e)) => Err(format!("{e:#}")),
                                    Err(_) => Err("image fetch panicked".to_string()),
                                };
                                let _ = tx.send(payload);
                            });
                            let outcome: std::result::Result<Vec<u8>, String> = loop {
                                match rx.recv_timeout(std::time::Duration::from_millis(100)) {
                                    Ok(thread_result) => break thread_result,
                                    Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {
                                        if cancel.load(Ordering::Relaxed) {
                                            break Err("cancelled".into());
                                        }
                                    }
                                    Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => {
                                        // Should be unreachable given
                                        // `catch_unwind` above; defense
                                        // branch surfaces an error rather
                                        // than busy-looping.
                                        break Err("image fetch thread died unexpectedly".into());
                                    }
                                }
                            };
                            let fetch_sigint = sigint_fired.swap(false, Ordering::Relaxed);
                            intercepting.store(false, Ordering::Relaxed);
                            // Cancel-state hygiene: a SIGINT during the wait
                            // sets BOTH `cancel` and `sigint_fired`. If the
                            // fetch happened to complete first
                            // (recv_timeout returned Ok before our cancel
                            // poll observed it), the Ok arm below would
                            // surface the bytes — but `cancel` would stay
                            // set and the next session call would hit a
                            // stale cancel. Clear it whenever SIGINT fired,
                            // regardless of outcome. Matches the generate
                            // path's discipline (PR #140 review).
                            if fetch_sigint {
                                cancel.store(false, Ordering::Relaxed);
                            }
                            match outcome {
                                Ok(bytes) => {
                                    eprintln!(
                                        "(image attached: {url}, {} bytes; sends with next message)",
                                        bytes.len()
                                    );
                                    pending_images.push(std::sync::Arc::new(bytes));
                                }
                                Err(_) if fetch_sigint => {
                                    eprintln!("(cancelled)");
                                }
                                Err(msg) => {
                                    eprintln!("error: /image {url}: {msg}");
                                }
                            }
                            continue;
                        }
                        other => {
                            eprintln!(
                                "unknown command: {other}. Type /help for available commands."
                            );
                            continue;
                        }
                    }
                }

                // History stores typed user text; images attached
                // via `/image` move into `history_images[i]`
                // aligned with the new user turn. Every subsequent
                // turn re-renders the whole conversation as
                // multimodal (when any turn has images) so the
                // model has actual pixel access for fine-grained
                // follow-ups, not just its turn-1 description.
                history.push(cera::tokenizer::ChatMessage {
                    role: "user".into(),
                    content: user.clone(),
                });
                history_images.push(pending_images.clone());

                // Re-render the full conversation per turn and rely on
                // the engine's prefix cache for fast turn-N+1 prefill.
                // Delta-prefill is a future optimization; the simplicity
                // of "render fresh, reset, prefill" is worth the lookup.
                // SIGINT during ANY part of this turn — prefill (incl.
                // any retries), the "assistant> " banner print, or
                // generate — should cancel the in-flight call, not kill
                // the REPL. Hold `intercepting=true` across the whole
                // turn span and only release it at the very end (after
                // we've read `sigint_fired`), so there's no gap where a
                // SIGINT would be misrouted to `process::exit(130)`.
                intercepting.store(true, Ordering::Relaxed);
                // Retry-on-overflow: on `CeraError::ContextOverflow`
                // drop the oldest user+assistant pair and re-render,
                // so a long conversation can keep going past the
                // window cap without forcing the user to `/clear`.
                // Bounded by `truncate_oldest_turn_pair` which
                // returns false once only the system + the just-
                // pushed user remain — at which point overflow is a
                // real "single prompt too large" and we surface it.
                //
                // Truncation runs against a SCRATCH copy of the history
                // — `scratch_history` / `scratch_images`. The
                // authoritative `history` / `history_images` are only
                // overwritten with the (possibly-truncated) scratch
                // AFTER the turn is fully durable (prefill + generate
                // both succeed). On any failure path the scratch is
                // discarded and the user keeps every typed turn. Image
                // bytes are `Arc<Vec<u8>>` so cloning the parallel
                // `Vec<Vec<…>>` is a refcount bump per attachment, not
                // a memcpy of up to 50 MB per image.
                let mut scratch_history = history.clone();
                let mut scratch_images = history_images.clone();
                let prefill_outcome: Result<(), String> = loop {
                    if let Err(e) = session.reset() {
                        break Err(format!("session reset failed: {e}"));
                    }
                    // Recompute per attempt: a truncation step may have
                    // dropped the last image-bearing turn, in which case
                    // the conversation is now text-only and the chat
                    // template renders a different (string-shaped vs
                    // list-shaped) content prefix.
                    let any_images = scratch_images.iter().any(|v| !v.is_empty());
                    let attempt: Result<(), CeraError> = if any_images {
                        // Multimodal prefill: synthesize multimodal
                        // messages by zipping scratch_history with
                        // scratch_images. Each user turn that had
                        // attachments rebuilds as
                        // `[Image*N, Text(content)?]`; turns without
                        // attachments rebuild as `[Text(content)]`.
                        // Image bytes flatten across all turns in
                        // document order, matching the chat template's
                        // `<image>` marker walk.
                        let messages: Vec<cera::tokenizer::ChatMessageMultimodal> = scratch_history
                            .iter()
                            .zip(scratch_images.iter())
                            .map(|(msg, imgs)| {
                                let mut content: Vec<cera::tokenizer::ContentItem> =
                                    vec![cera::tokenizer::ContentItem::Image; imgs.len()];
                                if !msg.content.is_empty() {
                                    content.push(cera::tokenizer::ContentItem::Text {
                                        text: msg.content.clone(),
                                    });
                                }
                                cera::tokenizer::ChatMessageMultimodal {
                                    role: msg.role.clone(),
                                    content,
                                }
                            })
                            .collect();
                        let images_refs: Vec<&[u8]> = scratch_images
                            .iter()
                            .flat_map(|v| v.iter().map(|a| a.as_slice()))
                            .collect();
                        session.append_chat_with_images(&messages, &images_refs, true)
                    } else {
                        match cera::tokenizer::apply_chat_template(
                            tokenizer,
                            &scratch_history,
                            true,
                        ) {
                            Ok(formatted) => {
                                let tokens = tokenizer.encode(&formatted);
                                session.append_tokens(&tokens)
                            }
                            Err(e) => {
                                break Err(format!("chat-template render failed: {e}"));
                            }
                        }
                    };
                    match attempt {
                        Ok(()) => break Ok(()),
                        Err(CeraError::ContextOverflow { max_seq_len, by }) => {
                            if !truncate_oldest_turn_pair(&mut scratch_history, &mut scratch_images)
                            {
                                break Err(format!(
                                    "prompt too large for context window: would need {} more \
                                     tokens past the {max_seq_len}-token cap, and there's no \
                                     older history to drop. Raise --context-size or shorten \
                                     the prompt.",
                                    by
                                ));
                            }
                            eprintln!(
                                "(history truncated to fit context: dropped oldest turn pair)"
                            );
                        }
                        Err(other) => {
                            // Cancelled, real decode failures, etc. —
                            // surface as the existing String-typed
                            // error path. Scratch is discarded by
                            // simply not committing it.
                            break Err(format!("prefill failed: {other}"));
                        }
                    }
                };
                if let Err(msg) = prefill_outcome {
                    // Read `sigint_fired` BEFORE releasing intercepting:
                    // if SIGINT lands between the swap and the store,
                    // the handler still routes to the cancel branch
                    // (loop-top defense clears the leftover next turn).
                    let prefill_sigint = sigint_fired.swap(false, Ordering::Relaxed);
                    intercepting.store(false, Ordering::Relaxed);
                    if prefill_sigint {
                        eprintln!("(cancelled)");
                    } else {
                        eprintln!("error: {msg}");
                    }
                    history.pop();
                    history_images.pop();
                    // Defense: clear the cancel atomic so the next turn
                    // doesn't carry stale state into the inner handler
                    // check before `session.reset()` clears it. Leave
                    // pending state intact so the user can retype the
                    // prompt without re-attaching the image.
                    cancel.store(false, Ordering::Relaxed);
                    continue;
                }

                eprint!("assistant> ");
                std::io::stderr().flush().ok();

                let mut sink = ChatSink::new(tokenizer, session.cancel_handle());
                let generate_result = session.generate(&opts, &mut sink);
                // Same swap-before-store discipline as the prefill arm —
                // capture in-turn SIGINTs before releasing intercepting.
                let generate_sigint = sigint_fired.swap(false, Ordering::Relaxed);
                intercepting.store(false, Ordering::Relaxed);
                let summary = match generate_result {
                    Ok(s) => s,
                    Err(e) => {
                        // `Session::generate` surfaces cancellation as
                        // `Ok(summary)` with `FinishReason::Cancelled`,
                        // not as `Err`. An `Err` here is always a real
                        // decode failure — print it verbatim so the
                        // user sees what actually broke, even if a
                        // SIGINT happened to fire concurrently. The
                        // turn isn't durable, so the scratch goes
                        // unused; authoritative `history` keeps every
                        // pre-truncation pair intact.
                        eprintln!("\nerror: generate failed: {e}");
                        history.pop();
                        history_images.pop();
                        cancel.store(false, Ordering::Relaxed);
                        // Same retry semantics as the prefill-error
                        // path: leave pending images intact. The
                        // next turn will run `session.reset()` which
                        // clears the KV state, then re-prefill with
                        // the same images — consistent and gives
                        // the user a clean retry.
                        continue;
                    }
                };
                // Generate succeeded (possibly with finish_reason =
                // Cancelled — that path is also durable: the user
                // saw partial assistant output streamed live, and a
                // Ctrl+C marker is added below). Commit the
                // (possibly-truncated) scratch back to authoritative
                // state. The current user turn is at the tail of
                // both vectors; truncation only ever removed pairs
                // from the front; appending the assistant reply
                // below uses `history` (the now-committed copy).
                history = scratch_history;
                history_images = scratch_images;
                // Mark a SIGINT-truncated turn before pushing it into
                // history so the user can see in scrollback that the
                // assistant reply was interrupted (otherwise it just
                // looks like the model trailed off mid-sentence). Both
                // gates required:
                // - `finish_reason == Cancelled` is the source of truth
                //   from the session — no marker if the model finished
                //   naturally, even if a SIGINT happened to fire (a
                //   `generate()` start-of-call cancel-reset can swallow
                //   one).
                // - `generate_sigint` separates SIGINT from the only
                //   other finish_reason=Cancelled path, the
                //   `ChatSink`-self-cancel-on-BrokenPipe escape below.
                let cancelled_clean =
                    matches!(summary.finish_reason, cera::FinishReason::Cancelled);
                if cancelled_clean && generate_sigint {
                    eprintln!("\n(cancelled)");
                } else {
                    eprintln!();
                }
                history.push(cera::tokenizer::ChatMessage {
                    role: "assistant".into(),
                    content: sink.into_text(),
                });
                history_images.push(Vec::new());
                // Image attachments for THIS user turn already
                // moved into `history_images` at send time, so
                // they're permanent for the rest of the session
                // (until `/clear`). Drain `pending_images` itself
                // — it's the holding pen for the NEXT turn.
                pending_images.clear();

                // Stop the REPL if the sink flipped cancel because stdout
                // is gone (BrokenPipe — the user piped us into `head` or
                // similar). Without this we'd keep prompting + decoding
                // even though nothing reaches the terminal anymore.
                // SIGINT cancellation also flips `cancel`, but we want to
                // stay in the REPL after Ctrl+C — `generate_sigint`
                // tells the two apart.
                if cancelled_clean && cancel.load(Ordering::Relaxed) && !generate_sigint {
                    break;
                }
                // Clear the cancel flag if SIGINT set it on a successful
                // turn — `session.reset()` at the top of the next turn
                // clears it too, but this keeps the inner cancel-load
                // checks fresh.
                if generate_sigint {
                    cancel.store(false, Ordering::Relaxed);
                }
            }
        }
        Command::Bench {
            model,
            bundle_id,
            quant,
            cache_dir,
            prompt,
            prompt_tokens,
            runs,
            warmup,
            max_tokens,
            device,
            context_size,
            no_cache,
            kv_cache_keys,
            ubatch_size,
        } => {
            anyhow::ensure!(runs >= 1, "--runs must be >= 1");
            if std::env::var("CERA_PROFILE").is_ok() {
                eprintln!(
                    "warning: CERA_PROFILE is set — bench numbers will be inflated by profile overhead"
                );
            }

            let engine = resolve_engine(
                model.as_deref(),
                bundle_id.as_deref(),
                quant.as_deref(),
                cache_dir.as_deref(),
                &device,
                context_size,
            )?;
            let tokenizer = engine.tokenizer();
            let add_bos = engine.metadata().add_bos_token;
            let kv_compression = setup_kv_compression(engine.model(), &kv_cache_keys)?;

            if no_cache {
                engine.configure_cache(cera::kv_cache::KvCacheConfig {
                    cache_dir: None,
                    max_warm_entries: 0,
                    max_warm_bytes: 0,
                    max_cold_bytes: 0,
                });
            }

            let mut tokens = Vec::new();
            if let Some(n) = prompt_tokens {
                // Generate N tokens by sampling from the vocabulary, skipping special tokens.
                let vocab_size = tokenizer.vocab_size() as u32;
                let mut tid = 100; // Start after typical special token range
                while tokens.len() < n {
                    if !tokenizer.is_special_token(tid % vocab_size) {
                        tokens.push(tid % vocab_size);
                    }
                    tid += 1;
                    if tid > vocab_size * 2 + n as u32 {
                        break; // Safety break
                    }
                }
                if tokens.len() != n {
                    return Err(anyhow::anyhow!(
                        "tokenizer only provides {} usable prompt token(s), but {} were requested",
                        tokens.len(),
                        n
                    ));
                }
            } else {
                if add_bos {
                    if let Some(bos) = tokenizer.bos_token() {
                        tokens.push(bos);
                    }
                }
                tokens.extend_from_slice(&tokenizer.encode(&prompt));
            }

            eprintln!(
                "Model: {} | {} layers | hidden={}",
                engine.model().config().architecture,
                engine.model().config().n_layers,
                engine.model().config().hidden_size
            );
            eprintln!(
                "Prompt tokens: {} | max_tokens: {} | warmup: {} | runs: {}",
                tokens.len(),
                max_tokens,
                warmup,
                runs
            );

            // Greedy (temp=0): deterministic, bench-friendly. NoopSink swallows tokens.
            let run_once = || -> Result<(f64, f64)> {
                let mut session = engine.new_session(cera::SessionConfig {
                    kv_compression: kv_compression.clone(),
                    seed: None,
                    ubatch_size,
                    ..Default::default()
                })?;
                let prefill_start = std::time::Instant::now();
                session.append_tokens(&tokens)?;
                let prefill_elapsed = prefill_start.elapsed();

                let opts = cera::GenerateOpts {
                    max_tokens: max_tokens as u32,
                    temperature: 0.0,
                    // llama-bench semantics: every run must decode exactly
                    // `max_tokens`, not stop early at EOS — otherwise short
                    // completions silently shrink the measured sample.
                    ignore_eos: true,
                    ..Default::default()
                };
                let mut sink = NoopSink;
                let summary = session.generate(&opts, &mut sink)?;

                let prefill_tps = if prefill_elapsed.as_secs_f64() > 0.0 {
                    tokens.len() as f64 / prefill_elapsed.as_secs_f64()
                } else {
                    0.0
                };
                let decode_tps = if summary.decode_ms > 0 {
                    summary.tokens_generated as f64 / (summary.decode_ms as f64 / 1000.0)
                } else {
                    0.0
                };
                Ok((prefill_tps, decode_tps))
            };

            // Thermal-headroom sampling (Android). A sustained CPU benchmark
            // heats the SoC within seconds, so annotate each run with headroom
            // (0.0 cool → 1.0 throttling threshold) to tell a real throughput
            // change from thermal drift. `None` off-Android / pre-API-30.
            let thermal = thermal::ThermalMonitor::new();
            let sample_headroom = || thermal.as_ref().and_then(|t| t.headroom(0));
            if let Some(h) = sample_headroom() {
                eprintln!("thermal headroom before warmup: {h:.2} (0=cool, 1.0=throttling)");
            }

            for i in 0..warmup {
                eprintln!("warmup {}/{}", i + 1, warmup);
                let _ = run_once()?;
            }

            let mut decode_tps = Vec::with_capacity(runs);
            let mut prefill_tps = Vec::with_capacity(runs);
            let mut headrooms = Vec::with_capacity(runs);
            for i in 0..runs {
                let (pf, dc) = run_once()?;
                let suffix = match sample_headroom() {
                    Some(h) => {
                        headrooms.push(h);
                        format!(" | headroom={h:.2}")
                    }
                    None => String::new(),
                };
                eprintln!(
                    "run {}/{}: prefill={pf:.0} decode={dc:.1} tok/s{suffix}",
                    i + 1,
                    runs
                );
                decode_tps.push(dc);
                prefill_tps.push(pf);
            }
            eprintln!();

            let (p10, p50, p90, mean, stddev) = summarize(decode_tps);
            eprintln!(
                "decode tok/s: p50={p50:.1} p10={p10:.1} p90={p90:.1} mean={mean:.1} stddev={stddev:.1} (n={runs})"
            );
            if !headrooms.is_empty() {
                let hmin = headrooms.iter().cloned().fold(f32::INFINITY, f32::min);
                let hmax = headrooms.iter().cloned().fold(f32::NEG_INFINITY, f32::max);
                eprintln!("thermal headroom over runs: min={hmin:.2} max={hmax:.2}");
                if hmax >= 0.95 {
                    eprintln!(
                        "WARNING: headroom reached {hmax:.2} — device was throttling; \
                         decode tok/s is thermally limited, not a stable ceiling. \
                         Cool the device (or reduce --runs/--max-tokens) and re-measure."
                    );
                }
            }
            let (p10, p50, p90, mean, stddev) = summarize(prefill_tps);
            eprintln!(
                "prefill tok/s: p50={p50:.0} p10={p10:.0} p90={p90:.0} mean={mean:.0} stddev={stddev:.0} (n={runs})"
            );
        }
    }

    Ok(())
}

#[cfg(test)]
mod tests {
    use std::sync::Arc;

    use super::{
        BundleQuantPair, Cli, Command, display_bundle_id, normalize_bundle_id, read_wav_pcm16_mono,
        resample_linear, resolve_engine, simulate_truncate_oldest_turn_pairs, split_at_marker,
        truncate_oldest_turn_pair, write_transcript, write_wav,
    };
    use cera::tokenizer::ChatMessage;
    use clap::Parser;

    fn msg(role: &str, content: &str) -> ChatMessage {
        ChatMessage {
            role: role.into(),
            content: content.into(),
        }
    }

    type ImagesByTurn = Vec<Vec<Arc<Vec<u8>>>>;

    /// Helper: build aligned (history, history_images) where every entry
    /// gets an empty image vec. Caller can override specific image vecs
    /// after the call.
    fn fixture(history: Vec<ChatMessage>) -> (Vec<ChatMessage>, ImagesByTurn) {
        let images = vec![Vec::new(); history.len()];
        (history, images)
    }

    #[test]
    fn truncate_drops_oldest_pair_with_system() {
        let (mut hist, mut imgs) = fixture(vec![
            msg("system", "you are helpful"),
            msg("user", "u1"),
            msg("assistant", "a1"),
            msg("user", "u2"),
            msg("assistant", "a2"),
            msg("user", "u3"),
        ]);
        assert!(truncate_oldest_turn_pair(&mut hist, &mut imgs));
        assert_eq!(
            hist.iter()
                .map(|m| (m.role.as_str(), m.content.as_str()))
                .collect::<Vec<_>>(),
            vec![
                ("system", "you are helpful"),
                ("user", "u2"),
                ("assistant", "a2"),
                ("user", "u3"),
            ]
        );
        assert_eq!(imgs.len(), hist.len());
    }

    #[test]
    fn truncate_drops_oldest_pair_no_system() {
        let (mut hist, mut imgs) = fixture(vec![
            msg("user", "u1"),
            msg("assistant", "a1"),
            msg("user", "u2"),
            msg("assistant", "a2"),
            msg("user", "u3"),
        ]);
        assert!(truncate_oldest_turn_pair(&mut hist, &mut imgs));
        assert_eq!(
            hist.iter().map(|m| m.content.as_str()).collect::<Vec<_>>(),
            vec!["u2", "a2", "u3"]
        );
    }

    #[test]
    fn truncate_drops_image_bytes_with_pair() {
        let (mut hist, mut imgs) = fixture(vec![
            msg("user", "u1"),
            msg("assistant", "a1"),
            msg("user", "u2"),
        ]);
        // Attach an image to the oldest user turn.
        imgs[0].push(Arc::new(vec![0xAB; 16]));
        assert!(truncate_oldest_turn_pair(&mut hist, &mut imgs));
        // u1+a1 dropped → only u2 left (no images on u2).
        assert_eq!(hist.len(), 1);
        assert_eq!(imgs.len(), 1);
        assert!(imgs[0].is_empty());
    }

    #[test]
    fn truncate_refuses_to_drop_current_user_turn_only() {
        // System + just the current user. Nothing older to drop.
        let (mut hist, mut imgs) = fixture(vec![msg("system", "sys"), msg("user", "u1")]);
        assert!(!truncate_oldest_turn_pair(&mut hist, &mut imgs));
        // Unchanged.
        assert_eq!(hist.len(), 2);
    }

    #[test]
    fn truncate_refuses_on_system_only() {
        let (mut hist, mut imgs) = fixture(vec![msg("system", "sys")]);
        assert!(!truncate_oldest_turn_pair(&mut hist, &mut imgs));
        assert_eq!(hist.len(), 1);
    }

    #[test]
    fn truncate_refuses_on_empty() {
        let mut hist: Vec<ChatMessage> = Vec::new();
        let mut imgs: Vec<Vec<Arc<Vec<u8>>>> = Vec::new();
        assert!(!truncate_oldest_turn_pair(&mut hist, &mut imgs));
    }

    #[test]
    fn truncate_handles_dangling_user_without_assistant() {
        // Edge case: a prior turn errored mid-flight and the assistant
        // reply was popped, leaving two consecutive user messages.
        // Drop one, leave the rest. Test guards against accidentally
        // dropping the second remove() when no assistant is present.
        let (mut hist, mut imgs) = fixture(vec![msg("user", "u_orphan"), msg("user", "u_current")]);
        assert!(truncate_oldest_turn_pair(&mut hist, &mut imgs));
        assert_eq!(hist.len(), 1);
        assert_eq!(hist[0].content, "u_current");
    }

    /// Equivalence: `simulate_truncate_oldest_turn_pairs` must produce the
    /// same kept-suffix as N consecutive `truncate_oldest_turn_pair` calls
    /// on the same input. The TUI dispatch path relies on this to skip the
    /// O(N) `Vec::remove` shifting per turn.
    #[test]
    fn simulate_truncate_matches_in_place_helper() {
        let cases: &[Vec<ChatMessage>] = &[
            vec![],
            vec![msg("system", "s")],
            vec![msg("system", "s"), msg("user", "u1")],
            vec![
                msg("system", "s"),
                msg("user", "u1"),
                msg("assistant", "a1"),
                msg("user", "u2"),
                msg("assistant", "a2"),
                msg("user", "u3"),
            ],
            vec![
                msg("user", "u1"),
                msg("assistant", "a1"),
                msg("user", "u2"),
                msg("assistant", "a2"),
                msg("user", "u3"),
            ],
            // Dangling-user history (orphaned by a prior generate failure
            // before the assistant reply landed).
            vec![
                msg("user", "u_orphan"),
                msg("user", "u2"),
                msg("assistant", "a2"),
                msg("user", "u3"),
            ],
        ];
        for hist in cases {
            for n in 0..=5 {
                // Reference: mutate via the in-place helper.
                let mut ref_hist = hist.clone();
                let mut ref_imgs: ImagesByTurn = vec![Vec::new(); ref_hist.len()];
                let mut ref_applied = 0usize;
                for _ in 0..n {
                    if !truncate_oldest_turn_pair(&mut ref_hist, &mut ref_imgs) {
                        break;
                    }
                    ref_applied += 1;
                }

                // Candidate: simulate, then build the kept suffix by chain.
                let (start, end, applied) = simulate_truncate_oldest_turn_pairs(hist, n);
                assert_eq!(
                    applied, ref_applied,
                    "applied count mismatch: hist={hist:?} n={n}"
                );
                let candidate: Vec<ChatMessage> = hist[..start]
                    .iter()
                    .chain(hist[end..].iter())
                    .cloned()
                    .collect();
                assert_eq!(
                    candidate.len(),
                    ref_hist.len(),
                    "kept-suffix length mismatch: hist={hist:?} n={n}"
                );
                for (i, (cand, refm)) in candidate.iter().zip(ref_hist.iter()).enumerate() {
                    assert_eq!(
                        (cand.role.as_str(), cand.content.as_str()),
                        (refm.role.as_str(), refm.content.as_str()),
                        "kept-suffix entry {i} mismatch: hist={hist:?} n={n}"
                    );
                }
            }
        }
    }

    /// Round-trip: deterministic samples → write_wav → read_wav_pcm16_mono.
    /// The reader must recover the same sample count + sample rate, with
    /// values within one quantization step of the originals.
    #[test]
    fn write_then_read_wav_roundtrips() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("rt.wav");
        let path_str = path.to_str().unwrap();

        let sr = 16_000u32;
        // 100 samples of a small triangle wave well inside [-1, 1].
        let samples: Vec<f32> = (0..100)
            .map(|i| ((i as f32) / 50.0 - 1.0).clamp(-0.9, 0.9))
            .collect();

        write_wav(path_str, &samples, sr).unwrap();
        let (back, back_sr) = read_wav_pcm16_mono(path_str).unwrap();

        assert_eq!(back_sr, sr, "sample rate must round-trip");
        assert_eq!(back.len(), samples.len(), "sample count must round-trip");
        // 16-bit PCM has ≈ 1/32768 quantization step; allow 2× that
        // for safety (write_wav uses 32767 scale, read uses 32768).
        let eps = 2.0 / 32768.0;
        for (i, (a, b)) in samples.iter().zip(back.iter()).enumerate() {
            assert!(
                (a - b).abs() < eps,
                "sample {i}: orig={a} read={b} diff={}",
                (a - b).abs()
            );
        }
    }

    /// `--audio-in` must parse cleanly without `--prompt`. This is the
    /// advertised audio-only entry point — clap-rejecting it would
    /// make the documented `cera run --audio-in <wav>` form unusable.
    #[test]
    fn audio_in_parses_without_prompt() {
        let r = Cli::try_parse_from([
            "cera",
            "run",
            "--model",
            "/tmp/x",
            "--audio-in",
            "/tmp/y.wav",
        ]);
        assert!(
            r.is_ok(),
            "expected --audio-in alone to parse, got: {:?}",
            r.err()
        );
    }

    /// `--audio-in` is mutually exclusive with several other flags so
    /// callers don't silently get wrong behavior. Verify each
    /// individual conflict surfaces from clap rather than reaching the
    /// dispatch. `--system` is NOT in this list — it's intentionally
    /// allowed alongside `--audio-in` so the chat-template flow can
    /// wrap audio in a system+user turn.
    #[test]
    fn audio_in_conflicts_are_enforced_by_clap() {
        for (label, extra) in [
            ("--vocoder", vec!["--vocoder", "/tmp/v.gguf"]),
            ("--audio-out", vec!["--audio-out", "/tmp/o.wav"]),
            ("--token-ids", vec!["--token-ids", "1,2,3"]),
        ] {
            let mut argv = vec![
                "cera",
                "run",
                "--model",
                "/tmp/x",
                "--audio-in",
                "/tmp/y.wav",
            ];
            argv.extend_from_slice(&extra);
            let r = Cli::try_parse_from(&argv);
            assert!(
                r.is_err(),
                "expected --audio-in + {label} to be rejected by clap, but parsing succeeded"
            );
        }
    }

    /// `--audio-in` + `--system` (and optionally `--prompt`) must
    /// parse cleanly — the chat-template flow runs at dispatch time.
    /// Negative case (missing audio marker token) lives in the
    /// `split_at_marker` test below; this one just guards the clap
    /// surface.
    #[test]
    fn audio_in_plus_system_parses() {
        let r = Cli::try_parse_from([
            "cera",
            "run",
            "--model",
            "/tmp/x",
            "--audio-in",
            "/tmp/y.wav",
            "--system",
            "Perform ASR.",
            "--prompt",
            "What did the speaker say?",
        ]);
        assert!(
            r.is_ok(),
            "expected --audio-in + --system + --prompt to parse, got: {:?}",
            r.err()
        );
    }

    /// `chat` subcommand must parse cleanly with the minimal
    /// `--model` flag — the rest of its surface has defaults so a
    /// bare invocation is the documented entry point.
    #[test]
    fn chat_subcommand_parses_minimal() {
        let r = Cli::try_parse_from(["cera", "chat", "--model", "/tmp/x"]);
        assert!(
            r.is_ok(),
            "expected `chat --model <path>` alone to parse, got: {:?}",
            r.err()
        );
    }

    /// `chat` must also accept the full v1 flag surface together —
    /// guards against a flag rename / clap drift breaking the
    /// documented invocation. Includes the KV prefix cache flags
    /// (`--cache-warm-mb`, `--cache-disk-gb`, `--no-cache`) so the
    /// mobile-app "survive process restart" config path stays
    /// parsable.
    #[test]
    fn chat_subcommand_parses_full_flags() {
        let r = Cli::try_parse_from([
            "cera",
            "chat",
            "--model",
            "/tmp/x",
            "--system",
            "Be brief",
            "--device",
            "cpu",
            "--context-size",
            "2048",
            "--max-tokens",
            "256",
            "--temperature",
            "0.5",
            "--seed",
            "42",
            "--cache-dir",
            "/tmp/cache",
            "--cache-warm-mb",
            "128",
            "--cache-disk-gb",
            "5",
        ]);
        assert!(
            r.is_ok(),
            "expected full `chat` flag surface to parse, got: {:?}",
            r.err()
        );
    }

    /// `run`, `chat`, and `embed` all accept `--lora <PATH>`; the flag
    /// must parse and thread into the command's `lora` field.
    #[test]
    fn lora_flag_parses_on_run_chat_embed() {
        let run = Cli::try_parse_from([
            "cera",
            "run",
            "-m",
            "/tmp/x",
            "-p",
            "hi",
            "--lora",
            "/tmp/a.safetensors",
        ]);
        let Ok(Cli {
            command: Command::Run { lora, .. },
        }) = run
        else {
            panic!("expected `run --lora` to parse, got: {:?}", run.err());
        };
        assert_eq!(lora.as_deref(), Some("/tmp/a.safetensors"));

        let chat = Cli::try_parse_from(["cera", "chat", "-m", "/tmp/x", "--lora", "/tmp/a.gguf"]);
        let Ok(Cli {
            command: Command::Chat { lora, .. },
        }) = chat
        else {
            panic!("expected `chat --lora` to parse, got: {:?}", chat.err());
        };
        assert_eq!(lora.as_deref(), Some("/tmp/a.gguf"));

        let embed = Cli::try_parse_from([
            "cera",
            "embed",
            "-m",
            "/tmp/x",
            "-p",
            "hi",
            "--lora",
            "/tmp/a.safetensors",
            "--lora-alpha",
            "16",
        ]);
        let Ok(Cli {
            command: Command::Embed {
                lora, lora_alpha, ..
            },
        }) = embed
        else {
            panic!(
                "expected `embed --lora --lora-alpha` to parse, got: {:?}",
                embed.err()
            );
        };
        assert_eq!(lora.as_deref(), Some("/tmp/a.safetensors"));
        assert_eq!(lora_alpha, Some(16.0));
    }

    /// `embed` requires `--prompt`, accepts a model source, and exposes
    /// `--per-token` / `--json` / `--lora`.
    #[test]
    fn embed_subcommand_parses_full_surface() {
        let r = Cli::try_parse_from([
            "cera",
            "embed",
            "-m",
            "/tmp/x",
            "-p",
            "a chunk",
            "--per-token",
            "--json",
            "--lora",
            "/tmp/a.gguf",
        ]);
        let Ok(Cli {
            command:
                Command::Embed {
                    prompt,
                    per_token,
                    json,
                    lora,
                    ..
                },
        }) = r
        else {
            panic!("expected full `embed` surface to parse, got: {:?}", r.err());
        };
        assert_eq!(prompt, "a chunk");
        assert!(per_token);
        assert!(json);
        assert_eq!(lora.as_deref(), Some("/tmp/a.gguf"));
    }

    /// `embed` without `--prompt` is rejected by clap — the prompt is required.
    #[test]
    fn embed_subcommand_requires_prompt() {
        let r = Cli::try_parse_from(["cera", "embed", "-m", "/tmp/x"]);
        assert!(
            r.is_err(),
            "expected `embed` without --prompt to be rejected"
        );
    }

    /// `chat --no-cache` must parse cleanly — explicit opt-out of
    /// the KV prefix cache for users who'd rather not write to disk.
    #[test]
    fn chat_subcommand_parses_no_cache() {
        let r = Cli::try_parse_from(["cera", "chat", "--model", "/tmp/x", "--no-cache"]);
        assert!(
            r.is_ok(),
            "expected `chat --no-cache` to parse, got: {:?}",
            r.err()
        );
    }

    /// `chat --bundle-id <id> --quant <q>` parses cleanly without
    /// `--model`. This is the documented auto-download entry
    /// point — clap-rejecting it would make the LeapBundles flow
    /// unusable.
    #[test]
    fn chat_subcommand_parses_with_bundle_id() {
        let r = Cli::try_parse_from([
            "cera",
            "chat",
            "--bundle-id",
            "LFM2-1.2B-GGUF",
            "--quant",
            "Q4_0",
        ]);
        assert!(
            r.is_ok(),
            "expected `chat --bundle-id X --quant Y` to parse, got: {:?}",
            r.err()
        );
    }

    /// `--bundle-id` without `--quant` must be rejected by clap
    /// (and vice-versa) because the LeapBundles URL needs both.
    /// Surfacing this at parse time is friendlier than letting
    /// it through to a runtime error.
    #[test]
    fn chat_subcommand_rejects_bundle_id_without_quant() {
        for partial in [
            vec!["cera", "chat", "--bundle-id", "X"],
            vec!["cera", "chat", "--quant", "Q4_0"],
        ] {
            let r = Cli::try_parse_from(&partial);
            assert!(
                r.is_err(),
                "expected partial bundle args {partial:?} to be rejected by clap"
            );
        }
    }

    /// `--model` is mutually exclusive with `--bundle-id` /
    /// `--quant` — passing both is meaningless and we want the
    /// error at parse time, not after a wasted download attempt.
    #[test]
    fn chat_subcommand_rejects_model_with_bundle_id() {
        let r = Cli::try_parse_from([
            "cera",
            "chat",
            "--model",
            "/tmp/x",
            "--bundle-id",
            "LFM2-1.2B-GGUF",
            "--quant",
            "Q4_0",
        ]);
        assert!(
            r.is_err(),
            "expected `--model` + `--bundle-id` to be rejected by clap"
        );
    }

    /// Same auto-download entry point on `run`. Symmetric with
    /// `chat`'s parse test — flag drift on either subcommand
    /// breaks the documented form.
    #[test]
    fn run_subcommand_parses_with_bundle_id() {
        let r = Cli::try_parse_from([
            "cera",
            "run",
            "--bundle-id",
            "LFM2-1.2B-GGUF",
            "--quant",
            "Q4_0",
            "--prompt",
            "hi",
        ]);
        assert!(
            r.is_ok(),
            "expected `run --bundle-id X --quant Y` to parse, got: {:?}",
            r.err()
        );
    }

    /// `bench` is the third subcommand carrying the bundle-id
    /// surface; ensure it parses too.
    #[test]
    fn bench_subcommand_parses_with_bundle_id() {
        let r = Cli::try_parse_from([
            "cera",
            "bench",
            "--bundle-id",
            "LFM2-1.2B-GGUF",
            "--quant",
            "Q4_0",
        ]);
        assert!(
            r.is_ok(),
            "expected `bench --bundle-id X --quant Y` to parse, got: {:?}",
            r.err()
        );
    }

    /// `bench --model` + `--bundle-id` must be rejected at parse
    /// time (mutually exclusive). Mirrors the gate on `run` /
    /// `chat`.
    #[test]
    fn bench_subcommand_rejects_model_with_bundle_id() {
        let r = Cli::try_parse_from([
            "cera",
            "bench",
            "--model",
            "/tmp/x",
            "--bundle-id",
            "LFM2-1.2B-GGUF",
            "--quant",
            "Q4_0",
        ]);
        assert!(
            r.is_err(),
            "expected `bench --model` + `--bundle-id` to be rejected by clap"
        );
    }

    #[test]
    fn download_bundles_parses_repeated_pairs() {
        let cli = Cli::try_parse_from([
            "cera",
            "download-bundles",
            "--bundle",
            "LFM2.5-350M:Q4_0",
            "--bundle",
            "LFM2-700M-GGUF:Q8_0",
            "--cache-dir",
            "/tmp/cera-cache",
        ])
        .expect("download-bundles should parse repeated ID:QUANT pairs");

        match cli.command {
            Command::DownloadBundles { bundles, cache_dir } => {
                assert_eq!(
                    bundles,
                    vec![
                        BundleQuantPair {
                            bundle_id: "LFM2.5-350M".into(),
                            quant: "Q4_0".into(),
                        },
                        BundleQuantPair {
                            bundle_id: "LFM2-700M-GGUF".into(),
                            quant: "Q8_0".into(),
                        },
                    ]
                );
                assert_eq!(cache_dir.as_deref(), Some("/tmp/cera-cache"));
            }
            _ => panic!("expected DownloadBundles command"),
        }
    }

    #[test]
    fn download_bundles_rejects_malformed_pair() {
        for arg in ["LFM2.5-350M", ":Q4_0", "LFM2.5-350M:"] {
            let r = Cli::try_parse_from(["cera", "download-bundles", "--bundle", arg]);
            assert!(
                r.is_err(),
                "expected malformed download pair `{arg}` to be rejected"
            );
        }
    }

    /// `resolve_engine` with no source flags errors out before
    /// touching disk or network — fast clear failure on a misuse
    /// that clap can't catch (both `--model` and `--bundle-id`
    /// being optional means clap accepts the empty case).
    #[test]
    fn resolve_engine_rejects_no_source() {
        let r = resolve_engine(None, None, None, None, "cpu", 1024);
        let err = match r {
            Ok(_) => panic!("expected an error when no source flags are set"),
            Err(e) => e,
        };
        let msg = format!("{err:#}");
        assert!(
            msg.contains("no model source"),
            "error should explain that no source was given; got: {msg}"
        );
    }

    /// `resolve_engine` rejects `--bundle-id` without `--quant`
    /// (and vice-versa). Clap's `requires` already catches this
    /// at parse time, but the helper has its own guard for
    /// programmatic callers (and as a defense-in-depth check).
    #[test]
    fn resolve_engine_rejects_partial_bundle_args() {
        let r = resolve_engine(None, Some("LFM2-1.2B-GGUF"), None, None, "cpu", 1024);
        assert!(
            r.is_err(),
            "expected partial bundle args (id only) to error"
        );
        let r = resolve_engine(None, None, Some("Q4_0"), None, "cpu", 1024);
        assert!(
            r.is_err(),
            "expected partial bundle args (quant only) to error"
        );
    }

    /// `normalize_bundle_id` appends `-GGUF` when missing and is
    /// idempotent when the suffix is already present. The CLI
    /// applies this in `resolve_engine` so users can type either
    /// form at `--bundle-id`.
    #[test]
    fn normalize_bundle_id_appends_when_missing() {
        assert_eq!(
            normalize_bundle_id("LFM2.5-1.2B-Instruct"),
            "LFM2.5-1.2B-Instruct-GGUF"
        );
        assert_eq!(normalize_bundle_id("Qwen3-1.7B"), "Qwen3-1.7B-GGUF");
    }

    #[test]
    fn normalize_bundle_id_is_idempotent() {
        assert_eq!(
            normalize_bundle_id("LFM2-1.2B-GGUF"),
            "LFM2-1.2B-GGUF",
            "must not double-append"
        );
    }

    /// `display_bundle_id` strips the trailing `-GGUF` for
    /// presentation (matches what users type at `--bundle-id`)
    /// and is a no-op for any future entry without the suffix.
    #[test]
    fn display_bundle_id_strips_gguf_suffix() {
        assert_eq!(display_bundle_id("LFM2-1.2B-GGUF"), "LFM2-1.2B");
        assert_eq!(
            display_bundle_id("LFM2.5-1.2B-Instruct-GGUF"),
            "LFM2.5-1.2B-Instruct"
        );
        // Hypothetical future non-GGUF bundle: passes through.
        assert_eq!(display_bundle_id("LFM3-MLX"), "LFM3-MLX");
    }

    /// `write_transcript` round-trips a small history: one block
    /// per turn shaped `<role>: <content>\n`, blank line between
    /// turns, trailing newline at file end. Multi-line content
    /// passes through verbatim (no escaping).
    #[test]
    fn write_transcript_round_trips_basic() {
        use cera::tokenizer::ChatMessage;
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("transcript.txt");
        let history = vec![
            ChatMessage {
                role: "system".into(),
                content: "You are helpful.".into(),
            },
            ChatMessage {
                role: "user".into(),
                content: "Hi".into(),
            },
            ChatMessage {
                role: "assistant".into(),
                content: "Hello!".into(),
            },
        ];
        write_transcript(&history, &path).unwrap();
        let got = std::fs::read_to_string(&path).unwrap();
        let want = "system: You are helpful.\n\nuser: Hi\n\nassistant: Hello!\n";
        assert_eq!(got, want);
    }

    /// Empty history → empty file (still creates the file). Lets
    /// `/save` succeed before any turns and overwrite with a
    /// transcript later.
    #[test]
    fn write_transcript_empty_history_writes_empty_file() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("empty.txt");
        write_transcript(&[], &path).unwrap();
        let got = std::fs::read_to_string(&path).unwrap();
        assert!(got.is_empty(), "expected empty file, got {got:?}");
    }

    /// Multi-line content (code blocks, paragraph breaks)
    /// round-trips verbatim. We don't escape `\n` because the
    /// transcript is for human reading; users can compare side
    /// by side with the rendered chat.
    #[test]
    fn write_transcript_handles_multiline_content() {
        use cera::tokenizer::ChatMessage;
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("multi.txt");
        let history = vec![ChatMessage {
            role: "assistant".into(),
            content: "line one\nline two\nline three".into(),
        }];
        write_transcript(&history, &path).unwrap();
        let got = std::fs::read_to_string(&path).unwrap();
        assert_eq!(got, "assistant: line one\nline two\nline three\n");
    }

    /// `split_at_marker` happy path: a marker in the middle of a
    /// token list returns the unique index, and the caller can
    /// slice prefix/suffix around it.
    #[test]
    fn split_at_marker_normal_case() {
        let toks = [10u32, 20, 99, 30, 40];
        let idx = split_at_marker(&toks, 99, "<|reserved_4|>").unwrap();
        assert_eq!(idx, 2);
        assert_eq!(&toks[..idx], &[10, 20]);
        assert_eq!(&toks[idx + 1..], &[30, 40]);
    }

    /// Marker at position 0 → empty prefix slice.
    #[test]
    fn split_at_marker_at_start() {
        let toks = [99u32, 1, 2, 3];
        let idx = split_at_marker(&toks, 99, "<|reserved_4|>").unwrap();
        assert_eq!(idx, 0);
        assert!(toks[..idx].is_empty());
        assert_eq!(&toks[idx + 1..], &[1, 2, 3]);
    }

    /// Marker at the last position → empty suffix slice.
    #[test]
    fn split_at_marker_at_end() {
        let toks = [1u32, 2, 3, 99];
        let idx = split_at_marker(&toks, 99, "<|reserved_4|>").unwrap();
        assert_eq!(idx, 3);
        assert_eq!(&toks[..idx], &[1, 2, 3]);
        assert!(toks[idx + 1..].is_empty());
    }

    /// Missing marker → typed error naming the marker by string
    /// AND id, so users know what literal to inspect (not just
    /// "id 99 missing"). Plus a hint to drop `--system`.
    #[test]
    fn split_at_marker_missing_errors() {
        let toks = [10u32, 20, 30];
        let err = split_at_marker(&toks, 99, "<|reserved_4|>").unwrap_err();
        let msg = format!("{err:#}");
        assert!(
            msg.contains("<|reserved_4|>") && msg.contains("99") && msg.contains("not found"),
            "error should name `<|reserved_4|>`, id 99, and 'not found': {msg}"
        );
        assert!(
            msg.contains("--system"),
            "error should hint at dropping --system: {msg}"
        );
    }

    /// Marker appearing more than once → typed error pointing at
    /// the user-supplied text as the likely culprit. Both the
    /// occurrence count and the marker name appear in the message.
    #[test]
    fn split_at_marker_duplicate_errors() {
        let toks = [10u32, 99, 20, 99, 30];
        let err = split_at_marker(&toks, 99, "<|reserved_4|>").unwrap_err();
        let msg = format!("{err:#}");
        assert!(
            msg.contains("<|reserved_4|>") && msg.contains("2 times"),
            "error should name `<|reserved_4|>` and report '2 times': {msg}"
        );
        assert!(
            msg.contains("--prompt") && msg.contains("--system"),
            "error should point at user-supplied text as the source: {msg}"
        );
    }

    /// `--image` accepts a single path. Confirms the flag round-trips
    /// through clap's `Vec<String>` collector and the destructure
    /// keeps it on `Run`.
    #[test]
    fn run_subcommand_parses_single_image() {
        let r = Cli::try_parse_from([
            "cera", "run", "--model", "/tmp/x", "--image", "pug.jpg", "--prompt", "describe",
        ]);
        let cli = r.expect("`run --model X --image Y --prompt Z` should parse");
        let Command::Run { image, prompt, .. } = cli.command else {
            panic!("expected Run subcommand, got something else");
        };
        assert_eq!(image, vec!["pug.jpg".to_string()]);
        assert_eq!(prompt.as_deref(), Some("describe"));
    }

    /// `--image` collects multiple values when the flag repeats —
    /// the multi-image path. clap default behavior for
    /// `Vec<String>` arguments.
    #[test]
    fn run_subcommand_parses_multiple_images() {
        let r = Cli::try_parse_from([
            "cera", "run", "--model", "/tmp/x", "--image", "a.jpg", "--image", "b.jpg", "--prompt",
            "compare",
        ]);
        let cli = r.expect("repeated --image should parse");
        let Command::Run { image, .. } = cli.command else {
            panic!("expected Run subcommand");
        };
        assert_eq!(image, vec!["a.jpg".to_string(), "b.jpg".to_string()]);
    }

    /// `--image` without `--prompt` parses (image-only inference is
    /// allowed; the dispatcher constructs `[ContentItem::Image]`
    /// content with no trailing text).
    #[test]
    fn run_subcommand_parses_image_without_prompt() {
        let r = Cli::try_parse_from(["cera", "run", "--model", "/tmp/x", "--image", "pug.jpg"]);
        assert!(
            r.is_ok(),
            "`run --model X --image Y` (no --prompt) should parse: {:?}",
            r.err()
        );
    }

    /// Clap rejects `--image` paired with the audio-in family:
    /// these modes are mutually exclusive ways to feed non-text
    /// input into the LLM, and combining them is a misuse, not a
    /// feature. The conflict is declared on the flag definition
    /// so the rejection happens at parse time, before engine load.
    #[test]
    fn run_subcommand_rejects_image_with_audio_in() {
        let r = Cli::try_parse_from([
            "cera",
            "run",
            "--model",
            "/tmp/x",
            "--image",
            "a.jpg",
            "--audio-in",
            "b.wav",
        ]);
        assert!(r.is_err(), "clap should reject --image with --audio-in");
    }

    /// Same conflict family — `--image` against `--vocoder`.
    #[test]
    fn run_subcommand_rejects_image_with_vocoder() {
        let r = Cli::try_parse_from([
            "cera",
            "run",
            "--model",
            "/tmp/x",
            "--image",
            "a.jpg",
            "--vocoder",
            "v.gguf",
        ]);
        assert!(r.is_err(), "clap should reject --image with --vocoder");
    }

    /// `--image` against `--token-ids` — raw-token mode bypasses
    /// the chat template the helper renders, so combining them
    /// would silently ignore one or the other.
    #[test]
    fn run_subcommand_rejects_image_with_token_ids() {
        let r = Cli::try_parse_from([
            "cera",
            "run",
            "--model",
            "/tmp/x",
            "--image",
            "a.jpg",
            "--token-ids",
            "1,2,3",
        ]);
        assert!(r.is_err(), "clap should reject --image with --token-ids");
    }

    /// Text mode without `--audio-in` and without `--prompt` is the
    /// negative case for the new optional `prompt`. Clap accepts the
    /// args (since prompt is now `Option<String>`); the runtime check
    /// in the dispatcher should bail with a clear "--prompt is
    /// required" message — but that path isn't exercised here (it
    /// runs after engine load). What we CAN check in unit tests is
    /// that clap parses both forms, leaving runtime validation as
    /// the single source of truth.
    #[test]
    fn run_without_prompt_or_audio_in_parses() {
        // Clap parses; the dispatcher will reject at runtime with the
        // usage error message. We don't try to construct an Engine here.
        let r = Cli::try_parse_from(["cera", "run", "--model", "/tmp/x"]);
        assert!(
            r.is_ok(),
            "expected bare `run --model` to parse, got: {:?}",
            r.err()
        );
    }

    /// Stereo WAV must be down-mixed to mono by averaging across
    /// channels. Hand-craft a 4-frame stereo file with L=+0.5,
    /// R=-0.5 and verify the mono output is all zeros (avg of
    /// opposites = 0).
    #[test]
    fn read_wav_downmixes_stereo_to_average() {
        // Stereo PCM16 @ 16 kHz, 4 frames. L=+0.5 (16384), R=-0.5 (-16384).
        let l: i16 = 16_384;
        let r: i16 = -16_384;
        let mut data: Vec<u8> = Vec::new();
        for _ in 0..4 {
            data.extend_from_slice(&l.to_le_bytes());
            data.extend_from_slice(&r.to_le_bytes());
        }
        let data_sz = data.len() as u32;

        let mut buf: Vec<u8> = Vec::new();
        buf.extend_from_slice(b"RIFF");
        buf.extend_from_slice(&(36 + data_sz).to_le_bytes());
        buf.extend_from_slice(b"WAVE");
        buf.extend_from_slice(b"fmt ");
        buf.extend_from_slice(&16u32.to_le_bytes());
        buf.extend_from_slice(&1u16.to_le_bytes()); // PCM
        buf.extend_from_slice(&2u16.to_le_bytes()); // 2 channels
        buf.extend_from_slice(&16_000u32.to_le_bytes());
        buf.extend_from_slice(&64_000u32.to_le_bytes());
        buf.extend_from_slice(&4u16.to_le_bytes()); // block align (2ch * 2B)
        buf.extend_from_slice(&16u16.to_le_bytes());
        buf.extend_from_slice(b"data");
        buf.extend_from_slice(&data_sz.to_le_bytes());
        buf.extend_from_slice(&data);

        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("stereo.wav");
        std::fs::write(&path, &buf).unwrap();

        let (samples, sr) = read_wav_pcm16_mono(path.to_str().unwrap()).unwrap();
        assert_eq!(sr, 16_000);
        assert_eq!(
            samples.len(),
            4,
            "stereo down-mix should yield 4 mono frames"
        );
        for (i, &s) in samples.iter().enumerate() {
            assert!(
                s.abs() < 1e-3,
                "frame {i}: avg of +0.5 and -0.5 should be ~0; got {s}"
            );
        }
    }

    /// 4-channel WAV must average all four channels per frame.
    #[test]
    fn read_wav_downmixes_quad_to_average() {
        // 4-channel @ 16 kHz, 2 frames. Channels = +1.0, +0.5, -0.5, -1.0.
        // Average per frame = 0.0.
        let s1: i16 = 32_767; // ~+1.0
        let s2: i16 = 16_384; // +0.5
        let s3: i16 = -16_384; // -0.5
        let s4: i16 = -32_768; // -1.0
        let mut data: Vec<u8> = Vec::new();
        for _ in 0..2 {
            data.extend_from_slice(&s1.to_le_bytes());
            data.extend_from_slice(&s2.to_le_bytes());
            data.extend_from_slice(&s3.to_le_bytes());
            data.extend_from_slice(&s4.to_le_bytes());
        }
        let data_sz = data.len() as u32;

        let mut buf: Vec<u8> = Vec::new();
        buf.extend_from_slice(b"RIFF");
        buf.extend_from_slice(&(36 + data_sz).to_le_bytes());
        buf.extend_from_slice(b"WAVE");
        buf.extend_from_slice(b"fmt ");
        buf.extend_from_slice(&16u32.to_le_bytes());
        buf.extend_from_slice(&1u16.to_le_bytes());
        buf.extend_from_slice(&4u16.to_le_bytes()); // 4 channels
        buf.extend_from_slice(&16_000u32.to_le_bytes());
        buf.extend_from_slice(&128_000u32.to_le_bytes());
        buf.extend_from_slice(&8u16.to_le_bytes()); // block align
        buf.extend_from_slice(&16u16.to_le_bytes());
        buf.extend_from_slice(b"data");
        buf.extend_from_slice(&data_sz.to_le_bytes());
        buf.extend_from_slice(&data);

        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("quad.wav");
        std::fs::write(&path, &buf).unwrap();

        let (samples, _sr) = read_wav_pcm16_mono(path.to_str().unwrap()).unwrap();
        assert_eq!(samples.len(), 2);
        // i16::MAX is 32767 vs i16::MIN = -32768 → asymmetric scale
        // means the +1.0/-1.0 pair averages to ~-1/(4*32768) ≈ -7.6e-6,
        // which combined with +0.5/-0.5 (exact 0) gives ~-1.9e-6.
        // Use a generous epsilon since the meaningful claim is "averages
        // to zero", not "byte-exact".
        for (i, &s) in samples.iter().enumerate() {
            assert!(
                s.abs() < 1e-3,
                "frame {i}: 4-channel avg should be ~0; got {s}"
            );
        }
    }

    /// channels=0 in the fmt header is malformed and must be rejected.
    #[test]
    fn read_wav_rejects_zero_channels() {
        let mut buf: Vec<u8> = Vec::new();
        buf.extend_from_slice(b"RIFF");
        buf.extend_from_slice(&36u32.to_le_bytes());
        buf.extend_from_slice(b"WAVE");
        buf.extend_from_slice(b"fmt ");
        buf.extend_from_slice(&16u32.to_le_bytes());
        buf.extend_from_slice(&1u16.to_le_bytes()); // PCM
        buf.extend_from_slice(&0u16.to_le_bytes()); // 0 channels (malformed)
        buf.extend_from_slice(&16_000u32.to_le_bytes());
        buf.extend_from_slice(&0u32.to_le_bytes());
        buf.extend_from_slice(&0u16.to_le_bytes());
        buf.extend_from_slice(&16u16.to_le_bytes());
        buf.extend_from_slice(b"data");
        buf.extend_from_slice(&0u32.to_le_bytes());

        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("zero_ch.wav");
        std::fs::write(&path, &buf).unwrap();

        let err = read_wav_pcm16_mono(path.to_str().unwrap()).unwrap_err();
        let msg = format!("{err:#}");
        assert!(
            msg.contains("channels=0"),
            "error should mention channels=0; got: {msg}"
        );
    }

    /// `resample_linear` with `sr_in == sr_out` must return the input
    /// unchanged. Hot path for the common 16 kHz → 16 kHz case (every
    /// invocation that doesn't actually need resampling); a regression
    /// here would silently corrupt every same-rate ASR call.
    #[test]
    fn resample_linear_same_rate_is_identity() {
        let samples: Vec<f32> = (0..1000).map(|i| (i as f32 * 0.01).sin()).collect();
        let out = resample_linear(&samples, 16_000, 16_000);
        assert_eq!(out, samples);
    }

    /// Empty input must produce empty output without panicking — the
    /// caller's `n_samples` could be 0 if a fixture WAV's data chunk
    /// is missing and the assertion above is bypassed somehow.
    #[test]
    fn resample_linear_empty_input() {
        let out = resample_linear(&[], 44_100, 16_000);
        assert!(out.is_empty());
        let out = resample_linear(&[1.0, 2.0], 0, 16_000);
        assert!(out.is_empty());
        let out = resample_linear(&[1.0, 2.0], 16_000, 0);
        assert!(out.is_empty());
    }

    /// 2× upsample (8 kHz → 16 kHz). Output length doubles; output
    /// values reproduce the original at even indices and the
    /// midpoint between adjacent originals at odd indices.
    #[test]
    fn resample_linear_2x_upsample_interpolates_midpoints() {
        let input = vec![0.0, 1.0, 0.0, -1.0]; // 4 samples
        let out = resample_linear(&input, 8_000, 16_000);
        // n_out = 4 * 2 = 8 samples expected.
        assert_eq!(out.len(), 8);
        // Even indices recover originals (positions 0, 1, 2, 3).
        assert!((out[0] - 0.0).abs() < 1e-6);
        assert!((out[2] - 1.0).abs() < 1e-6);
        assert!((out[4] - 0.0).abs() < 1e-6);
        assert!((out[6] - -1.0).abs() < 1e-6);
        // Odd indices interpolate midpoints (0.5, 0.5, -0.5).
        assert!((out[1] - 0.5).abs() < 1e-6);
        assert!((out[3] - 0.5).abs() < 1e-6);
        assert!((out[5] - -0.5).abs() < 1e-6);
        // Last odd index has no "next" sample — linear resamplers
        // typically hold the last value; we mirror that.
        assert!((out[7] - -1.0).abs() < 1e-6);
    }

    /// Tiny non-empty inputs must still produce ≥ 1 output sample.
    /// Without the `n_out.max(1)` clamp, a 1-sample input at 48 kHz
    /// → 16 kHz would round `n_out = 1 * 1/3 = 0.33 → 0` and hand
    /// back an empty buffer, which `Session::append_audio` surfaces
    /// as `EmptyInput` — degrading a degenerate-but-valid call into
    /// a confusing error several layers downstream.
    #[test]
    fn resample_linear_tiny_input_does_not_round_to_empty() {
        // 1 sample, 48 kHz → 16 kHz. Without the clamp, n_out = 0.
        let out = resample_linear(&[0.7], 48_000, 16_000);
        assert!(!out.is_empty(), "1 sample 48k → 16k should not be empty");
        assert_eq!(out.len(), 1);
        assert!((out[0] - 0.7).abs() < 1e-6);

        // 2 samples, 48 kHz → 16 kHz: n_out = round(2/3) = 1.
        // Different from the 1-sample case — clamp doesn't fire,
        // we get the natural rounded length.
        let out = resample_linear(&[0.5, 1.0], 48_000, 16_000);
        assert_eq!(out.len(), 1);
    }

    /// Output length scales by the rate ratio (within ±1 sample
    /// from rounding). 1 second of 44.1 kHz → ~16 000 samples at
    /// 16 kHz.
    #[test]
    fn resample_linear_output_length_matches_ratio() {
        let n_in = 44_100; // 1 s @ 44.1 kHz
        let input = vec![0.0; n_in];
        let out = resample_linear(&input, 44_100, 16_000);
        let expected = 16_000;
        let diff = (out.len() as i64 - expected as i64).abs();
        assert!(
            diff <= 1,
            "44.1k → 16k for {n_in} samples: got {} (expected {expected} ±1)",
            out.len()
        );
        // Spot-check 48 kHz → 16 kHz (exact 1/3 ratio).
        let n_in_48 = 48_000;
        let input48 = vec![0.0; n_in_48];
        let out48 = resample_linear(&input48, 48_000, 16_000);
        assert_eq!(out48.len(), 16_000);
    }
}