lean_ctx/core/config/

logic.rs

use std::path::Path;

#[allow(clippy::wildcard_imports)]
use super::*;
impl Config {
    /// Whether opt-in lossless JSON crushing of verbatim data commands (#936) is
    /// active. `LEAN_CTX_CRUSH_VERBATIM_JSON` (any value) wins, then the
    /// `crush_verbatim_json` config flag, else `false`.
    pub fn crush_verbatim_json_enabled(&self) -> bool {
        std::env::var("LEAN_CTX_CRUSH_VERBATIM_JSON").is_ok() || self.crush_verbatim_json
    }

    /// Effective proxy bind address (gateway mode, enterprise#8). Precedence:
    /// `LEAN_CTX_PROXY_BIND_HOST` env > `proxy_bind_host` config > loopback.
    /// The value must parse as an IP address; anything else (including a blank)
    /// resolves to `127.0.0.1` — a typo can only ever *narrow* exposure, never
    /// silently open the listener.
    #[must_use]
    pub fn resolved_proxy_bind_host(&self) -> std::net::IpAddr {
        let raw = std::env::var("LEAN_CTX_PROXY_BIND_HOST")
            .ok()
            .filter(|v| !v.trim().is_empty())
            .or_else(|| self.proxy_bind_host.clone());
        match raw.as_deref().map(str::trim) {
            Some(v) if !v.is_empty() => v.parse().unwrap_or_else(|_| {
                tracing::warn!(
                    "proxy_bind_host '{v}' is not a valid IP address — binding 127.0.0.1"
                );
                std::net::IpAddr::V4(std::net::Ipv4Addr::LOCALHOST)
            }),
            _ => std::net::IpAddr::V4(std::net::Ipv4Addr::LOCALHOST),
        }
    }

    /// Returns the effective rules scope, preferring env var over config file.
    pub fn rules_scope_effective(&self) -> RulesScope {
        let raw = std::env::var("LEAN_CTX_RULES_SCOPE")
            .ok()
            .or_else(|| self.rules_scope.clone())
            .unwrap_or_default();
        match raw.trim().to_lowercase().as_str() {
            "global" => RulesScope::Global,
            "project" => RulesScope::Project,
            _ => RulesScope::Both,
        }
    }

    /// Returns the effective rules injection mode, preferring env var over config.
    /// Default is `Shared` (zero-config discovery via a CLAUDE.md/CODEBUDDY.md/AGENTS.md block).
    pub fn rules_injection_effective(&self) -> RulesInjection {
        let raw = std::env::var("LEAN_CTX_RULES_INJECTION")
            .ok()
            .or_else(|| self.rules_injection.clone())
            .unwrap_or_default();
        match raw.trim().to_lowercase().as_str() {
            "dedicated" => RulesInjection::Dedicated,
            "off" | "none" | "disabled" => RulesInjection::Off,
            _ => RulesInjection::Shared,
        }
    }

    /// #1754: has the user declined lean-ctx steering their agent?
    ///
    /// `rules_injection = off` is the #1599 rule — off means off, on every
    /// channel, including text lean-ctx appends inside a tool result. Under
    /// `Off` such a reminder is also unclearable: `inject_all_rules`
    /// early-returns, and the `lean-ctx setup` it suggests removes the rules
    /// block rather than writing it, so the reminder returns next session.
    ///
    /// An explicit `setup.auto_inject_rules = false` says the same thing in the
    /// setup section. `None` (auto — rules simply not present yet) is not a
    /// refusal and still gets the reminder.
    #[must_use]
    pub fn declines_rule_steering(&self) -> bool {
        self.rules_injection_effective() == RulesInjection::Off
            || self.setup.auto_inject_rules == Some(false)
    }

    /// Provider prompt-cache hit rate for net-of-injection (#1104).
    /// Returns the configured value or None (caller picks the default).
    #[must_use]
    pub fn dashboard_cache_hit_rate(&self) -> Option<f64> {
        std::env::var("LEAN_CTX_CACHE_HIT_RATE")
            .ok()
            .and_then(|v| v.parse().ok())
            .or(self.dashboard_cache_hit_rate)
    }
    /// Returns the user-configured hook mode override, or `None` for auto-detect.
    /// Env var `LEAN_CTX_HOOK_MODE` takes priority over config.
    #[must_use]
    pub fn hook_mode_override(&self) -> Option<crate::core::hook_mode::HookMode> {
        let raw = std::env::var("LEAN_CTX_HOOK_MODE")
            .ok()
            .or_else(|| self.hook_mode.clone())?;
        crate::core::hook_mode::HookMode::from_str_loose(raw.trim())
    }

