dirge-agent 0.21.3

use std::sync::LazyLock;
use std::time::Duration;

use regex::Regex;

/// B3-2: match an HTTP 5xx status anchored by a structural
/// HTTP-context marker. Avoids false-positives on bare 5xx-shaped
/// numbers in non-HTTP text (e.g. "processed 500 items"). Patterns
/// observed from real rig/reqwest errors:
///   "503 Service Unavailable"        — leading status + reason
///   "Http status: 500"               — status: prefix
///   "status=502"                     — status= prefix
///   "error 504: ..."                 — error prefix
///   "(status_code=500)"              — status_code= prefix
///   "code: 500"                      — bare code: prefix
///   "received http 500"              — http prefix
///   "5xx server error response"      — already lowercase
static STATUS_5XX_RE: LazyLock<Regex> = LazyLock::new(|| {
    Regex::new(
        r"(?x)
        (?:
            # prefix-anchored: status / code / error / http /
            # response / request / returned, with optional
            # `:`/`=`/`-`/whitespace between marker and number.
            (?:status(?:_code)?|code|error|http|response|request|returned|returns)
            \s*[:=\-]?\s*
            5\d{2}
            (?:\D|$)
        )
        |
        (?:
            # leading status + HTTP reason phrase (5xx Service / 5xx
            # Gateway / 5xx Internal / 5xx Bad / 5xx Server).
            (?:^|\D)
            5\d{2}
            \s+
            (?:service|gateway|internal|bad|server)
        )
        ",
    )
    .expect("static regex compiles")
});

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum ErrorKind {
    ContextLength,
    RateLimit,
    /// A rate-limit-shaped 429 whose quota won't reset within a window
    /// we're willing to wait out — a provider usage cap (e.g. Zhipu/GLM's
    /// "5-hour usage limit", error code 1308), or any 429 whose
    /// `Retry-After` exceeds [`MAX_IN_RUN_RETRY_WAIT`]. Split from
    /// [`RateLimit`] because retrying with the capped backoff just
    /// re-hits the cap (burning the retry budget and stalling the run for
    /// minutes before dying mid-task); the run should stop cleanly and
    /// resume after the quota resets instead. Non-retryable, like Auth.
    UsageCap,
    Network,
    Auth,
    Other,
}

/// A rate-limit whose server-requested wait is longer than this is
/// treated as an [`ErrorKind::UsageCap`] rather than a retryable
/// [`ErrorKind::RateLimit`]: our backoff caps at the same 5 minutes
/// (`backoff_duration_for_msg`), so retrying sooner than the server asked
/// just earns another 429. Matches that ceiling.
pub(crate) const MAX_IN_RUN_RETRY_WAIT: Duration = Duration::from_secs(300);

#[derive(Debug, Clone)]
pub struct RecoveryPolicy {
    max_retries: usize,
    backoff_base: Duration,
}

impl Default for RecoveryPolicy {
    fn default() -> Self {
        Self {
            // Transient provider blips ("error sending request", 5xx, rate
            // limits) are common enough that 3 retries (~7s of backoff)
            // still surfaced hard failures to the user. 5 retries with the
            // exponential schedule below waits ~1+2+4+8+16 ≈ 31s before
            // giving up, which rides out the typical short outage without
            // stalling the agent indefinitely.
            max_retries: 5,
            backoff_base: Duration::from_secs(1),
        }
    }
}

impl RecoveryPolicy {
    pub fn max_retries(&self) -> usize {
        self.max_retries
    }

    pub fn should_retry(&self, attempts: usize, kind: ErrorKind) -> bool {
        if attempts >= self.max_retries {
            return false;
        }
        matches!(kind, ErrorKind::Network | ErrorKind::RateLimit)
    }

    pub fn backoff_duration(&self, attempts: usize) -> Duration {
        let exp = 1u64 << attempts.min(6); // cap at 2^6 = 64s
        let base = self.backoff_base.as_millis() as u64;
        let ms = base.saturating_mul(exp);
        // Additive jitter up to +25% so concurrent agents don't retry in
        // lockstep against a rate-limited endpoint. Never shorter than the
        // policy minimum. Seeded from the system clock — pseudo-random is
        // sufficient here.
        let jitter = pseudo_random(attempts as u64) % (ms / 4).max(1);
        Duration::from_millis(ms.saturating_add(jitter))
    }

    /// F14: combine `backoff_duration` with the provider's
    /// requested `Retry-After`. Prefer whichever is longer (since
    /// retrying earlier than the server asked just earns another
    /// 429), but cap at 5 minutes so a misformatted header can't
    /// stall the agent forever.
    pub fn backoff_duration_for_msg(&self, attempts: usize, error_msg: &str) -> Duration {
        let computed = self.backoff_duration(attempts);
        match retry_after_from_error_msg(error_msg) {
            Some(server_wants) => {
                const CAP: Duration = Duration::from_secs(300);
                let chosen = server_wants.max(computed);
                if chosen > CAP { CAP } else { chosen }
            }
            None => computed,
        }
    }

    #[cfg(test)]
    pub(crate) fn with_backoff(max_retries: usize, backoff_base: Duration) -> Self {
        Self {
            max_retries,
            backoff_base,
        }
    }
}

/// Run an async operation under a [`RecoveryPolicy`], retrying transient
/// (network / rate-limit) failures with the policy's exponential
/// backoff. Auth / context-length / other failures bail immediately.
///
/// Single home for the attempt → classify → backoff → sleep loop that
/// `AnyModel::btw_query` and the summarizer each hand-rolled (dirge-6cvc).
/// `attempt` is invoked fresh on every try; `label` names the operation
/// in the retry log line. The error type only needs `Display` — the
/// message is what `classify_error` inspects.
///
/// NOTE: the backoff sleep here is not yet cancellation-aware; wiring an
/// abort signal through the (signal-less) call sites is tracked
/// separately. The streaming retry wrapper in `agent_loop::retry` is a
/// different shape (per-event commit tracking) and keeps its own loop.
pub async fn run_with_retry<T, E, F, Fut>(
    policy: &RecoveryPolicy,
    label: &str,
    mut attempt: F,
) -> Result<T, E>
where
    F: FnMut() -> Fut,
    Fut: std::future::Future<Output = Result<T, E>>,
    E: std::fmt::Display,
{
    let mut attempts = 0;
    loop {
        match attempt().await {
            Ok(value) => return Ok(value),
            Err(err) => {
                let msg = err.to_string();
                let kind = classify_error(&msg);
                if !policy.should_retry(attempts, kind) {
                    // Distinguish the two reasons `should_retry` says no.
                    // Reporting "non-retryable" for an exhausted budget
                    // reads as a classification bug when it isn't — the
                    // #718 log shows `error_kind=RateLimit` next to
                    // "non-retryable error", which is exactly backwards.
                    let exhausted = attempts >= policy.max_retries();
                    tracing::error!(
                        op = label,
                        error_kind = %format!("{:?}", kind),
                        attempts = attempts,
                        max = policy.max_retries(),
                        error = %msg,
                        "{}",
                        if exhausted {
                            "retry budget exhausted, bailing"
                        } else {
                            "non-retryable error, bailing"
                        }
                    );
                    return Err(err);
                }
                let delay = policy.backoff_duration_for_msg(attempts, &msg);
                tracing::warn!(
                    op = label,
                    attempt = attempts + 1,
                    max = policy.max_retries(),
                    delay_ms = delay.as_millis() as u64,
                    kind = ?kind,
                    error = %msg,
                    "retrying after transient failure",
                );
                tokio::time::sleep(delay).await;
                attempts += 1;
            }
        }
    }
}

/// Case-insensitive search for an ASCII `label`, returning its byte
/// offset in `msg`.
///
/// Deliberately NOT implemented as "lowercase the message, then index
/// back into the original": `to_lowercase` can change byte length for
/// some unicode (Turkish `İ` → `i̇` is 2 → 3 bytes), so the offsets
/// disagree and slicing the original could land mid-UTF-8 and panic.
/// Scanning the original bytes window-by-window with case-insensitive
/// ASCII comparison is sound because the label is fixed ASCII — and an
/// ASCII byte can never occur inside a multi-byte UTF-8 sequence, so a
/// match is always on a char boundary.
fn find_label_ci(msg: &str, label: &str) -> Option<usize> {
    let label_bytes = label.as_bytes();
    let msg_bytes = msg.as_bytes();
    if msg_bytes.len() < label_bytes.len() {
        return None;
    }
    (0..=msg_bytes.len() - label_bytes.len()).find(|&i| {
        msg_bytes[i..i + label_bytes.len()]
            .iter()
            .zip(label_bytes.iter())
            .all(|(a, b)| a.eq_ignore_ascii_case(b))
    })
}