    /// Returns the effective permission-inheritance mode, preferring the
    /// `LEAN_CTX_PERMISSION_INHERITANCE` env var over config. Default is `Off`.
    /// Accepts `on`/`true`/`1` as enabled.
    #[must_use]
    pub fn permission_inheritance_effective(&self) -> PermissionInheritance {
        let raw = std::env::var("LEAN_CTX_PERMISSION_INHERITANCE")
            .ok()
            .or_else(|| self.permission_inheritance.clone())
            .unwrap_or_default();
        match raw.trim().to_lowercase().as_str() {
            "off" | "false" | "0" | "none" => PermissionInheritance::Off,
            // GH #1428: default to On so IDE permission rules (e.g. "rm *": "ask")
            // are honored by ctx_* tools out of the box. The check is read-only and
            // only activates when an IDE with a permission system is detected
            // (v1: OpenCode); undetected IDEs are always allowed through.
            _ => PermissionInheritance::On,
        }
    }

    /// True when lean-ctx should inject its rules via each agent's dedicated,
    /// non-polluting auto-load path *and* global rules are in scope.
    ///
    /// Gates the Claude/Codex `SessionStart` `additionalContext` summary: it
    /// stands in for the (now-skipped) shared CLAUDE.md/CODEBUDDY.md/AGENTS.md block, so it
    /// only fires when injection is `Dedicated` and the scope isn't project-only.
    #[must_use]
    pub fn dedicated_session_context_active(&self) -> bool {
        self.rules_injection_effective() == RulesInjection::Dedicated
            && self.rules_scope_effective() != RulesScope::Project
    }

    pub(super) fn parse_disabled_tools_env(val: &str) -> Vec<String> {
        val.split(',')
            .map(|s| s.trim().to_string())
            .filter(|s| !s.is_empty())
            .collect()
    }

    /// Returns the effective disabled tools list, preferring env var over config
    /// file. When `prefer_native_editor` is active, the lean-ctx edit tools are
    /// folded in so they are hidden from `list_tools` (#454).
    pub fn disabled_tools_effective(&self) -> Vec<String> {
        let mut list = if let Ok(val) = std::env::var("LEAN_CTX_DISABLED_TOOLS") {
            Self::parse_disabled_tools_env(&val)
        } else {
            self.disabled_tools.clone()
        };
        if self.prefer_native_editor_effective() {
            for name in EDIT_TOOL_NAMES {
                if !list.iter().any(|t| t == name) {
                    list.push((*name).to_string());
                }
            }
        }
        list
    }

    /// Whether lean-ctx edit operations are disabled in favour of the host's
    /// native editor (#454). `LEAN_CTX_PREFER_NATIVE_EDITOR` wins over config.
    pub fn prefer_native_editor_effective(&self) -> bool {
        match std::env::var("LEAN_CTX_PREFER_NATIVE_EDITOR") {
            Ok(raw) => matches!(
                raw.trim().to_lowercase().as_str(),
                "1" | "true" | "yes" | "on"
            ),
            Err(_) => self.prefer_native_editor,
        }
    }

    /// Cap on the rayon index-build worker threads. `LEANCTX_INDEX_THREADS` wins
    /// over config; `0` means "no cap" — rayon's all-cores default is kept.
    pub fn max_index_threads_effective(&self) -> usize {
        std::env::var("LEANCTX_INDEX_THREADS")
            .ok()
            .and_then(|raw| raw.trim().parse::<usize>().ok())
            .unwrap_or(self.max_index_threads)
    }

    /// Whether `name` is a lean-ctx edit operation that must be blocked from
    /// dispatch (direct and via `ctx_call`) when [`Self::prefer_native_editor_effective`]
    /// is set (#454). Read/search/shell/memory tools are never blocked.
    pub fn edit_tool_blocked(&self, name: &str) -> bool {
        self.prefer_native_editor_effective() && EDIT_TOOL_NAMES.contains(&name)
    }

    /// Returns `true` if minimal overhead is enabled via env var or config.
    pub fn minimal_overhead_effective(&self) -> bool {
        std::env::var("LEAN_CTX_MINIMAL").is_ok() || self.minimal_overhead
    }

    /// The `LEAN_CTX_MINIMAL` env var is the documented do-not-touch-anything
    /// escape hatch (3.9.19 triage incident): only IT may skip the pipeline's
    /// archive + ephemeral-firewall safety net. The `minimal_overhead` config
    /// key (default `true`) trims MCP instruction overhead only and must never
    /// disable archiving (#1540).
    pub fn minimal_escape_hatch() -> bool {
        std::env::var("LEAN_CTX_MINIMAL").is_ok()
    }

    /// Returns `true` if structure-first auto reads are enabled.
    ///
    /// The `LEAN_CTX_STRUCTURE_FIRST` env var wins over the config field, and
    /// accepts the usual truthy/falsy spellings so a harness can flip it per run
    /// (`LEAN_CTX_STRUCTURE_FIRST=0` forces it off even if config enables it).
    pub fn structure_first_effective(&self) -> bool {
        match std::env::var("LEAN_CTX_STRUCTURE_FIRST") {
            Ok(raw) => matches!(
                raw.trim().to_lowercase().as_str(),
                "1" | "true" | "yes" | "on"
            ),
            Err(_) => self.structure_first,
        }
    }

    /// Effective turn budget (fresh token limit per response). 0 = unlimited.
    pub fn turn_fresh_limit_effective(&self) -> usize {
        std::env::var("LEAN_CTX_TURN_FRESH_LIMIT")
            .ok()
            .and_then(|v| v.trim().parse().ok())
            .unwrap_or(self.turn_fresh_limit)
    }

    /// Effective turn budget for an explicitly verbatim response (#1582).
    ///
    /// 0 = unlimited. Never below `turn_fresh_limit_effective()`: raising the
    /// ordinary budget above the verbatim one must not make `raw=true` deliver
    /// *less* than a compressed read of the same file. An unlimited ordinary
    /// budget stays unlimited here.
    pub fn turn_fresh_limit_verbatim_effective(&self) -> usize {
        let ordinary = self.turn_fresh_limit_effective();
        if ordinary == 0 {
            return 0;
        }
        let verbatim = std::env::var("LEAN_CTX_TURN_FRESH_LIMIT_VERBATIM")
            .ok()
            .and_then(|v| v.trim().parse().ok())
            .unwrap_or(self.turn_fresh_limit_verbatim);
        resolve_verbatim_limit(ordinary, verbatim)
    }

    /// Whether progressive disclosure is active. Default true. The env var
    /// `LEAN_CTX_PROGRESSIVE_DISCLOSURE` overrides the config field.
    pub fn progressive_disclosure_effective(&self) -> bool {
        match std::env::var("LEAN_CTX_PROGRESSIVE_DISCLOSURE") {
            Ok(raw) => matches!(
                raw.trim().to_lowercase().as_str(),
                "1" | "true" | "yes" | "on"
            ),
            Err(_) => self.progressive_disclosure,
        }
    }

    /// Returns `true` if minimal overhead should be enabled for this MCP client.
    ///
    /// This is a superset of `minimal_overhead_effective()`:
    /// - `LEAN_CTX_OVERHEAD_MODE=minimal` forces minimal overhead
    /// - `LEAN_CTX_OVERHEAD_MODE=full` disables client/model heuristics (still honors LEAN_CTX_MINIMAL / config)
    /// - In auto mode (default), certain low-context clients/models are treated as minimal to prevent
    ///   large metadata blocks from destabilizing smaller context windows (e.g. Hermes + MiniMax).
    pub fn minimal_overhead_effective_for_client(&self, client_name: &str) -> bool {
        if let Ok(raw) = std::env::var("LEAN_CTX_OVERHEAD_MODE") {
            match raw.trim().to_lowercase().as_str() {
                "minimal" => return true,
                "full" => return self.minimal_overhead_effective(),
                _ => {}
            }
        }

        if self.minimal_overhead_effective() {
            return true;
        }

        let client_lower = client_name.trim().to_lowercase();
        if !client_lower.is_empty() {
            if let Ok(list) = std::env::var("LEAN_CTX_MINIMAL_CLIENTS") {
                for needle in list.split(',').map(|s| s.trim().to_lowercase()) {
                    if !needle.is_empty() && client_lower.contains(&needle) {
                        return true;
                    }
                }
            } else if client_lower.contains("hermes") || client_lower.contains("minimax") {
                return true;
            }
        }

        let model = std::env::var("LEAN_CTX_MODEL")
            .or_else(|_| std::env::var("LCTX_MODEL"))
            .unwrap_or_default();
        let model = model.trim().to_lowercase();
        if !model.is_empty() {
            let m = model.replace(['_', ' '], "-");
            if m.contains("minimax")
                || m.contains("mini-max")
                || m.contains("m2.7")
                || m.contains("m2-7")
            {
                return true;
            }
        }

        false
    }