/// Rate-limit facts recovered from a provider's 429 body.
///
/// GH #718: rig discards HTTP response headers (`non_success_status_error`
/// keeps only status + body text), so this parses the *body*. That covers
/// providers which echo their headers into the payload — OpenRouter nests
/// them under `error.metadata.headers`, Zhipu writes the reset into the
/// message prose. Providers that only ever send real headers (Anthropic,
/// OpenAI, Groq) are still parsed correctly here if the text ever reaches
/// us; making those headers visible at all is tracked separately.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct RateLimitSignal {
    /// How long until the exhausted window resets, when the provider said.
    pub reset_in: Option<Duration>,
    /// The provider reported zero remaining quota. This is the definitive
    /// bit: retrying before `reset_in` elapses *cannot* succeed, so the
    /// request is worth suppressing outright rather than spending.
    pub exhausted: bool,
    /// The window the provider named, e.g. `free-models-per-day`.
    pub scope: Option<String>,
}

/// Read the value following `label`. `reject_hyphen_suffix` keeps a lookup
/// for the generic `x-ratelimit-reset` from being satisfied by the longer
/// `x-ratelimit-reset-requests`; when set, a match followed by `-` is
/// skipped and the scan continues.
fn label_value(msg: &str, label: &str, reject_hyphen_suffix: bool) -> Option<String> {
    let mut from = 0usize;
    loop {
        if from >= msg.len() || !msg.is_char_boundary(from) {
            return None;
        }
        let idx = find_label_ci(&msg[from..], label)? + from;
        let after = idx + label.len();
        if !msg.is_char_boundary(after) {
            return None;
        }
        let rest = &msg[after..];
        if reject_hyphen_suffix && rest.starts_with('-') {
            // Advances by at least one byte every iteration (labels are
            // non-empty), so this terminates.
            from = after;
            continue;
        }
        let value: String = rest
            .trim_start_matches([':', '=', ' ', '\t', '"'])
            .chars()
            .take_while(|&c| !matches!(c, ',' | '"' | '}' | '\n' | '\r' | ';'))
            .collect();
        let value = value.trim();
        return (!value.is_empty()).then(|| value.to_string());
    }
}

/// Parse a Go-style duration — `1s`, `6m0s`, `2m59.56s`, `500ms`, `1h2m3s`.
/// OpenAI and Groq both report `x-ratelimit-reset-*` in this form. The
/// matches must tile the whole input so stray prose can't parse as a
/// duration.
fn parse_go_duration(raw: &str) -> Option<Duration> {
    static UNIT_RE: LazyLock<Regex> = LazyLock::new(|| {
        Regex::new(r"(?i)(\d+(?:\.\d+)?)(ms|h|m|s)").expect("static regex compiles")
    });
    let mut total_secs = 0f64;
    let mut consumed = 0usize;
    for caps in UNIT_RE.captures_iter(raw) {
        let whole = caps.get(0)?;
        // Any gap means the input isn't purely a duration.
        if whole.start() != consumed {
            return None;
        }
        consumed = whole.end();
        let value: f64 = caps[1].parse().ok()?;
        total_secs += match caps[2].to_ascii_lowercase().as_str() {
            "ms" => value / 1000.0,
            "s" => value,
            "m" => value * 60.0,
            "h" => value * 3600.0,
            _ => return None,
        };
    }
    if consumed == 0 || consumed != raw.len() {
        return None;
    }
    // Round to whole milliseconds — `from_secs_f64(7.66)` lands a few ns
    // short, which makes exact-value assertions (and log output) noisy.
    Some(Duration::from_millis(
        (total_secs * 1000.0).round().clamp(0.0, u64::MAX as f64) as u64,
    ))
}

/// Interpret a rate-limit reset value as a wait from now.
///
/// Providers disagree on the encoding, so discriminate by shape:
///   - Go duration (`6m0s`)            — OpenAI, Groq
///   - epoch milliseconds              — OpenRouter
///   - epoch seconds                   — common elsewhere
///   - a small integer                 — a relative second count
///   - RFC 3339 / RFC 2822 instant     — Anthropic
///
/// Absolute forms already in the past clamp to zero rather than wrapping,
/// so a stale or misconfigured value can't suppress a retry.
fn parse_reset_value(raw: &str) -> Option<Duration> {
    let raw = raw.trim().trim_matches('"').trim();
    if raw.is_empty() {
        return None;
    }

    // Checked before the numeric branch: a bare `500` is a count, but
    // `500ms` is a duration.
    if let Some(d) = parse_go_duration(raw) {
        return Some(d);
    }

    if raw.len() <= 20 && raw.chars().all(|c| c.is_ascii_digit()) {
        let n: u128 = raw.parse().ok()?;
        // Boundaries: 1e9 seconds ≈ 2001-09-09, and a *relative* wait of
        // 1e9 seconds would be 31 years — so anything at or above the
        // floor is an absolute timestamp, not a countdown.
        const EPOCH_SECS_FLOOR: u128 = 1_000_000_000;
        const EPOCH_MILLIS_FLOOR: u128 = 1_000_000_000_000;
        let target_ms = if n >= EPOCH_MILLIS_FLOOR {
            n
        } else if n >= EPOCH_SECS_FLOOR {
            n.saturating_mul(1_000)
        } else {
            return Some(Duration::from_secs(n.min(u64::MAX as u128) as u64));
        };
        let now_ms = chrono::Utc::now().timestamp_millis().max(0) as u128;
        return Some(Duration::from_millis(
            target_ms.saturating_sub(now_ms).min(u64::MAX as u128) as u64,
        ));
    }

    let parsed = chrono::DateTime::parse_from_rfc3339(raw)
        .ok()
        .or_else(|| chrono::DateTime::parse_from_rfc2822(raw).ok())?;
    let delta = parsed - chrono::Utc::now().fixed_offset();
    Some(Duration::from_secs(delta.num_seconds().max(0) as u64))
}

/// Extract whatever the provider told us about the rate limit it just
/// enforced. Never errors — an absent or unrecognized field simply stays
/// `None`/`false`, preserving the pre-#718 exponential-backoff behaviour.
pub fn rate_limit_signal(msg: &str) -> RateLimitSignal {
    // (remaining label, reset label, generic-form disambiguation needed)
    let mut dimensions: Vec<(String, String, bool)> = Vec::new();
    // OpenAI / Groq / OpenRouter family. The bare form is probed last and
    // must not be satisfied by one of the suffixed labels.
    for suffix in ["-requests", "-tokens", ""] {
        dimensions.push((
            format!("x-ratelimit-remaining{suffix}"),
            format!("x-ratelimit-reset{suffix}"),
            suffix.is_empty(),
        ));
    }
    // Anthropic puts the dimension in the middle of the label.
    for dim in ["requests", "tokens", "input-tokens", "output-tokens"] {
        dimensions.push((
            format!("anthropic-ratelimit-{dim}-remaining"),
            format!("anthropic-ratelimit-{dim}-reset"),
            false,
        ));
    }

    let mut exhausted = false;
    let mut exhausted_resets: Vec<Duration> = Vec::new();
    let mut any_resets: Vec<Duration> = Vec::new();

    for (remaining_label, reset_label, exact) in &dimensions {
        let remaining = label_value(msg, remaining_label, *exact)
            .and_then(|v| v.trim().trim_matches('"').parse::<u64>().ok());
        let reset = label_value(msg, reset_label, *exact).and_then(|v| parse_reset_value(&v));
        if let Some(r) = reset {
            any_resets.push(r);
        }
        if remaining == Some(0) {
            exhausted = true;
            if let Some(r) = reset {
                exhausted_resets.push(r);
            }
        }
    }

    // Prefer the dimension the provider actually ran out of: waiting on an
    // unrelated (possibly far longer) window would stall needlessly. When
    // several are empty, the latest reset is the one that unblocks us.
    let reset_in = if !exhausted_resets.is_empty() {
        exhausted_resets.into_iter().max()
    } else {
        any_resets.into_iter().max()
    };

    static SCOPE_RE: LazyLock<Regex> = LazyLock::new(|| {
        Regex::new(r"(?i)rate limit exceeded:\s*([A-Za-z0-9_-]+)").expect("static regex compiles")
    });
    let scope = SCOPE_RE
        .captures(msg)
        .and_then(|c| c.get(1))
        .map(|m| m.as_str().trim_end_matches('.').to_string());

    RateLimitSignal {
        reset_in,
        exhausted,
        scope,
    }
}