    /// Returns `true` if shell hook injection is disabled via env var or config.
    pub fn shell_hook_disabled_effective(&self) -> bool {
        std::env::var("LEAN_CTX_NO_HOOK").is_ok() || self.shell_hook_disabled
    }

    /// Returns the effective shell activation mode (env var > config > default).
    pub fn shell_activation_effective(&self) -> ShellActivation {
        ShellActivation::effective(self)
    }

    /// Returns `true` if `ctx_shell` may accept shell file-write redirects.
    /// `LEAN_CTX_SHELL_ALLOW_WRITES` (`1`/`true`/`yes`/`on`) overrides
    /// `config.toml`. The real command gating still applies either way.
    pub fn shell_allow_writes_effective(&self) -> bool {
        match std::env::var("LEAN_CTX_SHELL_ALLOW_WRITES") {
            Ok(raw) => matches!(
                raw.trim().to_ascii_lowercase().as_str(),
                "1" | "true" | "yes" | "on"
            ),
            Err(_) => self.shell_allow_writes,
        }
    }

    /// Returns the effective paths where shell output capture may write.
    /// Empty configuration intentionally falls back to OS temp directories.
    pub fn shell_write_allow_paths_effective(&self) -> Vec<String> {
        if self.write_allow_paths.is_empty() {
            default_shell_write_allow_paths()
        } else {
            self.write_allow_paths.clone()
        }
    }

    /// #814: returns `true` if `ctx_shell` may accept inline interpreter scripts
    /// (`python3 -c "..."`, `node -e "..."`, etc.).
    /// `LEAN_CTX_SHELL_ALLOW_INLINE_SCRIPTS` (`1`/`true`/`yes`/`on`) overrides
    /// `config.toml`. The real command gating (allowlist) still applies.
    pub fn shell_allow_inline_scripts_effective(&self) -> bool {
        match std::env::var("LEAN_CTX_SHELL_ALLOW_INLINE_SCRIPTS") {
            Ok(raw) => matches!(
                raw.trim().to_ascii_lowercase().as_str(),
                "1" | "true" | "yes" | "on"
            ),
            Err(_) => self.shell_allow_inline_scripts,
        }
    }

    /// Returns `true` if the daily update check is disabled via env var or config.
    pub fn update_check_disabled_effective(&self) -> bool {
        std::env::var("LEAN_CTX_NO_UPDATE_CHECK").is_ok() || self.update_check_disabled
    }

    pub fn memory_policy_effective(&self) -> Result<MemoryPolicy, String> {
        let mut policy = self.memory.clone();
        policy.apply_env_overrides();

        let budget = self.max_disk_mb_effective();
        if budget > 0 {
            let scale_factor = (budget as f64 / 500.0).clamp(0.5, 10.0);
            let default_policy = MemoryPolicy::default();
            // Facts are not scaled: knowledge has no fact limit.
            if policy.knowledge.max_patterns == default_policy.knowledge.max_patterns {
                policy.knowledge.max_patterns = (50.0 * scale_factor) as usize;
            }
        }

        policy.validate()?;
        Ok(policy)
    }

    /// Returns the effective set of default tool categories.
    /// Priority: LCTX_DEFAULT_CATEGORIES env var > config.toml > hardcoded default.
    pub fn default_tool_categories_effective(&self) -> Vec<String> {
        if let Ok(val) = std::env::var("LCTX_DEFAULT_CATEGORIES") {
            return val
                .split(',')
                .map(|s| s.trim().to_lowercase())
                .filter(|s| !s.is_empty())
                .collect();
        }
        if !self.default_tool_categories.is_empty() {
            return self
                .default_tool_categories
                .iter()
                .map(|s| s.to_lowercase())
                .collect();
        }
        vec!["core".to_string()]
    }

    /// Returns the effective tool profile.
    /// Priority: LEAN_CTX_TOOL_PROFILE env > config tool_profile > config
    /// tools_enabled > active persona's tool surface > power.
    ///
    /// Explicit settings win (backward compatible); when none are set, the
    /// active persona supplies the tool surface (the `coding` default resolves
    /// to `power`, so existing installs are unaffected).
    pub fn tool_profile_effective(&self) -> super::tool_profiles::ToolProfile {
        super::persona::Persona::resolve(self).effective_tool_profile(self)
    }

    /// The `[sensitivity]` config with the active persona's floor folded in
    /// (persona-spec-v1). Enforcement chokepoints use this instead of the raw
    /// field so a persona like `lead-gen` (`sensitivity_floor = "confidential"`)
    /// protects PII out of the box. The `coding` default (`public`) passes the
    /// config through unchanged.
    #[must_use]
    pub fn sensitivity_effective(&self) -> crate::core::sensitivity::SensitivityConfig {
        self.sensitivity
            .clone()
            .with_persona_floor(super::persona::Persona::resolve(self).sensitivity_floor)
    }

    /// Returns `true` if all automatic read-mode degradation is disabled.
    /// Checks LCTX_NO_DEGRADE env var first, then config.toml field.
    pub fn no_degrade_effective(&self) -> bool {
        if let Ok(val) = std::env::var("LCTX_NO_DEGRADE") {
            return val == "1" || val.eq_ignore_ascii_case("true");
        }
        self.no_degrade
    }

    /// Returns `true` if explicit `full`/`lines:N-M` re-reads of
    /// cached-but-changed files should be served as deltas (`mode=diff`)
    /// instead of re-emitting full content.
    ///
    /// Checks the `LCTX_DELTA_EXPLICIT` env var first, then the config.toml
    /// field. Unlike a presence-only knob, an explicit `0`/`false` in the env
    /// forces the feature OFF even when the config field is `true`, so the env
    /// can fully override config in both directions.
    pub fn delta_explicit_effective(&self) -> bool {
        if let Ok(val) = std::env::var("LCTX_DELTA_EXPLICIT") {
            return val == "1" || val.eq_ignore_ascii_case("true");
        }
        self.delta_explicit
    }

    /// Effective max_disk_mb from env or config.
    pub fn max_disk_mb_effective(&self) -> u64 {
        std::env::var("LEAN_CTX_MAX_DISK_MB")
            .ok()
            .and_then(|v| v.parse().ok())
            .unwrap_or(self.max_disk_mb)
    }

    /// Effective per-process RSS target of a stdio MCP server (MB) from env or config.
    pub fn mcp_max_rss_mb_effective(&self) -> u64 {
        std::env::var("LEAN_CTX_MCP_MAX_RSS_MB")
            .ok()
            .and_then(|v| v.trim().parse().ok())
            .unwrap_or(self.mcp_max_rss_mb)
    }

    /// Effective process RSS target of the background daemon (MB) from env or config.
    pub fn daemon_max_rss_mb_effective(&self) -> u64 {
        std::env::var("LEAN_CTX_DAEMON_MAX_RSS_MB")
            .ok()
            .and_then(|v| v.trim().parse().ok())
            .unwrap_or(self.daemon_max_rss_mb)
    }

    /// Effective idle-exit window of a stdio MCP server (minutes, 0 = never).
    pub fn mcp_idle_exit_minutes_effective(&self) -> u64 {
        std::env::var("LEAN_CTX_MCP_IDLE_EXIT_MINUTES")
            .ok()
            .and_then(|v| v.trim().parse().ok())
            .unwrap_or(self.mcp_idle_exit_minutes)
    }

    /// Effective max_staleness_days from env or config.
    pub fn max_staleness_days_effective(&self) -> u32 {
        std::env::var("LEAN_CTX_MAX_STALENESS_DAYS")
            .ok()
            .and_then(|v| v.parse().ok())
            .unwrap_or(self.max_staleness_days)
    }