/// Parse a `Retry-After` value out of an error message. Looks for
/// (in order):
/// 1. Anthropic-style `retry-after-ms: <N>` — milliseconds.
/// 2. Standard `Retry-After: <N>` — seconds.
/// 3. JSON body `"retry_after": <N>` — seconds.
/// 4. RFC 7231 HTTP-date form.
/// 5. `X-RateLimit-Reset` and friends (GH #718).
///
/// An explicit `Retry-After` outranks a reset header: it is the provider's
/// direct instruction, whereas a reset is a window boundary we infer from.
///
/// Returns `None` if no recognized form is present. Robust to the
/// `:` being absent (some providers emit `retry-after 30`).
pub(crate) fn retry_after_from_error_msg(msg: &str) -> Option<Duration> {
    fn parse_after_label(msg: &str, label: &str) -> Option<u64> {
        let idx = find_label_ci(msg, label)?;
        // `idx` is a byte offset into the original `msg`, guaranteed to be
        // a char boundary by `find_label_ci`. Defend on the end offset
        // anyway — for ASCII labels it cannot land mid-sequence.
        let after = idx + label.len();
        if !msg.is_char_boundary(after) {
            return None;
        }
        let tail = &msg[after..];
        let tail = tail.trim_start_matches([':', ' ', '\t', '"']).trim_start();
        // Consume contiguous digits, with a hard cap so a malformed
        // header (`Retry-After: 999999999999999999999`) doesn't
        // produce a parsed integer that overflows or is absurdly
        // large before the 5-min cap applies in the caller. Cap at
        // 10^10 — any value larger is clearly bogus, and the cap
        // saturates rather than overflowing u64.
        let n: String = tail
            .chars()
            .take_while(|c| c.is_ascii_digit())
            .take(11)
            .collect();
        if n.is_empty() {
            return None;
        }
        n.parse().ok()
    }

    if let Some(ms) = parse_after_label(msg, "retry-after-ms") {
        return Some(Duration::from_millis(ms));
    }
    if let Some(secs) = parse_after_label(msg, "retry-after") {
        return Some(Duration::from_secs(secs));
    }
    if let Some(secs) = parse_after_label(msg, "retry_after") {
        return Some(Duration::from_secs(secs));
    }
    // RFC 7231 HTTP-date form: `Retry-After: Wed, 21 Oct 2015 07:28:00 GMT`.
    // Tried last so the numeric forms above (which are far more common)
    // hit their fast path before we incur a chrono parse. Past dates
    // clamp to zero so a misconfigured server doesn't suppress retries
    // by emitting a stale or epoch-zero header.
    if let Some(d) = parse_http_date_retry_after(msg) {
        return Some(d);
    }
    // GH #718: no `Retry-After` at all, but the provider told us when the
    // window resets. OpenRouter is the motivating case — it nests
    // `X-RateLimit-Reset` (epoch millis) inside the 429 body and sends no
    // `Retry-After`, so before this the backoff was a blind exponential
    // guess that expired before the window rolled.
    rate_limit_signal(msg).reset_in
}

/// Best-effort human-readable reset time for a usage-cap error, for
/// surfacing "resets at …" to the user. Recognizes an ISO-ish
/// `YYYY-MM-DD HH:MM[:SS]` timestamp anywhere in the message — the form
/// Zhipu/GLM emits ("您的限额将在 2026-07-18 07:41:55 重置" / "resets at …");
/// failing that, derives a relative hint from a `Retry-After` header.
/// `None` when neither is present.
pub fn usage_cap_reset_hint(msg: &str) -> Option<String> {
    static RESET_TS_RE: LazyLock<Regex> = LazyLock::new(|| {
        Regex::new(r"\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}(?::\d{2})?").expect("static regex compiles")
    });
    if let Some(m) = RESET_TS_RE.find(msg) {
        return Some(m.as_str().to_string());
    }
    let wait = retry_after_from_error_msg(msg)?;
    let secs = wait.as_secs();
    Some(if secs >= 3600 {
        format!("~{}h from now", secs / 3600)
    } else if secs >= 60 {
        format!("~{}m from now", secs / 60)
    } else {
        format!("~{secs}s from now")
    })
}

/// Scan `msg` for a `Retry-After:` header whose value parses as an
/// RFC 7231 HTTP-date (IMF-fixdate, RFC 850, or asctime form). Returns
/// the time from now until that date, clamped to 0 if in the past.
/// Returns `None` if no `Retry-After:` is present or the value isn't a
/// recognized date form (the numeric forms are handled by
/// `parse_after_label` above).
fn parse_http_date_retry_after(msg: &str) -> Option<Duration> {
    // PROV-10: case-insensitive byte-window scan rather than
    // lowercasing the whole message and indexing back into the
    // original. `to_ascii_lowercase` on the message preserves byte
    // length only for ASCII inputs; a unicode-bearing message could
    // shift offsets and panic on `&msg[after..]`. Mirror the pattern
    // used in `parse_after_label`.
    let label = "retry-after";
    let label_bytes = label.as_bytes();
    let msg_bytes = msg.as_bytes();
    if msg_bytes.len() < label_bytes.len() {
        return None;
    }
    let mut found = None;
    for i in 0..=msg_bytes.len() - label_bytes.len() {
        let window = &msg_bytes[i..i + label_bytes.len()];
        if window
            .iter()
            .zip(label_bytes.iter())
            .all(|(a, b)| a.eq_ignore_ascii_case(b))
        {
            found = Some(i);
            break;
        }
    }
    let idx = found?;
    let after = idx + label.len();
    if !msg.is_char_boundary(after) {
        return None;
    }
    let tail = &msg[after..];
    let tail = tail.trim_start_matches([':', ' ', '\t', '"']);
    let value: String = tail
        .chars()
        .take_while(|&c| c != '\n' && c != '\r' && c != '"')
        .collect();
    let value = value.trim();
    if value.is_empty() {
        return None;
    }
    // chrono accepts the three RFC 7231 date forms via DateTime::parse_from_rfc2822
    // (IMF-fixdate is rfc2822-compatible) and DateTime::parse_from_str for
    // asctime. Try both; ignore Err.
    let parsed = chrono::DateTime::parse_from_rfc2822(value)
        .ok()
        .or_else(|| {
            chrono::NaiveDateTime::parse_from_str(value, "%a %b %e %H:%M:%S %Y")
                .ok()
                .map(|n| n.and_utc().fixed_offset())
        })?;
    let now = chrono::Utc::now().fixed_offset();
    let delta = parsed - now;
    Some(Duration::from_secs(delta.num_seconds().max(0) as u64))
}

fn pseudo_random(salt: u64) -> u64 {
    // Audit L16: two callers that hit `pseudo_random` in the same
    // `subsec_nanos()` slot with the same `salt` (`attempts`)
    // previously produced identical jitter, defeating the
    // anti-thundering-herd purpose. The process-local counter below
    // makes every call within a process unique even when the wall
    // clock + salt collide.
    use std::sync::atomic::{AtomicU64, Ordering};
    static SEQ: AtomicU64 = AtomicU64::new(0);
    let seq = SEQ.fetch_add(1, Ordering::Relaxed);
    let nanos = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.subsec_nanos() as u64)
        .unwrap_or(0);
    // splitmix64 finalizer for decent dispersion
    let mut z = nanos
        .wrapping_add(salt)
        .wrapping_add(seq.wrapping_mul(0xA240_2A1F_1CE4_E5B9))
        .wrapping_add(0x9E37_79B9_7F4A_7C15);
    z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
    z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
    z ^ (z >> 31)
}