    /// Effective retention window for explicit session cleanup, independent of
    /// the archive staleness policy.
    pub fn session_retention_days_effective(&self) -> u32 {
        std::env::var("LEAN_CTX_SESSION_RETENTION_DAYS")
            .ok()
            .and_then(|value| value.parse().ok())
            .unwrap_or(self.session_retention_days)
    }

    /// Effective fixed-context budget (tokens) from env or config (#964). `0`
    /// (env or config) disables the warning; otherwise the per-session footprint
    /// is checked against this in `doctor overhead` and `gain`.
    pub fn context_budget_tokens_effective(&self) -> usize {
        std::env::var("LEAN_CTX_CONTEXT_BUDGET_TOKENS")
            .ok()
            .and_then(|v| v.parse().ok())
            .unwrap_or(self.context.budget_tokens)
    }

    /// Whether later tool calls may receive matching CCR context.
    pub fn proactive_expansion_effective(&self) -> bool {
        self.context.proactive_expansion
    }

    /// Per-response token budget for proactive CCR expansion.
    pub fn proactive_expansion_budget_tokens_effective(&self) -> usize {
        self.context.proactive_expansion_budget_tokens
    }

    /// Normalized BM25 score threshold for proactive CCR expansion.
    pub fn proactive_expansion_threshold_effective(&self) -> f64 {
        self.context.proactive_expansion_threshold
    }

    /// Maximum archive age considered for proactive expansion.
    pub fn proactive_expansion_max_age_secs_effective(&self) -> u64 {
        self.context.proactive_expansion_max_age_secs
    }

    /// Archive max_disk_mb derived from simplified max_disk_mb if the detail
    /// value is still at its default. Explicit overrides take priority.
    pub fn archive_max_disk_mb_effective(&self) -> u64 {
        let budget = self.max_disk_mb_effective();
        if budget > 0 && self.archive.max_disk_mb == ArchiveConfig::default().max_disk_mb {
            budget * 25 / 100
        } else {
            self.archive.max_disk_mb
        }
    }

    /// Archive max_age_hours derived from max_staleness_days if the detail
    /// value is still at its default. Explicit overrides take priority.
    pub fn archive_max_age_hours_effective(&self) -> u64 {
        let staleness = self.max_staleness_days_effective();
        if staleness > 0 && self.archive.max_age_hours == ArchiveConfig::default().max_age_hours {
            staleness as u64 * 24
        } else {
            self.archive.max_age_hours
        }
    }

    /// Effective on-disk ceiling (MB) of the Context Gateway evidence store
    /// (`<data>/gateway`: receipts, trace sidecars, observations, egress
    /// records). `0` means no ceiling. Retention keeps the store below it
    /// (`receipt_store::retention`); a new receipt is refused only while the
    /// store stays full (`receipt_store::capacity`, G09).
    ///
    /// Priority: `LEAN_CTX_GATEWAY_STORE_MAX_MB` › `max_disk_mb` budget (10%) ›
    /// `receipt_store::capacity::DEFAULT_STORE_MB`.
    /// Deliberately not a `[context_gateway]` key: that table is hashed into
    /// every receipt's policy digest, and a storage ceiling decides no
    /// admission.
    pub fn gateway_store_max_mb_effective(&self) -> u64 {
        if let Some(explicit) = std::env::var("LEAN_CTX_GATEWAY_STORE_MAX_MB")
            .ok()
            .and_then(|value| value.trim().parse().ok())
        {
            return explicit;
        }
        self.gateway_store_configured_mb()
    }

    /// [`Self::gateway_store_max_mb_effective`] without the environment
    /// override: what this configuration gives. Noted for the store on every
    /// load, because the store's writers must not load a configuration.
    pub(crate) fn gateway_store_configured_mb(&self) -> u64 {
        let budget = self.max_disk_mb_effective();
        if budget > 0 {
            return (budget * 10 / 100).max(1);
        }
        crate::core::context_admission::receipt_store::capacity::DEFAULT_STORE_MB
    }

    /// Effective on-disk ceiling (MB) for the persisted BM25 index. Single source
    /// of truth for `save`/`load`, `cache prune`, and the doctor health check.
    ///
    /// Priority: explicit `bm25_max_cache_mb` › `max_disk_mb` budget (10%) ›
    /// generous default ([`DEFAULT_BM25_PERSIST_MB`]). The default is decoupled
    /// from the RAM profile so large repos persist instead of rebuilding forever
    /// (issue #249).
    pub fn bm25_max_cache_mb_effective(&self) -> u64 {
        if self.bm25_max_cache_mb != serde_defaults::default_bm25_max_cache_mb() {
            return self.bm25_max_cache_mb;
        }
        let budget = self.max_disk_mb_effective();
        if budget > 0 {
            return budget * 10 / 100;
        }
        DEFAULT_BM25_PERSIST_MB
    }
}

impl Config {
    /// Safely mutate and persist the GLOBAL config. Reads the global file only
    /// (no project-local merge), applies `f`, then writes minimally. Refuses
    /// (returns `Err`) when the file exists but is unparseable, so a typo can
    /// never clobber a customized config (#443). Returns the saved `Config`.
    ///
    /// This is the canonical persistence entry point: prefer it over
    /// `Config::load()` followed by `save()`, which leaks project-local
    /// overrides into the global file.
    pub fn update_global<F>(f: F) -> std::result::Result<Self, super::error::LeanCtxError>
    where
        F: FnOnce(&mut Self),
    {
        Self::try_update_global(|config| {
            f(config);
            Ok(())
        })
    }

    /// Fallible mutation using the same preserving writer; refusal never saves.
    pub fn try_update_global<F>(f: F) -> std::result::Result<Self, super::error::LeanCtxError>
    where
        F: FnOnce(&mut Self) -> std::result::Result<(), super::error::LeanCtxError>,
    {
        let path = Self::path().ok_or_else(|| {
            super::error::LeanCtxError::Config("cannot determine home directory".into())
        })?;
        Self::try_update_global_at(&path, f)
    }

    /// Path-parameterized core of [`Config::update_global`], for tests.
    #[cfg(test)]
    pub(crate) fn update_global_at<F>(
        path: &Path,
        f: F,
    ) -> std::result::Result<Self, super::error::LeanCtxError>
    where
        F: FnOnce(&mut Self),
    {
        Self::try_update_global_at(path, |config| {
            f(config);
            Ok(())
        })
    }

    /// Runs the whole read-modify-write under one hold of the config write
    /// lock (LR-TEL-01).
    ///
    /// This function always loaded the global file straight from disk
    /// (`try_load_global_from` — no `Config::CACHE`, no project-local merge)
    /// and still does; that part is unchanged. What changed is that the load
    /// and the save now happen inside **one** critical section. Previously a
    /// concurrent writer could commit in the window between them and be
    /// overwritten by this call's save.
    ///
    /// `f` must be pure in-memory mutation. It runs while an OS file lock is
    /// held, so no network, no I/O, and no nested config write belongs inside
    /// it — the lock is not reentrant and the wait is bounded.
    fn try_update_global_at<F>(
        path: &Path,
        f: F,
    ) -> std::result::Result<Self, super::error::LeanCtxError>
    where
        F: FnOnce(&mut Self) -> std::result::Result<(), super::error::LeanCtxError>,
    {
        let guard = crate::config_io::ConfigWriteGuard::acquire(path)
            .map_err(super::error::LeanCtxError::Config)?;
        let mut cfg = Self::try_load_global_from(guard.path())?;
        f(&mut cfg)?;
        cfg.save_to_locked(&guard)?;
        Ok(cfg)
    }

    /// Persists the current config to the global config file.
    ///
    /// Preserves user comments, formatting, and unknown keys, keeps the file
    /// minimal (defaults that were never set on disk stay implicit), and writes
    /// atomically with a `.bak` backup so customizations are always recoverable.
    pub fn save(&self) -> std::result::Result<(), super::error::LeanCtxError> {
        let path = Self::path().ok_or_else(|| {
            super::error::LeanCtxError::Config("cannot determine home directory".into())
        })?;
        self.save_to(&path)
    }

    /// Path-parameterized core of [`Config::save`] (unit-testable).
    ///
    /// Takes the guard itself, then writes through the same guarded path as
    /// [`Self::save_to_locked`], so a standalone save and a save inside an
    /// update land on the identical resolved file.
    pub(super) fn save_to(
        &self,
        path: &Path,
    ) -> std::result::Result<(), super::error::LeanCtxError> {
        let guard = crate::config_io::ConfigWriteGuard::acquire(path)
            .map_err(super::error::LeanCtxError::Config)?;
        self.save_to_locked(&guard)
    }