pub fn classify_error(msg: &str) -> ErrorKind {
    let lower = msg.to_lowercase();

    // Auth: HTTP status codes in error context
    if lower.contains(" 401 ")
        || lower.contains(" 403 ")
        || lower.contains("error 401")
        || lower.contains("error 403")
        || lower.starts_with("401 ")
        || lower.starts_with("403 ")
    {
        return ErrorKind::Auth;
    }

    if lower.contains("unauthorized")
        || lower.contains("invalid api key")
        || lower.contains("authentication failed")
    {
        return ErrorKind::Auth;
    }

    // PROV-8: OpenAI's `insufficient_quota` and the broader
    // billing-exhausted signal come through wrapped in a 429 but
    // are permanent failures (the user's billing account is
    // empty/suspended). Without this check we'd burn the full retry
    // budget on a request that will never succeed. Route to Auth so
    // the policy treats it as non-retryable.
    if lower.contains("insufficient_quota")
        || lower.contains("billing_not_active")
        || lower.contains("billing_hard_limit_reached")
    {
        return ErrorKind::Auth;
    }

    // Usage caps: rate-limit-shaped responses whose quota won't reset
    // within a retryable window. Zhipu/GLM returns HTTP 429 code 1308 with
    // a multi-hour reset ("已达到 5 小时的使用上限" — reached the 5-hour usage
    // limit); it contains "too many requests", so it MUST be caught before
    // the generic rate-limit arm below or it'd be retried futilely (the
    // reset is hours out; our backoff caps at 5 min — the run stalls
    // through its budget, then dies mid-task). Match the unambiguous cap
    // wording, not the 429 shell, so a momentary throttle stays retryable.
    if lower.contains("使用上限")            // Zhipu: "usage limit / ceiling"
        || lower.contains("usage limit")
        || lower.contains("usage cap")
        || lower.contains("daily limit")
        || lower.contains("quota exceeded")
        || lower.contains("code\":\"1308")   // Zhipu usage-cap error code
        || lower.contains("code\": \"1308")
    {
        return ErrorKind::UsageCap;
    }

    // Rate-limit-shaped 429s. PROV-7: Gemini emits `RESOURCE_EXHAUSTED`
    // bodies without the literal " 429 " / "rate limit" wording;
    // Anthropic's `overloaded_error` is a transient capacity signal
    // shaped like a rate-limit without that wording. All are transient —
    // retry with backoff — UNLESS the server's `Retry-After` is longer
    // than we'll wait (a usage cap in disguise; see below).
    let rate_limited = lower.contains("rate limit")
        || lower.contains("too many requests")
        || lower.contains(" 429 ")
        || lower.contains("error 429")
        || lower.starts_with("429 ")
        || lower.contains("resource_exhausted")
        || lower.contains("resource has been exhausted")
        || lower.contains("overloaded");
    if rate_limited {
        // A rate-limit whose requested wait exceeds our backoff ceiling
        // is effectively a usage cap: retrying at the capped delay just
        // re-hits it. Stop cleanly (UsageCap) rather than burning the
        // budget on retries that can't succeed.
        //
        // This is checked BEFORE the wording heuristic below: when the
        // provider gave us a hard number we trust it. A per-minute 429
        // whose body happens to mention a daily allowance stays a
        // retryable throttle, as it should.
        // A zero wait is NOT hard data — it means the reset we parsed has
        // already elapsed (a stale value, or the user's clock running
        // ahead of the provider's). Fall through to the wording heuristic
        // rather than declaring the window open on the strength of it.
        if let Some(wait) = retry_after_from_error_msg(msg).filter(|w| !w.is_zero()) {
            return if wait > MAX_IN_RUN_RETRY_WAIT {
                ErrorKind::UsageCap
            } else {
                ErrorKind::RateLimit
            };
        }
        // GH #718: no parseable reset, but the window the provider named
        // is a daily one — those reset hours out, well past anything we
        // would wait through. The list above ("daily limit", "usage
        // limit", "quota exceeded") missed OpenRouter's phrasing, so its
        // free-models-per-day 429 was retried like a transient blip.
        if lower.contains("per-day") || lower.contains("requests per day") {
            return ErrorKind::UsageCap;
        }
        return ErrorKind::RateLimit;
    }

    // B3-2 (audit fix): HTTP 5xx server errors. Previously only
    // 502/503/504 were caught and only when surrounded by spaces;
    // a bare 500 fell through to `Other` and the user saw a
    // one-shot failure on transient provider 5xx. Real-world rig/
    // reqwest errors come through in many shapes: "503 Service
    // Unavailable", "Http status: 500", "status=502", "error 504:
    // ...", "(status_code=500)". Match any 3-digit number starting
    // with 5 anywhere in the message, with a non-digit boundary on
    // BOTH sides so we don't false-positive on a 5xx-shaped
    // substring of a larger number (e.g. "request id 50012345").
    if STATUS_5XX_RE.is_match(&lower) {
        return ErrorKind::Network;
    }

    // Context-length indicators. Patterns collected from real
    // provider responses — each entry is a substring observed in
    // production from at least one provider (Anthropic, OpenAI,
    // Google, GLM, DeepSeek, Mistral, OpenRouter passthroughs).
    // Keep these substrings narrow enough to avoid colliding with
    // legitimate non-context-length errors that happen to mention
    // "tokens" or "long".
    if lower.contains("context_length_exceeded")
        || lower.contains("maximum context length")
        || lower.contains("reduce the length of the messages")
        || lower.contains("request too large")
        || lower.contains("prompt is too long")
        || lower.contains("input is too long")
        || lower.contains("input token count exceeds")
        || lower.contains("tokens exceed")
        || lower.contains("exceeds the model's context")
        // PROV-6: Anthropic `max_tokens is too large` (input + max_tokens > window);
        // Cohere/Mistral-via-OpenRouter `too many tokens`; DeepSeek
        // `Range of input length`; OpenRouter `messages.length too large`.
        || lower.contains("max_tokens is too large")
        || lower.contains("too many tokens")
        || lower.contains("range of input length")
        || lower.contains("messages.length too large")
    {
        return ErrorKind::ContextLength;
    }

    // HTML responses from intermediaries (Cloudflare 502/503,
    // nginx error pages, captive-portal interception). These never
    // parse as the JSON envelope rig/reqwest expect — without
    // detection they fell through to `Other` and the user saw a
    // one-shot opaque failure. Detect by leading HTML markers; the
    // status-text strings ("Bad Gateway", "Service Unavailable")
    // also appear in genuine JSON error bodies so we don't rely on
    // them alone.
    if lower.contains("<!doctype html")
        || lower.contains("<html")
        || lower.contains("bad gateway")
        || lower.contains("service unavailable")
        || lower.contains("gateway timeout")
        || lower.contains("cloudflare")
    {
        return ErrorKind::Network;
    }

    // Network errors — check for specific phrases (avoid "connection" false positive)
    if lower.contains("connection refused")
        || lower.contains("connection reset")
        || lower.contains("broken pipe")
        || lower.contains("dns error")
        || lower.contains("tls")
        || lower.contains("ssl")
        || lower.contains("timed out")
        || lower.contains("request timeout")
        || lower.contains("server error")
        // reqwest connect/send failures: the request never got a
        // response (connection refused/dropped, DNS, TCP connect, or
        // a mid-send drop). rig wraps these as "Http client error:
        // error sending request for url (…)". Transient — retry.
        || lower.contains("error sending request")
        || lower.contains("connect error")
        || lower.contains("tcp connect")
        // Mid-stream decode failures from reqwest/rig — the connection
        // returned bytes but they didn't deserialize into the expected
        // JSON envelope. Almost always transient (network blip,
        // truncated chunked response, provider hiccup), so it should
        // be retried like any other network error rather than surfacing
        // as a hard "Other" failure.
        || lower.contains("error decoding response body")
        || lower.contains("invalid response body")
        || lower.contains("decode error")
    {
        return ErrorKind::Network;
    }

    ErrorKind::Other
}