    /// [`Self::save_to`] for callers already inside a critical section.
    ///
    /// Takes the guard by reference rather than a path: the destination is the
    /// guard's bound path, so a guarded save cannot be aimed at a file the
    /// guard is not excluding, and the non-reentrant lock is never acquired
    /// twice on one call path.
    pub(super) fn save_to_locked(
        &self,
        guard: &crate::config_io::ConfigWriteGuard,
    ) -> std::result::Result<(), super::error::LeanCtxError> {
        // A loaded config carries the managed overlay; the user's file keeps
        // the user's own values for the managed members.
        let unmanaged;
        let this = match crate::core::config::managed::current() {
            Some(managed) if managed.config.is_ok() => {
                let on_disk = Self::try_load_global_from(guard.path())
                    .map(|config| config.hive)
                    .unwrap_or_default();
                let mut copy = self.clone();
                managed.keep_user_values(&mut copy.hive, &on_disk);
                unmanaged = copy;
                &unmanaged
            }
            _ => self,
        };
        let (content, defaults) = this.render_for_save(guard.path())?;
        guard
            .write_toml_preserving_minimal(&content, &defaults)
            .map_err(super::error::LeanCtxError::Config)?;
        Ok(())
    }

    /// Renders `(content, defaults)` for the minimal-preserving writer and
    /// ensures the parent directory exists. Shared by both save entry points so
    /// they stay byte-identical in what they emit.
    fn render_for_save(
        &self,
        path: &Path,
    ) -> std::result::Result<(String, String), super::error::LeanCtxError> {
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent)?;
        }
        let content = toml::to_string_pretty(self)
            .map_err(|e| super::error::LeanCtxError::Config(e.to_string().into()))?;
        // Baseline = what loading an empty config yields. This honors serde's
        // field-level `#[serde(default)]` (which can diverge from the struct's
        // `Default` impl), so minimal mode skips exactly the keys that a fresh
        // load would produce — no spurious lines on save.
        let baseline = toml::from_str::<Self>("").unwrap_or_else(|_| Self::default());
        let defaults = toml::to_string_pretty(&baseline)
            .map_err(|e| super::error::LeanCtxError::Config(e.to_string().into()))?;
        Ok((content, defaults))
    }

    /// Formats the current config as a human-readable string with file paths.
    pub fn show(&self) -> String {
        let global_path = Self::path().map_or_else(
            || "~/.lean-ctx/config.toml".to_string(),
            |p| p.to_string_lossy().to_string(),
        );
        let content = toml::to_string_pretty(self).unwrap_or_default();
        let mut out = format!("Global config: {global_path}\n\n{content}");

        if let Some(root) = Self::find_project_root() {
            let local = Self::local_path(&root);
            if local.exists() {
                out.push_str(&format!("\n\nLocal config (merged): {}\n", local.display()));
            } else {
                out.push_str(&format!(
                    "\n\nLocal config: not found (create {} to override per-project)\n",
                    local.display()
                ));
            }
        }
        out
    }
}

/// Resolve the verbatim turn budget from the two configured limits (#1582).
///
/// Pure so the precedence rules are testable without touching process env:
/// `0` means unlimited, and the verbatim budget is never smaller than the
/// ordinary one.
fn resolve_verbatim_limit(ordinary: usize, verbatim: usize) -> usize {
    if verbatim == 0 {
        return 0;
    }
    verbatim.max(ordinary)
}

#[cfg(test)]
mod verbatim_budget_tests {
    use super::resolve_verbatim_limit;

    #[test]
    fn verbatim_budget_is_larger_than_the_ordinary_backstop() {
        assert_eq!(resolve_verbatim_limit(4096, 32_768), 32_768);
    }

    #[test]
    fn zero_means_unlimited_verbatim_reads() {
        assert_eq!(resolve_verbatim_limit(4096, 0), 0);
    }

    #[test]
    fn a_raised_ordinary_budget_is_never_undercut() {
        // Someone who sets turn_fresh_limit = 64k must not get *less* content
        // back from an explicit raw read than from a compressed one.
        assert_eq!(resolve_verbatim_limit(65_536, 32_768), 65_536);
    }
}