/// Map a raw error message to a one-line user-facing explanation
/// that names *what* failed and *what to try next*. Used by the agent
/// runner when surfacing errors to the chat — beats dumping a stack
/// of `CompletionError: ProviderError: Http client error: …` at the
/// user.
///
/// The original message is appended in parentheses as the cause so
/// the user (and any bug reports) still have the underlying details.
///
/// Transitional after phase 4.5h-6 cutover: no production caller
/// at the moment. The bridge could pretty-format Error events
/// using this when h-7 testing surfaces real provider error
/// shapes; until then keep the helper (and its tests) alive.
#[allow(dead_code)]
pub fn user_facing_error(msg: &str, attempts: usize) -> String {
    let kind = classify_error(msg);
    let lower = msg.to_lowercase();

    let (headline, hint) = match kind {
        ErrorKind::Auth => (
            "authentication failed talking to the LLM provider",
            "check your API key env var (e.g. OPENROUTER_API_KEY) and provider config",
        ),
        ErrorKind::RateLimit => (
            "provider rate-limited the request",
            "wait a moment and retry, or switch to a different model via /model",
        ),
        ErrorKind::UsageCap => (
            "provider usage cap reached — the quota won't reset within a retryable window",
            "wait for the quota to reset (see the reset time in the cause), then re-run to resume; or switch providers via /model",
        ),
        ErrorKind::ContextLength => (
            "conversation exceeds the model's context window",
            "run /compress to summarize older turns and try again",
        ),
        ErrorKind::Network if lower.contains("error decoding response body") => (
            "lost the response stream from the provider (truncated or malformed body)",
            "usually transient — retry. If it persists the provider may be having issues or returning non-JSON (HTML error pages, plaintext)",
        ),
        ErrorKind::Network => (
            "network error reaching the LLM provider",
            "check connectivity / firewall / proxy; the request will retry automatically",
        ),
        ErrorKind::Other => (
            "the LLM provider returned an error we didn't recognize",
            "see the cause below; consider /model to try a different provider",
        ),
    };

    let attempts_note = if attempts > 1 {
        format!(" (after {} attempt(s))", attempts)
    } else {
        String::new()
    };

    format!(
        "{}{}\n  ↳ hint: {}\n  ↳ cause: {}",
        headline, attempts_note, hint, msg
    )
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::sync::atomic::{AtomicUsize, Ordering};

    #[test]
    fn default_budget_retries_transient_failures_up_to_five_times() {
        let p = RecoveryPolicy::default();
        assert_eq!(p.max_retries(), 5);
        // A transient (network) error is retryable up to, but not past,
        // the budget.
        assert!(p.should_retry(0, ErrorKind::Network));
        assert!(p.should_retry(4, ErrorKind::Network));
        assert!(!p.should_retry(5, ErrorKind::Network));
        // Non-retryable kinds never retry, regardless of budget.
        assert!(!p.should_retry(0, ErrorKind::Auth));
    }

    // dirge-6cvc: the shared retry helper — success, immediate bail on a
    // non-retryable error, and retry-then-succeed on a transient one.
    #[tokio::test]
    async fn run_with_retry_returns_first_success() {
        let policy = RecoveryPolicy::default();
        let calls = AtomicUsize::new(0);
        let r: Result<u32, String> = run_with_retry(&policy, "t", || {
            calls.fetch_add(1, Ordering::SeqCst);
            async { Ok(7) }
        })
        .await;
        assert_eq!(r.unwrap(), 7);
        assert_eq!(calls.load(Ordering::SeqCst), 1, "no retry on success");
    }

    #[tokio::test]
    async fn run_with_retry_bails_immediately_on_non_retryable() {
        let policy = RecoveryPolicy::default();
        let calls = AtomicUsize::new(0);
        let r: Result<u32, String> = run_with_retry(&policy, "t", || {
            calls.fetch_add(1, Ordering::SeqCst);
            async { Err("invalid api key".to_string()) }
        })
        .await;
        assert!(r.is_err());
        assert_eq!(
            calls.load(Ordering::SeqCst),
            1,
            "auth error must not be retried"
        );
    }

    #[tokio::test]
    async fn run_with_retry_retries_transient_then_succeeds() {
        // Tiny backoff so the test doesn't actually wait seconds.
        let policy = RecoveryPolicy::with_backoff(3, Duration::from_millis(1));
        let calls = AtomicUsize::new(0);
        let r: Result<u32, String> = run_with_retry(&policy, "t", || {
            let n = calls.fetch_add(1, Ordering::SeqCst);
            async move {
                if n < 2 {
                    Err("rate limit exceeded".to_string())
                } else {
                    Ok(42)
                }
            }
        })
        .await;
        assert_eq!(r.unwrap(), 42);
        assert_eq!(calls.load(Ordering::SeqCst), 3, "two retries then success");
    }

    #[tokio::test]
    async fn run_with_retry_exhausts_then_returns_last_error() {
        let policy = RecoveryPolicy::with_backoff(2, Duration::from_millis(1));
        let calls = AtomicUsize::new(0);
        let r: Result<u32, String> = run_with_retry(&policy, "t", || {
            calls.fetch_add(1, Ordering::SeqCst);
            async { Err("rate limit exceeded".to_string()) }
        })
        .await;
        assert!(r.is_err());
        // initial attempt + 2 retries = 3 calls.
        assert_eq!(calls.load(Ordering::SeqCst), 3);
    }

    // dirge-5ul5: reqwest connect/send failures (the connection couldn't
    // be established or dropped before a response) surface as "error
    // sending request for url …" wrapped in rig's "Http client error".
    // These are transient and MUST be retried, not classified Other.
    #[test]
    fn classify_connect_send_failures_as_network() {
        for msg in [
            "ProviderError: Http client error: error sending request for url (https://api.deepseek.com/v1/chat/completions)",
            "error sending request for url (https://api.openai.com/v1/chat/completions)",
            "reqwest::Error { kind: Connect, ... }: tcp connect error",
            "Http client error: connect error",
        ] {
            assert_eq!(
                classify_error(msg),
                ErrorKind::Network,
                "connect/send failure must be retryable: {msg}"
            );
        }
        let policy = RecoveryPolicy::default();
        assert!(
            policy.should_retry(0, classify_error("error sending request for url (x)")),
            "the DeepSeek connect failure must be retried"
        );
    }

    #[test]
    fn test_classify_context_length() {
        assert_eq!(
            classify_error("context_length_exceeded: prompt too long"),
            ErrorKind::ContextLength
        );
        assert_eq!(
            classify_error("reduce the length of the messages"),
            ErrorKind::ContextLength
        );
        assert_eq!(
            classify_error("request too large for model"),
            ErrorKind::ContextLength
        );
    }

    /// Audit H1: the original `classify_error` recognized only 4
    /// substrings and missed common provider phrasings. Each entry
    /// below corresponds to a real error string a provider can emit.
    #[test]
    fn test_classify_context_length_provider_variants() {
        // Anthropic: hits when input + max_tokens > context window.
        assert_eq!(
            classify_error("prompt is too long: 250000 tokens > 200000 maximum"),
            ErrorKind::ContextLength
        );
        // OpenAI o-series + gpt-4o family.
        assert_eq!(
            classify_error(
                "This model's maximum context length is 128000 tokens. However, your messages resulted in 130000 tokens."
            ),
            ErrorKind::ContextLength
        );
        // Generic "input too long" wording used by several providers.
        assert_eq!(
            classify_error("input is too long for the requested model"),
            ErrorKind::ContextLength
        );
        // Google Gemini 1.x token-limit message.
        assert_eq!(
            classify_error("The input token count exceeds the maximum number of tokens allowed"),
            ErrorKind::ContextLength
        );
        // GLM / DeepSeek / Mistral all surface variants of "tokens exceed".
        assert_eq!(
            classify_error("Total tokens exceed model's context window"),
            ErrorKind::ContextLength
        );
        // OpenAI returns this when chat history exceeds context.
        assert_eq!(
            classify_error("the messages array exceeds the model's context length"),
            ErrorKind::ContextLength
        );
    }

    /// Audit H5: Cloudflare / nginx 502/503 pages and captive-portal
    /// interceptions arrive as HTML, not JSON. Without HTML-aware
    /// detection these fell through to `Other` (no retry); reclassify
    /// as `Network`.
    #[test]
    fn test_classify_html_proxy_response_as_network() {
        // Cloudflare 502 page snippet.
        assert_eq!(
            classify_error("<!DOCTYPE html><html><head><title>502 Bad Gateway</title>"),
            ErrorKind::Network
        );
        // nginx error page.
        assert_eq!(
            classify_error("<html><body><h1>503 Service Unavailable</h1></body></html>"),
            ErrorKind::Network
        );
        // Captive-portal interception (login page returned for the API URL).
        assert_eq!(
            classify_error("ProviderError: <html><head><meta http-equiv=\"refresh\""),
            ErrorKind::Network
        );
    }

    /// Audit H2: `Retry-After` may arrive as an HTTP-date per RFC 7231.
    /// Parser must accept this form and return a Duration in seconds
    /// from now (clamped to 0 if the date is in the past).
    #[test]
    fn retry_after_http_date_parses() {
        // Build a date ~30s in the future, then check we recover ~30s.
        let future = chrono::Utc::now() + chrono::Duration::seconds(30);
        // RFC 7231 IMF-fixdate format.
        let header = future.format("%a, %d %b %Y %H:%M:%S GMT").to_string();
        let msg = format!("429 Too Many Requests\nRetry-After: {}", header);
        let parsed = retry_after_from_error_msg(&msg).expect("HTTP-date should parse");
        let secs = parsed.as_secs();
        assert!(
            (25..=35).contains(&secs),
            "expected ~30s, got {}s (header={})",
            secs,
            header
        );
    }

    /// Past dates must clamp to 0 rather than wrapping. A misconfigured
    /// server occasionally returns `Retry-After: Thu, 01 Jan 1970 00:00:00 GMT`
    /// — we want to retry immediately, not panic or skip retries.
    #[test]
    fn retry_after_http_date_in_past_clamps_to_zero() {
        let msg = "Retry-After: Thu, 01 Jan 1970 00:00:00 GMT";
        let parsed = retry_after_from_error_msg(msg).expect("past HTTP-date should parse");
        assert_eq!(parsed, Duration::from_secs(0));
    }

    #[test]
    fn test_classify_network() {
        assert_eq!(classify_error("connection refused"), ErrorKind::Network);
        assert_eq!(
            classify_error("connection reset by peer"),
            ErrorKind::Network
        );
        assert_eq!(classify_error("request timed out"), ErrorKind::Network);
        // dirge-u44q: a request-establish timeout is a connection stall —
        // retryable so the loop reconnects.
        assert_eq!(
            classify_error(
                "request establish timed out after 300s — the connection/handshake stalled"
            ),
            ErrorKind::Network
        );
        assert_eq!(
            classify_error("503 service unavailable"),
            ErrorKind::Network
        );
        // Reqwest decode failure mid-stream — rig surfaces it as
        // `CompletionError: ProviderError: Http client error: error
        // decoding response body`. Should be retried like any other
        // transient network blip rather than surfacing as Other.
        assert_eq!(
            classify_error(
                "CompletionError: ProviderError: Http client error: error decoding response body"
            ),
            ErrorKind::Network
        );
        assert_eq!(classify_error("decode error: EOF"), ErrorKind::Network);

        // B3-2: 5xx variants beyond the previous strict set.
        // Plain 500 (was previously falling through to Other).
        assert_eq!(
            classify_error("500 Internal Server Error"),
            ErrorKind::Network
        );
        // Prefix-anchored forms.
        assert_eq!(classify_error("Http status: 500"), ErrorKind::Network);
        assert_eq!(classify_error("status=502"), ErrorKind::Network);
        assert_eq!(classify_error("status_code=503"), ErrorKind::Network);
        assert_eq!(classify_error("code: 504"), ErrorKind::Network);
        assert_eq!(
            classify_error("CompletionError: error 500: backend hiccup"),
            ErrorKind::Network
        );
        assert_eq!(
            classify_error("received http 502 from upstream"),
            ErrorKind::Network
        );
    }

    /// dirge-u6zc: Zhipu/GLM's 5-hour usage cap (HTTP 429, code 1308) is
    /// a UsageCap, not a retryable RateLimit — retrying just re-hits it.
    #[test]
    fn zhipu_usage_cap_1308_is_usage_cap_not_ratelimit() {
        let msg = r#"ProviderError: Invalid status code 429 Too Many Requests with message: {"error":{"code":"1308","message":"已达到 5 小时的使用上限。您的限额将在 2026-07-18 07:41:55 重置。"}}"#;
        assert_eq!(classify_error(msg), ErrorKind::UsageCap);
    }

    /// A rate-limit whose Retry-After exceeds our backoff ceiling is a
    /// usage cap in disguise — retrying at the capped delay can't succeed.
    #[test]
    fn long_retry_after_promotes_ratelimit_to_usage_cap() {
        assert_eq!(
            classify_error("429 Too Many Requests; Retry-After: 18000"),
            ErrorKind::UsageCap
        );
    }

    /// A short Retry-After stays a retryable RateLimit — a momentary
    /// throttle, not a cap.
    #[test]
    fn short_retry_after_stays_ratelimit() {
        assert_eq!(
            classify_error("429 Too Many Requests; Retry-After: 30"),
            ErrorKind::RateLimit
        );
    }

    /// A plain 429 with no cap signal and no long Retry-After stays a
    /// retryable RateLimit (regression guard for the common case).
    #[test]
    fn plain_429_without_cap_signal_stays_ratelimit() {
        assert_eq!(
            classify_error("HTTP 429 Too Many Requests"),
            ErrorKind::RateLimit
        );
        assert_eq!(classify_error("rate limit exceeded"), ErrorKind::RateLimit);
        assert_eq!(classify_error("overloaded_error"), ErrorKind::RateLimit);
    }

    /// UsageCap is non-retryable — the retry policy must not burn the
    /// budget on it.
    #[test]
    fn usage_cap_is_not_retryable() {
        let p = RecoveryPolicy::default();
        assert!(!p.should_retry(0, ErrorKind::UsageCap));
    }

    /// The reset hint pulls the Zhipu timestamp so the user knows when
    /// to resume; a Retry-After yields a relative hint.
    #[test]
    fn usage_cap_reset_hint_extracts_reset_time() {
        let zhipu = r#"{"code":"1308","message":"已达到 5 小时的使用上限。您的限额将在 2026-07-18 07:41:55 重置。"}"#;
        assert_eq!(
            usage_cap_reset_hint(zhipu).as_deref(),
            Some("2026-07-18 07:41:55")
        );
        assert_eq!(
            usage_cap_reset_hint("429; Retry-After: 18000").as_deref(),
            Some("~5h from now")
        );
        assert_eq!(
            usage_cap_reset_hint("plain error, no reset").as_deref(),
            None
        );
    }

    /// UsageCap gets its own user-facing headline distinct from RateLimit.
    #[test]
    fn user_facing_error_classifies_usage_cap() {
        let pretty = user_facing_error(
            r#"429 Too Many Requests {"code":"1308","message":"使用上限"}"#,
            2,
        );
        assert!(pretty.to_lowercase().contains("usage cap"));
        assert!(pretty.contains("cause:"));
    }

    /// `user_facing_error` produces a multi-line message with headline,
    /// hint, and cause. The cause must contain the original raw
    /// message so debug context isn't lost.
    #[test]
    fn user_facing_error_includes_cause() {
        let raw = "CompletionError: ProviderError: Http client error: error decoding response body";
        let pretty = user_facing_error(raw, 1);
        assert!(pretty.contains("lost the response stream"));
        assert!(pretty.contains("hint:"));
        assert!(pretty.contains("cause:"));
        assert!(pretty.contains(raw));
    }

    /// Auth errors get a distinct headline pointing at the API key.
    #[test]
    fn user_facing_error_classifies_auth() {
        let pretty = user_facing_error("401 unauthorized", 1);
        assert!(pretty.contains("authentication failed"));
        assert!(pretty.contains("API key"));
    }

    /// Context-length errors point at /compress.
    #[test]
    fn user_facing_error_classifies_context_length() {
        let pretty = user_facing_error("maximum context length exceeded", 1);
        assert!(pretty.contains("/compress"));
    }

    #[test]
    fn test_classify_rate_limit() {
        assert_eq!(classify_error("rate limit exceeded"), ErrorKind::RateLimit);
        assert_eq!(
            classify_error("429 too many requests"),
            ErrorKind::RateLimit
        );
    }

    /// Anthropic returns `{"type": "overloaded_error", ...}` when its
    /// service is at capacity. The body is structurally similar to a
    /// rate-limit (transient + retryable) but doesn't contain the
    /// "rate limit" / "too many" / "429" patterns. Without explicit
    /// handling it falls into `Other` and dirge doesn't retry —
    /// users see a one-shot failure on a transient backend issue.
    #[test]
    fn classify_anthropic_overloaded_error_as_retryable() {
        assert_eq!(
            classify_error("overloaded_error: Anthropic API is overloaded"),
            ErrorKind::RateLimit,
        );
        // Just the lowercase token is enough — provider stringifies
        // the structured error differently across rig versions.
        assert_eq!(
            classify_error("Provider overloaded; please retry later"),
            ErrorKind::RateLimit,
        );
    }

    #[test]
    fn test_classify_auth() {
        assert_eq!(classify_error("401 unauthorized"), ErrorKind::Auth);
        assert_eq!(classify_error("invalid api key"), ErrorKind::Auth);
    }

    #[test]
    fn test_classify_other() {
        assert_eq!(classify_error("something else"), ErrorKind::Other);
        assert_eq!(classify_error("file not found"), ErrorKind::Other);
        // "connection" alone should not trigger network
        assert_eq!(
            classify_error("database connection closed"),
            ErrorKind::Other
        );
        // "reset" alone should not trigger
        assert_eq!(classify_error("form reset successful"), ErrorKind::Other);
        // "500" in non-HTTP context should not trigger
        assert_eq!(classify_error("processed 500 items"), ErrorKind::Other);
    }

    #[test]
    fn test_retry_policy() {
        let policy = RecoveryPolicy::default();

        // Network errors are retryable up to the budget (5).
        assert!(policy.should_retry(0, ErrorKind::Network));
        assert!(policy.should_retry(2, ErrorKind::Network));
        assert!(policy.should_retry(4, ErrorKind::Network));
        assert!(!policy.should_retry(5, ErrorKind::Network));

        // Rate limits are retryable
        assert!(policy.should_retry(0, ErrorKind::RateLimit));

        // Context length is NOT retryable (needs compaction)
        assert!(!policy.should_retry(0, ErrorKind::ContextLength));

        // Auth is not retryable
        assert!(!policy.should_retry(0, ErrorKind::Auth));

        // Other is not retryable
        assert!(!policy.should_retry(0, ErrorKind::Other));
    }

    #[test]
    fn test_backoff_duration() {
        let policy = RecoveryPolicy::default();
        let d0 = policy.backoff_duration(0);
        let d1 = policy.backoff_duration(1);
        let d2 = policy.backoff_duration(2);

        assert!(d0 >= Duration::from_secs(1));
        assert!(d1 >= Duration::from_secs(2));
        assert!(d2 >= Duration::from_secs(4));
    }

    #[test]
    fn test_backoff_overflow_guard() {
        let policy = RecoveryPolicy::default();
        let d = policy.backoff_duration(20); // capped at attempts=6 via min()
        // 1s * 2^6 = 64s plus up to +25% jitter = 80s ceiling
        assert!(d >= Duration::from_secs(64));
        assert!(d < Duration::from_secs(81));
    }

    #[test]
    fn test_backoff_jitter_present() {
        let policy = RecoveryPolicy::default();
        // Repeated calls at the same attempt count should yield differing values
        // most of the time. Run a small batch and confirm we see at least two
        // distinct values — proves jitter is wired in.
        let mut seen = std::collections::HashSet::new();
        for _ in 0..8 {
            seen.insert(policy.backoff_duration(3));
            std::thread::sleep(Duration::from_millis(1));
        }
        assert!(
            seen.len() > 1,
            "expected jittered backoff to vary across calls"
        );
    }

    /// F14: Anthropic-style `retry-after-ms` parses as ms.
    #[test]
    fn retry_after_parses_anthropic_ms() {
        let msg = "rate limited: retry-after-ms: 5000";
        assert_eq!(
            retry_after_from_error_msg(msg),
            Some(Duration::from_millis(5000)),
        );
    }

    /// Standard HTTP `Retry-After: <seconds>` parses as seconds.
    #[test]
    fn retry_after_parses_standard_seconds() {
        let msg = "HTTP 429 Too Many Requests\nRetry-After: 30";
        assert_eq!(
            retry_after_from_error_msg(msg),
            Some(Duration::from_secs(30)),
        );
    }

    /// JSON body form: `"retry_after": 12`.
    #[test]
    fn retry_after_parses_json_body() {
        let msg = r#"{"error":"rate_limit","retry_after":12}"#;
        assert_eq!(
            retry_after_from_error_msg(msg),
            Some(Duration::from_secs(12)),
        );
    }

    /// Bare-without-colon variant (some proxies log `retry-after 30`).
    #[test]
    fn retry_after_parses_no_colon() {
        let msg = "got 429, retry-after 7 next time";
        assert_eq!(
            retry_after_from_error_msg(msg),
            Some(Duration::from_secs(7)),
        );
    }

    /// No retry-after present → None.
    #[test]
    fn retry_after_returns_none_when_absent() {
        let msg = "generic network error: connection reset";
        assert_eq!(retry_after_from_error_msg(msg), None);
    }

    /// Regression: messages with multi-byte UTF-8 BEFORE the label
    /// previously could panic — the original parser found the
    /// label in a lowercased copy and indexed into the original
    /// at that byte offset. `to_lowercase` can change byte length
    /// (Turkish `İ` is 2 bytes lowercase as `i̇` = 3 bytes), so
    /// the offsets disagreed and `&msg[idx + label.len()..]` could
    /// land mid-UTF-8 → panic. Now the search is on byte windows
    /// of the original string with case-insensitive ASCII compare.
    #[test]
    fn retry_after_handles_unicode_before_label() {
        // Provider error message with a Turkish capital I before
        // the label. Lowercasing produces a different byte length.
        let msg = "İoError: Retry-After: 8";
        assert_eq!(
            retry_after_from_error_msg(msg),
            Some(Duration::from_secs(8)),
        );
    }

    /// Case-insensitive matching against the label name itself.
    /// `RETRY-AFTER-MS` and `retry-after-ms` should both parse.
    #[test]
    fn retry_after_label_match_is_case_insensitive() {
        assert_eq!(
            retry_after_from_error_msg("rate limited: RETRY-AFTER-MS: 750"),
            Some(Duration::from_millis(750)),
        );
        assert_eq!(
            retry_after_from_error_msg("Retry-After-Ms: 750"),
            Some(Duration::from_millis(750)),
        );
    }

    /// Pathological huge digit run: cap at 11 digits before parse,
    /// so `Retry-After: 999999999999999999999...` doesn't overflow
    /// or produce a 100-year wait before the upper cap clamps.
    #[test]
    fn retry_after_caps_pathological_digit_run() {
        let msg = "Retry-After: 99999999999999999999999";
        let parsed = retry_after_from_error_msg(msg);
        // 11 digits = max ~10^11 seconds — `backoff_duration_for_msg`
        // will cap at 5 minutes, but the unsanitized parse must
        // produce SOMETHING (not None, not a panic). We don't pin
        // the exact value; just verify it's bounded by the cap
        // behavior in `backoff_duration_for_msg`.
        assert!(parsed.is_some(), "must parse, not return None");
        let policy = RecoveryPolicy::default();
        let d = policy.backoff_duration_for_msg(0, msg);
        assert!(
            d <= Duration::from_secs(300),
            "backoff must cap at 5min; got {:?}",
            d,
        );
    }

    /// `backoff_duration_for_msg` picks the longer of the
    /// computed exponential backoff and the server's retry-after,
    /// capped at 5 minutes.
    #[test]
    fn backoff_duration_for_msg_prefers_longer_value() {
        let policy = RecoveryPolicy::default();
        // attempts=0 → ~1s computed. retry-after=10s → 10s wins.
        let d = policy.backoff_duration_for_msg(0, "Retry-After: 10");
        assert!(d >= Duration::from_secs(10) && d < Duration::from_secs(11));

        // Server asks for ms below computed → computed wins.
        let d = policy.backoff_duration_for_msg(3, "retry-after-ms: 50");
        // 2^3 = 8s computed.
        assert!(d >= Duration::from_secs(8));
    }

    /// Cap retry-after at 5 minutes in case the header is bogus.
    #[test]
    fn backoff_duration_for_msg_caps_at_5_minutes() {
        let policy = RecoveryPolicy::default();
        let d = policy.backoff_duration_for_msg(0, "Retry-After: 9999");
        assert!(d <= Duration::from_secs(300));
    }

    // ---------------------------------------------------------------
    // GH #718 — rate-limit reset headers.
    //
    // rig discards response headers (`non_success_status_error` keeps
    // only status + body), so everything below is parsed out of the
    // error BODY text. Formats are drawn from each provider's docs:
    //   OpenRouter  X-RateLimit-Reset        epoch millis
    //   OpenAI      x-ratelimit-reset-*      Go duration ("6m0s")
    //   Groq        x-ratelimit-reset-*      Go duration ("2m59.56s")
    //   Anthropic   anthropic-ratelimit-*-reset  RFC 3339
    // ---------------------------------------------------------------

    /// Go/OpenAI/Groq duration strings.
    #[test]
    fn reset_value_parses_go_duration_strings() {
        for (raw, want_ms) in [
            ("1s", 1_000u64),
            ("6m0s", 360_000),
            ("7.66s", 7_660),
            ("2m59.56s", 179_560),
            ("1h2m3s", 3_723_000),
            ("500ms", 500),
        ] {
            assert_eq!(
                parse_reset_value(raw),
                Some(Duration::from_millis(want_ms)),
                "duration string {raw}",
            );
        }
    }

    /// Bare text that isn't a duration must not parse as one.
    #[test]
    fn reset_value_rejects_non_duration_text() {
        assert_eq!(parse_reset_value("soon"), None);
        assert_eq!(parse_reset_value(""), None);
        assert_eq!(parse_reset_value("12x"), None);
    }

    /// Epoch millis (OpenRouter) vs epoch seconds vs a relative count are
    /// told apart by magnitude.
    #[test]
    fn reset_value_discriminates_epoch_millis_seconds_and_relative() {
        let now = chrono::Utc::now();
        let in_90s = now + chrono::Duration::seconds(90);

        // Epoch millis — the OpenRouter form.
        let ms = in_90s.timestamp_millis().to_string();
        let d = parse_reset_value(&ms).expect("epoch millis parses");
        assert!(
            (85..=95).contains(&d.as_secs()),
            "epoch millis should yield ~90s, got {d:?}",
        );

        // Epoch seconds.
        let secs = in_90s.timestamp().to_string();
        let d = parse_reset_value(&secs).expect("epoch seconds parses");
        assert!(
            (85..=95).contains(&d.as_secs()),
            "epoch seconds should yield ~90s, got {d:?}",
        );

        // Small integer — a relative wait, not an epoch.
        assert_eq!(parse_reset_value("42"), Some(Duration::from_secs(42)));
    }

    /// A reset already in the past clamps to zero rather than wrapping.
    #[test]
    fn reset_value_in_the_past_clamps_to_zero() {
        let past = (chrono::Utc::now() - chrono::Duration::hours(1))
            .timestamp_millis()
            .to_string();
        assert_eq!(parse_reset_value(&past), Some(Duration::ZERO));
    }

    /// The reporter's verbatim OpenRouter per-minute 429 (GH #718).
    /// Reset 1785056700000 = 2026-07-26T09:05:00Z, ~42s after the log
    /// timestamp. Before the fix this parsed to `None` and the retry
    /// layer fell back to bare exponential backoff.
    #[test]
    fn openrouter_per_minute_429_yields_reset_and_exhaustion() {
        let msg = r#"Invalid status code 429 Too Many Requests with message: {"error":{"message":"Rate limit exceeded: free-models-per-min. ","code":429,"metadata":{"headers":{"X-RateLimit-Limit":"20","X-RateLimit-Remaining":"0","X-RateLimit-Reset":"1785056700000"},"provider_name":null}},"user_id":"<redacted>"}"#;
        let sig = rate_limit_signal(msg);
        assert!(
            sig.exhausted,
            "X-RateLimit-Remaining: 0 is a definitive exhaustion signal",
        );
        assert_eq!(sig.scope.as_deref(), Some("free-models-per-min"));
        assert!(sig.reset_in.is_some(), "X-RateLimit-Reset must parse");
        // The log is from 2026 so the absolute reset is long past now;
        // what matters is that it parsed and clamped rather than
        // returning None.
        assert!(retry_after_from_error_msg(msg).is_some());
    }

    /// The reporter's verbatim OpenRouter per-DAY 429. The reset is
    /// ~14.9h out, so this must classify as a non-retryable UsageCap —
    /// retrying at the 5-minute backoff ceiling can never succeed.
    #[test]
    fn openrouter_per_day_429_is_a_usage_cap_not_a_retryable_ratelimit() {
        // Reset far in the future so the assertion holds regardless of
        // when the suite runs.
        let reset = (chrono::Utc::now() + chrono::Duration::hours(14)).timestamp_millis();
        let msg = format!(
            r#"Invalid status code 429 Too Many Requests with message: {{"error":{{"message":"Rate limit exceeded: free-models-per-day. Add 10 credits to unlock 1000 free model requests per day","code":429,"metadata":{{"headers":{{"X-RateLimit-Limit":"50","X-RateLimit-Remaining":"0","X-RateLimit-Reset":"{reset}"}},"provider_name":null}}}},"user_id":"<redacted>"}}"#
        );
        assert_eq!(
            classify_error(&msg),
            ErrorKind::UsageCap,
            "a 14h reset must not be retried like a transient throttle",
        );
        let p = RecoveryPolicy::default();
        assert!(!p.should_retry(0, classify_error(&msg)));
    }

    /// Even with the reset stripped out, the "per day" wording alone is
    /// enough to recognise a cap — the old substring list only knew
    /// "daily limit" and missed OpenRouter's phrasing entirely.
    #[test]
    fn per_day_wording_alone_is_a_usage_cap() {
        assert_eq!(
            classify_error("429 Too Many Requests: Rate limit exceeded: free-models-per-day."),
            ErrorKind::UsageCap,
        );
        assert_eq!(
            classify_error("HTTP 429 Too Many Requests: you have exceeded your requests per day"),
            ErrorKind::UsageCap,
        );
    }

    /// A per-MINUTE window stays a retryable RateLimit, and the backoff
    /// becomes the server's actual reset instead of the exponential
    /// guess. This is the fix for the reporter's first symptom: one
    /// 42s wait instead of five doomed attempts over ~31s.
    #[test]
    fn per_minute_reset_drives_the_backoff_and_stays_retryable() {
        let reset = (chrono::Utc::now() + chrono::Duration::seconds(42)).timestamp_millis();
        let msg = format!(
            r#"429 Too Many Requests {{"message":"Rate limit exceeded: free-models-per-min. ","metadata":{{"headers":{{"X-RateLimit-Limit":"20","X-RateLimit-Remaining":"0","X-RateLimit-Reset":"{reset}"}}}}}}"#
        );
        assert_eq!(classify_error(&msg), ErrorKind::RateLimit);
        let p = RecoveryPolicy::default();
        // attempts=0 would otherwise give ~1s; the reset must win.
        let d = p.backoff_duration_for_msg(0, &msg);
        assert!(
            d >= Duration::from_secs(38) && d <= Duration::from_secs(45),
            "backoff should track the ~42s reset, got {d:?}",
        );
    }

    /// OpenAI / Groq split the reset per dimension. When only ONE
    /// dimension is exhausted, wait for that dimension — not the other,
    /// unrelated (possibly much longer) window.
    #[test]
    fn per_dimension_reset_pairs_with_the_exhausted_dimension() {
        // Requests exhausted (reset 3s), tokens fine (reset 6m0s).
        let msg = "429 Too Many Requests\n\
             x-ratelimit-remaining-requests: 0\n\
             x-ratelimit-reset-requests: 3s\n\
             x-ratelimit-remaining-tokens: 149984\n\
             x-ratelimit-reset-tokens: 6m0s";
        let sig = rate_limit_signal(msg);
        assert!(sig.exhausted);
        assert_eq!(
            sig.reset_in,
            Some(Duration::from_secs(3)),
            "must wait on the exhausted dimension, not the healthy one",
        );
    }

    /// Both dimensions exhausted → wait for the later of the two, since
    /// retrying while either is still empty just earns another 429.
    #[test]
    fn both_dimensions_exhausted_waits_for_the_later_reset() {
        let msg = "429\n\
             x-ratelimit-remaining-requests: 0\n\
             x-ratelimit-reset-requests: 3s\n\
             x-ratelimit-remaining-tokens: 0\n\
             x-ratelimit-reset-tokens: 45s";
        assert_eq!(
            rate_limit_signal(msg).reset_in,
            Some(Duration::from_secs(45))
        );
    }

    /// The generic `x-ratelimit-reset` lookup must not be satisfied by
    /// the longer `x-ratelimit-reset-requests` label.
    #[test]
    fn generic_reset_label_does_not_swallow_the_suffixed_one() {
        let msg = "429 x-ratelimit-reset-tokens: 90s";
        let sig = rate_limit_signal(msg);
        assert_eq!(sig.reset_in, Some(Duration::from_secs(90)));
        // No bare `x-ratelimit-reset:` present, so nothing should have
        // matched a truncated prefix and produced a different value.
        assert!(!sig.exhausted, "no remaining:0 was reported");
    }

    /// Anthropic publishes resets as RFC 3339 instants.
    #[test]
    fn anthropic_rfc3339_reset_headers_parse() {
        let reset = (chrono::Utc::now() + chrono::Duration::seconds(25)).to_rfc3339();
        let msg = format!(
            "429 Too Many Requests\n\
             anthropic-ratelimit-requests-remaining: 0\n\
             anthropic-ratelimit-requests-reset: {reset}"
        );
        let sig = rate_limit_signal(&msg);
        assert!(sig.exhausted);
        let d = sig.reset_in.expect("RFC 3339 reset parses");
        assert!((20..=30).contains(&d.as_secs()), "expected ~25s, got {d:?}",);
    }

    /// An explicit `Retry-After` still outranks the reset headers — it is
    /// the provider's direct instruction, whereas a reset is the window
    /// boundary we infer from.
    #[test]
    fn retry_after_takes_priority_over_ratelimit_reset() {
        let msg = "429; Retry-After: 7; x-ratelimit-reset: 300s";
        assert_eq!(
            retry_after_from_error_msg(msg),
            Some(Duration::from_secs(7)),
        );
    }

    /// A reset that has already elapsed (stale value, or the local clock
    /// running ahead of the provider's) must not be read as "the window is
    /// open" — that would let a daily cap through as a retryable throttle.
    /// The wording heuristic still catches it.
    #[test]
    fn an_already_elapsed_reset_falls_through_to_the_wording_heuristic() {
        let past = (chrono::Utc::now() - chrono::Duration::hours(1)).timestamp_millis();
        let msg = format!(
            r#"429 Too Many Requests {{"message":"Rate limit exceeded: free-models-per-day.","metadata":{{"headers":{{"X-RateLimit-Remaining":"0","X-RateLimit-Reset":"{past}"}}}}}}"#
        );
        assert_eq!(classify_error(&msg), ErrorKind::UsageCap);
    }

    /// ...but an elapsed reset on a per-MINUTE window still stays
    /// retryable — the window really has rolled, so retrying is right.
    #[test]
    fn an_elapsed_reset_on_a_short_window_stays_retryable() {
        let past = (chrono::Utc::now() - chrono::Duration::minutes(5)).timestamp_millis();
        let msg = format!(
            r#"429 Too Many Requests {{"message":"Rate limit exceeded: free-models-per-min.","metadata":{{"headers":{{"X-RateLimit-Remaining":"0","X-RateLimit-Reset":"{past}"}}}}}}"#
        );
        assert_eq!(classify_error(&msg), ErrorKind::RateLimit);
        // And the backoff falls back to the exponential schedule rather
        // than retrying instantly on a zero wait.
        let d = RecoveryPolicy::default().backoff_duration_for_msg(0, &msg);
        assert!(d >= Duration::from_secs(1), "got {d:?}");
    }

    /// A 429 with no reset information at all keeps the old behaviour:
    /// retryable, exponential backoff, nothing invented.
    #[test]
    fn bare_429_without_reset_info_is_unchanged() {
        let sig = rate_limit_signal("HTTP 429 Too Many Requests");
        assert!(!sig.exhausted);
        assert_eq!(sig.reset_in, None);
        assert_eq!(
            classify_error("HTTP 429 Too Many Requests"),
            ErrorKind::RateLimit
        );
    }

    /// A non-rate-limit message must not yield a signal — the extractor
    /// is only consulted for 429-shaped errors, but keep it honest.
    #[test]
    fn unrelated_error_yields_no_rate_limit_signal() {
        let sig = rate_limit_signal("connection reset by peer");
        assert!(!sig.exhausted);
        assert_eq!(sig.reset_in, None);
        assert_eq!(sig.scope, None);
    }

    /// `remaining: 0` with no parseable reset is still a definitive
    /// "this attempt cannot succeed" — the gate needs to know that even
    /// when it can't compute a deadline.
    #[test]
    fn exhaustion_is_reported_even_without_a_parseable_reset() {
        let sig = rate_limit_signal(r#"429 {"X-RateLimit-Remaining":"0"}"#);
        assert!(sig.exhausted);
        assert_eq!(sig.reset_in, None);
    }
}