Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
321 KB
Raw Blame
//! Runtime configuration loader.
//!
//! All settings are read exactly once at startup, merged into a single
//! immutable [`Config`] value, and passed by reference everywhere. There is
//! no second read path (lesson from agentmemory #456 / #469 — the dimension
//! guard read `process.env` while the rest of the codebase used
//! `getMergedEnv()`, masking the bug for weeks).

use std::collections::{BTreeMap, HashSet};
use std::ffi::OsString;
use std::path::{Path, PathBuf};
use std::sync::Arc;

use ai_memory_llm::{
    AuthRequirement, CURSOR_DEFAULT_MODEL, Candidate, CursorAuth, EmbedderChoice, EmbedderConfig,
    ExtraHeaders, FallbackLlmProvider, LlmError, LlmProvider, LlmResult, OPENCODE_DEFAULT_MODEL,
    ProviderAuth, ProviderChoice, ProviderConfig, ReasoningEffort, build_provider,
    cursor_executable,
};
use anyhow::{Context, Result};
use figment::{
    Figment,
    providers::{Env, Format, Serialized, Toml},
};
use secrecy::{ExposeSecret, SecretString};
use serde::{Deserialize, Serialize};

/// Default HTTP bind address for the local single-user server.
pub const DEFAULT_BIND: &str = "127.0.0.1:49374";

/// Default idle time (seconds) before TCP keepalive probes start on an
/// accepted `serve` connection. Conservative: long enough to never fire on a
/// live, merely-quiet MCP/hook connection, short enough that a dead peer's
/// fd is reclaimed in minutes rather than the OS default of ~2 hours (#792).
pub const DEFAULT_TCP_KEEPALIVE_SECS: u64 = 60;

/// Default base URL used by thin-client CLI subcommands.
pub const DEFAULT_SERVER_URL: &str = "http://127.0.0.1:49374";

/// Default number of failed hook-spool drain passes before dropping an event.
pub const DEFAULT_HOOK_SPOOL_MAX_ATTEMPTS: u32 = 8;

/// Placeholder credential that lets `Config::load` validate a fallback
/// profile whose `api_key_env` is absent from this process. Never reaches a
/// provider: the config built from it is discarded (#762).
const UNRESOLVED_FALLBACK_KEY: &str = "unresolved-llm-fallback-credential";

/// Default MCP endpoint URL rendered for client integrations.
pub const DEFAULT_MCP_URL: &str = "http://127.0.0.1:49374/mcp";

/// Default confidence floor for staged auto-improvement proposals.
pub const DEFAULT_AUTO_IMPROVE_MIN_CONFIDENCE: f32 =
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MIN_CONFIDENCE;

/// Default workspace name used by the single-workspace v1 flow.
pub const DEFAULT_WORKSPACE: &str = ai_memory_core::DEFAULT_WORKSPACE_NAME;

/// Defensive project fallback used only when no cwd/project is available.
pub const DEFAULT_PROJECT: &str = ai_memory_core::DEFAULT_PROJECT_NAME;

/// Optional per-tier retention half-lives, expressed in **days**.
///
/// This is the operator-facing `[decay.half_life_days]` sub-table. Half-life in
/// days is the intuitive knob ("episodic pages: a 180-day half-life"); it is
/// converted to the internal per-day decay rate λ (`λ = ln(2) / days`) in
/// [`DecaySettings::decay_params`]. Every key is optional: an omitted key falls
/// back to the scalar `lambda`, so the default (all keys unset) reproduces
/// today's single-λ behaviour byte-for-byte and no upgrade changes a score.
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
#[serde(default)]
pub struct DecayHalfLifeDays {
    /// Half-life in days for `working`-tier pages; unset uses the scalar λ.
    pub working: Option<f64>,
    /// Half-life in days for `episodic`-tier pages; unset uses the scalar λ.
    pub episodic: Option<f64>,
    /// Half-life in days for `semantic`-tier pages; unset uses the scalar λ.
    pub semantic: Option<f64>,
    /// Half-life in days for `procedural`-tier pages; unset uses the scalar λ.
    pub procedural: Option<f64>,
}

/// Config-file representation of retention settings.
///
/// The breadth coefficient lives here rather than expanding the public
/// `ai_memory_store::DecayParams` struct, preserving source compatibility for
/// downstream Rust callers that construct that struct directly.
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
#[serde(default)]
pub struct DecaySettings {
    /// Per-day decay rate.
    pub lambda: f64,
    /// Access-reinforcement magnitude.
    pub sigma: f64,
    /// Per-day decay of access reinforcement.
    pub mu: f64,
    /// Default page salience.
    pub salience_default: f64,
    /// Wiki-backed eviction threshold.
    pub cold_threshold: f64,
    /// Grace period before permanently deleting an evicted version chain.
    pub hard_delete_after_days: i64,
    /// Optional weight for the number of distinct authenticated readers.
    pub breadth_weight: f64,
    /// Age past which a consolidated session's raw observations may be pruned.
    /// `0` disables the pass; nothing is deleted until an operator opts in.
    pub observation_retention_days: i64,
    /// Observation rows deleted per prune transaction.
    pub observation_prune_batch: usize,
    /// Age, in whole UTC calendar months after a month ends, past which the
    /// forget sweep deletes that month's hook event ledger
    /// (`log-YYYY-MM.md`). `0` disables the pass; nothing is deleted until an
    /// operator opts in. The current and the previous month are never deleted.
    pub ledger_retention_months: i64,
    /// A2 extractive tier-down (`[decay] compact_cold_episodic`). When `true`,
    /// the forget sweep COMPACTS a cold episodic page — keeping its L0 abstract,
    /// an L1 summary and the L2 keep-token set, dropping the prose — instead of
    /// evicting it. Reversible (the full body stays in git + the supersession
    /// chain) and non-destructive. Defaults to `false`, so an upgrade changes
    /// nothing until an operator opts in.
    pub compact_cold_episodic: bool,
    /// A3 cold-cluster dedup (`[decay] dedup_cold_clusters`). When `true` AND an
    /// embedder is configured, the forget sweep clusters near-duplicate cold
    /// episodic pages by embedding (cosine DBSCAN, adaptive eps) and collapses
    /// each cluster to one survivor via supersession + a merge note.
    /// Non-destructive (merged-away members stay reachable) and zero generative
    /// LLM. Defaults to `false`, and is a clean no-op with no embedder, so an
    /// upgrade changes nothing until an operator opts in.
    pub dedup_cold_clusters: bool,
    /// DBSCAN density floor for A3. `0` ⇒ the conservative default (2).
    pub dedup_min_pts: usize,
    /// Conservative ceiling on the adaptive eps (cosine distance) for A3.
    /// `0.0` ⇒ the conservative default. Lower errs harder toward NOT merging.
    pub dedup_max_eps: f32,
    /// Optional per-tier half-life overrides (`[decay.half_life_days]`). All
    /// keys default to unset ⇒ the scalar `lambda` applies to every tier, which
    /// is byte-identical to the historical single-λ behaviour.
    pub half_life_days: DecayHalfLifeDays,
}

impl Default for DecaySettings {
    fn default() -> Self {
        let base = ai_memory_store::DecayParams::default();
        Self {
            lambda: base.lambda,
            sigma: base.sigma,
            mu: base.mu,
            salience_default: base.salience_default,
            cold_threshold: base.cold_threshold,
            hard_delete_after_days: base.hard_delete_after_days,
            breadth_weight: 0.0,
            observation_retention_days: 0,
            observation_prune_batch: ai_memory_consolidate::DEFAULT_OBSERVATION_PRUNE_BATCH,
            ledger_retention_months: 0,
            compact_cold_episodic: false,
            dedup_cold_clusters: false,
            dedup_min_pts: 0,
            dedup_max_eps: 0.0,
            half_life_days: DecayHalfLifeDays::default(),
        }
    }
}

impl DecaySettings {
    /// Retention coefficients consumed by existing store/consolidation APIs.
    #[must_use]
    pub fn decay_params(self) -> ai_memory_store::DecayParams {
        ai_memory_store::DecayParams {
            lambda: self.lambda,
            sigma: self.sigma,
            mu: self.mu,
            salience_default: self.salience_default,
            cold_threshold: self.cold_threshold,
            hard_delete_after_days: self.hard_delete_after_days,
            // Half-life-in-days is the user surface; λ is the math. Convert here
            // once. An unset key stays `None`, so `lambda_for` falls back to the
            // scalar `lambda` unchanged — the identity default, no days↔λ
            // round-trip that could perturb an unconfigured store's scores.
            tier_lambda: ai_memory_store::TierLambdas {
                working: self
                    .half_life_days
                    .working
                    .map(ai_memory_store::lambda_from_half_life_days),
                episodic: self
                    .half_life_days
                    .episodic
                    .map(ai_memory_store::lambda_from_half_life_days),
                semantic: self
                    .half_life_days
                    .semantic
                    .map(ai_memory_store::lambda_from_half_life_days),
                procedural: self
                    .half_life_days
                    .procedural
                    .map(ai_memory_store::lambda_from_half_life_days),
            },
        }
    }

    /// Opt-in observation prune bound consumed by the M8 sweep.
    ///
    /// Deliberately separate from [`Self::decay_params`]: keeping it out of the
    /// public `DecayParams` struct is what lets every downstream Rust caller
    /// that builds one directly keep compiling — and keep today's behaviour.
    #[must_use]
    pub fn observation_retention(self) -> ai_memory_consolidate::ObservationRetention {
        ai_memory_consolidate::ObservationRetention {
            days: self.observation_retention_days,
            batch: self.observation_prune_batch,
        }
    }

    /// Opt-in event ledger age bound consumed by the forget sweep. Disabled
    /// (`months == 0`) unless `[decay] ledger_retention_months` is positive.
    #[must_use]
    pub fn ledger_retention(self) -> ai_memory_consolidate::LedgerRetention {
        ai_memory_consolidate::LedgerRetention {
            months: self.ledger_retention_months,
        }
    }

    /// A3 cold-cluster dedup options for the M8 sweep.
    ///
    /// `embedding` is the running server's configured embedder coordinate, or
    /// `None` when no embedder is configured — in which case A3 is a clean no-op
    /// even with the flag on (there are no stored vectors to cluster).
    #[must_use]
    pub fn cold_cluster_dedup(
        self,
        embedding: Option<ai_memory_consolidate::EmbeddingCoord>,
    ) -> ai_memory_consolidate::ColdClusterDedup {
        ai_memory_consolidate::ColdClusterDedup {
            enabled: self.dedup_cold_clusters,
            embedding,
            min_pts: self.dedup_min_pts,
            max_eps: self.dedup_max_eps,
        }
    }
}

/// One `[[llm_fallbacks]]` entry: an ordered LLM provider tried only after
/// the primary (`llm_provider`) fails a transient call
/// (`LlmError::is_transient()`). See `docs/llm-provider-fallback.md`.
///
/// `Config::load` validates every profile and resolves its credential once,
/// at startup — a missing/empty provider or model, an unknown provider, or
/// a missing credential fails startup rather than leaving a latent fallback
/// that only fails under an outage.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default)]
pub struct FallbackProfile {
    /// Provider selection (same wire names as `llm_provider`).
    pub provider: String,
    /// Model id for this candidate.
    pub model: String,
    /// Optional base URL override (required for `openai-compat`, same as
    /// the top-level `llm_base_url`).
    pub base_url: Option<String>,
    /// Environment-variable name holding this profile's API key. Optional
    /// only for a provider with a native credential source (OpenAI OAuth,
    /// Copilot); every other provider must set it — it is never inherited
    /// from the primary provider's own env var.
    pub api_key_env: Option<String>,
}

/// Top-level runtime configuration.
///
/// `deny_unknown_fields` is intentionally NOT set: figment's
/// `Env::prefixed("AI_MEMORY_")` pulls every env var with that prefix
/// (including future keys not represented here yet). Strict rejection
/// here would crash on harmless deploy-specific env vars before the
/// rest of the config has a chance to validate what it actually uses.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct Config {
    /// Root data directory holding `wiki/`, `raw/`, `db/`, `models/`, `logs/`.
    pub data_dir: PathBuf,
    /// Whether `--data-dir`, `AI_MEMORY_DATA_DIR` or the config file's
    /// `data_dir` key chose [`Self::data_dir`], including an explicit value
    /// equal to the platform default.
    ///
    /// Loader provenance, like [`Self::server_url_explicit`]. `install-mcp`
    /// names the data dir in the bridge entries it writes only when it was
    /// chosen, so a bridge installed against a non-default data dir reads the
    /// same config and token as the hooks of that install, while a default
    /// install keeps resolving its data dir when the bridge starts.
    #[serde(skip)]
    pub data_dir_explicit: bool,
    /// HTTP bind address used by `ai-memory serve`.
    pub bind: String,
    /// Idle-time (seconds) before the OS starts probing an accepted `serve`
    /// connection with TCP keepalive. `0` disables keepalive entirely. A
    /// hook client's peer can die without sending FIN (laptop sleep, a
    /// VPN/Tailscale flap, an abrupt kill); without keepalive the socket
    /// stays `ESTABLISHED` forever and leaks one fd per dead peer until
    /// `accept()` fails with `EMFILE` and the healthcheck breaks (#792). Set
    /// with `AI_MEMORY_TCP_KEEPALIVE_SECS`.
    pub tcp_keepalive_secs: u64,
    /// Base URL used by thin-client CLI commands to contact the running server.
    ///
    /// When neither this file nor `AI_MEMORY_SERVER_URL` sets it, the loader
    /// derives it from [`Self::bind`] so a thin client reaches the server this
    /// same config starts (#1269); see [`Self::server_url_derived_from_bind`].
    pub server_url: String,
    /// Whether `server_url` was derived from `bind` rather than set by the
    /// config file or the environment (#1269).
    ///
    /// Kept separate from `server_url` itself so
    /// [`Self::server_url_configured`] can keep answering "did the operator
    /// choose the URL" -- the question `install-hooks` / `install-mcp` ask --
    /// without a derived value being mistaken for a deliberate one.
    ///
    /// Not deserialized from the file: it describes what the loader did, not
    /// something an operator states.
    #[serde(skip)]
    pub server_url_derived_from_bind: bool,
    /// Whether the operator explicitly set `server_url` in config or the
    /// process environment, including an explicit value equal to the default.
    ///
    /// This is loader provenance, not persisted configuration. Comparing the
    /// loaded value with [`DEFAULT_SERVER_URL`] loses this distinction and can
    /// make installers overwrite an intentional default URL (#1269 follow-up).
    #[serde(skip)]
    pub server_url_explicit: bool,
    /// Optional override for the GitHub Releases base URL used by
    /// `ai-memory upgrade` (archive + `.sha256` download). Empty/unset
    /// means `https://github.com/akitaonrails/ai-memory/releases`. Set via
    /// `AI_MEMORY_RELEASE_BASE_URL` or `release_base_url` in config.toml —
    /// intended for hermetic tests and mirrors, not day-to-day installs.
    #[serde(default)]
    pub release_base_url: Option<String>,
    /// URL subpath the server is mounted under (e.g. `/wiki`). Thin-client
    /// CLI commands prepend it to every `/admin/*` request so deployments
    /// hosted behind a reverse proxy under a subpath don't 404. Settable via
    /// `AI_MEMORY_BASE_PATH`. Empty for root-mounted deployments (the
    /// default). The `serve` subcommand uses this value unless an explicit
    /// flag or env override wins, so it mounts the same prefix thin clients
    /// resolve without another environment read (invariant: one config-read path).
    #[serde(default)]
    pub base_path: String,
    /// Operator home directory, captured once here (the single config-read
    /// path) from `AI_MEMORY_HOME`, `$HOME`, or Windows `%USERPROFILE%`. Used
    /// to keep the cwd->project resolver and the startup heal from treating
    /// the user profile as a prefix-match catch-all (issue #103) without env
    /// reads scattered through the runtime. Not a config.toml key: always
    /// derived from the process environment at load.
    #[serde(skip)]
    pub home_dir: Option<String>,
    /// Per-subsystem log filter (overridable by `RUST_LOG`).
    pub log_level: String,
    /// Optional LLM provider (`anthropic`, `openai`, `gemini`, `openai-compat`,
    /// `openai-oauth`, `codex`, `copilot`).
    pub llm_provider: Option<String>,
    /// Optional LLM model override.
    pub llm_model: Option<String>,
    /// Optional LLM base URL override.
    pub llm_base_url: Option<String>,
    /// Send `response_format=json_schema` (strict) to the `openai-compat`
    /// provider instead of relying on prose instructions and extracting the
    /// first balanced object. On by default because every structured call
    /// already supplies its own schema. Set
    /// `AI_MEMORY_LLM_COMPAT_STRICT=false` for an incompatible endpoint.
    pub llm_compat_strict: bool,
    /// OpenAI-compat only: send
    /// `chat_template_kwargs: {"enable_thinking": false}` with every chat
    /// request, for thinking-capable local engines (vLLM / SGLang serving
    /// Qwen3-class models): the engine otherwise spends the output budget
    /// on a reasoning pass before the structured payload and can truncate
    /// it mid-JSON. Ignored by every other provider; off by default. Set
    /// with `AI_MEMORY_LLM_COMPAT_DISABLE_THINKING` (or
    /// `llm_compat_disable_thinking = true` in `config.toml`).
    pub llm_compat_disable_thinking: bool,
    /// Per-request timeout (seconds) applied to every chat
    /// completion request and to the Copilot token exchange; the
    /// openai-oauth token refresh keeps the built-in default ceiling
    /// (it is a quick grant exchange). Defaults to
    /// `ai_memory_llm::DEFAULT_REQUEST_TIMEOUT_SECS` (300s), which
    /// tolerates a local engine cold-loading a large model. Raise it
    /// for slow hosted gateways whose long completions exceed the
    /// ceiling (observed with free aggregator tiers). Set with
    /// `AI_MEMORY_LLM_TIMEOUT_SECS`.
    pub llm_timeout_secs: u64,
    /// Optional reasoning / thinking effort. Omitted when unset so the
    /// model default applies. Env: `AI_MEMORY_LLM_REASONING_EFFORT`.
    /// Values: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`,
    /// `max`, `ultra`, `persistent`. Each provider maps this to its
    /// native request field (OpenAI `reasoning_effort`, OpenRouter
    /// `reasoning`, xAI Grok `reasoning_effort`, Anthropic
    /// `output_config.effort`, Codex `reasoning.effort`).
    pub llm_reasoning_effort: Option<ReasoningEffort>,
    /// Extra HTTP headers attached to every LLM chat request, as
    /// `Name: Value` (or `Name=Value`) entries. Empty by default.
    ///
    /// Exists for gateways that require a caller-identifying header:
    /// OpenCode asks callers for `x-opencode-session` plus a specific
    /// `User-Agent` and reports traffic carrying neither as an unknown
    /// client. Set with
    /// `AI_MEMORY_LLM_HEADERS='["x-opencode-session=…","user-agent=…"]'` (a
    /// JSON array of `Name: Value` / `Name=Value` strings; a bare comma
    /// separated string is rejected at config load) or
    /// `llm_headers = [...]` in `config.toml`.
    ///
    /// Headers ai-memory sets itself (`authorization`, `content-type`,
    /// `x-api-key`, …) are refused at startup: `reqwest` appends rather than
    /// replaces, so a duplicate would break the request instead of
    /// overriding it. Values are never logged.
    pub llm_headers: Vec<String>,
    /// Ordered LLM fallback chain, tried after the primary provider only on
    /// a transient failure (`LlmError::is_transient()`); empty by default
    /// (no behavior change). See [`FallbackProfile`] and
    /// `docs/llm-provider-fallback.md`. Configure via TOML:
    /// ```toml
    /// [[llm_fallbacks]]
    /// provider = "openai-compat"
    /// model = "poolside/laguna-s-2.1-free"
    /// base_url = "http://127.0.0.1:49375/v1"
    /// api_key_env = "AI_MEMORY_LOCAL_ROUTER_TOKEN"
    /// ```
    /// No environment-variable shorthand: figment cannot round-trip
    /// `Vec<Struct>` from `AI_MEMORY_*` env vars (see
    /// `AI_MEMORY_ADMISSION_WEBHOOKS_JSON`'s comment below), and encoding
    /// per-profile credential names into one env var would be ambiguous.
    #[serde(default)]
    pub llm_fallbacks: Vec<FallbackProfile>,
    /// Validated [`ProviderConfig`] for each `llm_fallbacks` entry
    /// (credentials included), resolved once by `Config::load` in
    /// declaration order. Not a config-file key — see
    /// [`Self::llm_provider_chain`]. `pub` (like [`Self::runtime_env`])
    /// only so struct-update syntax (`..Config::default()`) keeps working
    /// from every call site; construct it through `Config::load`, not by
    /// hand.
    #[serde(skip)]
    pub llm_fallback_configs: Vec<ProviderConfig>,
    /// One message per `llm_fallbacks` entry whose `api_key_env` names a
    /// variable absent from this process's environment. Such an entry is left
    /// out of [`Self::llm_fallback_configs`]; the failure is raised by
    /// [`Self::require_llm_fallback_credentials`] instead of by `load`, so a
    /// CLI invocation that never builds the LLM chain does not need the
    /// server's credentials (#762). Same `pub` rationale as above.
    #[serde(skip)]
    pub llm_fallback_unresolved: Vec<String>,
    /// Opt-in: run LLM consolidation on SessionEnd (in addition to the
    /// always-written heuristic session page), when an LLM provider is
    /// configured. Off by default. Provider work is durably queued after the
    /// deterministic session page and handoff, then handled outside the hook
    /// response by one bounded retrying worker. The LLM checkpoint otherwise
    /// happens on PreCompact and via manual `memory_consolidate`. Set with
    /// `AI_MEMORY_CONSOLIDATE_ON_SESSION_END=true`.
    pub consolidate_on_session_end: bool,
    /// Server-side opt-in for assistant/Stop capture (#196). When true, the
    /// server honors a client's sanitized `_ai_memory_assistant` marker on a
    /// `Stop` event and persists the excerpt as the Stop body. Off by default;
    /// when off the marker is stripped and the Stop stays empty. The client half
    /// of the double opt-in is baked separately by
    /// `install-hooks --capture-assistant`. Set with
    /// `AI_MEMORY_CAPTURE_ASSISTANT=true`.
    pub capture_assistant: bool,
    /// On by default. When the project's ai-memory store is brand new (empty),
    /// the SessionStart hook triggers a one-time, bounded import of this
    /// project's existing local harness session history so installing hooks
    /// mid-project does not start amnesiac. The import is read-only on the local
    /// side, sanitized on the server exactly like live capture, and only ever
    /// bootstraps an empty project (never overwrites an established one). Turn
    /// off with `AI_MEMORY_BACKFILL_ON_START=false` or `backfill_on_start =
    /// false`; `ai-memory backfill` remains available to run it by hand.
    pub backfill_on_start: bool,
    /// On by default. The first time `ai-memory run <harness>` launches a
    /// harness (per harness, binary version and config home), it auto-installs
    /// that harness's ai-memory lifecycle hooks and MCP server if they are not
    /// already wired, so managed launches capture and can query memory without
    /// a manual `install-hooks` / `install-mcp` step. Idempotent and one-time
    /// per harness and config home. Turn off with `AI_MEMORY_RUN_AUTOWIRE=false` /
    /// `run_autowire = false`, or per launch with `ai-memory run --no-autowire`.
    pub run_autowire: bool,
    /// Managed-launch settings, including the exit menu and named, env-only
    /// presets for `ai-memory run --profile NAME`.
    /// Profiles deliberately do not carry executable paths, native argv, or
    /// permission-bypass flags. Configure them under `[run.profiles.<name>.env]`.
    #[serde(default)]
    pub run: RunSettings,
    /// Off by default. When true, a Claude `ai-memory run --yolo` additionally
    /// applies [`apply_claude_true_yolo`](ai_memory_workstream::apply_claude_true_yolo),
    /// injecting `--settings` that forces `bypassPermissions` over any
    /// settings `defaultMode`. It never turns a launch without `--yolo` into a
    /// bypassing one, and it cannot silence the user's own `ask` rules, which
    /// Claude Code enforces in every mode. No-op for every other harness. Best
    /// paired with ai-jail (see `docs/design-yolo-safety-ai-jail.md`). Set with
    /// `AI_MEMORY_CLAUDE_TRUE_YOLO=true` or `claude_true_yolo = true` in
    /// config.toml; `ai-memory run --true-yolo` requests it per launch.
    pub claude_true_yolo: bool,
    /// Strip root-level `anyOf`/`oneOf`/`allOf` from MCP tool input
    /// schemas (e.g. `memory_read_page`'s "exactly one of path/query"
    /// contract) on every `tools/list`, regardless of client or `?flavor=`
    /// marker. Moonshot and Bedrock reject root combinators with a 400, and
    /// generic MCP clients (OpenCode, Cursor) never send the flavor marker —
    /// so operators routing through a strict upstream can opt in here.
    /// Runtime "exactly one of" validation is unchanged and remains the
    /// enforcement backstop (issue #412). Set with
    /// `AI_MEMORY_STRIP_ROOT_COMBINATORS=true` or `strip_root_combinators = true`
    /// in config.toml.
    pub strip_root_combinators: bool,
    /// Serve MCP tool input schemas in the subset Google's `Schema`
    /// (Vertex/Gemini `functionDeclaration.parameters`) accepts: the nullable
    /// unions `schemars` emits for every optional argument collapse to a single
    /// `type` plus `nullable: true`. Vertex rejects the union outright once a
    /// client forwards it verbatim — "specified other fields alongside any_of"
    /// — and fails the whole session at `tools/list`. Gemini CLI and
    /// Antigravity CLI normalize schemas client-side and need nothing; this is
    /// for pass-through clients such as OpenCode on a Gemini/Vertex model.
    /// Implies `strip_root_combinators`. Runtime validation is unchanged. Set
    /// with `AI_MEMORY_GEMINI_SAFE_SCHEMAS=true` or
    /// `gemini_safe_schemas = true` in config.toml; the per-request
    /// `?flavor=gemini` marker on the MCP URL is the equivalent opt-in for one
    /// client.
    pub gemini_safe_schemas: bool,
    /// Opt-in post-RRF reranker for `memory_query`. Only `"llm"` is
    /// supported: LLM-as-judge over the configured LLM provider, so it
    /// requires `AI_MEMORY_LLM_PROVIDER` too. Off by default — it puts
    /// an LLM call on the search hot path, trading latency for recall
    /// at the top of the ranking. On any error or timeout the query
    /// preserves the fused, authority-adjusted order. Set with
    /// `AI_MEMORY_RERANKER=llm`.
    pub reranker: Option<String>,
    /// Wall-clock budget, in seconds, for one rerank call before the search
    /// answers from the pre-rerank order. Defaults to
    /// `ai_memory_llm::reranker::RERANK_TIMEOUT` (20s). Raise it when the
    /// LLM chain falls back across slow free-tier candidates (a hosted 503
    /// can take ~20s alone). Set with `AI_MEMORY_RERANK_TIMEOUT_SECS`.
    pub rerank_timeout_secs: u64,
    /// Optional embedding provider (`openai`, `voyage`, `google` / `gemini`,
    /// or `openai-compat`).
    pub embedding_provider: Option<String>,
    /// Optional embedding model override.
    pub embedding_model: Option<String>,
    /// Optional embedding dimension override.
    pub embedding_dim: Option<u32>,
    /// Optional embedding base URL override.
    pub embedding_base_url: Option<String>,
    /// Optional prefix prepended to every embedding **query** before it is
    /// sent to the `openai` or `openai-compat` embedder, ahead of the
    /// existing truncation. Unset (the default) is a no-op — no behaviour
    /// change. Asymmetric self-hosted models need a query-side instruction
    /// their publisher specifies; the OpenAI-compatible `/v1/embeddings`
    /// wire format has no field for it, so the client prepends it instead.
    /// `nvidia/Nemotron-3-Embed-1B-BF16` and base E5 models
    /// (`intfloat/e5-base-v2`, multilingual E5, …) use a simple
    /// `"query: "` / `"passage: "` pair (documents get
    /// `embedding_document_prefix = "passage: "`). Instruction-tuned E5
    /// variants and Qwen3-Embedding instead need a full task-instruction
    /// string on the query side only, with **different exact spacing each**
    /// — leave `embedding_document_prefix` unset for both (their documents
    /// are plain text, no prefix):
    /// `e5-mistral-7b-instruct` wants
    /// `"Instruct: {task description}\nQuery: "` (a trailing space after
    /// `Query:`); Qwen3-Embedding wants
    /// `"Instruct: {task description}\nQuery:"` (no trailing space — the
    /// query text follows the colon directly). Not trimmed: a publisher's
    /// trailing space or embedded newline is significant and preserved
    /// verbatim. Ignored by `google` (which has its own built-in
    /// query/document asymmetry), `voyage`, `local`, and `copilot`.
    /// Changing only this key never requires re-embedding existing pages —
    /// the query side has no stored identity. See `docs/llm-providers.md`.
    /// Settable via `AI_MEMORY_EMBEDDING_QUERY_PREFIX` (figment's `Env`
    /// provider would otherwise trim a trailing space; `Config::load`
    /// overlays the raw env bytes for this key specifically).
    pub embedding_query_prefix: Option<String>,
    /// Document-side counterpart of `embedding_query_prefix` (e.g.
    /// `"passage: "` for Nemotron-3-Embed / base E5; see that field's doc
    /// comment for which models this applies to). Unlike the query prefix,
    /// this one IS folded into the stored embedding identity
    /// (`Embedder::model_identity`): a non-empty value makes newly
    /// embedded pages distinguishable from ones embedded before the
    /// change (or under a different prefix), so `memory_query` and
    /// `ai-memory embed`'s stale-row detection both treat a document-prefix
    /// change like a model change — no manual `--force` needed, and an
    /// empty value keeps the pre-existing (legacy) identity so upgrading
    /// installs need no migration. Settable via
    /// `AI_MEMORY_EMBEDDING_DOCUMENT_PREFIX` (same raw-env overlay as
    /// `embedding_query_prefix`).
    pub embedding_document_prefix: Option<String>,
    /// M8 retention-sweep parameters. The defaults give an ~80-day
    /// "survival floor" for unused episodic content (above the cold
    /// threshold), followed by ~180 days of tombstone grace before permanent
    /// version-chain deletion. Tune `decay.lambda` down to slow decay or
    /// `decay.cold_threshold` to evict more / less aggressively.
    pub decay: DecaySettings,
    /// Server-side scheduled maintenance. Jobs run outside hook latency.
    pub maintenance: MaintenanceSettings,
    /// Server-side session lifecycle (idle auto-end tick).
    pub sessions: SessionsSettings,
    /// Lower edge (inclusive) of `memory_lint`'s A5 zero-LLM
    /// contradiction-detection cosine-similarity band. Two cold pages whose
    /// embeddings sit in `[contradiction_band_min, contradiction_band_max)`
    /// are "same topic, not a duplicate" — flagged as a likely conflict.
    ///
    /// The band is a fixed absolute cosine value, but the background
    /// similarity of unrelated pages is corpus-dependent: on a
    /// single-language or single-domain store (or one written in a
    /// non-English language), unrelated pages already sit well above the
    /// general-purpose default floor, so the band ends up measuring domain
    /// proximity rather than conflict and produces noisy findings. Raise
    /// this floor for such a store. Default `0.4` preserves the historical
    /// fixed band exactly. Settable via `AI_MEMORY_CONTRADICTION_BAND_MIN`.
    pub contradiction_band_min: f32,
    /// Upper edge (exclusive) of the band — see `contradiction_band_min`. At
    /// or above this, two pages are treated as a near-duplicate (A3
    /// cold-cluster dedup's territory) rather than a contradiction. Default
    /// `0.75`. Settable via `AI_MEMORY_CONTRADICTION_BAND_MAX`.
    pub contradiction_band_max: f32,
    /// Opt-in LLM "dream" pass (B2/B3/B4): rewrite/merge cold clusters with the
    /// configured provider, scheduled on idle and cancelled the moment the
    /// operator returns. OFF by default and gated on an R2 number before it may
    /// default on; never deletes a source.
    pub dream: DreamSettings,
    /// Opt-in post-fusion ranking signals for `memory_query` (hotness boost,
    /// lexical query-intent routing). All off by default.
    pub retrieval: RetrievalSettings,
    /// Search-path tuning that is not a ranking signal (contrast with
    /// `retrieval`): today, only the FTS stopword list (issue #953).
    pub search: SearchSettings,
    /// Memory-slot behaviour.
    pub slots: SlotSettings,
    /// LLM consolidation prompt limits. Defaults are sized for a model with a
    /// 200k-token context window.
    pub consolidation: ConsolidationSettings,
    /// Optional context admission for query answer synthesis.
    pub query_answer: QueryAnswerSettings,
    /// Auto-improvement reviewer. The scheduler launches background review for
    /// newly completed sessions; manual CLI/admin/MCP runs remain available.
    /// Both approve validated proposals by default unless `require_approval` is
    /// set. The SessionEnd trigger stays off by default.
    pub auto_improve: AutoImproveSettings,
    /// Session-start handoff delivery (design: #959). Default keeps today's
    /// automatic-claim behavior unchanged.
    pub handoff: HandoffSettings,
    /// `[profile]` — the cross-project profile: how this user usually works,
    /// delivered to every project as defaults below the repository's rules
    /// file (`docs/design-cross-project-profile.md`,
    /// `docs/cross-project-profile.md`). `enabled = "auto"` (the default)
    /// turns it on for a single-operator server, shared across every
    /// workspace, and leaves it off for a multi-user one. Settable via
    /// `AI_MEMORY_PROFILE__<KEY>` (for example `AI_MEMORY_PROFILE__SHARE`).
    pub profile: ai_memory_core::profile::ProfileSettings,
    /// Privacy-strip tuning. Built-in patterns always run; this section
    /// lets the operator extend or punch holes in them.
    pub sanitize: ai_memory_core::SanitizeConfig,
    /// Bearer token required on every HTTP request. When `None`/unset,
    /// the server runs open (zero-config local-dev behaviour). When set,
    /// requests to /mcp + /hook + /handoff must carry
    /// `Authorization: Bearer <token>`. Settable via the
    /// `AI_MEMORY_AUTH_TOKEN` env var or `[auth].bearer_token` in
    /// config.toml.
    pub auth: AuthSettings,
    /// `[auto_scope]` — isolation of the hook-published "current project"
    /// pointer used by MCP tools that omit `workspace`/`project`. The default
    /// `per_actor` mode keys it by whatever coordinate the caller has;
    /// `per_session` keys by `session_id`, and `single` keeps the pre-v1.39
    /// global slot. See [`AutoScopeSettings`]
    /// and [`ai_memory_core::ActiveProjectMode`].
    pub auto_scope: AutoScopeSettings,
    /// `[routing]` — how mid-session events whose cwd moved are attributed.
    /// Default `follow-cwd` preserves the historical per-event resolution;
    /// `sticky` keeps the session's project. See [`RoutingSettings`].
    pub routing: RoutingSettings,
    /// Client-side hook spool retry policy.
    pub hook_spool: HookSpoolSettings,
    /// `[ingest]` — server-side drop list for tool events (#1241).
    pub ingest: IngestSettings,
    /// Env-backed alias for hook ingest tokens per second per source.
    pub hook_rate_per_sec: f64,
    /// Env-backed alias for hook ingest burst tokens per source.
    pub hook_rate_burst: f64,
    /// `Host`-header allowlist for the HTTP server. Requests whose
    /// `Host` header doesn't match this list are rejected before they
    /// reach MCP, hook, admin, or web routes (DNS-rebinding defence).
    /// Default is loopback only; to expose ai-memory on a LAN
    /// IP / `home.lan` / etc., add that authority here or pass it via
    /// `AI_MEMORY_ALLOWED_HOSTS=host1,host2,…` at startup.
    ///
    /// Accepts either a TOML/JSON sequence (`["a","b"]`) or a
    /// comma-separated string (`"a,b"`) for ergonomics — env vars
    /// can't be sequences without ugly escaping.
    #[serde(deserialize_with = "deserialize_string_or_vec")]
    pub allowed_hosts: Vec<String>,
    /// Origins allowed to make cross-origin requests to /api/v1. Empty
    /// (default) means same-origin only — host your SPA via --web-ui-dir
    /// instead of using CORS if you can. When non-empty, a CorsLayer is
    /// attached ONLY to /api/v1; /mcp, /hook, /admin, and /web are NOT
    /// CORS-enabled (those aren't browser-accessible by design).
    ///
    /// Settable via AI_MEMORY_CORS_ALLOW_ORIGINS=a,b,c or one or more
    /// --cors-allow-origin flags. Each entry must include a scheme;
    /// `*` is rejected.
    #[serde(deserialize_with = "deserialize_string_or_vec", default)]
    pub cors_allow_origins: Vec<String>,
    /// Admission webhook chain — synchronous HTTP hooks invoked in
    /// [`ai_memory_wiki::Wiki::write_page`] just before page persistence.
    /// Each entry is a [`ai_memory_wiki::WebhookConfig`]. Empty by default
    /// (no chain attached → engine runs as before). Configure via TOML:
    /// ```toml
    /// [[admission_webhooks]]
    /// name = "contributors"
    /// url  = "http://contributors-webhook.memory.svc.cluster.local/enrich"
    /// timeout_ms = 2000
    /// failure_policy = "ignore"
    /// events = ["write_page", "consolidate"]
    /// ```
    /// Env override: `AI_MEMORY_ADMISSION_WEBHOOKS__0__URL=…`,
    /// `AI_MEMORY_ADMISSION_WEBHOOKS__0__NAME=…`, etc.
    /// See [`ai_memory_wiki::admission`] for the contract.
    #[serde(default)]
    pub admission_webhooks: Vec<ai_memory_wiki::WebhookConfig>,
    /// Process-only env values that should never be written to config files.
    #[serde(skip)]
    pub runtime_env: RuntimeEnv,
}

#[derive(Clone, Default)]
struct CapturedProcessEnv(Vec<(OsString, OsString)>);

impl std::fmt::Debug for CapturedProcessEnv {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("CapturedProcessEnv")
            .field("entries", &self.0.len())
            .finish()
    }
}

/// Whether a captured environment key names `name`: exactly, or ignoring
/// ASCII case where the platform's environment is case-insensitive (Windows).
fn env_name_matches(key: &std::ffi::OsStr, name: &str, case_insensitive: bool) -> bool {
    if case_insensitive {
        key.to_str()
            .is_some_and(|key| key.eq_ignore_ascii_case(name))
    } else {
        key == name
    }
}

/// Environment-only values captured once by [`Config::load`].
#[derive(Debug, Clone, Default)]
pub struct RuntimeEnv {
    data_dir: Option<PathBuf>,
    home_dir: Option<String>,
    platform_home: Option<PathBuf>,
    codex_home: Option<PathBuf>,
    codex_executable: Option<PathBuf>,
    cursor_executable: Option<PathBuf>,
    temp_dir: Option<PathBuf>,
    server_url: Option<String>,
    auth_token: Option<String>,
    host_cwd: Option<String>,
    scope_cwd: Option<String>,
    ignore_marker: bool,
    project_strategy: Option<String>,
    process_env: CapturedProcessEnv,
    capture_owner_active: bool,
    claude_code_session_id: Option<String>,
    muse_session_id: Option<String>,
    anthropic_api_key: Option<SecretString>,
    anthropic_oauth_token: Option<SecretString>,
    openai_api_key: Option<SecretString>,
    gemini_api_key: Option<SecretString>,
    llm_api_key: Option<SecretString>,
    llm_base_url: Option<String>,
    embedding_api_key: Option<SecretString>,
    copilot_github_token: Option<SecretString>,
    github_copilot_api_token: Option<SecretString>,
    copilot_api_url: Option<String>,
    copilot_client_id: Option<String>,
    voyage_api_key: Option<SecretString>,
    opencode_api_key: Option<SecretString>,
    hook_spool_max_attempts: Option<String>,
    run_require_server: Option<String>,
}

impl RuntimeEnv {
    pub(crate) fn from_process() -> Self {
        let platform_home = dirs::home_dir();
        let process_env = CapturedProcessEnv(std::env::vars_os().collect());
        Self {
            data_dir: env_path("AI_MEMORY_DATA_DIR"),
            home_dir: resolve_operator_home(
                env_string("AI_MEMORY_HOME").as_deref(),
                env_string("HOME").as_deref(),
                env_string("USERPROFILE").as_deref(),
                platform_home.as_deref(),
            ),
            platform_home,
            codex_home: env_path("CODEX_HOME"),
            codex_executable: env_path("AI_MEMORY_CODEX_EXECUTABLE"),
            cursor_executable: env_path("AI_MEMORY_CURSOR_AGENT"),
            temp_dir: Some(std::env::temp_dir()),
            server_url: env_string("AI_MEMORY_SERVER_URL"),
            auth_token: env_string("AI_MEMORY_AUTH_TOKEN"),
            host_cwd: env_string("AI_MEMORY_HOST_CWD"),
            scope_cwd: env_string("AI_MEMORY_SCOPE_CWD"),
            // One-invocation escape hatch: run a command against the fallback
            // scope without editing (or leaving) the marker's tree.
            ignore_marker: env_string("AI_MEMORY_IGNORE_MARKER")
                .is_some_and(|value| crate::marker::is_truthy(&value)),
            // Install-wide project strategy, matching what `install-hooks
            // --project-strategy` bakes into the generated hook commands.
            // Consulted only when a marker does not pin one.
            project_strategy: env_string("AI_MEMORY_PROJECT_STRATEGY"),
            process_env,
            capture_owner_active: env_string("AI_MEMORY_CAPTURE_OWNER")
                .is_some_and(|value| !value.trim().is_empty()),
            claude_code_session_id: env_string("CLAUDE_CODE_SESSION_ID"),
            muse_session_id: env_string("MUSE_SESSION_ID"),
            anthropic_api_key: env_secret("ANTHROPIC_API_KEY"),
            // CLAUDE_CODE_OAUTH_TOKEN is the name Claude Code reads the
            // `claude setup-token` token from; ANTHROPIC_OAUTH_TOKEN is our
            // canonical name — accept both.
            anthropic_oauth_token: env_secret("ANTHROPIC_OAUTH_TOKEN")
                .or_else(|| env_secret("CLAUDE_CODE_OAUTH_TOKEN")),
            openai_api_key: env_secret("OPENAI_API_KEY"),
            // GOOGLE_API_KEY is the older alias many Google docs still
            // mention; accept either so users don't get tripped up.
            gemini_api_key: env_secret("GEMINI_API_KEY").or_else(|| env_secret("GOOGLE_API_KEY")),
            llm_api_key: env_secret("LLM_API_KEY"),
            llm_base_url: env_string("LLM_BASE_URL"),
            // The embedding counterpart of LLM_API_KEY: it credentials the
            // embedding role alone, so the embedder can target a different
            // provider than the chat model instead of borrowing its key.
            embedding_api_key: env_secret("EMBEDDING_API_KEY"),
            copilot_github_token: env_secret("COPILOT_GITHUB_TOKEN")
                .or_else(|| env_secret("GH_TOKEN"))
                .or_else(|| env_secret("GITHUB_TOKEN")),
            github_copilot_api_token: env_secret("GITHUB_COPILOT_API_TOKEN"),
            copilot_api_url: env_string("COPILOT_API_URL"),
            copilot_client_id: env_string("AI_MEMORY_COPILOT_CLIENT_ID"),
            voyage_api_key: env_secret("VOYAGE_API_KEY"),
            opencode_api_key: env_secret("OPENCODE_API_KEY"),
            hook_spool_max_attempts: std::env::var("AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS").ok(),
            // A flat env var (not `AI_MEMORY_RUN__REQUIRE_SERVER`, which
            // figment's `__` split would map onto `run.require_server`) so it
            // reads the same way as `AI_MEMORY_RUN_AUTOWIRE`; applied in
            // `load_with_runtime_env` instead of figment for that reason.
            run_require_server: std::env::var("AI_MEMORY_RUN_REQUIRE_SERVER").ok(),
        }
    }

    /// Data directory captured from the process environment, if present.
    #[must_use]
    pub fn data_dir(&self) -> Option<&Path> {
        self.data_dir.as_deref()
    }

    /// Host cwd forwarded by the docker wrapper, if present.
    #[must_use]
    pub fn host_cwd(&self) -> Option<&str> {
        self.host_cwd.as_deref()
    }

    /// Container-visible cwd used only for marker discovery.
    #[must_use]
    pub fn scope_cwd(&self) -> Option<&str> {
        self.scope_cwd.as_deref()
    }

    /// Operator home captured by the single config-read path.
    #[must_use]
    pub fn home_dir(&self) -> Option<&str> {
        self.home_dir.as_deref()
    }

    /// Whether `AI_MEMORY_IGNORE_MARKER` asked this invocation to resolve its
    /// scope as if no `.ai-memory.toml` existed.
    #[must_use]
    pub fn ignore_marker(&self) -> bool {
        self.ignore_marker
    }

    /// Install-wide `--project-strategy` default baked into the environment.
    #[must_use]
    pub fn project_strategy(&self) -> Option<&str> {
        self.project_strategy.as_deref()
    }

    /// Complete process environment captured by the single config-read path.
    #[must_use]
    pub fn process_env(&self) -> &[(OsString, OsString)] {
        &self.process_env.0
    }

    /// One variable of the captured process environment. Third-party harness
    /// homes (`CODEX_HOME`, `COPILOT_HOME`, ...) are read through here so a
    /// command never re-reads the live environment (invariant #1) and tests
    /// can inject them. Names match case-insensitively on Windows, as
    /// `std::env::var_os` does there.
    #[must_use]
    pub(crate) fn var_os(&self, name: &str) -> Option<OsString> {
        self.process_env
            .0
            .iter()
            .find(|(key, _)| env_name_matches(key, name, cfg!(windows)))
            .map(|(_, value)| value.clone())
    }

    /// Whether this invocation delegates native capture to an external producer.
    #[must_use]
    pub fn capture_owner_active(&self) -> bool {
        self.capture_owner_active
    }

    /// Claude Code lifecycle session id inherited by an stdio MCP subprocess.
    #[must_use]
    pub fn claude_code_session_id(&self) -> Option<&str> {
        self.claude_code_session_id.as_deref()
    }

    /// Meta Muse Code session id, which Muse sets for its stdio MCP servers
    /// and hooks.
    #[must_use]
    pub fn muse_session_id(&self) -> Option<&str> {
        self.muse_session_id.as_deref()
    }

    /// Hook-spool attempt override captured from the process environment.
    #[must_use]
    pub fn hook_spool_max_attempts(&self) -> Option<&str> {
        self.hook_spool_max_attempts.as_deref()
    }

    /// Managed-launch fail-closed override captured from the process
    /// environment.
    #[must_use]
    pub fn run_require_server(&self) -> Option<&str> {
        self.run_require_server.as_deref()
    }

    #[cfg(test)]
    pub fn with_host_cwd_for_tests(host_cwd: impl Into<String>) -> Self {
        Self {
            host_cwd: Some(host_cwd.into()),
            ..Self::default()
        }
    }

    #[cfg(test)]
    pub fn with_host_cwd_and_home_for_tests(
        host_cwd: impl Into<String>,
        home_dir: impl Into<String>,
    ) -> Self {
        Self {
            host_cwd: Some(host_cwd.into()),
            home_dir: Some(home_dir.into()),
            ..Self::default()
        }
    }

    #[cfg(test)]
    pub fn with_session_ids_for_tests(claude_code: Option<&str>, muse: Option<&str>) -> Self {
        Self {
            claude_code_session_id: claude_code.map(str::to_owned),
            muse_session_id: muse.map(str::to_owned),
            ..Self::default()
        }
    }

    #[cfg(test)]
    pub fn with_process_env_for_tests(pairs: &[(&str, &str)]) -> Self {
        Self {
            process_env: CapturedProcessEnv(
                pairs
                    .iter()
                    .map(|(key, value)| (OsString::from(key), OsString::from(value)))
                    .collect(),
            ),
            ..Self::default()
        }
    }

    #[cfg(test)]
    pub fn with_openai_api_key_for_tests(api_key: impl Into<String>) -> Self {
        Self {
            openai_api_key: Some(SecretString::from(api_key.into())),
            ..Self::default()
        }
    }
}

/// Accept `Vec<String>` either as a real sequence (config.toml /
/// JSON array) or as a comma-separated single string (env var).
fn deserialize_string_or_vec<'de, D>(deserializer: D) -> Result<Vec<String>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    #[derive(Deserialize)]
    #[serde(untagged)]
    enum Either {
        Single(String),
        Many(Vec<String>),
    }
    Ok(match Either::deserialize(deserializer)? {
        Either::Single(s) => s
            .split(',')
            .map(|x| x.trim().to_string())
            .filter(|x| !x.is_empty())
            .collect(),
        Either::Many(v) => v,
    })
}

/// `[auth]` section of `config.toml`.
#[derive(Clone, Default, Serialize, Deserialize)]
#[serde(default)]
pub struct AuthSettings {
    /// Shared bearer token. When set, all HTTP routes require
    /// `Authorization: Bearer <token>`. Generate one with
    /// `ai-memory generate-auth-token`.
    pub bearer_token: Option<String>,
    /// File holding the shared bearer token, one line, owner-only. A relative
    /// path resolves against the data dir, so a container that mounts the data
    /// dir at `/data` and a host client that sees it at its host path read the
    /// same file. `ai-memory init` on a fresh data dir and `ai-memory auth
    /// enable` set this to `auth-tokens/default`.
    ///
    /// Read once by [`Config::load`] into [`Self::bearer_token`].
    /// `AI_MEMORY_AUTH_TOKEN` still wins over it; setting it together with
    /// `bearer_token` is refused as ambiguous. A token read from here is never
    /// written into a harness config (see [`Self::renderable_bearer_token`]).
    pub bearer_token_file: Option<PathBuf>,
    /// Where `bearer_token_file` resolved to and whether it held a token. Set
    /// by [`Config::load`]; never read from or written to a config file.
    #[serde(skip)]
    pub(crate) token_file: Option<ResolvedTokenFile>,
    /// Create every new project `restricted` rather than `open` (#708).
    ///
    /// Off by default: a new project is open to every authenticated user, as
    /// every project was before per-project access existed. On, a new project
    /// admits only its creator — who is granted `write` on it — and root,
    /// until someone grants others. Existing projects are never changed by
    /// this; an operator restricts one with `ai-memory project access`. The
    /// reserved `scratch` and global-preferences projects are always open.
    pub new_projects_restricted: bool,
    /// Mark the browser session cookie `Secure`. Human authentication on a
    /// non-loopback listener requires this explicit HTTPS reverse-proxy
    /// posture. It may be false only for direct loopback smoke/development.
    pub secure_cookie: bool,
    /// Username attributed to writes authenticated by the bearer
    /// token (rung 1: "identified single-user"). When set, the
    /// auth middleware injects an
    /// [`ai_memory_core::ActorContext`] with `user =
    /// Some(root_username)` on root-token requests, so audit_log
    /// and page frontmatter record the operator instead of
    /// staying anonymous. Omit (or leave empty) to keep the
    /// pre-multi-user behaviour — bearer authenticates but
    /// attributes anonymously.
    pub root_username: Option<String>,
    /// OIDC issuer for the root operator when a trusted proxy asserts stable
    /// identities. Configure together with [`Self::root_subject`].
    pub root_issuer: Option<String>,
    /// OIDC subject for the root operator. Configure together with
    /// [`Self::root_issuer`]; only this pair can grant a proxy-authenticated
    /// request root capability. A display username is not a stable root key.
    pub root_subject: Option<String>,
    /// Optional email for the root user, surfaced alongside
    /// `root_username` in the web UI + `/api/v1` responses.
    pub root_email: Option<String>,
    /// Optional display name for the root user (e.g.
    /// `"Alice Smith"`); falls back to `root_username` in UIs.
    pub root_name: Option<String>,
    /// Per-server token pepper used by
    /// [`ai_memory_store::hash_token`] to keep stolen
    /// `api_credentials.token_hash` rows useless to an offline attacker.
    /// Auto-generated by `ai-memory init` (32 bytes of OS CSPRNG,
    /// hex-encoded). MUST NOT change after the first native API key is
    /// added — rotating it invalidates every existing native key. Human
    /// passwords and sessions do not use this pepper.
    pub token_pepper: Option<String>,
    /// Dedicated bearer token for a trusted authenticating proxy, allowing it
    /// to name the real end user in `X-Memory-Actor-*` headers.
    ///
    /// A proxy that terminates SSO usually cannot forward the user's own
    /// credential upstream. This token must differ from [`Self::bearer_token`]
    /// so an omitted or malformed identity cannot fall through as root.
    /// Actor headers on ordinary root and DB-user requests are ignored.
    ///
    /// Only set this when the server is reachable *only* through that proxy.
    pub actor_proxy_bearer_token: Option<String>,
    /// One-shot greenfield root password. Consumed when
    /// `human_auth_state.bootstrap_completed` is false, then ignored forever.
    /// Set with `AI_MEMORY_AUTH__INITIAL_ROOT_PASSWORD`.
    #[serde(skip_serializing)]
    pub initial_root_password: Option<SecretString>,
    /// Break-glass recovery secret for `POST /auth/recovery`. Compared
    /// constant-time; never stored in SQLite. Set with
    /// `AI_MEMORY_AUTH__RECOVERY_TOKEN`.
    #[serde(skip_serializing)]
    pub recovery_token: Option<SecretString>,
    /// CIDRs allowed to supply `X-Forwarded-For` for login rate limiting.
    /// Bare addresses are treated as `/32` or `/128`. Set with
    /// `AI_MEMORY_AUTH__TRUSTED_PROXY_CIDRS`.
    #[serde(default, deserialize_with = "deserialize_string_or_vec")]
    pub trusted_proxy_cidrs: Vec<String>,
}

impl std::fmt::Debug for AuthSettings {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("AuthSettings")
            .field(
                "bearer_token",
                &self.bearer_token.as_ref().map(|_| "<redacted>"),
            )
            .field("bearer_token_file", &self.bearer_token_file)
            .field("token_file", &self.token_file)
            .field("secure_cookie", &self.secure_cookie)
            .field("root_username", &self.root_username)
            .field("root_issuer", &self.root_issuer)
            .field("root_subject", &self.root_subject)
            .field("root_email", &self.root_email)
            .field("root_name", &self.root_name)
            .field(
                "token_pepper",
                &self.token_pepper.as_ref().map(|_| "<redacted>"),
            )
            .field(
                "actor_proxy_bearer_token",
                &self.actor_proxy_bearer_token.as_ref().map(|_| "<redacted>"),
            )
            .field(
                "initial_root_password",
                &self.initial_root_password.as_ref().map(|_| "<redacted>"),
            )
            .field(
                "recovery_token",
                &self.recovery_token.as_ref().map(|_| "<redacted>"),
            )
            .field("trusted_proxy_cidrs", &self.trusted_proxy_cidrs)
            .finish()
    }
}

/// `[auth].bearer_token_file` after [`Config::load`] resolved it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct ResolvedTokenFile {
    /// Absolute path the token was read from.
    pub(crate) path: PathBuf,
    /// Whether the file held a non-blank token. A configured file that is
    /// missing or blank leaves [`AuthSettings::bearer_token`] unset, and
    /// `serve` refuses to start rather than run open.
    pub(crate) loaded: bool,
    /// Whether [`discover_root_token`] found it rather than the config naming
    /// it, so a credential this install chose can outrank it.
    pub(crate) discovered: bool,
}

impl AuthSettings {
    /// The bearer an installer may write into a harness config or print in a
    /// snippet: one the operator supplied inline (`[auth].bearer_token` or
    /// `AI_MEMORY_AUTH_TOKEN`). A token read from `bearer_token_file` is
    /// `None` here, because that file exists to keep the secret out of
    /// harness configs (#552); those installs reach it through `ai-memory
    /// mcp-bridge`, an env-var reference, or the hook credential files.
    #[must_use]
    pub fn renderable_bearer_token(&self) -> Option<&str> {
        if self.token_file.as_ref().is_some_and(|file| file.loaded) {
            return None;
        }
        self.bearer_token.as_deref()
    }

    /// The token file this install's bearer comes from, when it comes from
    /// one (loaded or not).
    #[must_use]
    pub(crate) fn token_file_path(&self) -> Option<&Path> {
        self.token_file.as_ref().map(|file| file.path.as_path())
    }

    /// The bearer the environment, the inline key or `[auth].bearer_token_file`
    /// supplied, leaving out a root token only [`discover_root_token`] found.
    #[must_use]
    pub(crate) fn configured_bearer_token(&self) -> Option<&str> {
        if self.token_file.as_ref().is_some_and(|file| file.discovered) {
            return None;
        }
        self.bearer_token.as_deref()
    }

    /// The configured token file when it could not supply a token.
    #[must_use]
    pub(crate) fn missing_token_file(&self) -> Option<&Path> {
        self.token_file
            .as_ref()
            .filter(|file| !file.loaded)
            .map(|file| file.path.as_path())
    }

    /// Record a token read from `path`, the way [`Config::load`] would have.
    /// For `auth enable`, which provisions the file after config was loaded and
    /// re-renders wiring in the same process.
    pub(crate) fn adopt_token_file(&mut self, path: PathBuf, token: String) {
        self.bearer_token = Some(token);
        self.token_file = Some(ResolvedTokenFile {
            path,
            loaded: true,
            discovered: false,
        });
    }
}

/// What [`apply_bearer_token_file`] needs to know about the load.
struct TokenFileContext<'a> {
    data_dir: &'a Path,
    /// `AI_MEMORY_AUTH_TOKEN` was set (it already replaced `bearer_token`).
    env_token: bool,
    /// A config file exists at the path this load read.
    config_file_exists: bool,
    server_url: &'a str,
}

/// Resolve `[auth].bearer_token_file` against the final data dir and read it.
///
/// `AI_MEMORY_AUTH_TOKEN` already replaced `bearer_token` and wins here too,
/// exactly as it wins over the inline key. Both keys set in config is
/// refused: which one the server enforces must never be a guess.
///
/// With no key at all, see [`discover_root_token`].
fn apply_bearer_token_file(auth: &mut AuthSettings, ctx: &TokenFileContext<'_>) -> Result<()> {
    if ctx.env_token {
        return Ok(());
    }
    let Some(raw) = auth
        .bearer_token_file
        .as_ref()
        .filter(|path| !path.as_os_str().is_empty())
    else {
        discover_root_token(auth, ctx);
        return Ok(());
    };
    if non_empty(auth.bearer_token.as_deref()).is_some() {
        anyhow::bail!(
            "[auth].bearer_token and [auth].bearer_token_file are both set; keep only one"
        );
    }
    let path = if raw.is_absolute() {
        raw.clone()
    } else {
        ctx.data_dir.join(raw)
    };
    let token = read_trimmed_secret(&path);
    auth.token_file = Some(ResolvedTokenFile {
        path,
        loaded: token.is_some(),
        discovered: false,
    });
    auth.bearer_token = token;
    Ok(())
}

/// Find this install's root bearer when the config this command loaded does
/// not name it.
///
/// A packaged install keeps its config outside the data dir (`init --config
/// ~/.config/ai-memory/config.toml`, the systemd unit passes the same path),
/// while `install-mcp`, `status` and the bridge run without `--config` and so
/// read no config file at all. They still need the token `init` minted at
/// `<data_dir>/auth-tokens/default`. It is used, as a file-sourced token, only
/// when every one of these holds:
///
/// - no bearer is configured any other way (env, inline key, file key);
/// - no config file exists where this load looked, so no config chose to run
///   without one (an existing install with a config keeps its behaviour);
/// - the server URL is loopback, so the token can only reach this machine;
/// - no server profile named `default` is registered, whose token file this
///   would be (#992).
fn discover_root_token(auth: &mut AuthSettings, ctx: &TokenFileContext<'_>) {
    if non_empty(auth.bearer_token.as_deref()).is_some()
        || ctx.config_file_exists
        || !crate::http_client::is_loopback_url(ctx.server_url)
    {
        return;
    }
    let path = crate::server_profiles::root_token_path(ctx.data_dir);
    let Some(token) = read_trimmed_secret(&path) else {
        return;
    };
    // An unreadable registry cannot prove the name is free.
    let profile_named_default =
        crate::server_profiles::root_token_name_is_registered(ctx.data_dir).unwrap_or(true);
    if profile_named_default {
        return;
    }
    auth.token_file = Some(ResolvedTokenFile {
        path,
        loaded: true,
        discovered: true,
    });
    auth.bearer_token = Some(token);
}

/// `[auto_scope]` — controls how the hook-published "currently active
/// project" pointer is shared across concurrent callers. The default is
/// `per_actor` (since v1.39), which keys the pointer by whatever coordinate the
/// caller has; `per_session` keys by `session_id`, and `single` keeps the
/// pre-v1.39 process-wide slot (last-write-wins).
///
/// Set under `[auto_scope]` in `config.toml` or via the
/// `AI_MEMORY_AUTO_SCOPE__MODE`, `AI_MEMORY_AUTO_SCOPE__SESSION_TTL_SECS`,
/// and `AI_MEMORY_AUTO_SCOPE__MAX_ENTRIES` env vars.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct AutoScopeSettings {
    /// `per_actor` (default), `per_session`, or `single`. See
    /// [`ai_memory_core::ActiveProjectMode`] for full semantics.
    pub mode: ai_memory_core::ActiveProjectMode,
    /// TTL (seconds) for per-key entries in `per_session`/`per_actor`
    /// modes. Default is 1 hour. Set to 0 to fall back to the default.
    pub session_ttl_secs: u64,
    /// Hard upper bound on the per-key map size, evicting the oldest
    /// insertions first. Default 4096; lower for very small installs,
    /// raise for shared engines with many concurrent agents.
    pub max_entries: usize,
}

impl Default for AutoScopeSettings {
    fn default() -> Self {
        Self {
            mode: ai_memory_core::ActiveProjectMode::default(),
            session_ttl_secs: ai_memory_core::DEFAULT_PER_KEY_TTL.as_secs(),
            max_entries: ai_memory_core::DEFAULT_MAX_ENTRIES,
        }
    }
}

/// `[routing]` section of `config.toml`.
///
/// Set under `[routing]` in `config.toml` or via the
/// `AI_MEMORY_ROUTING__MID_SESSION` env var.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default)]
pub struct RoutingSettings {
    /// `follow-cwd` (default) or `sticky`. See
    /// [`ai_memory_core::MidSessionRouting`] for full semantics.
    pub mid_session: ai_memory_core::MidSessionRouting,
}

/// `[ingest]`: tool events the server drops whatever the client sends
/// (#1241). The tool lists and the event-kind list are all empty by default
/// and apply to every project on the server. Validated once by
/// [`Config::load`] into [`Self::drop_list`].
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default)]
pub struct IngestSettings {
    /// Drop a tool event whose `tool_use_id` starts with one of these.
    pub drop_tool_use_id_prefixes: Vec<String>,
    /// Drop a tool event whose tool name equals one of these exactly.
    pub drop_tool_names: Vec<String>,
    /// Drop whole hook event kinds, whatever the client sends. Each value is a
    /// hook event kind (e.g. `pre-tool-use`); a matching event is acknowledged
    /// and discarded before it is stored. Empty by default (nothing dropped).
    ///
    /// `session-start` and `session-end` are rejected at load: the router uses
    /// them to open and close a session, so dropping them would strand the
    /// session state machine. Accepts either a TOML/JSON sequence
    /// (`["pre-tool-use"]`) or a comma-separated env string
    /// (`AI_MEMORY_INGEST__DROP_EVENTS=pre-tool-use`).
    #[serde(default, deserialize_with = "deserialize_string_or_vec")]
    pub drop_events: Vec<String>,
    /// Name each tool call in its observation: `tool non-file: Bash` instead
    /// of `tool non-file`, plus the skill (`Skill`) or subagent type
    /// (`Agent`) a Claude Code call ran. Only identifiers are kept, never a
    /// tool's arguments, and a call a capture policy reduced to metadata stays
    /// unnamed. Off by default (`AI_MEMORY_INGEST__RECORD_TOOL_NAMES`).
    pub record_tool_names: bool,
    /// The validated list the hook router checks. Set by [`Config::load`];
    /// never read from or written to a config file. Kept off the `Config`
    /// stack frame because that value is constructed in short-stack CLI
    /// entry points on Windows.
    #[serde(skip)]
    pub drop_list: Box<ai_memory_hooks::IngestDropList>,
}

/// Client-side hook spool retry policy.
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
#[serde(default)]
pub struct HookSpoolSettings {
    /// Failed drain passes before an event is dropped; zero disables this limit.
    #[serde(
        default = "default_hook_spool_max_attempts",
        deserialize_with = "deserialize_hook_spool_max_attempts"
    )]
    pub max_attempts: u32,
}

impl Default for HookSpoolSettings {
    fn default() -> Self {
        Self {
            max_attempts: default_hook_spool_max_attempts(),
        }
    }
}

const fn default_hook_spool_max_attempts() -> u32 {
    DEFAULT_HOOK_SPOOL_MAX_ATTEMPTS
}

fn deserialize_hook_spool_max_attempts<'de, D>(deserializer: D) -> Result<u32, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let value = serde_json::Value::deserialize(deserializer)?;
    Ok(value
        .as_u64()
        .and_then(|value| u32::try_from(value).ok())
        .unwrap_or(DEFAULT_HOOK_SPOOL_MAX_ATTEMPTS))
}

impl Default for Config {
    fn default() -> Self {
        Self {
            data_dir: default_data_dir(),
            data_dir_explicit: false,
            bind: DEFAULT_BIND.into(),
            tcp_keepalive_secs: DEFAULT_TCP_KEEPALIVE_SECS,
            server_url: DEFAULT_SERVER_URL.into(),
            server_url_derived_from_bind: false,
            server_url_explicit: false,
            release_base_url: None,
            base_path: String::new(),
            home_dir: None,
            log_level: "info".into(),
            llm_provider: None,
            llm_model: None,
            llm_base_url: None,
            llm_compat_strict: true,
            llm_compat_disable_thinking: false,
            llm_timeout_secs: ai_memory_llm::DEFAULT_REQUEST_TIMEOUT_SECS,
            llm_reasoning_effort: None,
            llm_headers: Vec::new(),
            llm_fallbacks: Vec::new(),
            llm_fallback_configs: Vec::new(),
            llm_fallback_unresolved: Vec::new(),
            consolidate_on_session_end: false,
            capture_assistant: false,
            backfill_on_start: true,
            run_autowire: true,
            run: RunSettings::default(),
            claude_true_yolo: false,
            strip_root_combinators: false,
            gemini_safe_schemas: false,
            reranker: None,
            rerank_timeout_secs: ai_memory_llm::reranker::RERANK_TIMEOUT.as_secs(),
            embedding_provider: None,
            embedding_model: None,
            embedding_dim: None,
            embedding_base_url: None,
            embedding_query_prefix: None,
            embedding_document_prefix: None,
            decay: DecaySettings::default(),
            maintenance: MaintenanceSettings::default(),
            sessions: SessionsSettings::default(),
            contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
            contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
            dream: DreamSettings::default(),
            retrieval: RetrievalSettings::default(),
            search: SearchSettings::default(),
            slots: SlotSettings::default(),
            consolidation: ConsolidationSettings::default(),
            query_answer: QueryAnswerSettings::default(),
            auto_improve: AutoImproveSettings::default(),
            handoff: HandoffSettings::default(),
            profile: ai_memory_core::profile::ProfileSettings::default(),
            sanitize: ai_memory_core::SanitizeConfig::default(),
            auth: AuthSettings::default(),
            auto_scope: AutoScopeSettings::default(),
            routing: RoutingSettings::default(),
            hook_spool: HookSpoolSettings::default(),
            ingest: IngestSettings::default(),
            hook_rate_per_sec: 0.0,
            hook_rate_burst: 0.0,
            allowed_hosts: vec!["localhost".into(), "127.0.0.1".into(), "::1".into()],
            cors_allow_origins: Vec::new(),
            admission_webhooks: Vec::new(),
            runtime_env: RuntimeEnv::default(),
        }
    }
}

/// `[run]` settings for the managed harness launcher.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct RunSettings {
    /// Offer the switch/rerun menu after a successful interactive session.
    /// On by default; `AI_MEMORY_RUN_EXIT_PROMPT=false` or
    /// `run --no-exit-prompt` disables it.
    pub exit_prompt: bool,
    /// Persisted env-only launch profiles, selected with `run --profile`.
    pub profiles: BTreeMap<String, RunProfile>,
    /// Fail a managed launch when the server is unreachable instead of
    /// degrading to a serverless launch (`docs/managed-workstreams.md`).
    /// Off by default; the `--require-server` flag and
    /// `AI_MEMORY_RUN_REQUIRE_SERVER=true` request it per launch or per
    /// environment.
    pub require_server: bool,
}

impl Default for RunSettings {
    fn default() -> Self {
        Self {
            exit_prompt: true,
            profiles: BTreeMap::new(),
            require_server: false,
        }
    }
}

/// One named managed-launch preset.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct RunProfile {
    /// Environment overrides applied before `--env-file` and `--env`.
    pub env: BTreeMap<String, String>,
}

/// A blank `[sanitize] allowlist` entry is a substring of every match, so it
/// would exempt everything from redaction. The sanitizer ignores such entries
/// too; dropping them here is where the operator hears about it.
fn drop_blank_sanitize_allowlist_entries(sanitize: &mut ai_memory_core::SanitizeConfig) {
    let before = sanitize.allowlist.len();
    sanitize.allowlist.retain(|entry| !entry.trim().is_empty());
    let dropped = before - sanitize.allowlist.len();
    if dropped > 0 {
        tracing::warn!(
            dropped,
            "ignoring blank [sanitize] allowlist entries: an empty entry would \
             exempt every match from redaction"
        );
    }
}

fn validate_run_profiles(run: &RunSettings) -> Result<()> {
    const MAX_PROFILES: usize = 128;
    const MAX_PROFILE_NAME: usize = 64;
    const MAX_ENV_PER_PROFILE: usize = 128;
    const MAX_ENV_KEY: usize = 256;
    const MAX_ENV_VALUE: usize = 64 * 1024;

    if run.profiles.len() > MAX_PROFILES {
        anyhow::bail!("run.profiles may contain at most {MAX_PROFILES} profiles");
    }
    for (name, profile) in &run.profiles {
        if name.is_empty()
            || name.len() > MAX_PROFILE_NAME
            || !name
                .bytes()
                .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-'))
        {
            anyhow::bail!(
                "invalid run profile name {name:?}; use 1-{MAX_PROFILE_NAME} ASCII letters, digits, '.', '_' or '-'"
            );
        }
        if profile.env.len() > MAX_ENV_PER_PROFILE {
            anyhow::bail!(
                "run profile {name:?} may contain at most {MAX_ENV_PER_PROFILE} environment entries"
            );
        }
        let mut folded = HashSet::with_capacity(profile.env.len());
        for (key, value) in &profile.env {
            if key.is_empty() || key.len() > MAX_ENV_KEY || key.contains(['=', '\0']) {
                anyhow::bail!("run profile {name:?} has invalid environment key {key:?}");
            }
            if value.len() > MAX_ENV_VALUE || value.contains('\0') {
                anyhow::bail!(
                    "run profile {name:?} environment value for {key:?} is invalid or exceeds {MAX_ENV_VALUE} bytes"
                );
            }
            if !folded.insert(key.to_ascii_uppercase()) {
                anyhow::bail!(
                    "run profile {name:?} repeats environment key {key:?} with different ASCII case"
                );
            }
        }
    }
    Ok(())
}

/// Optional query-answer context admission. Omitted means unlimited admission.
/// The limit counts each UTF-8 input byte as one estimated token and reserves
/// schema, 1024 envelope units and the requested output token allowance.
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
#[serde(default)]
pub struct QueryAnswerSettings {
    /// Conservative combined context target; not a tokenizer-exact guarantee.
    pub max_context_tokens: Option<usize>,
}

/// `[consolidation]` LLM consolidation prompt sizing.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct ConsolidationSettings {
    /// Add bounded literal diagnostics from observations omitted or truncated
    /// by the normal projection. Off by default because it widens the subset
    /// of captured text sent to the configured provider.
    pub verbatim_residue: bool,
    /// Approximate token target for the entire consolidation prompt:
    /// observation dump, current page body, system prompt, page conventions,
    /// slot snapshots, and the structured-output schema.
    ///
    /// The exact tokenizer is provider-specific, so leave headroom. This value
    /// plus [`Self::max_output_tokens`] must fit the model's context window.
    pub max_input_tokens: usize,
    /// Maximum tokens the provider may generate for a consolidation response.
    /// Small-context models must lower this together with `max_input_tokens`.
    pub max_output_tokens: u32,
    /// Safety margin applied to the `max_input_tokens` budget (`0 < m <= 1`).
    ///
    /// `max_input_tokens` is an approximate char-count heuristic (a flat
    /// chars-per-token ratio), so it under-budgets denser corpora — pt-BR text
    /// and source code tokenize at fewer chars per token than English prose and
    /// can overshoot a provider's real input limit by ~40%. This margin shrinks
    /// the effective char budget (default 0.8); lower it further for a corpus
    /// that is mostly non-English or code. (#884)
    pub input_token_safety_margin: f64,
}

impl Default for ConsolidationSettings {
    fn default() -> Self {
        Self {
            verbatim_residue: false,
            max_input_tokens: ai_memory_consolidate::DEFAULT_CONSOLIDATION_MAX_INPUT_TOKENS,
            max_output_tokens: ai_memory_consolidate::DEFAULT_CONSOLIDATION_MAX_OUTPUT_TOKENS,
            input_token_safety_margin:
                ai_memory_consolidate::DEFAULT_CONSOLIDATION_INPUT_TOKEN_SAFETY_MARGIN,
        }
    }
}

/// `[handoff]` session handoff delivery and creation settings.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct HandoffSettings {
    /// When `true` (default — unchanged behavior), a `SessionStart` that
    /// finds a pending handoff claims it automatically, exactly as before
    /// this setting existed.
    ///
    /// When `false`, `SessionStart` does not claim the handoff. It instead
    /// renders a non-consuming notice naming the exact `handoff_id`, the
    /// `from_agent`, and its age — mirroring the existing inbox notice
    /// (`render_inbox_notice`): metadata only, never the stored summary
    /// text, since a handoff's summary is written by whatever agent or
    /// operator ended the prior session and a non-consuming notice cannot be
    /// deliberately skipped the way `memory_handoff_accept` can be left
    /// uncalled. The agent (or operator) picks it up explicitly with
    /// `memory_handoff_accept` using that id. This fixes an unrelated next
    /// session (or a non-interactive launch) silently consuming a baton
    /// meant for a different session (#959).
    ///
    /// Server-wide: applies to every operator on this server. A per-project
    /// override is intentionally left for a follow-up change.
    pub claim_on_session_start: bool,
    /// When `true` (default — unchanged behavior), ending an unmanaged session
    /// creates an automatic open handoff for the next session.
    ///
    /// When `false`, `SessionEnd` writes the session summary page and
    /// enqueues consolidation as usual, but does not create an automatic
    /// handoff (#1043). Explicit handoffs created via `memory_handoff_begin`
    /// and managed runs are unaffected.
    ///
    /// Server-wide: applies to every operator on this server.
    pub create_on_session_end: bool,
}

impl Default for HandoffSettings {
    fn default() -> Self {
        Self {
            claim_on_session_start: true,
            create_on_session_end: true,
        }
    }
}

/// `[auto_improve]` optional post-session reviewer settings.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct AutoImproveSettings {
    /// Background scheduler settings. This controls whether reviews are launched
    /// automatically; it does not control whether accepted proposals are applied.
    pub scheduler: AutoImproveSchedulerSettings,
    /// Optional executable evaluation gate for selected proposal targets.
    pub eval: AutoImproveEvalSettings,
    /// Require manual pending-writes approval. Defaults false so validated
    /// proposals are staged for audit and immediately approved through the
    /// normal wiki write path.
    pub require_approval: bool,
    /// Whether SessionEnd should schedule a reviewer run. Defaults off so hooks
    /// stay cheap and fire-and-forget.
    pub on_session_end: bool,
    /// Minimum observations before a session is worth reviewing.
    pub min_observations: usize,
    /// Minimum span between first and last observation before review.
    pub min_session_duration_secs: u64,
    /// Minimum model confidence accepted by validation.
    pub min_confidence: f32,
    /// Approximate chars/4 prompt budget for review input.
    pub max_input_tokens: usize,
    /// Maximum validated proposals returned from one run.
    pub max_proposals_per_run: usize,
    /// Maximum existing patchable pages included for patch proposals.
    pub max_patchable_pages: usize,
    /// Wiki folder prefixes whose page bodies the reviewer may read.
    ///
    /// Defaults to `_rules/` and `procedures/`. A project that keeps durable
    /// knowledge elsewhere — `decisions/`, `gotchas/` — can add those folders so
    /// the reviewer stops proposing what is already written there (#834).
    #[serde(default = "default_patchable_page_prefixes")]
    pub patchable_page_prefixes: Vec<String>,
    /// Maximum body chars rendered per patchable target page.
    pub max_patchable_body_chars: usize,
    /// Maximum patch edits per proposal.
    pub max_edits_per_proposal: usize,
    /// Maximum content chars in one patch edit.
    pub max_edit_content_chars: usize,
    /// Maximum aggregate changed chars in one patch proposal.
    pub max_changed_chars_per_proposal: usize,
    /// Maximum patch edits accepted across one review run.
    pub max_patch_edits_per_run: usize,
    /// Maximum recent rejection-buffer entries rendered into prompt context.
    pub max_rejection_context: usize,
    /// Maximum age in days for rejection-buffer prompt context.
    pub rejection_context_days: u32,
    /// Maximum materialized final body size.
    pub max_final_body_chars: usize,
    /// Maximum approximate tokens allowed in one _rules/ page.
    pub max_rule_page_tokens: usize,
    /// Maximum approximate tokens allowed in one procedures/ page.
    pub max_procedure_page_tokens: usize,
    /// Whether future reviewers may include raw observation fallback details.
    pub include_raw_fallback: bool,
    /// Synthetic actor used for autonomous proposal provenance.
    pub proposal_actor: String,
    /// Wiki-relative folder for non-indexed pending proposal sidecars.
    pub pending_path: String,
}

/// `[auto_improve.eval]` optional executable proposal gate settings.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct AutoImproveEvalSettings {
    /// Whether the eval command gate is enabled.
    pub enabled: bool,
    /// Executable command plus whitespace-separated args. Executed directly, not through a shell.
    pub command: String,
    /// Built-in scorer, run in-process. `structure` is the only one; it is
    /// mutually exclusive with `command` (#1638).
    pub builtin: String,
    /// Timeout per proposal eval command.
    pub timeout_secs: u64,
    /// Wiki path prefixes that require eval when enabled.
    pub targets: Vec<String>,
    /// Required score_after - score_before when scores are present.
    pub min_delta: f64,
}

impl Default for AutoImproveEvalSettings {
    fn default() -> Self {
        Self {
            enabled: false,
            command: String::new(),
            builtin: String::new(),
            timeout_secs: 120,
            targets: ai_memory_consolidate::default_auto_improve_eval_targets(),
            min_delta: 0.0,
        }
    }
}

/// `[auto_improve.scheduler]` background learning loop settings.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct AutoImproveSchedulerSettings {
    /// Whether the server should periodically review newly-completed sessions.
    pub enabled: bool,
    /// Scheduler cadence. `0` disables the scheduler while keeping manual runs.
    pub interval_secs: u64,
    /// Maximum sessions reviewed per project in one scheduler tick. `0` disables the scheduler.
    pub max_sessions_per_tick: usize,
    /// Minimum age after SessionEnd before a session becomes eligible.
    pub min_session_age_secs: u64,
    /// Cross-session ("experience") pass: run after this many NEW
    /// completed sessions per project. `0` (default) disables the pass —
    /// it is opt-in and shaped by docs/experience.md.
    pub experience_every_sessions: u64,
    /// How many recent session summary pages one experience pass reads.
    pub experience_sessions: usize,
    /// A4 entropy / boilerplate pre-filter for the experience pass
    /// (`[auto_improve.scheduler.experience_entropy_filter]`). Off by default:
    /// low-information session pages are skipped from consolidation only when an
    /// operator enables it. Advisory (skip, never delete).
    pub experience_entropy_filter: ai_memory_consolidate::EntropyFilterConfig,
}

impl Default for AutoImproveSchedulerSettings {
    fn default() -> Self {
        Self {
            enabled: true,
            interval_secs: 3_600,
            max_sessions_per_tick: 1,
            min_session_age_secs: 600,
            experience_every_sessions: 0,
            experience_sessions: 10,
            experience_entropy_filter: ai_memory_consolidate::EntropyFilterConfig::default(),
        }
    }
}

impl Default for AutoImproveSettings {
    fn default() -> Self {
        Self {
            scheduler: AutoImproveSchedulerSettings::default(),
            eval: AutoImproveEvalSettings::default(),
            require_approval: false,
            on_session_end: false,
            min_observations: ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MIN_OBSERVATIONS,
            min_session_duration_secs:
                ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MIN_SESSION_DURATION_SECS,
            min_confidence: DEFAULT_AUTO_IMPROVE_MIN_CONFIDENCE,
            max_input_tokens: ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_INPUT_TOKENS,
            max_proposals_per_run: ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_PROPOSALS,
            max_patchable_pages: ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_PATCHABLE_PAGES,
            patchable_page_prefixes: default_patchable_page_prefixes(),
            max_patchable_body_chars:
                ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_PATCHABLE_BODY_CHARS,
            max_edits_per_proposal:
                ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_EDITS_PER_PROPOSAL,
            max_edit_content_chars:
                ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_EDIT_CONTENT_CHARS,
            max_changed_chars_per_proposal:
                ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_CHANGED_CHARS_PER_PROPOSAL,
            max_patch_edits_per_run:
                ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_PATCH_EDITS_PER_RUN,
            max_rejection_context:
                ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_REJECTION_CONTEXT,
            rejection_context_days:
                ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_REJECTION_CONTEXT_DAYS,
            max_final_body_chars: ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_FINAL_BODY_CHARS,
            max_rule_page_tokens: ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_RULE_PAGE_TOKENS,
            max_procedure_page_tokens:
                ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_PROCEDURE_PAGE_TOKENS,
            include_raw_fallback: false,
            proposal_actor: ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_PROPOSAL_ACTOR.into(),
            pending_path: ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_PENDING_PATH.into(),
        }
    }
}

/// `[slots]` memory-slot behaviour.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default)]
pub struct SlotSettings {
    /// Namespace engine-written slots under the operator that produced them
    /// (`_slots/u-alice/current-focus.md` instead of
    /// `_slots/current-focus.md`). The segment is the operator's
    /// `IdentityKey::path_segment()` — `u-<name>` for lowercase safe usernames
    /// and a bounded deterministic identifier for mixed-case, Windows-unsafe,
    /// or otherwise path-hostile usernames and complete OIDC issuer/subject
    /// pairs — never a raw OIDC value.
    ///
    /// Off by default, so nothing changes for an existing install: with the
    /// flag off a nested slot path carries no ownership meaning at all, and
    /// every slot goes into every brief exactly as it did before.
    ///
    /// Turning it ON changes reads and writes, in both directions:
    ///
    /// * a session brief and the consolidation prompt see the shared slots
    ///   plus the requesting operator's own — so a slot already stored under
    ///   `_slots/<segment>/…` becomes visible to that operator alone;
    /// * writing into another operator's namespace is refused (admins aside);
    /// * a write naming the SHARED slot is namespaced into the writer's own
    ///   prefix, whether it comes from the engine or from `memory_write_page`.
    ///
    /// What the flag scopes is INJECTION, not access: an exact-path read
    /// still returns anyone's slot, like any other page.
    ///
    /// Turning it back OFF restores the pre-feature rule everywhere: personal
    /// slots become visible to everyone again and nested writes stop being
    /// gated. Un-namespaced slots are shared under either setting, so nothing
    /// already stored is ever hidden or reinterpreted.
    ///
    /// Only meaningful once requests carry distinct identities; with a single
    /// shared credential every slot lands under the same namespace.
    pub per_user: bool,
}

/// `[maintenance]` scheduled server jobs.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct MaintenanceSettings {
    /// Master switch for scheduled jobs.
    pub enabled: bool,
    /// Interval for the retention forget sweep. `0` disables this job. Successful
    /// runs persist cadence across restarts; overdue work starts after a bounded
    /// startup delay.
    pub forget_sweep_interval_secs: u64,
    /// Interval for rule-based wiki lint. `0` disables this job. Successful runs
    /// persist cadence across restarts; overdue work starts after a bounded
    /// startup delay.
    pub lint_interval_secs: u64,
    /// Interval for embedding backfill. `0` disables this job.
    /// Defaults to off because it may call a paid provider.
    pub embedding_backfill_interval_secs: u64,
    /// Opt-in reconcile-delete safety net (#929). When `true`, the watcher's
    /// 30s reconcile pass tombstones (`is_latest = 0` + `superseded_at`, never
    /// a filesystem touch or a BLOCKING admission dispatch) an OKF-imported
    /// content page (session summary pages are excluded — a same-workspace
    /// `move-session` re-home can leave one with a correct row and no file, a
    /// separate pre-existing bug) whose file has been missing on two
    /// consecutive passes, after a circuit breaker that refuses to act on a
    /// scope where more than `max(3, 50%)` of its candidate pages look
    /// missing at once, or where a non-partial walk finds nothing at all
    /// (see `ai_memory_wiki::watcher::reconcile_delete_breaker_threshold`) —
    /// either shape is far more likely a walk/mount problem (an unmounted
    /// volume, a git checkout mid-walk) than genuine deletions.
    ///
    /// The tombstone is NOT exempt from the aged-tombstone hard-delete sweep
    /// (`hard_delete_after_days`) — the actual guarantee is narrower: a
    /// reconcile tombstone is never itself destroyed while its chain has no
    /// successor. If the file returns, the new version re-links to the
    /// tombstoned chain (`ops::upsert_page_in_tx`'s resurrection path)
    /// instead of starting fresh, so nothing is orphaned for that sweep to
    /// destroy.
    ///
    /// Defaults to `false`: with this off, reconcile's behavior is
    /// byte-identical to before this feature existed — deletions still
    /// require `ai-memory delete-page`, and nothing new is logged. Doc:
    /// `docs/okf.md`, `docs/install.md`.
    pub reconcile_tombstones_deleted_pages: bool,
}

impl Default for MaintenanceSettings {
    fn default() -> Self {
        Self {
            enabled: true,
            forget_sweep_interval_secs: 86_400,
            lint_interval_secs: 86_400,
            embedding_backfill_interval_secs: 0,
            reconcile_tombstones_deleted_pages: false,
        }
    }
}

/// `[sessions]` server-side session lifecycle.
///
/// Env form: `AI_MEMORY_SESSIONS__IDLE_END_AFTER_HOURS=24`.
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
#[serde(default)]
pub struct SessionsSettings {
    /// Hours of silence after which the maintenance tick ends an open
    /// session that never received a `SessionEnd` (crashed harness, closed
    /// terminal, timed-out hook): summary page + consolidation job, no
    /// handoff. `0` (the default) disables the tick — the explicit
    /// `finalize-on-exit` / `repair-backfill-timestamps` path stays the only
    /// end for sessions an operator may still come back to.
    pub idle_end_after_hours: u32,
}

/// `[dream]` — the opt-in LLM dream pass (docs/design-memory-aging.md §B2–B4).
///
/// OFF by default (`enabled = false`): the scheduled job is not started, and even
/// a direct call is a clean no-op. It runs only when this flag is set AND a
/// provider AND an embedder are configured; a provider-less store keeps the
/// zero-LLM A3 path (invariant #13). Gated on an R2 number before default-on.
///
/// Env form: `AI_MEMORY_DREAM__ENABLED=true`,
/// `AI_MEMORY_DREAM__IDLE_WINDOW_SECS=600`.
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
#[serde(default)]
pub struct DreamSettings {
    /// Master switch. `false` (the default) means the job never starts.
    pub enabled: bool,
    /// How often the scheduler CONSIDERS a run (seconds). It still only runs when
    /// the operator has been idle for `idle_window_secs`. `0` ⇒ a conservative
    /// default cadence.
    pub interval_secs: u64,
    /// Idle window (seconds) the operator must be quiet for before a run starts,
    /// and past which returning activity cancels an in-flight run (B3). `0` ⇒
    /// [`ai_memory_consolidate::DEFAULT_DREAM_IDLE_WINDOW_SECS`].
    pub idle_window_secs: u64,
    /// DBSCAN density floor. `0` ⇒ the conservative default (2).
    pub min_pts: usize,
    /// Conservative eps ceiling (cosine distance). `0.0` ⇒ the conservative
    /// default; lower errs harder toward NOT merging.
    pub max_eps: f32,
    /// Hard cap on clusters rewritten per run (bounded fan-out, invariant #5).
    /// `0` ⇒ [`ai_memory_consolidate::DEFAULT_DREAM_MAX_CLUSTERS_PER_RUN`].
    pub max_clusters_per_run: usize,
    /// Minimum cold pages before a run does work (the events-accrued gate). `0` ⇒
    /// [`ai_memory_consolidate::DEFAULT_DREAM_MIN_COLD_PAGES`].
    pub min_cold_pages: usize,
}

impl Default for DreamSettings {
    fn default() -> Self {
        Self {
            enabled: false,
            // A conservative default cadence: the job wakes hourly to check
            // whether the box has been idle long enough to run.
            interval_secs: 3_600,
            idle_window_secs: 0,
            min_pts: 0,
            max_eps: 0.0,
            max_clusters_per_run: 0,
            min_cold_pages: 0,
        }
    }
}

impl DreamSettings {
    /// The effective scheduler interval in seconds (never zero).
    #[must_use]
    pub fn effective_interval_secs(self) -> u64 {
        if self.interval_secs == 0 {
            3_600
        } else {
            self.interval_secs
        }
    }

    /// Build the [`ai_memory_consolidate::DreamConfig`] for the pass.
    ///
    /// `embedding` is the running server's configured embedder coordinate, or
    /// `None` when no embedder is configured — in which case the dream pass is a
    /// clean no-op even with the flag on (there are no stored vectors).
    #[must_use]
    pub fn dream_config(
        self,
        embedding: Option<ai_memory_consolidate::EmbeddingCoord>,
    ) -> ai_memory_consolidate::DreamConfig {
        ai_memory_consolidate::DreamConfig {
            enabled: self.enabled,
            embedding,
            min_pts: self.min_pts,
            max_eps: self.max_eps,
            max_clusters_per_run: self.max_clusters_per_run,
            min_cold_pages: self.min_cold_pages,
            idle_window_secs: self.idle_window_secs,
        }
    }
}

/// `[retrieval]` ranking signals layered on the RRF fusion in
/// `memory_query`. Only `observation_stream` is on by default; with it
/// turned off, every other default leaves ranking byte-identical to a store
/// that never heard of this section.
///
/// Env form: `AI_MEMORY_RETRIEVAL__QUERY_INTENT=true`,
/// `AI_MEMORY_RETRIEVAL__ABSTRACT_VECTORS=true`,
/// `AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=false`.
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
#[serde(default)]
pub struct RetrievalSettings {
    /// Lexical session-recall routing: queries phrased as "find a past
    /// session / what we did back then" ("上次 / …的会话 / last time /
    /// yesterday …") hand session pages back their default kind/tier
    /// authority penalty so they can compete for these queries.
    pub query_intent: bool,
    /// Extra authority granted to session pages when the routing fires,
    /// on top of cancelling their default kind/tier penalty.
    pub session_recall_bonus: f64,
    /// Add the L0 abstract-embedding stream (`page_abstract_embeddings`) to
    /// the RRF fusion. Pages gain an abstract vector when their frontmatter
    /// carries `abstract:` and the embedding backfill runs.
    pub abstract_vectors: bool,
    /// Weight of the belief-strength confidence factor folded into page
    /// authority (P2). `0.0` (the default) is inert — ranking is byte-identical
    /// and no belief query runs. Positive folds a page's evidence-derived
    /// `confidence` into its authority factor, inside the existing bounds.
    /// OFF by default: enabling it is gated on a positive R2 delta.
    pub belief_authority_weight: f64,
    /// Add the observation-evidence stream (R1) to the RRF fusion: matching
    /// observation bodies vote, once per session, for that session's latest
    /// `sessions/<id>.md` page in the same project. Read-only; the wiki is
    /// not enlarged. ON by default; `false` restores the previous ranking.
    pub observation_stream: bool,
}

impl Default for RetrievalSettings {
    fn default() -> Self {
        let base = ai_memory_store::RetrievalTuning::default();
        Self {
            query_intent: base.session_recall_routing,
            session_recall_bonus: base.session_recall_bonus,
            abstract_vectors: base.abstract_vectors,
            belief_authority_weight: base.belief_authority_weight,
            observation_stream: base.observation_stream,
        }
    }
}

impl RetrievalSettings {
    /// Store-side tuning consumed by `ReaderPool::set_retrieval_tuning`.
    #[must_use]
    pub fn tuning(self) -> ai_memory_store::RetrievalTuning {
        ai_memory_store::RetrievalTuning {
            session_recall_routing: self.query_intent,
            session_recall_bonus: self.session_recall_bonus.max(0.0),
            abstract_vectors: self.abstract_vectors,
            // A negative weight would flip the boost into a penalty on
            // supported pages; clamp it out so misconfiguration is inert, not
            // inverted.
            belief_authority_weight: self.belief_authority_weight.max(0.0),
            observation_stream: self.observation_stream,
        }
    }
}

/// Upper bound on `search.fts.stopwords` list length: a stopword filter is a
/// short function-word list (the built-in English one has ~60 entries), not
/// a document blocklist. Rejected at load rather than silently accepted and
/// then slow (or meaningless) at search time.
const MAX_FTS_STOPWORDS: usize = 2000;
/// Upper bound on a single `search.fts.stopwords` entry, in Unicode scalar
/// values. Stopwords are short function words; a value this size is almost
/// certainly a misconfiguration (a pasted sentence, a stray delimiter).
const MAX_FTS_STOPWORD_LEN: usize = 64;

/// `[search]` search-path tuning that is not itself a ranking signal —
/// contrast with `[retrieval]`, which is. Today this holds only the FTS
/// stopword list (issue #953).
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default)]
pub struct SearchSettings {
    /// FTS5 query-preparation tuning.
    pub fts: FtsSettings,
}

/// `[search.fts]` bare natural-language FTS query preparation.
///
/// Env form: `AI_MEMORY_SEARCH_FTS_STOPWORDS` (a comma-separated string),
/// the same convention `allowed_hosts` / `cors_allow_origins` /
/// `auth.trusted_proxy_cidrs` use for a `Vec<String>` via
/// `deserialize_string_or_vec`. This key does NOT go through that shared
/// helper or the usual `__`-split figment `Env` layer, though: figment
/// merges raw values before any deserializer runs, so a *present but blank*
/// env var would silently replace a real `config.toml` list with nothing at
/// the value level — there is no chance for a deserializer to treat "blank"
/// specially after the fact. `stopwords` also carries a real meaning for
/// "empty" (`[]` disables filtering outright) that must not be confused with
/// "the env var happened to be unset/blank", so this key is read once in
/// `Config::load` (see `apply_fts_stopwords_env`) and only overrides when the
/// env var is set to a non-blank value — the same pattern
/// `overlay_embedding_prefixes` uses for `AI_MEMORY_EMBEDDING_QUERY_PREFIX`.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default)]
pub struct FtsSettings {
    /// Words dropped from a bare (non-explicit-syntax) natural-language FTS
    /// query, and from the bag-of-words fallback for syntax that does not
    /// parse, before the OR-join
    /// (`ai_memory_store::fts_query::prepare_fts5_query`).
    ///
    /// - **Absent** (the default, `None`): the built-in English list —
    ///   byte-identical to every install that predates this key.
    /// - **`[]`** (`Some(vec![])`): disables the filter entirely — every
    ///   token, including English function words, survives the OR-join.
    /// - **A non-empty list**: replaces the default outright with exactly
    ///   those words (trimmed and validated by `Config::load`).
    ///
    /// Comparison folds full Unicode case (not ASCII-only) but never strips
    /// diacritics — see `ai_memory_store::fts_query::FtsStopwords`'s doc
    /// comment for the exact fold and why. In short: what matters here is
    /// how a query is actually TYPED, not how wiki content is spelled —
    /// content matches through the FTS index's own diacritic-folding
    /// tokenizer regardless of this filter, but a bare query's stopword
    /// check only ever sees the literal characters someone typed. A list
    /// for an accented language should include every spelling a user or
    /// agent might type, e.g. Portuguese `"e"` AND `"é"`, `"nao"` AND
    /// `"não"`. Also note the filter matches whitespace-split raw tokens
    /// before any punctuation handling, so an entry never matches a token
    /// with attached punctuation (`"de,"`, `"que?"`) — the same limitation
    /// English stopwords have always had. The fallback for syntax that does
    /// not parse strips quotes and parens first, and keeps quoted words.
    ///
    /// A non-English or mixed-language wiki should set this to that
    /// language's function words, or to `[]`: left unset, only the built-in
    /// English list is filtered, so another language's high-document-frequency
    /// function words (`em`, `de`, `que`, `uma`, …) pass straight through the
    /// OR-join and contaminate BM25 term-frequency scoring for every page
    /// that happens to contain them (issue #953). Configuring this list does
    /// not retroactively fix anything by itself — an install has to opt in.
    pub stopwords: Option<Vec<String>>,
}

impl FtsSettings {
    /// Store-side stopword set consumed by `ReaderPool::set_fts_stopwords`.
    /// Assumes `Config::load` already validated `stopwords` (entry count and
    /// length bounds) — this method does not re-validate.
    #[must_use]
    pub fn stopwords(&self) -> ai_memory_store::FtsStopwords {
        match &self.stopwords {
            None => ai_memory_store::FtsStopwords::default(),
            Some(words) => ai_memory_store::FtsStopwords::new(words),
        }
    }

    /// Validate and normalize `stopwords` in place: trims each entry's ends
    /// (a hand-edited `config.toml` or a CSV env override can easily carry a
    /// stray space) rather than rejecting it, then rejects a bound violation
    /// or an entry with INTERNAL whitespace. A bare FTS query is tokenized
    /// with `str::split_whitespace()` (`ai_memory_store::fts_query`), so a
    /// multi-word entry like `"de la"` could never equal one token — it
    /// would look configured while silently doing nothing.
    ///
    /// # Errors
    /// Returns a message naming the offending bound or entry, always
    /// prefixed `search.fts.stopwords` so the error is self-locating.
    fn validate(&mut self) -> Result<(), String> {
        let Some(words) = self.stopwords.as_mut() else {
            return Ok(());
        };
        if words.len() > MAX_FTS_STOPWORDS {
            return Err(format!(
                "search.fts.stopwords must have at most {MAX_FTS_STOPWORDS} entries (got {}); \
                 this filters function words out of bare FTS queries, not a document blocklist",
                words.len()
            ));
        }
        for word in words.iter_mut() {
            let trimmed = word.trim();
            if trimmed.is_empty() {
                return Err(
                    "search.fts.stopwords entries must not be empty or whitespace-only".to_string(),
                );
            }
            if trimmed.chars().count() > MAX_FTS_STOPWORD_LEN {
                return Err(format!(
                    "search.fts.stopwords entry {word:?} exceeds the {MAX_FTS_STOPWORD_LEN}-\
                     character limit (stopwords are short function words, not phrases or \
                     sentences)"
                ));
            }
            if trimmed.split_whitespace().count() > 1 {
                return Err(format!(
                    "search.fts.stopwords entry {word:?} contains internal whitespace; a bare \
                     FTS query is split on whitespace before comparison, so a multi-word entry \
                     can never match one token"
                ));
            }
            if trimmed != word {
                *word = trimmed.to_string();
            }
        }
        Ok(())
    }
}

/// Point `server_url` at the server `bind` starts, when nothing named one
/// (#1269).
///
/// Only runs when neither the config file nor `AI_MEMORY_SERVER_URL` set
/// `server_url` (`explicit_server_url`), even to the default URL itself.
///
/// Rules, matching the reporter's proposal:
/// - an unspecified address becomes loopback, because it is not itself a
///   reachable target (`0.0.0.0` -> `127.0.0.1`, `[::]` -> `[::1]`);
/// - any other host is used as given, hostname included, since the server may
///   bind a name this process cannot resolve the same way;
/// - a `bind` that does not parse as `host:port` leaves the default URL alone
///   rather than building one out of a fragment. `serve` still rejects the bad
///   bind at startup, so the operator sees the real error there.
///
/// The default `bind` derives exactly [`DEFAULT_SERVER_URL`], so an install
/// that never touched either key is byte-identical to before.
fn derive_server_url_from_bind(config: &mut Config, explicit_server_url: bool) {
    if explicit_server_url || config.server_url != DEFAULT_SERVER_URL {
        return;
    }
    // A bind that differs from the default is the case this exists for; the
    // default derives the same URL, so skip the parse entirely for it.
    if config.bind == DEFAULT_BIND {
        return;
    }
    let Some(url) = server_url_for_bind(&config.bind) else {
        return;
    };
    // A bind that resolves to the default URL anyway (a container's
    // `0.0.0.0:49374`) changes nothing, so it is not marked derived.
    if url == DEFAULT_SERVER_URL {
        return;
    }
    config.server_url = url;
    config.server_url_derived_from_bind = true;
}

/// The client URL for one `bind` value, or `None` when it is not a
/// `host:port` this can turn into a URL.
///
/// Parsed by hand rather than with `SocketAddr` so a HOSTNAME survives: a
/// server may bind `memory.lan:9000`, and resolving it here would both change
/// which address the client dials and fail outright on a host this process
/// cannot resolve but the server can.
fn server_url_for_bind(bind: &str) -> Option<String> {
    let bind = bind.trim();
    // Split on the LAST colon so an IPv6 literal in brackets, which contains
    // colons of its own, keeps its host in one piece.
    let (host, port) = bind.rsplit_once(':')?;
    let port: u16 = port.parse().ok()?;
    // Port 0 asks the OS for any free port, so no client can know it in
    // advance; keep the default URL.
    if host.is_empty() || port == 0 {
        return None;
    }
    let host = if host == "0.0.0.0" {
        "127.0.0.1".to_string()
    } else if host == "[::]" {
        "[::1]".to_string()
    } else if host.starts_with('[') {
        // An IPv6 literal must carry its brackets into the URL.
        if !host.ends_with(']') {
            return None;
        }
        host.to_string()
    } else if host.contains(':') {
        // A bare IPv6 literal, or a bracketed one split wrong. Rejecting is
        // safer than emitting a URL whose host cannot be read back.
        return None;
    } else {
        host.to_string()
    };
    Some(format!("http://{host}:{port}"))
}

/// Parse the `AI_MEMORY_SEARCH_FTS_STOPWORDS` env override into
/// `config.search.fts.stopwords`, following the CSV-string convention
/// `deserialize_string_or_vec` already uses for `allowed_hosts` /
/// `cors_allow_origins` / `auth.trusted_proxy_cidrs`.
///
/// Not wired through the usual `__`-split figment `Env` layer +
/// `deserialize_with`, because that layer merges RAW values across
/// providers before any deserializer runs: a present-but-blank env var
/// would silently replace a real `config.toml` list with nothing at the
/// value level, before a deserializer ever got a chance to treat "blank"
/// specially. Reading and applying it here instead, once, as data — the
/// same pattern `overlay_embedding_prefixes` uses — lets an unset OR blank
/// env var leave whatever `config.toml`/the default already resolved
/// untouched, while a real comma list still overrides it. `raw` is the
/// value already read by the caller (`Config::load`), so this stays
/// directly unit-testable without mutating process env.
fn apply_fts_stopwords_env(config: &mut Config, raw: Option<&str>) {
    let Some(raw) = raw else { return };
    if raw.trim().is_empty() {
        // A present-but-blank env var means "unset" here, not "disable
        // filtering" — an empty `config.toml` `stopwords = []` is still the
        // unambiguous way to ask for that.
        return;
    }
    config.search.fts.stopwords = Some(
        raw.split(',')
            .map(|w| w.trim().to_string())
            .filter(|w| !w.is_empty())
            .collect(),
    );
}

fn apply_hook_spool_max_attempts_env(config: &mut Config, raw: Option<&str>) {
    let Some(raw) = raw else { return };
    config.hook_spool.max_attempts = raw
        .trim()
        .parse()
        .unwrap_or(DEFAULT_HOOK_SPOOL_MAX_ATTEMPTS);
}

/// `AI_MEMORY_RUN_REQUIRE_SERVER` only ever turns the fail-closed behavior
/// on: an absent, blank, or non-truthy value leaves whatever `config.toml`
/// selected, and only an explicit truthy spelling overrides it to on.
fn apply_run_require_server_env(config: &mut Config, raw: Option<&str>) {
    let Some(raw) = raw else { return };
    if crate::marker::is_truthy(raw) {
        config.run.require_server = true;
    }
}

impl Config {
    /// Load the merged configuration: defaults → file → env → CLI.
    ///
    /// # Errors
    /// Returns an error if the config file is malformed or any required
    /// field is missing.
    pub fn load(config_path: Option<&Path>, cli_data_dir: Option<PathBuf>) -> Result<Self> {
        Self::load_with_runtime_env(config_path, cli_data_dir, RuntimeEnv::from_process())
    }

    pub(crate) fn load_with_runtime_env(
        config_path: Option<&Path>,
        cli_data_dir: Option<PathBuf>,
        runtime_env: RuntimeEnv,
    ) -> Result<Self> {
        // Figure out where the config file *would* live so we can read it
        // before knowing the final data dir. CLI > env > default.
        let probe_data_dir = cli_data_dir
            .clone()
            .or_else(|| runtime_env.data_dir.clone())
            .unwrap_or_else(default_data_dir);
        let resolved_config_path = config_path
            .map(PathBuf::from)
            .unwrap_or_else(|| probe_data_dir.join("config.toml"));

        let mut figment = Figment::from(Serialized::defaults(Self::default()));
        if resolved_config_path.exists() {
            figment = figment.merge(Toml::file(&resolved_config_path));
        }
        figment = figment.merge(Env::prefixed("AI_MEMORY_").split("__"));
        // The environment is read once, here, and passed down as data —
        // never inside `overlay_embedding_prefixes` itself — so that
        // function stays directly testable without mutating process env or
        // cwd (see its doc comment).
        figment = overlay_embedding_prefixes(
            figment,
            std::env::var("AI_MEMORY_EMBEDDING_QUERY_PREFIX")
                .ok()
                .as_deref(),
            std::env::var("AI_MEMORY_EMBEDDING_DOCUMENT_PREFIX")
                .ok()
                .as_deref(),
        );

        let mut config: Config = figment.extract().with_context(|| {
            format!(
                "loading configuration (config file = {})",
                resolved_config_path.display()
            )
        })?;

        if let Some(token) = runtime_env.auth_token.clone() {
            config.auth.bearer_token = Some(token);
        }
        // Whether the file or the environment named a server URL. `server_url`
        // is the one key #1269 derives rather than only defaulting, and the
        // derivation must not fire when either source set it, even to the
        // default URL itself, so the file is asked for the key rather than
        // the loaded value being compared against the default.
        let explicit_server_url = runtime_env.server_url.is_some()
            || (resolved_config_path.exists()
                && Figment::from(Toml::file(&resolved_config_path))
                    .find_value("server_url")
                    .is_ok());
        config.server_url_explicit = explicit_server_url;
        if let Some(server_url) = runtime_env.server_url.clone() {
            config.server_url = server_url;
        }
        // Convenience env override for the admission webhook list. Figment
        // can't reliably round-trip `Vec<Struct>` from `AI_MEMORY_X__0__Y`
        // (env split builds a Map, not a Vec), so we accept a single
        // JSON-encoded env var instead — perfect for charts that
        // `toJson` a values.yaml list. Overrides anything figment loaded
        // from file/other env layers.
        if let Ok(raw) = std::env::var("AI_MEMORY_ADMISSION_WEBHOOKS_JSON")
            && !raw.trim().is_empty()
        {
            let parsed: Vec<ai_memory_wiki::WebhookConfig> = serde_json::from_str(&raw)
                .with_context(|| {
                    "parsing AI_MEMORY_ADMISSION_WEBHOOKS_JSON (must be a JSON array of \
                     {name,url,timeout_ms?,failure_policy?,events})"
                })?;
            config.admission_webhooks = parsed;
        }
        // FTS stopword list (issue #953): CSV env override, applied as data
        // (see `apply_fts_stopwords_env`'s doc comment for why this can't go
        // through the usual `__`-split figment `Env` layer).
        apply_fts_stopwords_env(
            &mut config,
            std::env::var("AI_MEMORY_SEARCH_FTS_STOPWORDS")
                .ok()
                .as_deref(),
        );
        apply_hook_spool_max_attempts_env(&mut config, runtime_env.hook_spool_max_attempts());
        apply_run_require_server_env(&mut config, runtime_env.run_require_server());
        // The flat spelling would otherwise resolve to `run_exit_prompt`,
        // not `run.exit_prompt`, through figment's `__` split.
        if let Some(raw) = runtime_env.var_os("AI_MEMORY_RUN_EXIT_PROMPT") {
            config.run.exit_prompt = raw
                .to_str()
                .and_then(|value| value.trim().parse().ok())
                .context("AI_MEMORY_RUN_EXIT_PROMPT must be true or false")?;
        }

        // Home is captured once in RuntimeEnv (config-read-path invariant);
        // threaded to the resolver guard and startup heal so neither reads the
        // env directly. AI_MEMORY_HOME is accepted for tests/wrappers that need
        // to emulate a host home distinct from the process HOME. Native Windows
        // often has no HOME; USERPROFILE (then dirs::home_dir) fills that gap
        // so the #103 catch-all guard is not inert there.
        config.home_dir = runtime_env.home_dir.as_deref().and_then(normalize_home_dir);

        // As with `server_url`, the file is asked for the key: a chosen dir
        // equal to the default still counts as chosen.
        config.data_dir_explicit = cli_data_dir.is_some()
            || runtime_env.data_dir.is_some()
            || (resolved_config_path.exists()
                && Figment::from(Toml::file(&resolved_config_path))
                    .find_value("data_dir")
                    .is_ok());
        // CLI override always wins (figment doesn't see it because clap has
        // already parsed the flag into `cli_data_dir`).
        if let Some(dir) = cli_data_dir {
            config.data_dir = dir;
        } else if let Some(dir) = runtime_env.data_dir.clone() {
            config.data_dir = dir;
        }

        config.data_dir = canonicalise_or_keep(&config.data_dir);
        // #1269: with neither the file nor the environment naming a server
        // URL, reach the server this same config starts rather than the
        // compiled-in default. A thin client that ignored `bind` either failed
        // (nothing on the default port) or, worse, operated on whatever
        // server WAS on the default port -- which is how the reporter wrote
        // test pages into their real store.
        derive_server_url_from_bind(&mut config, explicit_server_url);
        apply_bearer_token_file(
            &mut config.auth,
            &TokenFileContext {
                data_dir: &config.data_dir,
                env_token: runtime_env.auth_token.is_some(),
                config_file_exists: resolved_config_path.exists(),
                server_url: &config.server_url,
            },
        )?;
        config.runtime_env = runtime_env;

        validate_run_profiles(&config.run)?;
        drop_blank_sanitize_allowlist_entries(&mut config.sanitize);

        // The idle auto-end tick turns `idle_end_after_hours` into a
        // microsecond cutoff: a value above a year is a configuration
        // mistake (a typo of minutes for days), and a huge value would also
        // push the cutoff microsecond arithmetic toward `i64` overflow.
        // Bound it at load rather than at 3am inside the tick.
        if config.sessions.idle_end_after_hours > 8760 {
            anyhow::bail!(
                "sessions.idle_end_after_hours must be 0 (off) or at most 8760 hours \
                 (one year); got {}",
                config.sessions.idle_end_after_hours
            );
        }

        if !config.decay.breadth_weight.is_finite() || config.decay.breadth_weight < 0.0 {
            anyhow::bail!(
                "decay.breadth_weight must be a finite number greater than or equal to zero"
            );
        }

        // A per-tier half-life must be a real, positive number of days: `0` (or
        // negative/NaN) would convert to a nonsensical λ (+inf / negative /
        // NaN) and silently mass-evict or never decay that tier. Reject it at
        // load rather than at 3am inside the sweep. An unset key is fine — it
        // falls back to the scalar `lambda`.
        for (tier, value) in [
            ("working", config.decay.half_life_days.working),
            ("episodic", config.decay.half_life_days.episodic),
            ("semantic", config.decay.half_life_days.semantic),
            ("procedural", config.decay.half_life_days.procedural),
        ] {
            if let Some(days) = value
                && (!days.is_finite() || days <= 0.0)
            {
                anyhow::bail!(
                    "decay.half_life_days.{tier} must be a finite number greater than zero \
                     (got {days}); omit the key to use the default decay rate"
                );
            }
        }

        // Fail closed at load rather than at 3am inside a destructive pass: a
        // negative age would be a nonsensical cutoff, and a zero batch would
        // spin the prune loop forever without deleting anything.
        if config.decay.observation_retention_days < 0 {
            anyhow::bail!(
                "decay.observation_retention_days must be greater than or equal to zero \
                 (0 disables observation pruning)"
            );
        }
        if config.decay.observation_prune_batch == 0 {
            anyhow::bail!("decay.observation_prune_batch must be greater than zero");
        }
        // The same fail-closed rule for the opt-in ledger sweep: a negative
        // age is not a cutoff, and this pass deletes files.
        if config.decay.ledger_retention_months < 0 {
            anyhow::bail!(
                "decay.ledger_retention_months must be greater than or equal to zero \
                 (0 disables ledger deletion)"
            );
        }
        // A5 zero-LLM contradiction band (`memory_lint`): both edges must be
        // finite and inside cosine similarity's own range, and the band must
        // be non-empty. An inverted or out-of-range band would either
        // silently disable A5 (no pair ever falls inside an empty range) or
        // compare against a meaningless similarity value; reject it at load
        // rather than inside the lint pass.
        if !config.contradiction_band_min.is_finite()
            || !config.contradiction_band_max.is_finite()
            || config.contradiction_band_min < 0.0
            || config.contradiction_band_max > 1.0
            || config.contradiction_band_min >= config.contradiction_band_max
        {
            anyhow::bail!(
                "contradiction_band_min/contradiction_band_max must satisfy \
                 0.0 <= contradiction_band_min < contradiction_band_max <= 1.0 \
                 (got min={}, max={})",
                config.contradiction_band_min,
                config.contradiction_band_max
            );
        }
        // FTS stopword list (issue #953): a configured list is a short
        // function-word table, not a document blocklist or free-text field.
        // Reject an oversized or malformed list (or normalize a trimmable
        // one) at startup rather than shipping a slow, meaningless, or
        // silently-inert filter into every search.
        if let Err(message) = config.search.fts.validate() {
            anyhow::bail!("{message}");
        }
        config.ingest.drop_list = Box::new(
            ai_memory_hooks::IngestDropList::new(
                config.ingest.drop_tool_use_id_prefixes.clone(),
                config.ingest.drop_tool_names.clone(),
                &config.ingest.drop_events,
            )
            .map_err(|message| anyhow::anyhow!(message))?,
        );
        // One scorer per gate: an operator who set both meant one of them, and
        // silently ignoring the builtin (as the gate does) would leave a config
        // that reads as if it ran both (#1638).
        let eval = &config.auto_improve.eval;
        if !eval.builtin.trim().is_empty() && !eval.command.trim().is_empty() {
            anyhow::bail!(
                "auto_improve.eval.builtin and auto_improve.eval.command are mutually exclusive; \
                 remove one (builtin `structure` runs in-process, a command runs your own scorer)"
            );
        }
        let builtin = eval.builtin.trim();
        if !builtin.is_empty() && builtin != "structure" {
            anyhow::bail!(
                "auto_improve.eval.builtin `{builtin}` is not a known scorer; the only one is \
                 `structure`"
            );
        }

        // A4 entropy filter thresholds: reject an unusable threshold at startup
        // rather than silently ignoring it on the first experience pass.
        if let Err(message) = config
            .auto_improve
            .scheduler
            .experience_entropy_filter
            .validate()
        {
            anyhow::bail!("auto_improve.scheduler.experience_{message}");
        }

        // The safety margin scales the input budget, so a non-positive value
        // would starve every prompt and one above 1.0 would loosen the budget
        // past the nominal token limit it is meant to tighten (#884). NaN also
        // fails every comparison below, so it is rejected here too.
        //
        // Validated before the floor check below, which needs a trustworthy
        // margin to compute the effective budget.
        let safety_margin = config.consolidation.input_token_safety_margin;
        if !(safety_margin > 0.0 && safety_margin <= 1.0) {
            anyhow::bail!(
                "consolidation.input_token_safety_margin must be in (0.0, 1.0] \
                 (got {safety_margin}); it scales the approximate input-token budget"
            );
        }

        // Fail at startup rather than shipping a prompt that is all scaffolding
        // and no observations: below this floor the fixed system prompt and page
        // conventions consume the entire budget, so every consolidation would
        // either be evidence-free or rejected by the provider.
        //
        // The floor is a *character* budget -- what the builders actually need
        // to hold the fixed prompts plus MIN_OBSERVATION_RESERVE_CHARS of
        // evidence -- expressed in tokens at the default margin. Comparing the
        // configured budget against it therefore has to put both sides on the
        // same footing: the configured budget at ITS margin, the requirement at
        // the DEFAULT margin.
        //
        // Scoring the configured side at the default margin instead would make
        // the check a no-op, because the margin cancels out of both sides and
        // it collapses back to `max_input_tokens < MIN_CONSOLIDATION_MAX_INPUT_TOKENS`
        // -- the raw-count comparison this replaced. Doing it this way is what
        // makes a lowered margin demand more tokens, which is the point: the
        // margin exists to buy headroom on dense corpora (#884), and buying it
        // by shrinking the budget below what the prompt needs is exactly the
        // case that used to pass and then omit every observation (#1234).
        let min_input_tokens = ai_memory_consolidate::MIN_CONSOLIDATION_MAX_INPUT_TOKENS;
        let required_input_chars = ai_memory_consolidate::effective_input_chars(
            min_input_tokens,
            ai_memory_consolidate::DEFAULT_CONSOLIDATION_INPUT_TOKEN_SAFETY_MARGIN,
        );
        let effective_input_chars = ai_memory_consolidate::effective_input_chars(
            config.consolidation.max_input_tokens,
            safety_margin,
        );
        if effective_input_chars < required_input_chars {
            anyhow::bail!(
                "consolidation.max_input_tokens must leave at least {required_input_chars} \
                 characters for the prompt ({min_input_tokens} tokens at the default \
                 input_token_safety_margin) (got {}, which is {effective_input_chars} at \
                 input_token_safety_margin = {safety_margin}); below that the system \
                 prompt and page conventions leave no room for observations. Raise \
                 max_input_tokens, or raise input_token_safety_margin towards 1.0",
                config.consolidation.max_input_tokens
            );
        }
        let min_output_tokens = ai_memory_consolidate::MIN_CONSOLIDATION_MAX_OUTPUT_TOKENS;
        if config.consolidation.max_output_tokens < min_output_tokens {
            anyhow::bail!(
                "consolidation.max_output_tokens must be at least {min_output_tokens} \
                 (got {}); below that a structured consolidation response is unlikely to fit",
                config.consolidation.max_output_tokens
            );
        }
        // Zero (or a sub-second remainder rounded down) would cut every
        // provider request off before it is sent.
        if config.llm_timeout_secs == 0 {
            anyhow::bail!(
                "llm_timeout_secs must be at least 1 second (got {}); \
                 AI_MEMORY_LLM_TIMEOUT_SECS is read in seconds",
                config.llm_timeout_secs
            );
        }
        // Zero would time out every rerank before the provider is called,
        // silently turning reranking off while it still reports as enabled.
        if config.rerank_timeout_secs == 0 {
            anyhow::bail!(
                "rerank_timeout_secs must be at least 1 second (got {}); \
                 AI_MEMORY_RERANK_TIMEOUT_SECS is read in seconds",
                config.rerank_timeout_secs
            );
        }
        // Parsed (and discarded) here so a malformed header list is rejected
        // at startup rather than on the first consolidation pass. The typed
        // value is rebuilt by `llm_provider_config`: `ExtraHeaders` is not
        // serialisable, and `Config` must stay so.
        config
            .llm_extra_headers()
            .context("parsing AI_MEMORY_LLM_HEADERS / llm_headers")?;
        validate_auth_settings(&config.auth)?;

        // Validated and resolved eagerly, unlike the primary provider (which
        // stays lazily checked at `serve` startup): a fallback can otherwise
        // sit unused for months and only fail once the primary is already
        // down. The environment is read here, once, per invariant #1 (no
        // `std::env::var` outside `load`).
        //
        // An absent credential is the one failure that is deferred rather than
        // raised (#762): the variable belongs in the server's environment (a
        // service wrapper's env block), not in every shell that runs
        // `ai-memory status`. It is recorded here and enforced by
        // `require_llm_fallback_credentials` at `serve` startup and by
        // `llm_provider_chain`, so the server still fails closed.
        let mut fallback_configs = Vec::with_capacity(config.llm_fallbacks.len());
        let mut unresolved = Vec::new();
        for (i, profile) in config.llm_fallbacks.iter().enumerate() {
            let (resolved_key, missing) = match non_empty(profile.api_key_env.as_deref()) {
                Some(name) => match env_string(name) {
                    Some(key) => (Some(SecretString::from(key)), None),
                    None => (
                        // Stands in for the absent key so the rest of the
                        // profile is still validated eagerly below; the
                        // config built from it is discarded.
                        Some(SecretString::from(UNRESOLVED_FALLBACK_KEY)),
                        Some(format!(
                            "llm_fallbacks[{i}].api_key_env={name} is set but the \
                             environment variable is missing or empty"
                        )),
                    ),
                },
                None => (None, None),
            };
            let provider_cfg = config
                .fallback_provider_config(i, profile, resolved_key)
                .with_context(|| format!("validating llm_fallbacks[{i}]"))?;
            // Constructed and discarded so a malformed profile (missing
            // base_url, bad credential shape) fails startup instead of
            // silently sitting unused until the primary has an outage.
            build_provider(provider_cfg.clone())
                .with_context(|| format!("building llm_fallbacks[{i}]"))?;
            match missing {
                Some(message) => unresolved.push(message),
                None => fallback_configs.push(provider_cfg),
            }
        }
        config.llm_fallback_configs = fallback_configs;
        config.llm_fallback_unresolved = unresolved;

        Ok(config)
    }

    /// Whether the server URL came from config/env instead of being derived
    /// from `bind` or left at the default.
    ///
    /// Deliberately unchanged by the #1269 derivation: `install-hooks` and
    /// `install-mcp` read this to decide whether the operator chose the URL
    /// themselves, and a user who only edited `bind` did not. `server_url` can
    /// therefore differ from `DEFAULT_SERVER_URL` without this being true,
    /// which is exactly why [`Self::server_url_derived_from_bind`] exists.
    #[must_use]
    pub fn server_url_configured(&self) -> bool {
        self.server_url_explicit
            || self.server_url != DEFAULT_SERVER_URL && !self.server_url_derived_from_bind
            || self.runtime_env.server_url.is_some()
    }

    /// Parse [`Self::llm_headers`] into typed header material.
    ///
    /// # Errors
    /// Returns [`LlmError::NotConfigured`] for an entry with no `Name: Value`
    /// separator, an invalid header name or value, or a header ai-memory
    /// sets itself.
    pub fn llm_extra_headers(&self) -> LlmResult<ExtraHeaders> {
        ExtraHeaders::parse(&self.llm_headers)
    }

    /// Build the configured LLM provider settings, if LLM support is enabled.
    ///
    /// # Errors
    /// Returns [`LlmError::NotConfigured`] for unknown providers, missing
    /// provider-specific required values, or a malformed
    /// [`Self::llm_headers`] entry.
    pub fn llm_provider_config(&self) -> LlmResult<Option<ProviderConfig>> {
        let Some(provider_raw) = non_empty(self.llm_provider.as_deref()) else {
            return Ok(None);
        };
        let provider = provider_choice_from_str(provider_raw).ok_or_else(|| {
            LlmError::NotConfigured(format!(
                "AI_MEMORY_LLM_PROVIDER={provider_raw} is not one of \
                 anthropic|openai|gemini|openai-compat|openai-oauth|codex|copilot|anthropic-oauth|opencode|cursor"
            ))
        })?;
        let model = match non_empty(self.llm_model.as_deref()) {
            Some(s) => s.to_string(),
            None => match provider {
                ProviderChoice::Anthropic => "claude-haiku-4-5".to_string(),
                ProviderChoice::AnthropicOAuth => "claude-sonnet-4-6".to_string(),
                ProviderChoice::OpenAi => "gpt-5.4-mini".to_string(),
                ProviderChoice::Gemini => "gemini-3.5-flash".to_string(),
                ProviderChoice::OpenAiOAuth => "gpt-5.5".to_string(),
                ProviderChoice::Codex => "gpt-5.6-luna".to_string(),
                ProviderChoice::Copilot => "gpt-5.5".to_string(),
                ProviderChoice::OpenAiCompat => {
                    return Err(LlmError::NotConfigured(
                        "AI_MEMORY_LLM_MODEL must be set explicitly for openai-compat \
                         (no safe default for self-hosted / aggregator endpoints)"
                            .into(),
                    ));
                }
                ProviderChoice::OpenCode => OPENCODE_DEFAULT_MODEL.to_string(),
                ProviderChoice::Cursor => CURSOR_DEFAULT_MODEL.to_string(),
            },
        };
        Ok(Some(ProviderConfig {
            provider,
            model,
            auth: self.provider_auth(provider, None),
            base_url: self.resolve_base_url(provider),
            compat_strict: self.llm_compat_strict,
            compat_disable_thinking: self.llm_compat_disable_thinking,
            request_timeout_secs: self.llm_timeout_secs,
            reasoning_effort: self.llm_reasoning_effort,
            extra_headers: self.llm_extra_headers()?,
        }))
    }

    /// Resolve one `[[llm_fallbacks]]` profile into a validated
    /// [`ProviderConfig`].
    ///
    /// `resolved_key` is the value already read from the profile's
    /// `api_key_env` (or `None` when it sets none) — the environment is
    /// read once, in [`Self::load`], and passed down as data so this stays
    /// directly testable without mutating process env (`std::env::set_var`
    /// is `unsafe` under edition 2024, forbidden workspace-wide).
    ///
    /// # Errors
    /// Returns [`LlmError::NotConfigured`] for an empty provider/model, an
    /// unknown provider, or a `RequiredApiKey` provider with no resolved
    /// credential.
    fn fallback_provider_config(
        &self,
        index: usize,
        profile: &FallbackProfile,
        resolved_key: Option<SecretString>,
    ) -> LlmResult<ProviderConfig> {
        let provider_raw = non_empty(Some(profile.provider.as_str())).ok_or_else(|| {
            LlmError::NotConfigured(format!("llm_fallbacks[{index}].provider must not be empty"))
        })?;
        let provider = provider_choice_from_str(provider_raw).ok_or_else(|| {
            LlmError::NotConfigured(format!(
                "llm_fallbacks[{index}].provider={provider_raw} is not one of \
                 anthropic|openai|gemini|openai-compat|openai-oauth|codex|copilot|anthropic-oauth|opencode|cursor"
            ))
        })?;
        let model = non_empty(Some(profile.model.as_str()))
            .ok_or_else(|| {
                LlmError::NotConfigured(format!("llm_fallbacks[{index}].model must not be empty"))
            })?
            .to_string();
        if resolved_key.is_none()
            && matches!(
                provider.auth_requirement(),
                AuthRequirement::RequiredApiKey { .. }
            )
        {
            return Err(LlmError::NotConfigured(format!(
                "llm_fallbacks[{index}] provider={provider_raw} requires api_key_env \
                 (no native credential source for this provider)"
            )));
        }
        Ok(ProviderConfig {
            provider,
            model,
            auth: self.fallback_provider_auth(provider, resolved_key),
            base_url: non_empty(profile.base_url.as_deref()).map(str::to_string),
            compat_strict: self.llm_compat_strict,
            compat_disable_thinking: self.llm_compat_disable_thinking,
            request_timeout_secs: self.llm_timeout_secs,
            reasoning_effort: self.llm_reasoning_effort,
            extra_headers: self.llm_extra_headers()?,
        })
    }

    /// Auth resolution for a fallback profile. Deliberately distinct from
    /// [`Self::provider_auth`]: that method falls back to the *primary*
    /// provider's own fixed env var
    /// (e.g. `ANTHROPIC_API_KEY`) when no override is given, which would let
    /// a fallback profile silently reuse the primary's credential even
    /// though it omitted `api_key_env` — defeating the "fails startup"
    /// validation in [`Self::fallback_provider_config`]. Native credential
    /// sources (OpenAI OAuth, Copilot, Anthropic OAuth) are process-wide by
    /// nature and are still shared with the primary provider.
    fn fallback_provider_auth(
        &self,
        provider: ProviderChoice,
        resolved_key: Option<SecretString>,
    ) -> ProviderAuth {
        match provider.auth_requirement() {
            AuthRequirement::RequiredApiKey { env_var } => {
                ProviderAuth::required_api_key_from_env(env_var, resolved_key)
            }
            AuthRequirement::OptionalApiKey { env_var } => {
                ProviderAuth::optional_api_key_from_env(env_var, resolved_key)
            }
            AuthRequirement::OpenAiOAuthToken => {
                ProviderAuth::openai_oauth_token_file(self.openai_oauth_token_path())
            }
            AuthRequirement::CodexAuthFile => ProviderAuth::codex(
                resolve_codex_auth_file(
                    self.runtime_env.codex_home.as_deref(),
                    self.runtime_env.platform_home.as_deref(),
                ),
                self.runtime_env
                    .codex_executable
                    .clone()
                    .unwrap_or_else(|| PathBuf::from("codex")),
            ),
            AuthRequirement::CopilotToken => ProviderAuth::copilot(
                self.copilot_token_path(),
                self.runtime_env.copilot_github_token.clone(),
                self.runtime_env.github_copilot_api_token.clone(),
                self.runtime_env.copilot_api_url.clone(),
            ),
            AuthRequirement::AnthropicOAuthToken => {
                ProviderAuth::anthropic_oauth_token(self.runtime_env.anthropic_oauth_token.clone())
            }
            AuthRequirement::CursorCli => ProviderAuth::cursor(self.cursor_auth()),
        }
    }

    /// Fail when an `llm_fallbacks` credential named by `api_key_env` is
    /// absent from this process's environment.
    ///
    /// `serve` calls this at startup, so a fallback that could never
    /// authenticate stops the server before it runs, whether or not a primary
    /// provider is configured. Other subcommands do not: they never build the
    /// chain, and requiring the server's credentials in every shell would
    /// spread them to every process the operator runs (#762).
    ///
    /// # Errors
    /// Names the first unresolved profile and its variable.
    pub fn require_llm_fallback_credentials(&self) -> Result<()> {
        match self.llm_fallback_unresolved.first() {
            Some(message) => anyhow::bail!("{message}"),
            None => Ok(()),
        }
    }

    /// Build the configured LLM provider, including any ordered
    /// `llm_fallbacks` chain.
    ///
    /// `None` when no LLM is configured; the plain provider when no
    /// fallback is configured (existing single-provider callers are
    /// unaffected); otherwise a [`FallbackLlmProvider`] wrapping the
    /// primary and its fallbacks in declaration order. See
    /// `docs/llm-provider-fallback.md`.
    ///
    /// # Errors
    /// Propagates any error from constructing the primary or a fallback
    /// provider (`build_provider` is the sole construction path for both).
    pub fn llm_provider_chain(&self) -> LlmResult<Option<Arc<dyn LlmProvider>>> {
        // A chain with a profile silently dropped would look healthy until
        // the primary has an outage.
        if let Some(message) = self.llm_fallback_unresolved.first() {
            return Err(LlmError::NotConfigured(message.clone()));
        }
        let Some(primary_cfg) = self.llm_provider_config()? else {
            return Ok(None);
        };
        if self.llm_fallback_configs.is_empty() {
            return Ok(Some(build_provider(primary_cfg)?));
        }
        let mut candidates = Vec::with_capacity(1 + self.llm_fallback_configs.len());
        candidates.push(Candidate::new(
            primary_cfg.provider.name(),
            primary_cfg.model.clone(),
            build_provider(primary_cfg)?,
        ));
        for cfg in &self.llm_fallback_configs {
            candidates.push(Candidate::new(
                cfg.provider.name(),
                cfg.model.clone(),
                build_provider(cfg.clone())?,
            ));
        }
        Ok(Some(Arc::new(FallbackLlmProvider::new(candidates))))
    }

    /// OpenAI-compatible embedding key. `EMBEDDING_API_KEY` is checked first
    /// so an operator can point the embedder at one provider while the LLM
    /// uses another; without it, direct OpenAI keeps requiring
    /// `OPENAI_API_KEY` and a custom embedding base URL may reuse
    /// `LLM_API_KEY` for gateways such as OpenRouter.
    fn openai_embedding_api_key(&self) -> LlmResult<SecretString> {
        if let Some(key) = self.runtime_env.embedding_api_key.clone() {
            return Ok(key);
        }
        if let Some(key) = self.runtime_env.openai_api_key.clone() {
            return Ok(key);
        }
        if non_empty(self.embedding_base_url.as_deref()).is_some() {
            if let Some(key) = self.runtime_env.llm_api_key.clone() {
                return Ok(key);
            }
            return Err(LlmError::NotConfigured(
                "EMBEDDING_API_KEY, OPENAI_API_KEY or LLM_API_KEY required for \
                 openai-compatible embeddings"
                    .into(),
            ));
        }
        Err(LlmError::NotConfigured(
            "EMBEDDING_API_KEY or OPENAI_API_KEY".into(),
        ))
    }

    /// Whether the operator opted into post-RRF reranking.
    ///
    /// Unknown values are rejected loudly at *startup* rather than
    /// silently disabling the feature — a typo'd `AI_MEMORY_RERANKER`
    /// should not look like "reranking is on" in the operator's head
    /// while eligible queries keep their normal ranking.
    ///
    /// # Errors
    /// Returns [`LlmError::NotConfigured`] for any value other than
    /// `llm` (case-insensitive) or empty.
    pub fn reranker_choice(&self) -> LlmResult<bool> {
        match non_empty(self.reranker.as_deref()).map(str::to_ascii_lowercase) {
            None => Ok(false),
            Some(v) if v == "llm" => Ok(true),
            Some(other) => Err(LlmError::NotConfigured(format!(
                "AI_MEMORY_RERANKER={other} is not supported (only `llm`)"
            ))),
        }
    }

    /// Build the configured embedder settings, if hybrid search is enabled.
    ///
    /// # Errors
    /// Returns [`LlmError::NotConfigured`] for unknown providers, missing API
    /// keys, or invalid dimensions.
    pub fn embedder_config(&self) -> LlmResult<Option<EmbedderConfig>> {
        // 2.0 default: hybrid retrieval out of the box. An unset provider
        // selects in-process `local` embeddings BEST-EFFORT (the serve
        // layer degrades to no-embedder if the model cannot be fetched or
        // loaded); `embedding_provider = "none"` opts out entirely, and an
        // explicitly configured provider keeps hard-failure semantics.
        let (provider_raw, defaulted) = match non_empty(self.embedding_provider.as_deref()) {
            Some("none" | "off" | "disabled") => return Ok(None),
            Some(raw) => (raw, false),
            None => ("local", true),
        };
        let provider = match provider_raw {
            "openai" => EmbedderChoice::OpenAi,
            "voyage" => EmbedderChoice::Voyage,
            "google" | "gemini" => EmbedderChoice::Google,
            "openai-compat" | "openai_compat" => EmbedderChoice::OpenAiCompat,
            "local" => EmbedderChoice::Local,
            "copilot" => EmbedderChoice::Copilot,
            other => {
                return Err(LlmError::NotConfigured(format!(
                    "AI_MEMORY_EMBEDDING_PROVIDER={other} not one of \
                     openai|voyage|google|gemini|openai-compat|local|copilot|none"
                )));
            }
        };
        let model = match non_empty(self.embedding_model.as_deref()) {
            Some(s) => s.to_string(),
            None => match provider {
                EmbedderChoice::OpenAi => "text-embedding-3-small".to_string(),
                EmbedderChoice::Voyage => "voyage-3".to_string(),
                EmbedderChoice::Google => ai_memory_llm::GOOGLE_DEFAULT_EMBED_MODEL.to_string(),
                EmbedderChoice::OpenAiCompat => {
                    return Err(LlmError::NotConfigured(
                        "AI_MEMORY_EMBEDDING_MODEL must be set explicitly for openai-compat \
                         (no safe default for self-hosted engines)"
                            .into(),
                    ));
                }
                EmbedderChoice::Local => ai_memory_llm::LOCAL_MODEL.to_string(),
                EmbedderChoice::Copilot => ai_memory_llm::COPILOT_DEFAULT_EMBED_MODEL.to_string(),
            },
        };
        let dim = match self.embedding_dim {
            Some(0) => {
                return Err(LlmError::NotConfigured(
                    "AI_MEMORY_EMBEDDING_DIM must be greater than zero".into(),
                ));
            }
            Some(d) => d,
            None => {
                ai_memory_llm::try_default_embedding_dim(provider, &model).ok_or_else(|| {
                    LlmError::NotConfigured(
                        "AI_MEMORY_EMBEDDING_DIM must be set explicitly for openai-compat \
                         (self-hosted model dims vary)"
                            .into(),
                    )
                })?
            }
        };
        let api_key = match provider {
            EmbedderChoice::OpenAi => self.openai_embedding_api_key()?,
            EmbedderChoice::Voyage => self
                .runtime_env
                .voyage_api_key
                .clone()
                .ok_or_else(|| LlmError::NotConfigured("VOYAGE_API_KEY".into()))?,
            EmbedderChoice::Google => self.runtime_env.gemini_api_key.clone().ok_or_else(|| {
                LlmError::NotConfigured("GEMINI_API_KEY or GOOGLE_API_KEY".into())
            })?,
            // Keyless engines (Ollama, LM Studio) are the norm; a
            // gateway key rides on EMBEDDING_API_KEY, or on LLM_API_KEY
            // when the chat model shares that gateway.
            EmbedderChoice::OpenAiCompat => self
                .runtime_env
                .embedding_api_key
                .clone()
                .or_else(|| self.runtime_env.llm_api_key.clone())
                .unwrap_or_else(|| SecretString::from(String::new())),
            // In-process: no key, ever.
            EmbedderChoice::Local => SecretString::from(String::new()),
            // OAuth-backed: no API key, ever; see `copilot_auth` below.
            EmbedderChoice::Copilot => SecretString::from(String::new()),
        };
        let base_url = self.embedding_base_url.clone();
        if provider == EmbedderChoice::OpenAiCompat && non_empty(base_url.as_deref()).is_none() {
            return Err(LlmError::NotConfigured(
                "AI_MEMORY_EMBEDDING_BASE_URL required for openai-compat embeddings".into(),
            ));
        }
        // Resolve Copilot auth only when the embedding provider is actually
        // copilot (invariant 14: auth resolves before construction). Mirrors
        // exactly how the chat-provider path builds `ProviderAuth::copilot`.
        let copilot_auth = if provider == EmbedderChoice::Copilot {
            Some(
                self.provider_auth(ProviderChoice::Copilot, None)
                    .require_copilot_auth()?,
            )
        } else {
            None
        };
        // Not `non_empty`: that trims, and a publisher's trailing space
        // (e.g. Nemotron-3-Embed's `"query: "`) is significant. By the time
        // `Load` has run, `self.embedding_query_prefix` already holds the
        // exact configured bytes regardless of source (TOML or env) — see
        // `Config::load`'s env-prefix overlay, which corrects for
        // figment's `Env` provider trimming unquoted values.
        let query_prefix = self.embedding_query_prefix.clone().unwrap_or_default();
        let document_prefix = self.embedding_document_prefix.clone().unwrap_or_default();
        Ok(Some(EmbedderConfig {
            provider,
            model,
            dim,
            api_key,
            base_url,
            models_dir: Some(self.data_dir.join("models")),
            copilot_auth,
            defaulted,
            query_prefix,
            document_prefix,
        }))
    }

    /// Resolve an API key for an explicit `llm-test` provider choice.
    #[must_use]
    pub fn provider_api_key(&self, provider: ProviderChoice) -> Option<SecretString> {
        match provider {
            ProviderChoice::Anthropic => self.runtime_env.anthropic_api_key.clone(),
            ProviderChoice::OpenAi => self.runtime_env.openai_api_key.clone(),
            ProviderChoice::Gemini => self.runtime_env.gemini_api_key.clone(),
            ProviderChoice::OpenAiCompat => self.runtime_env.llm_api_key.clone(),
            ProviderChoice::OpenAiOAuth => None,
            ProviderChoice::Codex => None,
            ProviderChoice::Copilot => None,
            ProviderChoice::AnthropicOAuth => None,
            ProviderChoice::OpenCode => self.runtime_env.opencode_api_key.clone(),
            ProviderChoice::Cursor => None,
        }
    }

    /// Shared provider auth token file path.
    #[must_use]
    pub fn auth_token_path(&self) -> PathBuf {
        self.data_dir.join("auth.json")
    }

    /// Shared OpenAI OAuth token file path.
    #[must_use]
    pub fn openai_oauth_token_path(&self) -> PathBuf {
        self.auth_token_path()
    }

    /// Codex CLI-owned auth file resolved from the Codex or platform home.
    #[must_use]
    pub fn codex_auth_file_path(&self) -> PathBuf {
        let platform_home = self
            .runtime_env
            .platform_home
            .as_deref()
            .or_else(|| self.runtime_env.home_dir.as_deref().map(Path::new));
        resolve_codex_auth_file(self.runtime_env.codex_home.as_deref(), platform_home)
    }

    /// Cursor Agent CLI inputs, from values captured once by [`Config::load`].
    ///
    /// The child gets only the allowlisted part of the captured process
    /// environment. Without a captured temp dir (a test-built config) the
    /// root is empty and the provider refuses to run instead of writing the
    /// prompt under its cwd.
    fn cursor_auth(&self) -> CursorAuth {
        CursorAuth::new(
            cursor_executable(self.runtime_env.cursor_executable.as_deref()),
            self.runtime_env.temp_dir.clone().unwrap_or_default(),
            self.runtime_env.process_env(),
        )
    }

    /// Shared Copilot auth token file path.
    #[must_use]
    pub fn copilot_token_path(&self) -> PathBuf {
        self.auth_token_path()
    }

    /// Shared OIDC device-grant token file path.
    #[must_use]
    pub fn oidc_device_token_path(&self) -> PathBuf {
        self.auth_token_path()
    }

    /// GitHub token resolved for Copilot auth login/provider use.
    #[must_use]
    pub fn copilot_github_token(&self) -> Option<SecretString> {
        self.runtime_env.copilot_github_token.clone()
    }

    /// Copilot OAuth client id override for `auth login copilot`.
    #[must_use]
    pub fn copilot_client_id(&self) -> Option<&str> {
        self.runtime_env.copilot_client_id.as_deref()
    }

    /// Resolve typed auth material for a provider.
    ///
    /// `api_key_override` is used by `llm-test --api-key`; normal server
    /// startup passes `None` so env/config resolution remains the single path.
    #[must_use]
    pub fn provider_auth(
        &self,
        provider: ProviderChoice,
        api_key_override: Option<SecretString>,
    ) -> ProviderAuth {
        match provider.auth_requirement() {
            AuthRequirement::RequiredApiKey { env_var } => {
                ProviderAuth::required_api_key_from_env(env_var, self.provider_api_key(provider))
                    .with_cli_api_key_override(api_key_override)
            }
            AuthRequirement::OptionalApiKey { env_var } => {
                ProviderAuth::optional_api_key_from_env(env_var, self.provider_api_key(provider))
                    .with_cli_api_key_override(api_key_override)
            }
            AuthRequirement::OpenAiOAuthToken => {
                ProviderAuth::openai_oauth_token_file(self.openai_oauth_token_path())
            }
            AuthRequirement::CodexAuthFile => ProviderAuth::codex(
                self.codex_auth_file_path(),
                self.runtime_env
                    .codex_executable
                    .clone()
                    .unwrap_or_else(|| PathBuf::from("codex")),
            ),
            AuthRequirement::CopilotToken => ProviderAuth::copilot(
                self.copilot_token_path(),
                self.runtime_env.copilot_github_token.clone(),
                self.runtime_env.github_copilot_api_token.clone(),
                self.runtime_env
                    .copilot_api_url
                    .clone()
                    .or_else(|| self.llm_base_url.clone()),
            ),
            AuthRequirement::AnthropicOAuthToken => {
                ProviderAuth::anthropic_oauth_token(self.runtime_env.anthropic_oauth_token.clone())
            }
            AuthRequirement::CursorCli => ProviderAuth::cursor(self.cursor_auth()),
        }
    }

    /// Base URL for `provider`, from the two sources that can supply one.
    ///
    /// An explicit ai-memory setting (`llm_base_url` in `config.toml`, or
    /// `AI_MEMORY_LLM_BASE_URL`) configures every HTTP API provider: naming
    /// ai-memory is how an operator says they mean it, and proxying a vendor
    /// endpoint is a legitimate deployment. The ChatGPT backend
    /// (`openai-oauth`, `codex`) and `cursor`'s CLI take no override.
    ///
    /// The bare `LLM_BASE_URL` is different in kind — a cross-tool convention
    /// an operator exports once for a local Ollama and forgets. It reaches
    /// only the providers whose endpoint is theirs to choose anyway; sending
    /// it to a vendor-fixed endpoint silently rewrites every request onto a
    /// host that does not speak the dialect (#691), so it is ignored and the
    /// reason is logged rather than left for a 404 to explain.
    fn resolve_base_url(&self, provider: ProviderChoice) -> Option<String> {
        if let Some(explicit) = non_empty(self.llm_base_url.as_deref()) {
            return Some(explicit.to_string());
        }
        let ambient = non_empty(self.runtime_env.llm_base_url.as_deref())?;
        if provider.endpoint_is_operator_chosen() {
            return Some(ambient.to_string());
        }
        tracing::warn!(
            provider = provider.name(),
            base_url = ambient,
            "ignoring ambient LLM_BASE_URL: this provider talks to a fixed vendor \
             endpoint. Set llm_base_url (or AI_MEMORY_LLM_BASE_URL) to point it \
             somewhere else on purpose."
        );
        None
    }

    /// Base URL fallback for `llm-test`. Resolves exactly as
    /// [`Self::provider_config`] does, so `llm-test` exercises the endpoint
    /// `serve` will use — including an `opencode` override onto Zen, and the
    /// same refusal to inherit an ambient `LLM_BASE_URL`.
    #[must_use]
    pub fn llm_test_base_url(&self, provider: ProviderChoice) -> Option<String> {
        self.resolve_base_url(provider)
    }
}

/// Wire-name parsing shared by `llm_provider` and `llm_fallbacks[].provider`.
fn provider_choice_from_str(raw: &str) -> Option<ProviderChoice> {
    Some(match raw {
        "anthropic" => ProviderChoice::Anthropic,
        "openai" => ProviderChoice::OpenAi,
        "gemini" | "google" => ProviderChoice::Gemini,
        "openai-compat" | "openai_compat" => ProviderChoice::OpenAiCompat,
        "openai-oauth" | "openai_oauth" => ProviderChoice::OpenAiOAuth,
        "codex" => ProviderChoice::Codex,
        "copilot" | "github-copilot" | "github_copilot" => ProviderChoice::Copilot,
        "anthropic-oauth" | "anthropic_oauth" => ProviderChoice::AnthropicOAuth,
        "opencode" | "opencode-zen" | "opencode_zen" => ProviderChoice::OpenCode,
        "cursor" => ProviderChoice::Cursor,
        _ => return None,
    })
}

/// Operator home used as the #103 catch-all prefix guard.
///
/// Precedence: `AI_MEMORY_HOME`, then `$HOME`, then Windows `%USERPROFILE%`,
/// then the platform home from `dirs`. Empty strings are skipped so an
/// exported-but-blank `HOME` cannot hide a real profile. Arguments are
/// injected so tests do not mutate process env (`std::env::set_var` is
/// `unsafe` under edition 2024).
fn resolve_operator_home(
    ai_memory_home: Option<&str>,
    home: Option<&str>,
    userprofile: Option<&str>,
    platform_home: Option<&Path>,
) -> Option<String> {
    [ai_memory_home, home, userprofile]
        .into_iter()
        .flatten()
        .find(|s| !s.trim().is_empty())
        .map(str::to_owned)
        .or_else(|| {
            platform_home
                .and_then(Path::to_str)
                .filter(|s| !s.trim().is_empty())
                .map(str::to_owned)
        })
}

fn env_string(name: &str) -> Option<String> {
    std::env::var(name).ok().and_then(|s| {
        let trimmed = s.trim();
        if trimmed.is_empty() {
            None
        } else {
            Some(trimmed.to_string())
        }
    })
}

/// Overlay the two embedding-prefix keys onto `figment` with their raw,
/// untrimmed values, whenever the corresponding parameter is `Some` (even
/// `Some("")` — an operator clearing a `config.toml`-set prefix back to
/// none via an empty env var; only `None`, the variable genuinely absent,
/// leaves a `config.toml` value or the default untouched).
///
/// figment's `Env` provider parses each var's string as a loose value
/// (`figment::value::parse::value`), and its bare/unquoted branch calls
/// `.trim()` — so `AI_MEMORY_EMBEDDING_QUERY_PREFIX="query: "` would
/// otherwise reach `embedding_query_prefix` as `"query:"`, silently
/// dropping the publisher-significant trailing space (verified against
/// figment 0.10.19's vendored source, `src/value/parse.rs:78`).
/// [`Serialized`] values are handed to figment as already-typed data (via
/// `serde::Serialize`), so they never pass through that string parser and
/// so are never trimmed. Callers merge this after `Env::prefixed` so it
/// wins over the (possibly trimmed) value that provider already set.
///
/// The values come in as parameters, already read by the caller, rather
/// than this function reading `std::env::var` itself — the same pattern
/// `ai-memory-cli/src/commands/path_util.rs`'s `agent_config_home` and
/// `ai-memory-hooks`'s `drain_with_live_token` use, and for the same
/// reason: it keeps this function directly unit-testable without
/// mutating process environment or the current directory. Both are
/// unsafe or actively harmful to do from a `#[test]` in this crate's
/// multi-threaded lib test binary — `std::env::set_var` is `unsafe` under
/// edition 2024 and forbidden workspace-wide, and even a "safe" wrapper
/// such as `figment::Jail` still calls `std::env::set_current_dir` on the
/// real process (verified against its vendored source,
/// `src/jail.rs:141`), racing every other test in the binary that reads
/// env or relies on cwd — e.g. `tests/suite/backfill_e2e.rs`'s
/// `Command::current_dir` calls.
fn overlay_embedding_prefixes(
    mut figment: Figment,
    query_prefix_env: Option<&str>,
    document_prefix_env: Option<&str>,
) -> Figment {
    if let Some(v) = query_prefix_env {
        figment = figment.merge(Serialized::default("embedding_query_prefix", v));
    }
    if let Some(v) = document_prefix_env {
        figment = figment.merge(Serialized::default("embedding_document_prefix", v));
    }
    figment
}

fn env_path(name: &str) -> Option<PathBuf> {
    env_string(name).map(PathBuf::from)
}

fn resolve_codex_auth_file(codex_home: Option<&Path>, platform_home: Option<&Path>) -> PathBuf {
    if let Some(home) = codex_home.filter(|path| !path.as_os_str().is_empty()) {
        return home.join("auth.json");
    }
    platform_home
        .unwrap_or_else(|| Path::new("."))
        .join(".codex")
        .join("auth.json")
}

fn env_secret(name: &str) -> Option<SecretString> {
    env_string(name).map(SecretString::from)
}

fn non_empty_secret(secret: Option<&SecretString>) -> Option<&str> {
    non_empty(secret.map(ExposeSecret::expose_secret))
}

/// Reject equal configured secrets without logging their values.
///
/// Named without "secret": CodeQL's sensitive-name heuristic treats a call
/// whose name matches it as a source, and taints the whole `Config` this
/// borrows from, so every printed config field (the data dir, the server URL)
/// was reported as cleartext logging. Real secret fields are still reported by
/// their own names.
fn validate_auth_settings(auth: &AuthSettings) -> Result<()> {
    let mut named: Vec<(&str, &str)> = Vec::new();
    if let Some(v) = non_empty(auth.bearer_token.as_deref()) {
        named.push(("[auth].bearer_token", v));
    }
    if let Some(v) = non_empty(auth.actor_proxy_bearer_token.as_deref()) {
        named.push(("[auth].actor_proxy_bearer_token", v));
    }
    if let Some(v) = non_empty_secret(auth.recovery_token.as_ref()) {
        if v.len() < 32 {
            anyhow::bail!("[auth].recovery_token must be at least 32 characters");
        }
        if v.starts_with(ai_memory_core::SESSION_SECRET_PREFIX)
            || v.starts_with(ai_memory_core::NATIVE_API_KEY_PREFIX)
            || v.starts_with(ai_memory_core::EXTERNAL_API_KEY_PREFIX)
        {
            anyhow::bail!("[auth].recovery_token must not use a reserved credential prefix");
        }
        named.push(("[auth].recovery_token", v));
    }
    if let Some(v) = non_empty_secret(auth.initial_root_password.as_ref()) {
        named.push(("[auth].initial_root_password", v));
    }
    for i in 0..named.len() {
        for j in (i + 1)..named.len() {
            if named[i].1 == named[j].1 {
                anyhow::bail!(
                    "{} must differ from {}; reuse would collapse credential classes",
                    named[i].0,
                    named[j].0
                );
            }
        }
    }
    Ok(())
}

fn non_empty(s: Option<&str>) -> Option<&str> {
    s.map(str::trim).filter(|s| !s.is_empty())
}

/// `<data_dir>/auth-token` — the raw bearer, `0600`.
#[must_use]
pub fn hook_auth_token_path_in(data_dir: &Path) -> PathBuf {
    data_dir.join("auth-token")
}

/// `<data_dir>/auth-header` — the same bearer as a complete
/// `Authorization:` line, `0600`.
///
/// A second file rather than a second parse: the shell hooks pass this to
/// `curl -H @<file>`, which is what keeps the credential out of *curl's*
/// argv. Building the header inline would put it straight back on a command
/// line, which is the whole problem (#552).
#[must_use]
pub fn hook_auth_header_path_in(data_dir: &Path) -> PathBuf {
    data_dir.join("auth-header")
}

/// Persist the bearer for hooks to read, replacing any previous pair.
///
/// Both files are written `0600` inside the data dir, which is itself `0700`.
/// That is strictly less exposure than the status quo, where the token sat in
/// the agent's own config file *and* on the command line of every hook and
/// every `curl` — readable through `/proc/<pid>/cmdline` by any local user for
/// as long as each ran.
///
/// # Errors
/// Propagates IO failures from creating the data dir or writing either file.
pub fn store_hook_auth_token(data_dir: &Path, token: &str) -> std::io::Result<()> {
    std::fs::create_dir_all(data_dir)?;
    let token_path = hook_auth_token_path_in(data_dir);
    let header_path = hook_auth_header_path_in(data_dir);
    let previous_token = read_optional_secret_bytes(&token_path)?;
    let previous_header = read_optional_secret_bytes(&header_path)?;

    write_secret(&token_path, token)?;
    if let Err(error) = write_secret(&header_path, &format!("Authorization: Bearer {token}\n")) {
        let token_rollback = restore_secret_bytes(&token_path, previous_token.as_deref());
        let header_rollback = restore_secret_bytes(&header_path, previous_header.as_deref());
        if let Err(rollback) = token_rollback.and(header_rollback) {
            return Err(std::io::Error::other(format!(
                "writing hook credential pair failed ({error}); rollback also failed ({rollback})"
            )));
        }
        return Err(error);
    }
    Ok(())
}

fn read_optional_secret_bytes(path: &Path) -> std::io::Result<Option<Vec<u8>>> {
    match std::fs::read(path) {
        Ok(bytes) => Ok(Some(bytes)),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
        Err(error) => Err(error),
    }
}

fn restore_secret_bytes(path: &Path, previous: Option<&[u8]>) -> std::io::Result<()> {
    match previous {
        Some(bytes) => write_secret_bytes(path, bytes),
        None => match std::fs::remove_file(path) {
            Ok(()) => Ok(()),
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
            Err(error) => Err(error),
        },
    }
}

/// Remove a persisted bearer pair. Absent files are not an error.
///
/// # Errors
/// Propagates IO failures other than "not found".
pub fn clear_hook_auth_token(data_dir: &Path) -> std::io::Result<()> {
    for path in [
        hook_auth_token_path_in(data_dir),
        hook_auth_header_path_in(data_dir),
    ] {
        match std::fs::remove_file(&path) {
            Ok(()) => {}
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
            Err(e) => return Err(e),
        }
    }
    Ok(())
}

/// Read the persisted bearer, if one was stored. Trailing newline trimmed.
#[must_use]
pub fn read_hook_auth_token(data_dir: &Path) -> Option<String> {
    read_trimmed_secret(&hook_auth_token_path_in(data_dir))
}

/// Read a one-value secret file. Surrounding whitespace is trimmed, and a
/// missing, unreadable, or blank file is `None` — never an empty bearer.
pub(crate) fn read_trimmed_secret(path: &Path) -> Option<String> {
    let raw = std::fs::read_to_string(path).ok()?;
    let trimmed = raw.trim();
    (!trimmed.is_empty()).then(|| trimmed.to_owned())
}

/// Write `contents` to `path` with owner-only permissions.
///
/// The mode is set on the handle before any bytes are written on Unix, so the
/// secret is never briefly world-readable between `create` and `set_permissions`.
fn write_secret(path: &Path, contents: &str) -> std::io::Result<()> {
    write_secret_bytes(path, contents.as_bytes())
}

fn write_secret_bytes(path: &Path, contents: &[u8]) -> std::io::Result<()> {
    #[cfg(unix)]
    {
        use std::io::Write as _;
        use std::os::unix::fs::OpenOptionsExt as _;
        let mut file = std::fs::OpenOptions::new()
            .write(true)
            .create(true)
            .truncate(true)
            .mode(0o600)
            .open(path)?;
        file.write_all(contents)
    }
    #[cfg(not(unix))]
    {
        // Windows has no mode bits here; the data dir's own ACL is the boundary.
        std::fs::write(path, contents)
    }
}

/// The historical patchable folders, kept as the default so an existing config
/// that omits the key behaves exactly as before (#834).
fn default_patchable_page_prefixes() -> Vec<String> {
    ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_PATCHABLE_PAGE_PREFIXES
        .iter()
        .map(|p| (*p).to_string())
        .collect()
}

fn default_data_dir() -> PathBuf {
    dirs::data_local_dir()
        .unwrap_or_else(|| PathBuf::from("."))
        .join("ai-memory")
}

fn canonicalise_or_keep(p: &Path) -> PathBuf {
    if let Ok(canon) = p.canonicalize() {
        return canon;
    }
    // Path may not exist yet (init hasn't run). Canonicalise the parent
    // and rejoin so logs and downstream comparisons still see the truth.
    if let (Some(parent), Some(name)) = (p.parent(), p.file_name())
        && let Ok(canon_parent) = parent.canonicalize()
    {
        return canon_parent.join(name);
    }
    if p.is_absolute() {
        return p.to_path_buf();
    }
    // A nested path may have no existing ancestor beyond the current
    // directory yet. Keep the invocation-time meaning when this path is later
    // embedded in an MCP entry launched from an unrelated project directory.
    std::env::current_dir()
        .map(|cwd| cwd.join(p))
        .unwrap_or_else(|_| p.to_path_buf())
}

/// Normalize home for prefix-match comparisons: accept either slash spelling,
/// strip trailing separators,
/// so a stored `repo_path` of `/home/u` still equals a `$HOME` of `/home/u/`
/// (the cwd side is trimmed the same way in `find_project_by_cwd_prefix`).
/// All-separator or empty input yields `None` (no usable home).
fn normalize_home_dir(home: &str) -> Option<String> {
    let normalized = home.replace('\\', "/");
    let trimmed = normalized.trim_end_matches('/');
    (!trimmed.is_empty()).then(|| trimmed.to_string())
}

#[cfg(test)]
mod tests {

    /// Windows environment names are case-insensitive (`std::env::var_os`
    /// finds `Codex_Home` for `CODEX_HOME`), so the captured lookup must be
    /// too there, and stay exact elsewhere.
    #[test]
    fn captured_env_names_match_case_insensitively_only_on_windows_rules() {
        use std::ffi::OsStr;
        assert!(super::env_name_matches(
            OsStr::new("Codex_Home"),
            "CODEX_HOME",
            true
        ));
        assert!(super::env_name_matches(
            OsStr::new("CODEX_HOME"),
            "CODEX_HOME",
            true
        ));
        assert!(!super::env_name_matches(
            OsStr::new("CODEX_HOMES"),
            "CODEX_HOME",
            true
        ));
        assert!(!super::env_name_matches(
            OsStr::new("Codex_Home"),
            "CODEX_HOME",
            false
        ));
        assert!(super::env_name_matches(
            OsStr::new("CODEX_HOME"),
            "CODEX_HOME",
            false
        ));
    }

    /// #552: the bearer used to travel on every hook's command line, readable
    /// through `/proc/<pid>/cmdline` by any local user. It now lives in the
    /// data dir instead — which is only an improvement if the files are not
    /// world-readable, so the mode is asserted rather than assumed.
    #[test]
    fn a_persisted_hook_token_is_owner_only_and_round_trips() {
        let tmp = TempDir::new().unwrap();
        let dd = tmp.path().join("data");

        store_hook_auth_token(&dd, "s3cret-bearer").unwrap();

        assert_eq!(read_hook_auth_token(&dd).as_deref(), Some("s3cret-bearer"));
        assert_eq!(
            std::fs::read_to_string(hook_auth_header_path_in(&dd)).unwrap(),
            "Authorization: Bearer s3cret-bearer\n",
            "the header file is what curl reads with -H @file"
        );

        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt as _;
            for path in [hook_auth_token_path_in(&dd), hook_auth_header_path_in(&dd)] {
                let mode = std::fs::metadata(&path).unwrap().permissions().mode() & 0o777;
                assert_eq!(
                    mode,
                    0o600,
                    "{} must be owner-only, got {mode:o}",
                    path.display()
                );
            }
        }
    }

    /// Re-running `install-hooks --apply` after `api-key rotate` must leave
    /// the new bearer, not both.
    #[test]
    fn storing_a_second_token_replaces_the_first() {
        let tmp = TempDir::new().unwrap();
        let dd = tmp.path().join("data");
        store_hook_auth_token(&dd, "old-token").unwrap();
        store_hook_auth_token(&dd, "new-token").unwrap();

        assert_eq!(read_hook_auth_token(&dd).as_deref(), Some("new-token"));
        assert!(
            !std::fs::read_to_string(hook_auth_header_path_in(&dd))
                .unwrap()
                .contains("old-token"),
            "a rotated token must not leave the previous one behind"
        );
    }

    #[test]
    fn an_invalid_header_target_cannot_partially_replace_the_token() {
        let tmp = TempDir::new().unwrap();
        let dd = tmp.path().join("data");
        std::fs::create_dir_all(hook_auth_header_path_in(&dd)).unwrap();

        let error = store_hook_auth_token(&dd, "must-not-stick").unwrap_err();
        assert_ne!(error.kind(), std::io::ErrorKind::NotFound);
        assert!(!hook_auth_token_path_in(&dd).exists());
    }

    #[test]
    fn a_nested_nonexistent_relative_data_dir_becomes_absolute() {
        let relative = Path::new("target/nonexistent-ai-memory-test/data");
        let resolved = canonicalise_or_keep(relative);
        assert!(resolved.is_absolute(), "{}", resolved.display());
        assert!(resolved.ends_with(relative));
    }

    /// Absent, empty, and whitespace-only files all read as "no token" rather
    /// than as an empty bearer, which would send `Authorization: Bearer `.
    #[test]
    fn an_absent_or_blank_token_file_reads_as_none() {
        let tmp = TempDir::new().unwrap();
        let dd = tmp.path().join("data");
        assert!(read_hook_auth_token(&dd).is_none(), "absent");

        std::fs::create_dir_all(&dd).unwrap();
        std::fs::write(hook_auth_token_path_in(&dd), "").unwrap();
        assert!(read_hook_auth_token(&dd).is_none(), "empty");
        std::fs::write(hook_auth_token_path_in(&dd), "  \n ").unwrap();
        assert!(read_hook_auth_token(&dd).is_none(), "whitespace only");
    }

    #[test]
    fn clearing_a_token_is_idempotent() {
        let tmp = TempDir::new().unwrap();
        let dd = tmp.path().join("data");
        store_hook_auth_token(&dd, "tok").unwrap();
        clear_hook_auth_token(&dd).unwrap();
        assert!(read_hook_auth_token(&dd).is_none());
        clear_hook_auth_token(&dd).expect("clearing twice must not error");
    }

    /// Adversarial: the stored hook key is a client credential, read by the
    /// hooks and, as a last resort, by `mcp-bridge`. `Config::load` must never
    /// adopt it, or `serve` on the same data dir would start requiring that
    /// key and accepting it as its bearer. Control: a key named by
    /// `[auth].bearer_token_file` is adopted.
    /// A blank allowlist entry would turn redaction off; loading drops it and
    /// keeps the real entries.
    #[test]
    fn config_load_drops_blank_sanitize_allowlist_entries() {
        let tmp = TempDir::new().unwrap();
        let dd = tmp.path().join("data");
        std::fs::create_dir_all(&dd).unwrap();
        let config_path = dd.join("config.toml");
        std::fs::write(
            &config_path,
            "[sanitize]\nallowlist = [\"\", \"   \", \"KEEP_ME\"]\n",
        )
        .unwrap();
        let cfg = Config::load_with_runtime_env(
            Some(&config_path),
            Some(dd.clone()),
            RuntimeEnv::default(),
        )
        .unwrap();
        assert_eq!(cfg.sanitize.allowlist, vec!["KEEP_ME".to_string()]);
    }

    #[test]
    fn config_load_never_adopts_the_stored_hook_key() {
        let tmp = TempDir::new().unwrap();
        let dd = tmp.path().join("data");
        store_hook_auth_token(&dd, "aim_hook_key").unwrap();
        let config_path = dd.join("config.toml");
        std::fs::write(&config_path, "bind = \"127.0.0.1:49921\"\n").unwrap();
        let cfg = Config::load_with_runtime_env(
            Some(&config_path),
            Some(dd.clone()),
            RuntimeEnv::default(),
        )
        .unwrap();
        assert_eq!(cfg.auth.bearer_token, None);
        assert!(cfg.auth.token_file_path().is_none());

        std::fs::write(
            &config_path,
            "bind = \"127.0.0.1:49921\"\n[auth]\nbearer_token_file = \"auth-token\"\n",
        )
        .unwrap();
        let cfg = Config::load_with_runtime_env(
            Some(&config_path),
            Some(dd.clone()),
            RuntimeEnv::default(),
        )
        .unwrap();
        assert_eq!(cfg.auth.bearer_token.as_deref(), Some("aim_hook_key"));
    }
    use super::*;
    use rstest::rstest;
    use secrecy::{ExposeSecret, SecretString};
    use tempfile::TempDir;

    #[test]
    fn auth_settings_debug_redacts_secrets_in_auth_and_config() {
        let auth = AuthSettings {
            bearer_token: Some("bearer-secret-sentinel".into()),
            root_username: Some("operator".into()),
            token_pepper: Some("pepper-secret-sentinel".into()),
            actor_proxy_bearer_token: Some("proxy-secret-sentinel".into()),
            initial_root_password: Some(SecretString::from("initial-password-sentinel")),
            recovery_token: Some(SecretString::from("recovery-token-sentinel-32chars")),
            ..AuthSettings::default()
        };
        let config = Config {
            auth: auth.clone(),
            ..Config::default()
        };

        for rendered in [format!("{auth:?}"), format!("{config:?}")] {
            assert!(rendered.contains("root_username: Some(\"operator\")"));
            assert!(rendered.contains("<redacted>"));
            for sentinel in [
                "bearer-secret-sentinel",
                "pepper-secret-sentinel",
                "proxy-secret-sentinel",
                "initial-password-sentinel",
                "recovery-token-sentinel-32chars",
            ] {
                assert!(
                    !rendered.contains(sentinel),
                    "Debug output exposed {sentinel}"
                );
            }
        }
    }

    #[test]
    fn validate_auth_settings_rejects_short_recovery_token() {
        let auth = AuthSettings {
            recovery_token: Some(SecretString::from("too-short-recovery-token")),
            ..AuthSettings::default()
        };
        let err = validate_auth_settings(&auth).unwrap_err();
        assert!(err.to_string().contains("32"), "{err:#}");
        assert!(!err.to_string().contains("too-short-recovery-token"));
    }

    #[test]
    fn validate_auth_settings_rejects_equal_recovery_and_bearer() {
        let secret = "this-recovery-token-is-32-chars!!";
        let auth = AuthSettings {
            bearer_token: Some(secret.into()),
            recovery_token: Some(SecretString::from(secret)),
            ..AuthSettings::default()
        };
        let err = validate_auth_settings(&auth).unwrap_err();
        assert!(err.to_string().contains("must differ"), "{err:#}");
    }

    #[test]
    fn validate_auth_settings_rejects_recovery_credential_prefixes() {
        for prefix in [
            ai_memory_core::SESSION_SECRET_PREFIX,
            ai_memory_core::NATIVE_API_KEY_PREFIX,
            ai_memory_core::EXTERNAL_API_KEY_PREFIX,
        ] {
            let auth = AuthSettings {
                recovery_token: Some(SecretString::from(format!(
                    "{prefix}reserved-recovery-token-padding-32"
                ))),
                ..AuthSettings::default()
            };
            let err = validate_auth_settings(&auth).unwrap_err();
            assert!(
                err.to_string().contains("reserved credential prefix"),
                "{err:#}"
            );
        }
    }

    /// The shipped `config.default.toml` must actually load.
    ///
    /// It is `include_str!`-ed by `init` and written as-is, so a template
    /// that does not parse would only surface when someone ran `init` and
    /// started the server. Comments added by #1269 are the kind of edit that
    /// can break it silently (a stray quote, a line that stops being a
    /// comment), and nothing tested the file itself.
    #[test]
    fn the_shipped_default_config_parses() {
        const TEMPLATE: &str = include_str!("../templates/config.default.toml");
        let cfg = load_with_toml(TEMPLATE).expect("config.default.toml must load");
        assert_eq!(cfg.bind, DEFAULT_BIND);
        assert_eq!(
            cfg.server_url, DEFAULT_SERVER_URL,
            "the template leaves server_url unset, so the default bind derives the default URL"
        );
        assert!(
            !cfg.server_url_derived_from_bind,
            "the default bind short-circuits the derivation, so nothing is marked derived"
        );
    }

    /// #1506: an example table in the shipped config must not capture the
    /// top-level examples below it.
    ///
    /// A TOML table header owns every key after it. The commented
    /// `[run.profiles.work.env]` and `[ingest]` examples sat above top-level
    /// examples such as `reranker` and `capture_assistant`, so an operator who
    /// uncommented both put the top-level key inside the table: `[ingest]`
    /// dropped it without a warning, and the profile's string-only env map
    /// refused it or exported it to the harness. Top-level keys end at the
    /// first real table, so the example tables belong below it, and
    /// uncommenting every example must still set the keys they document.
    #[test]
    fn the_shipped_default_config_examples_keep_their_tables() {
        const TEMPLATE: &str = include_str!("../templates/config.default.toml");
        // A one-line example is `# ` followed by a line that parses as TOML on
        // its own. Indented examples stay commented: some are alternatives
        // for the same key, others span several lines.
        fn example(line: &str) -> Option<&str> {
            line.strip_prefix("# ")
                .filter(|code| !code.starts_with(' '))
                .filter(|code| code.parse::<toml_edit::DocumentMut>().is_ok())
        }

        let first_table = TEMPLATE
            .lines()
            .position(|line| line.trim_start().starts_with('['))
            .expect("the template declares tables");
        for line in TEMPLATE.lines().take(first_table) {
            let example_table = example(line).is_some_and(|code| code.starts_with('['));
            assert!(
                !example_table,
                "{line:?} is above the first table and would capture top-level keys"
            );
        }

        let uncommented = TEMPLATE
            .lines()
            .map(|line| example(line).unwrap_or(line))
            .collect::<Vec<_>>()
            .join("\n");
        let cfg = load_with_toml(&uncommented).expect("the uncommented template must load");
        assert_eq!(cfg.reranker.as_deref(), Some("llm"));
        assert_eq!(
            cfg.run.profiles["work"].env.keys().collect::<Vec<_>>(),
            ["ANTHROPIC_BASE_URL", "CLAUDE_CONFIG_DIR"]
        );
        assert_eq!(cfg.ingest.drop_tool_use_id_prefixes, ["toolu_plugin_"]);
        assert_eq!(cfg.ingest.drop_tool_names, ["mcp__noisy__poll"]);
    }

    /// #1269: a thin client must reach the server the SAME config starts.
    ///
    /// `server_url` defaulted to a constant and was never derived from `bind`,
    /// so `ai-memory --data-dir X status` called `127.0.0.1:49374` whatever
    /// `bind` said. With nothing listening there the command failed; with the
    /// default install's server listening there it silently operated on the
    /// WRONG store, which is how the reporter wrote twelve test pages into
    /// their real one.
    ///
    /// Each case here is one cell of the truth table: what the file sets, what
    /// the environment sets, and the URL the client must end up using.
    #[test]
    fn server_url_is_derived_from_a_custom_bind() {
        // No `server_url` anywhere: the bind decides. The port differs from
        // the default on purpose, so a client that ignored `bind` would be
        // caught rather than accidentally matching.
        let cfg = load_with_toml("bind = \"127.0.0.1:49921\"\n").unwrap();
        assert_eq!(cfg.bind, "127.0.0.1:49921");
        assert_eq!(cfg.server_url, "http://127.0.0.1:49921");

        // A LAN bind is used as given: the operator named a real interface.
        let cfg = load_with_toml("bind = \"192.0.2.10:8080\"\n").unwrap();
        assert_eq!(cfg.server_url, "http://192.0.2.10:8080");

        // A hostname is passed through rather than resolved: the server may
        // bind a name this process cannot resolve the same way.
        let cfg = load_with_toml("bind = \"memory.lan:9000\"\n").unwrap();
        assert_eq!(cfg.server_url, "http://memory.lan:9000");
    }

    /// An unspecified bind is not a reachable address, so it maps to loopback
    /// the way a client would have to reach it anyway.
    #[test]
    fn server_url_maps_an_unspecified_bind_to_loopback() {
        let cfg = load_with_toml("bind = \"0.0.0.0:49921\"\n").unwrap();
        assert_eq!(cfg.server_url, "http://127.0.0.1:49921");

        let cfg = load_with_toml("bind = \"[::]:49921\"\n").unwrap();
        assert_eq!(
            cfg.server_url, "http://[::1]:49921",
            "an IPv6 unspecified address must map to the IPv6 loopback, not to 0.0.0.0"
        );

        // A specific IPv6 address is used as given, brackets included.
        let cfg = load_with_toml("bind = \"[::1]:49921\"\n").unwrap();
        assert_eq!(cfg.server_url, "http://[::1]:49921");
    }

    /// An explicit `server_url` still wins, in the file and in the
    /// environment. This is the control for the derivation: without it a
    /// change that ignored the operator's own value would look correct.
    #[test]
    fn an_explicit_server_url_still_wins_over_a_custom_bind() {
        let cfg =
            load_with_toml("bind = \"127.0.0.1:49921\"\nserver_url = \"https://memory.example\"\n")
                .unwrap();
        assert_eq!(cfg.server_url, "https://memory.example");

        // The environment wins over the file, as it does for every other key.
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(
            &config_path,
            "bind = \"127.0.0.1:49921\"\nserver_url = \"https://from-file.example\"\n",
        )
        .unwrap();
        let cfg = Config::load_with_runtime_env(
            Some(&config_path),
            Some(tmp.path().to_path_buf()),
            RuntimeEnv {
                server_url: Some("https://from-env.example".into()),
                ..RuntimeEnv::default()
            },
        )
        .unwrap();
        assert_eq!(cfg.server_url, "https://from-env.example");
    }

    /// An explicit `server_url` that happens to name the default URL is still
    /// explicit: neither the file nor the environment may be overridden by a
    /// custom `bind` just because the value matches the default.
    #[test]
    fn an_explicit_default_server_url_is_not_rederived_from_bind() {
        let cfg = load_with_toml(&format!(
            "bind = \"127.0.0.1:49921\"\nserver_url = \"{DEFAULT_SERVER_URL}\"\n"
        ))
        .unwrap();
        assert_eq!(cfg.server_url, DEFAULT_SERVER_URL);
        assert!(!cfg.server_url_derived_from_bind);
        assert!(cfg.server_url_configured());

        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, "bind = \"127.0.0.1:49921\"\n").unwrap();
        let cfg = Config::load_with_runtime_env(
            Some(&config_path),
            Some(tmp.path().to_path_buf()),
            RuntimeEnv {
                server_url: Some(DEFAULT_SERVER_URL.into()),
                ..RuntimeEnv::default()
            },
        )
        .unwrap();
        assert_eq!(cfg.server_url, DEFAULT_SERVER_URL);
        assert!(!cfg.server_url_derived_from_bind);
        assert!(cfg.server_url_configured());
    }

    /// `data_dir_explicit` records whether the flag, the environment or the
    /// file chose the data dir, never whether it differs from the default.
    #[test]
    fn data_dir_explicit_tracks_who_chose_the_data_dir() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, "bind = \"127.0.0.1:49921\"\n").unwrap();
        let load = |config_path: &Path, cli: Option<PathBuf>, env: Option<PathBuf>| {
            Config::load_with_runtime_env(
                Some(config_path),
                cli,
                RuntimeEnv {
                    data_dir: env,
                    ..RuntimeEnv::default()
                },
            )
            .unwrap()
        };

        assert!(!load(&config_path, None, None).data_dir_explicit);
        assert!(load(&config_path, Some(tmp.path().to_path_buf()), None).data_dir_explicit);
        assert!(load(&config_path, None, Some(tmp.path().to_path_buf())).data_dir_explicit);

        // The file's key counts even when it names the default dir itself.
        let from_file = tmp.path().join("from-file.toml");
        std::fs::write(
            &from_file,
            format!("data_dir = {:?}\n", default_data_dir().to_string_lossy()),
        )
        .unwrap();
        assert!(load(&from_file, None, None).data_dir_explicit);
    }

    /// A bind that maps onto the default URL (an unspecified address on the
    /// default port, as containers bind) is not a derivation.
    #[test]
    fn a_bind_that_maps_to_the_default_url_is_not_marked_derived() {
        let cfg = load_with_toml("bind = \"0.0.0.0:49374\"\n").unwrap();
        assert_eq!(cfg.server_url, DEFAULT_SERVER_URL);
        assert!(!cfg.server_url_derived_from_bind);
    }

    /// Port 0 picks a free port at startup, so no client URL can be derived
    /// from it; the default URL stays.
    #[test]
    fn a_port_zero_bind_keeps_the_default_server_url() {
        for bind in ["127.0.0.1:0", "0.0.0.0:0", "[::1]:0"] {
            let cfg = load_with_toml(&format!("bind = \"{bind}\"\n")).unwrap();
            assert_eq!(cfg.server_url, DEFAULT_SERVER_URL, "{bind}");
            assert!(!cfg.server_url_derived_from_bind, "{bind}");
        }
    }

    /// #1269: deriving the URL must not make an operator look like they
    /// configured it.
    ///
    /// `server_url_configured()` is what `install-hooks` and `install-mcp`
    /// read to decide whether to infer the URL from an existing MCP entry
    /// rather than fall back to the compiled default. Someone who only edited
    /// `bind` has not chosen a `server_url`, so the answer has to stay false
    /// or those installers change behaviour for them.
    #[test]
    fn a_derived_server_url_is_not_reported_as_configured() {
        let cfg = load_with_toml("bind = \"127.0.0.1:49921\"\n").unwrap();
        assert_eq!(cfg.server_url, "http://127.0.0.1:49921");
        assert!(
            cfg.server_url_derived_from_bind,
            "the loader must record that it derived the value"
        );
        assert!(
            !cfg.server_url_configured(),
            "a bind-derived URL is not an operator-configured one"
        );

        // Control: a value the operator actually wrote is still reported as
        // configured, and is not marked derived.
        let cfg = load_with_toml("server_url = \"https://memory.example\"\n").unwrap();
        assert!(!cfg.server_url_derived_from_bind);
        assert!(cfg.server_url_configured());

        // Control: the environment counts as explicit too, even when it names
        // the default URL.
        let tmp = TempDir::new().unwrap();
        let cfg = Config::load_with_runtime_env(
            None,
            Some(tmp.path().to_path_buf()),
            RuntimeEnv {
                server_url: Some(DEFAULT_SERVER_URL.into()),
                ..RuntimeEnv::default()
            },
        )
        .unwrap();
        assert!(!cfg.server_url_derived_from_bind);
        assert!(cfg.server_url_configured());
    }

    /// The default install must be byte-identical to before this change: the
    /// default bind derives exactly the default URL.
    #[test]
    fn the_default_bind_still_resolves_to_the_default_url() {
        let cfg = load_with_toml("").unwrap();
        assert_eq!(cfg.server_url, DEFAULT_SERVER_URL);
        assert_eq!(cfg.bind, DEFAULT_BIND);

        // Spelling the default bind out is not a "custom" bind and must not
        // change the outcome either.
        let cfg = load_with_toml(&format!("bind = \"{DEFAULT_BIND}\"\n")).unwrap();
        assert_eq!(cfg.server_url, DEFAULT_SERVER_URL);
    }

    /// A bind that cannot be parsed as `host:port` is not guessed at: the
    /// client falls back to the default URL instead of building a URL out of
    /// a fragment. `serve` still reports the bad bind when it starts.
    #[test]
    fn an_unparseable_bind_falls_back_to_the_default_url() {
        let cfg = load_with_toml("bind = \"not-a-bind\"\n").unwrap();
        assert_eq!(cfg.server_url, DEFAULT_SERVER_URL);
    }

    #[test]
    fn defaults_have_canonical_endings() {
        let cfg = Config::default();
        assert!(cfg.data_dir.ends_with("ai-memory"));
        assert_eq!(cfg.bind, DEFAULT_BIND);
        assert_eq!(cfg.tcp_keepalive_secs, DEFAULT_TCP_KEEPALIVE_SECS);
        assert_eq!(cfg.server_url, DEFAULT_SERVER_URL);
        assert_eq!(cfg.hook_spool.max_attempts, DEFAULT_HOOK_SPOOL_MAX_ATTEMPTS);
        assert_eq!(cfg.log_level, "info");
        assert_eq!(
            cfg.llm_timeout_secs,
            ai_memory_llm::DEFAULT_REQUEST_TIMEOUT_SECS
        );
        assert!(!cfg.auth.secure_cookie);
        assert!(cfg.maintenance.enabled);
        assert_eq!(cfg.maintenance.forget_sweep_interval_secs, 86_400);
        assert_eq!(cfg.maintenance.lint_interval_secs, 86_400);
        assert_eq!(cfg.maintenance.embedding_backfill_interval_secs, 0);
        assert_eq!(cfg.decay.breadth_weight, 0.0);
        // Observation pruning must stay OFF by default: an install that never
        // opts in keeps every raw observation it has today.
        assert_eq!(cfg.decay.observation_retention_days, 0);
        assert_eq!(cfg.decay.observation_prune_batch, 5_000);
        assert!(!cfg.decay.observation_retention().is_enabled());
        // Same contract for the hook event ledgers: kept unless opted in.
        assert_eq!(cfg.decay.ledger_retention_months, 0);
        assert!(!cfg.decay.ledger_retention().is_enabled());
        assert!(!cfg.slots.per_user);
        assert!(cfg.auto_improve.scheduler.enabled);
        assert_eq!(cfg.auto_improve.scheduler.interval_secs, 3_600);
        assert_eq!(cfg.auto_improve.scheduler.max_sessions_per_tick, 1);
        assert_eq!(cfg.auto_improve.scheduler.min_session_age_secs, 600);
        assert!(!cfg.auto_improve.on_session_end);
        assert!(!cfg.auto_improve.require_approval);
        assert_eq!(cfg.auto_improve.min_observations, 8);
        assert_eq!(cfg.auto_improve.min_session_duration_secs, 120);
        assert_eq!(
            cfg.auto_improve.min_confidence,
            DEFAULT_AUTO_IMPROVE_MIN_CONFIDENCE
        );
        assert_eq!(cfg.auto_improve.max_input_tokens, 24_000);
        assert_eq!(cfg.auto_improve.max_proposals_per_run, 5);
        assert_eq!(cfg.auto_improve.max_patchable_pages, 8);
        assert_eq!(cfg.auto_improve.max_patchable_body_chars, 8_000);
        assert_eq!(cfg.auto_improve.max_edits_per_proposal, 5);
        assert_eq!(cfg.auto_improve.max_edit_content_chars, 4_000);
        assert_eq!(cfg.auto_improve.max_changed_chars_per_proposal, 12_000);
        assert_eq!(cfg.auto_improve.max_patch_edits_per_run, 8);
        assert_eq!(cfg.auto_improve.max_rejection_context, 50);
        assert_eq!(cfg.auto_improve.rejection_context_days, 180);
        assert_eq!(cfg.auto_improve.max_final_body_chars, 32_000);
        assert_eq!(cfg.auto_improve.max_rule_page_tokens, 2_000);
        assert_eq!(cfg.auto_improve.max_procedure_page_tokens, 2_000);
        assert!(!cfg.auto_improve.eval.enabled);
        assert_eq!(cfg.auto_improve.eval.command, "");
        assert_eq!(cfg.auto_improve.eval.timeout_secs, 120);
        assert_eq!(cfg.auto_improve.eval.targets, vec!["_rules", "procedures"]);
        assert_eq!(cfg.auto_improve.eval.min_delta, 0.0);
        assert!(!cfg.auto_improve.include_raw_fallback);
        assert_eq!(cfg.auto_improve.proposal_actor, "auto_improve");
        assert_eq!(cfg.auto_improve.pending_path, "_pending/auto-improve");
    }

    #[test]
    fn cli_override_wins() {
        let tmp = TempDir::new().unwrap();
        let cli_dir = tmp.path().join("override");
        let cfg = Config::load(None, Some(cli_dir.clone())).unwrap();
        assert_eq!(
            cfg.data_dir,
            // We don't expect the directory to exist yet, so the
            // canonicalise-parent fallback will return parent + name.
            cli_dir
                .parent()
                .and_then(|p| p.canonicalize().ok())
                .map(|c| c.join(cli_dir.file_name().unwrap()))
                .unwrap_or(cli_dir)
        );
    }

    /// An install that never touched `contradiction_band_min`/`_max` sees no
    /// change: the defaults are exactly the historical fixed band.
    #[test]
    fn contradiction_band_defaults_match_the_historical_fixed_band() {
        let cfg = Config::default();
        assert_eq!(
            cfg.contradiction_band_min,
            ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW
        );
        assert_eq!(
            cfg.contradiction_band_max,
            ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH
        );
    }

    #[test]
    fn load_rejects_invalid_contradiction_band() {
        for (min, max) in [
            ("0.8", "0.4"),   // min >= max (inverted)
            ("0.4", "0.4"),   // min >= max (equal)
            ("-0.1", "0.75"), // min out of range
            ("0.4", "1.5"),   // max out of range
            ("nan", "0.75"),  // NaN
            ("0.4", "nan"),   // NaN
            ("0.4", "inf"),   // infinite (not finite)
        ] {
            let tmp = TempDir::new().unwrap();
            let config_path = tmp.path().join("config.toml");
            std::fs::write(
                &config_path,
                format!("contradiction_band_min = {min}\ncontradiction_band_max = {max}\n"),
            )
            .unwrap();
            let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
                .expect_err(&format!("min={min} max={max} must fail closed"));
            assert!(
                error.to_string().contains("contradiction_band"),
                "unexpected error for min={min} max={max}: {error:#}"
            );
        }
    }

    #[test]
    fn retrieval_observation_stream_defaults_on_and_loads_from_toml() {
        assert!(Config::default().retrieval.tuning().observation_stream);
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, "[retrieval]\nobservation_stream = false\n").unwrap();
        let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
        assert!(!config.retrieval.tuning().observation_stream);
        // The other [retrieval] signals keep their defaults.
        assert!(!config.retrieval.tuning().abstract_vectors);
        // A config that never names the key gets the default.
        std::fs::write(&config_path, "[retrieval]\nabstract_vectors = false\n").unwrap();
        let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
        assert!(config.retrieval.tuning().observation_stream);
    }

    #[test]
    fn retrieval_observation_stream_env_overrides_config() {
        const CHILD_MARKER: &str = "AI_MEMORY_TEST_OBSERVATION_STREAM_CHILD";
        if std::env::var_os(CHILD_MARKER).is_some() {
            let tmp = TempDir::new().unwrap();
            let config_path = tmp.path().join("config.toml");
            std::fs::write(&config_path, "[retrieval]\nobservation_stream = true\n").unwrap();
            let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
            assert!(!config.retrieval.tuning().observation_stream);
            println!("observation-stream-env-applied");
            return;
        }

        let output = std::process::Command::new(std::env::current_exe().unwrap())
            .arg("--exact")
            .arg("config::tests::retrieval_observation_stream_env_overrides_config")
            .arg("--test-threads=1")
            .arg("--nocapture")
            .env(CHILD_MARKER, "1")
            .env("AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM", "false")
            .output()
            .unwrap();
        assert!(
            output.status.success(),
            "child test failed:\nstdout: {}\nstderr: {}",
            String::from_utf8_lossy(&output.stdout),
            String::from_utf8_lossy(&output.stderr)
        );
        assert!(
            String::from_utf8_lossy(&output.stdout).contains("observation-stream-env-applied"),
            "child stdout: {}",
            String::from_utf8_lossy(&output.stdout)
        );
    }

    #[test]
    fn load_rejects_destructive_invalid_breadth_weights() {
        for value in ["-0.1", "nan", "inf"] {
            let tmp = TempDir::new().unwrap();
            let config_path = tmp.path().join("config.toml");
            std::fs::write(&config_path, format!("[decay]\nbreadth_weight = {value}\n")).unwrap();
            let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
                .expect_err("invalid breadth weight must fail closed");
            assert!(
                error.to_string().contains("breadth_weight"),
                "unexpected error for {value}: {error:#}"
            );
        }
    }

    // --- issue #953: `[search.fts]` stopword config -------------------

    /// Absent `[search.fts]` resolves to `None`, which `FtsSettings::stopwords`
    /// turns into the built-in English list — an install that never touches
    /// this key sees byte-identical search behaviour.
    #[test]
    fn absent_search_fts_defaults_to_builtin_english_list() {
        let cfg = Config::default();
        assert_eq!(cfg.search.fts.stopwords, None);
        assert_eq!(
            cfg.search.fts.stopwords(),
            ai_memory_store::FtsStopwords::default()
        );
    }

    /// An explicit empty list parses to `Some(vec![])`, which resolves to
    /// "no filtering" rather than being treated the same as an absent key.
    #[test]
    fn explicit_empty_search_fts_stopwords_disables_filtering() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, "[search.fts]\nstopwords = []\n").unwrap();
        let cfg = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
        assert_eq!(cfg.search.fts.stopwords, Some(Vec::new()));
        assert_eq!(
            cfg.search.fts.stopwords(),
            ai_memory_store::FtsStopwords::none()
        );
    }

    /// A configured list parses verbatim and resolves to exactly those
    /// words (lowercased), replacing the default outright rather than
    /// extending it.
    fn load_auth(data_dir: &Path, toml: &str, env_token: Option<&str>) -> Result<Config> {
        let config_path = data_dir.join("config.toml");
        std::fs::write(&config_path, toml).unwrap();
        Config::load_with_runtime_env(
            Some(&config_path),
            Some(data_dir.to_path_buf()),
            RuntimeEnv {
                auth_token: env_token.map(str::to_owned),
                ..RuntimeEnv::default()
            },
        )
    }

    /// A relative `bearer_token_file` resolves against the data dir it was
    /// loaded with, so a container (data dir `/data`) and a host client (the
    /// host path of the same bind mount) read one file.
    #[test]
    fn a_relative_bearer_token_file_resolves_against_the_data_dir() {
        let tmp = TempDir::new().unwrap();
        for dir in ["host", "container"] {
            let dd = tmp.path().join(dir);
            std::fs::create_dir_all(dd.join("auth-tokens")).unwrap();
            std::fs::write(
                dd.join("auth-tokens").join("default"),
                format!("tok-{dir}\n"),
            )
            .unwrap();
            let config = load_auth(
                &dd,
                "[auth]\nbearer_token_file = \"auth-tokens/default\"\n",
                None,
            )
            .unwrap();
            assert_eq!(
                config.auth.bearer_token.as_deref(),
                Some(format!("tok-{dir}").as_str())
            );
            assert_eq!(config.auth.renderable_bearer_token(), None);
            assert_eq!(
                config.auth.token_file_path(),
                Some(config.data_dir.join("auth-tokens/default").as_path())
            );
            assert_eq!(config.auth.missing_token_file(), None);
        }
    }

    #[test]
    fn an_absolute_bearer_token_file_is_read_as_is() {
        let tmp = TempDir::new().unwrap();
        let elsewhere = tmp.path().join("secret");
        std::fs::write(&elsewhere, "abs-token").unwrap();
        let toml = format!(
            "[auth]\nbearer_token_file = {}\n",
            toml_edit::Value::from(elsewhere.to_string_lossy().as_ref())
        );
        let config = load_auth(tmp.path(), &toml, None).unwrap();
        assert_eq!(config.auth.bearer_token.as_deref(), Some("abs-token"));
    }

    /// A configured file that is missing or blank yields no bearer, never an
    /// empty one, and is reported so `serve` can refuse to start open.
    #[test]
    fn a_missing_or_blank_bearer_token_file_is_reported_not_guessed() {
        let tmp = TempDir::new().unwrap();
        let toml = "[auth]\nbearer_token_file = \"auth-tokens/default\"\n";
        let missing = load_auth(tmp.path(), toml, None).unwrap();
        assert!(missing.auth.bearer_token.is_none());
        assert!(missing.auth.missing_token_file().is_some());

        std::fs::create_dir_all(tmp.path().join("auth-tokens")).unwrap();
        std::fs::write(tmp.path().join("auth-tokens").join("default"), " \n").unwrap();
        let blank = load_auth(tmp.path(), toml, None).unwrap();
        assert!(blank.auth.bearer_token.is_none());
        assert!(blank.auth.missing_token_file().is_some());
    }

    /// `AI_MEMORY_AUTH_TOKEN` wins over the file, as it wins over the inline
    /// key, and then counts as an inline (renderable) token as before.
    #[test]
    fn the_env_token_wins_over_the_bearer_token_file() {
        let tmp = TempDir::new().unwrap();
        std::fs::create_dir_all(tmp.path().join("auth-tokens")).unwrap();
        std::fs::write(tmp.path().join("auth-tokens").join("default"), "file-token").unwrap();
        let config = load_auth(
            tmp.path(),
            "[auth]\nbearer_token_file = \"auth-tokens/default\"\n",
            Some("env-token"),
        )
        .unwrap();
        assert_eq!(config.auth.bearer_token.as_deref(), Some("env-token"));
        assert_eq!(config.auth.renderable_bearer_token(), Some("env-token"));
        assert_eq!(config.auth.token_file_path(), None);
    }

    #[test]
    fn an_inline_bearer_and_a_bearer_token_file_together_are_refused() {
        let tmp = TempDir::new().unwrap();
        let err = load_auth(
            tmp.path(),
            "[auth]\nbearer_token = \"inline\"\nbearer_token_file = \"auth-tokens/default\"\n",
            None,
        )
        .unwrap_err();
        assert!(format!("{err:#}").contains("both set"), "{err:#}");
    }

    fn plant_root_token(data_dir: &Path) {
        std::fs::create_dir_all(data_dir.join("auth-tokens")).unwrap();
        std::fs::write(data_dir.join("auth-tokens").join("default"), "root-token\n").unwrap();
    }

    fn load_without_config(data_dir: &Path, runtime_env: RuntimeEnv) -> Config {
        Config::load_with_runtime_env(None, Some(data_dir.to_path_buf()), runtime_env).unwrap()
    }

    /// A packaged install's client commands read no config file (it lives
    /// outside the data dir) and still find the token `init` minted, as a
    /// file-sourced token.
    #[test]
    fn a_client_without_a_config_file_discovers_the_root_bearer() {
        let tmp = TempDir::new().unwrap();
        plant_root_token(tmp.path());
        let config = load_without_config(tmp.path(), RuntimeEnv::default());
        assert_eq!(config.auth.bearer_token.as_deref(), Some("root-token"));
        assert_eq!(config.auth.renderable_bearer_token(), None);
    }

    /// Each guard on discovery, with the case above as the control.
    #[test]
    fn root_bearer_discovery_is_refused_outside_its_narrow_case() {
        // A config file exists and names no token: that install runs open.
        let tmp = TempDir::new().unwrap();
        plant_root_token(tmp.path());
        let config = load_auth(tmp.path(), "[auth]\nsecure_cookie = false\n", None).unwrap();
        assert!(
            config.auth.bearer_token.is_none(),
            "existing config keeps its posture"
        );

        // A remote server must never be handed this machine's root bearer.
        let tmp = TempDir::new().unwrap();
        plant_root_token(tmp.path());
        let remote = load_without_config(
            tmp.path(),
            RuntimeEnv {
                server_url: Some("https://memory.example".into()),
                ..RuntimeEnv::default()
            },
        );
        assert!(remote.auth.bearer_token.is_none());

        // Nor a remote server whose URL starts with a loopback name: the text
        // before `@` is user information, not the host.
        for url in [
            "http://localhost:[email protected]",
            "http://127.0.0.1:[email protected]/",
        ] {
            let tmp = TempDir::new().unwrap();
            plant_root_token(tmp.path());
            let disguised = load_without_config(
                tmp.path(),
                RuntimeEnv {
                    server_url: Some(url.into()),
                    ..RuntimeEnv::default()
                },
            );
            assert!(disguised.auth.bearer_token.is_none(), "{url}");
        }

        // A registered profile named `default` owns that file (#992).
        let tmp = TempDir::new().unwrap();
        let name = crate::server_profiles::ProfileName::parse("default").unwrap();
        crate::server_profiles::add(tmp.path(), &name, "https://team.example", &[], Some("team"))
            .unwrap();
        let profiled = load_without_config(tmp.path(), RuntimeEnv::default());
        assert!(
            profiled.auth.bearer_token.is_none(),
            "a profile token is not a root bearer"
        );

        // An explicit env token wins, as always.
        let tmp = TempDir::new().unwrap();
        plant_root_token(tmp.path());
        let env = load_without_config(
            tmp.path(),
            RuntimeEnv {
                auth_token: Some("env".into()),
                ..RuntimeEnv::default()
            },
        );
        assert_eq!(env.auth.bearer_token.as_deref(), Some("env"));
        assert_eq!(env.auth.token_file_path(), None);
    }

    /// Control: a pre-default config (no key) loads exactly as before, inline
    /// token renderable, no file consulted.
    #[test]
    fn a_config_without_a_bearer_token_file_loads_as_before() {
        let tmp = TempDir::new().unwrap();
        let open = load_auth(tmp.path(), "[auth]\nsecure_cookie = false\n", None).unwrap();
        assert!(open.auth.bearer_token.is_none());
        assert_eq!(open.auth.token_file_path(), None);
        let inline = load_auth(tmp.path(), "[auth]\nbearer_token = \"inline\"\n", None).unwrap();
        assert_eq!(inline.auth.renderable_bearer_token(), Some("inline"));
    }

    #[test]
    fn hook_spool_max_attempts_config_and_runtime_override_precedence() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, "[hook_spool]\nmax_attempts = 3\n").unwrap();

        let from_config = Config::load_with_runtime_env(
            Some(&config_path),
            Some(tmp.path().to_path_buf()),
            RuntimeEnv::default(),
        )
        .unwrap();
        assert_eq!(from_config.hook_spool.max_attempts, 3);

        let overridden = Config::load_with_runtime_env(
            Some(&config_path),
            Some(tmp.path().to_path_buf()),
            RuntimeEnv {
                hook_spool_max_attempts: Some("0".into()),
                ..RuntimeEnv::default()
            },
        )
        .unwrap();
        assert_eq!(overridden.hook_spool.max_attempts, 0);
    }

    #[test]
    fn run_exit_prompt_rejects_invalid_environment_values() {
        let tmp = TempDir::new().unwrap();
        for raw in ["", "not-a-bool"] {
            let error = Config::load_with_runtime_env(
                Some(&tmp.path().join("config.toml")),
                Some(tmp.path().to_path_buf()),
                RuntimeEnv::with_process_env_for_tests(&[("AI_MEMORY_RUN_EXIT_PROMPT", raw)]),
            )
            .unwrap_err();
            assert!(
                error
                    .to_string()
                    .contains("AI_MEMORY_RUN_EXIT_PROMPT must be true or false")
            );
        }
    }

    #[test]
    fn run_require_server_config_and_runtime_env() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");

        let off = Config::load_with_runtime_env(
            Some(&config_path),
            Some(tmp.path().to_path_buf()),
            RuntimeEnv::default(),
        )
        .unwrap();
        assert!(!off.run.require_server, "off by default");

        std::fs::write(&config_path, "[run]\nrequire_server = true\n").unwrap();
        let from_config = Config::load_with_runtime_env(
            Some(&config_path),
            Some(tmp.path().to_path_buf()),
            RuntimeEnv::default(),
        )
        .unwrap();
        assert!(from_config.run.require_server);

        // The env var only turns it on; it never turns a config-file on back
        // off, and a non-truthy spelling is inert.
        for raw in ["", "false", "no", "0"] {
            let inert = Config::load_with_runtime_env(
                Some(&config_path),
                Some(tmp.path().to_path_buf()),
                RuntimeEnv {
                    run_require_server: Some(raw.into()),
                    ..RuntimeEnv::default()
                },
            )
            .unwrap();
            assert!(inert.run.require_server, "{raw:?} must stay inert");
        }
        let truthy = Config::load_with_runtime_env(
            Some(&config_path),
            None,
            RuntimeEnv {
                run_require_server: Some("true".into()),
                ..RuntimeEnv::default()
            },
        )
        .unwrap();
        assert!(truthy.run.require_server);
    }

    #[test]
    fn loader_hook_spool_runtime_env_overrides_config() {
        const CHILD_MARKER: &str = "AI_MEMORY_TEST_HOOK_SPOOL_CONFIG_CHILD";
        if std::env::var_os(CHILD_MARKER).is_some() {
            let tmp = TempDir::new().unwrap();
            let config_path = tmp.path().join("config.toml");
            std::fs::write(&config_path, "[hook_spool]\nmax_attempts = 3\n").unwrap();
            let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
            assert_eq!(config.hook_spool.max_attempts, 0);
            println!("runtime-override-applied");
            return;
        }

        let output = std::process::Command::new(std::env::current_exe().unwrap())
            .arg("--exact")
            .arg("config::tests::loader_hook_spool_runtime_env_overrides_config")
            .arg("--test-threads=1")
            .arg("--nocapture")
            .env(CHILD_MARKER, "1")
            .env("AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS", "0")
            .output()
            .unwrap();
        assert!(
            output.status.success(),
            "child test failed:\nstdout: {}\nstderr: {}",
            String::from_utf8_lossy(&output.stdout),
            String::from_utf8_lossy(&output.stderr)
        );
        assert!(
            String::from_utf8_lossy(&output.stdout).contains("runtime-override-applied"),
            "child stdout: {}",
            String::from_utf8_lossy(&output.stdout)
        );
    }

    #[test]
    fn invalid_hook_spool_max_attempts_values_use_default() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        for invalid in ["-1", "\"invalid\""] {
            std::fs::write(
                &config_path,
                format!("[hook_spool]\nmax_attempts = {invalid}\n"),
            )
            .unwrap();
            let config = Config::load_with_runtime_env(
                Some(&config_path),
                Some(tmp.path().to_path_buf()),
                RuntimeEnv::default(),
            )
            .unwrap();
            assert_eq!(
                config.hook_spool.max_attempts, DEFAULT_HOOK_SPOOL_MAX_ATTEMPTS,
                "invalid config value {invalid} must use the default"
            );
        }

        std::fs::remove_file(&config_path).unwrap();
        for invalid in ["invalid", "-1", ""] {
            let invalid_env = Config::load_with_runtime_env(
                Some(&config_path),
                Some(tmp.path().to_path_buf()),
                RuntimeEnv {
                    hook_spool_max_attempts: Some(invalid.into()),
                    ..RuntimeEnv::default()
                },
            )
            .unwrap();
            assert_eq!(
                invalid_env.hook_spool.max_attempts, DEFAULT_HOOK_SPOOL_MAX_ATTEMPTS,
                "invalid env value {invalid:?} must use the default"
            );
        }
    }

    #[test]
    fn configured_search_fts_stopwords_list_parses_and_replaces_default() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(
            &config_path,
            "[search.fts]\nstopwords = [\"O\", \"de\", \"que\"]\n",
        )
        .unwrap();
        let cfg = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
        assert_eq!(
            cfg.search.fts.stopwords,
            Some(vec!["O".to_string(), "de".to_string(), "que".to_string()])
        );
        let resolved = cfg.search.fts.stopwords();
        // Replaces, not extends: an English stopword absent from the
        // configured list is no longer filtered.
        assert_eq!(
            resolved,
            ai_memory_store::FtsStopwords::new(["o", "de", "que"])
        );
        assert_ne!(resolved, ai_memory_store::FtsStopwords::default());
    }

    #[test]
    fn load_rejects_oversized_search_fts_stopwords_list() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        let words: Vec<String> = (0..(MAX_FTS_STOPWORDS + 1))
            .map(|i| format!("w{i}"))
            .collect();
        let toml = format!(
            "[search.fts]\nstopwords = [{}]\n",
            words
                .iter()
                .map(|w| format!("{w:?}"))
                .collect::<Vec<_>>()
                .join(", ")
        );
        std::fs::write(&config_path, toml).unwrap();
        let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
            .expect_err("oversized stopword list must fail closed");
        assert!(
            error.to_string().contains("search.fts.stopwords"),
            "unexpected error: {error:#}"
        );
    }

    #[test]
    fn load_rejects_blank_search_fts_stopword_entry() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, "[search.fts]\nstopwords = [\"de\", \"  \"]\n").unwrap();
        let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
            .expect_err("blank stopword entry must fail closed");
        assert!(
            error.to_string().contains("search.fts.stopwords"),
            "unexpected error: {error:#}"
        );
    }

    #[test]
    fn load_rejects_oversized_search_fts_stopword_entry() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        let long_word = "a".repeat(MAX_FTS_STOPWORD_LEN + 1);
        std::fs::write(
            &config_path,
            format!("[search.fts]\nstopwords = [{long_word:?}]\n"),
        )
        .unwrap();
        let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
            .expect_err("oversized stopword entry must fail closed");
        assert!(
            error.to_string().contains("search.fts.stopwords"),
            "unexpected error: {error:#}"
        );
    }

    // `apply_fts_stopwords_env` and `FtsSettings::validate` are pure
    // functions specifically so the env-override and validation logic stay
    // unit-testable without mutating process env — `std::env::set_var` is
    // unsafe under edition 2024 and forbidden workspace-wide, since it races
    // every other test in this crate's multi-threaded lib test binary (see
    // `overlay_embedding_prefixes`'s doc comment above, the precedent this
    // mirrors). `Config::load` itself only ever reads the env var once and
    // hands it to `apply_fts_stopwords_env` as a plain `Option<&str>`.

    #[test]
    fn apply_fts_stopwords_env_ignores_absent_env() {
        let mut cfg = Config::default();
        apply_fts_stopwords_env(&mut cfg, None);
        assert_eq!(cfg.search.fts.stopwords, None);
    }

    /// A present-but-blank env var must mean "unset", never "disable
    /// filtering" — it must not clobber a real list `config.toml` already
    /// resolved. `stopwords = []` in `config.toml` remains the unambiguous
    /// way to disable filtering.
    #[test]
    fn apply_fts_stopwords_env_treats_blank_as_unset_and_does_not_clobber_config() {
        let mut cfg = Config {
            search: SearchSettings {
                fts: FtsSettings {
                    stopwords: Some(vec!["de".to_string()]),
                },
            },
            ..Config::default()
        };
        apply_fts_stopwords_env(&mut cfg, Some(""));
        assert_eq!(
            cfg.search.fts.stopwords,
            Some(vec!["de".to_string()]),
            "blank env must not clobber an already-configured list"
        );
        apply_fts_stopwords_env(&mut cfg, Some("   "));
        assert_eq!(
            cfg.search.fts.stopwords,
            Some(vec!["de".to_string()]),
            "whitespace-only env must not clobber it either"
        );
    }

    #[test]
    fn apply_fts_stopwords_env_parses_csv_and_overrides() {
        let mut cfg = Config::default();
        apply_fts_stopwords_env(&mut cfg, Some("o, de , que"));
        assert_eq!(
            cfg.search.fts.stopwords,
            Some(vec!["o".to_string(), "de".to_string(), "que".to_string()])
        );
    }

    /// A CSV value that is present (non-blank as a whole string) but has no
    /// real entries once split and trimmed still resolves to an explicit
    /// empty list — matching `deserialize_string_or_vec`'s own filtering —
    /// distinct from a truly blank/absent env var.
    #[test]
    fn apply_fts_stopwords_env_comma_only_value_yields_explicit_empty_list() {
        let mut cfg = Config::default();
        apply_fts_stopwords_env(&mut cfg, Some(" , , "));
        assert_eq!(cfg.search.fts.stopwords, Some(Vec::new()));
    }

    #[test]
    fn fts_settings_validate_accepts_none_and_explicit_empty() {
        assert!(FtsSettings::default().validate().is_ok());
        let mut empty = FtsSettings {
            stopwords: Some(Vec::new()),
        };
        assert!(empty.validate().is_ok());
    }

    /// Ends are trimmed rather than rejected (a hand-edited `config.toml` or
    /// CSV env value can easily carry a stray space).
    #[test]
    fn fts_settings_validate_trims_entry_ends_without_rejecting() {
        let mut fts = FtsSettings {
            stopwords: Some(vec![" de".to_string(), "que ".to_string()]),
        };
        fts.validate().unwrap();
        assert_eq!(
            fts.stopwords,
            Some(vec!["de".to_string(), "que".to_string()])
        );
    }

    /// An entry with INTERNAL whitespace (`"de la"`) can never equal one
    /// `str::split_whitespace()` token, so it would look configured while
    /// silently doing nothing — reject it instead.
    #[test]
    fn fts_settings_validate_rejects_internal_whitespace_entry() {
        let mut fts = FtsSettings {
            stopwords: Some(vec!["de la".to_string()]),
        };
        let err = fts.validate().unwrap_err();
        assert!(err.contains("internal whitespace"), "{err}");
    }

    #[test]
    fn fts_settings_validate_rejects_blank_entry() {
        let mut fts = FtsSettings {
            stopwords: Some(vec!["  ".to_string()]),
        };
        let err = fts.validate().unwrap_err();
        assert!(err.contains("empty or whitespace-only"), "{err}");
    }

    #[test]
    fn fts_settings_validate_rejects_oversized_entry() {
        let mut fts = FtsSettings {
            stopwords: Some(vec!["a".repeat(MAX_FTS_STOPWORD_LEN + 1)]),
        };
        let err = fts.validate().unwrap_err();
        assert!(err.contains("character limit"), "{err}");
    }

    #[test]
    fn fts_settings_validate_rejects_oversized_list() {
        let mut fts = FtsSettings {
            stopwords: Some(
                (0..(MAX_FTS_STOPWORDS + 1))
                    .map(|i| format!("w{i}"))
                    .collect(),
            ),
        };
        let err = fts.validate().unwrap_err();
        assert!(err.contains("at most"), "{err}");
    }

    /// `[decay.half_life_days]` parses per-tier half-lives (in days) and
    /// converts each to the internal λ; an omitted key falls back to the scalar
    /// `lambda`, so the resulting `DecayParams` is a pure identity for every
    /// unset tier.
    #[test]
    fn load_parses_per_tier_half_lives_and_falls_back_for_omitted_keys() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(
            &config_path,
            "[decay.half_life_days]\nepisodic = 365.0\nworking = 7.0\n",
        )
        .unwrap();
        let cfg = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
        let params = cfg.decay.decay_params();

        // Configured tiers convert days -> λ = ln(2) / days.
        let expect = |days: f64| std::f64::consts::LN_2 / days;
        assert_eq!(
            params.lambda_for(ai_memory_core::Tier::Episodic).to_bits(),
            expect(365.0).to_bits(),
        );
        assert_eq!(
            params.lambda_for(ai_memory_core::Tier::Working).to_bits(),
            expect(7.0).to_bits(),
        );
        // Omitted tiers fall back to the scalar λ, byte-for-byte.
        assert_eq!(
            params.lambda_for(ai_memory_core::Tier::Semantic).to_bits(),
            params.lambda.to_bits(),
        );
        assert_eq!(
            params
                .lambda_for(ai_memory_core::Tier::Procedural)
                .to_bits(),
            params.lambda.to_bits(),
        );
    }

    /// With no `[decay.half_life_days]` table the resolved `DecayParams` is the
    /// store default: every tier's λ is the scalar `lambda` (the identity
    /// upgrade guarantee at the config layer).
    #[test]
    fn load_without_half_lives_is_identity_to_the_default_params() {
        let tmp = TempDir::new().unwrap();
        let cfg = Config::load(None, Some(tmp.path().to_path_buf())).unwrap();
        let params = cfg.decay.decay_params();
        let default = ai_memory_store::DecayParams::default();
        for tier in [
            ai_memory_core::Tier::Working,
            ai_memory_core::Tier::Episodic,
            ai_memory_core::Tier::Semantic,
            ai_memory_core::Tier::Procedural,
        ] {
            assert_eq!(
                params.lambda_for(tier).to_bits(),
                default.lambda_for(tier).to_bits(),
                "tier {tier:?} must decay at the default scalar λ",
            );
        }
    }

    /// A zero, negative, or non-finite half-life converts to a nonsensical λ,
    /// so it is rejected at load rather than silently mass-evicting (or never
    /// decaying) that tier.
    #[test]
    fn load_rejects_invalid_per_tier_half_lives() {
        for (tier, value) in [
            ("episodic", "0.0"),
            ("working", "-5.0"),
            ("semantic", "nan"),
            ("procedural", "inf"),
        ] {
            let tmp = TempDir::new().unwrap();
            let config_path = tmp.path().join("config.toml");
            std::fs::write(
                &config_path,
                format!("[decay.half_life_days]\n{tier} = {value}\n"),
            )
            .unwrap();
            let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
                .expect_err("an invalid per-tier half-life must fail closed");
            assert!(
                error
                    .to_string()
                    .contains(&format!("decay.half_life_days.{tier}")),
                "unexpected error for {tier} = {value}: {error:#}"
            );
        }
    }

    /// A negative retention age or a zero batch is rejected at load, beside
    /// the breadth-weight guard, so a destructive pass can never be configured
    /// into a nonsensical shape.
    #[test]
    fn load_rejects_destructive_invalid_observation_retention() {
        for (key, value) in [
            ("observation_retention_days", "-1"),
            ("observation_prune_batch", "0"),
        ] {
            let tmp = TempDir::new().unwrap();
            let config_path = tmp.path().join("config.toml");
            std::fs::write(&config_path, format!("[decay]\n{key} = {value}\n")).unwrap();
            let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
                .expect_err("invalid observation retention must fail closed");
            assert!(
                error.to_string().contains(key),
                "unexpected error for {key} = {value}: {error:#}"
            );
        }
    }

    /// A negative ledger age is rejected at load, like the observation age: a
    /// destructive pass is never configured into a nonsensical shape. `0` is
    /// the valid "disabled" value and loads.
    #[test]
    fn load_rejects_a_negative_ledger_retention() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, "[decay]\nledger_retention_months = -1\n").unwrap();
        let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
            .expect_err("a negative ledger retention must fail closed");
        assert!(
            error.to_string().contains("ledger_retention_months"),
            "unexpected error: {error:#}"
        );

        std::fs::write(&config_path, "[decay]\nledger_retention_months = 0\n").unwrap();
        let cfg = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
            .expect("zero disables the pass and must load");
        assert!(!cfg.decay.ledger_retention().is_enabled());

        std::fs::write(&config_path, "[decay]\nledger_retention_months = 12\n").unwrap();
        let cfg = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
            .expect("a positive age must load");
        assert_eq!(cfg.decay.ledger_retention().months, 12);
    }

    #[test]
    fn query_answer_budget_defaults_off_and_loads_explicit_limits() {
        assert_eq!(Config::default().query_answer.max_context_tokens, None);
        for limit in [0usize, 1, 16_000] {
            let tmp = TempDir::new().unwrap();
            let path = tmp.path().join("config.toml");
            std::fs::write(
                &path,
                format!("[query_answer]\nmax_context_tokens = {limit}\n"),
            )
            .unwrap();
            let config = Config::load_with_runtime_env(
                Some(&path),
                Some(tmp.path().to_path_buf()),
                RuntimeEnv::default(),
            )
            .unwrap();
            assert_eq!(config.query_answer.max_context_tokens, Some(limit));
        }
    }

    /// The consolidation budget must be big enough to leave room for
    /// observations after the fixed system prompt and page conventions.
    /// Below the floor every consolidation would be evidence-free, so it
    /// fails at startup instead of once per PreCompact.
    #[test]
    fn load_rejects_a_consolidation_budget_below_the_prompt_reserve() {
        let min = ai_memory_consolidate::MIN_CONSOLIDATION_MAX_INPUT_TOKENS;
        for value in [0, 1, min - 1] {
            let tmp = TempDir::new().unwrap();
            let config_path = tmp.path().join("config.toml");
            std::fs::write(
                &config_path,
                format!("[consolidation]\nmax_input_tokens = {value}\n"),
            )
            .unwrap();
            let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
                .expect_err("an unusable consolidation budget must fail closed");
            assert!(
                error.to_string().contains("consolidation.max_input_tokens"),
                "unexpected error for {value}: {error:#}"
            );
        }
    }

    /// #1234: the floor's promise is a *character* budget -- enough room for
    /// the fixed prompts plus `MIN_OBSERVATION_RESERVE_CHARS` of evidence -- so
    /// the check has to score the configured budget at its own margin against
    /// that requirement at the default margin. 8,000 tokens is the case that
    /// used to load and then send every observation to the omission marker:
    /// it clears the requirement at margin 1.0 but not at the default 0.8.
    #[test]
    fn load_rejects_a_budget_whose_effective_size_is_below_the_floor() {
        // Clears the character requirement at margin 1.0, misses it at 0.8.
        for (tokens, margin) in [(8_000, 0.8), (8_000, 0.6), (8_000, 0.5), (9_000, 0.7)] {
            let tmp = TempDir::new().unwrap();
            let config_path = tmp.path().join("config.toml");
            std::fs::write(
                &config_path,
                format!(
                    "[consolidation]
max_input_tokens = {tokens}
                     input_token_safety_margin = {margin}
"
                ),
            )
            .unwrap();
            let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
                .expect_err("a budget too small at its own margin must fail closed");
            assert!(
                error.to_string().contains("consolidation.max_input_tokens"),
                "unexpected error for {tokens} tokens at margin {margin}: {error:#}"
            );
        }
    }

    /// Controls for the test above, so a blanket rejection cannot pass for a
    /// working guard: the same token counts are accepted once the margin is
    /// high enough to clear the requirement, and 8,000 at margin 1.0 -- which
    /// the reject test deliberately excludes -- must still load.
    #[test]
    fn load_accepts_a_budget_whose_effective_size_clears_the_floor() {
        for (tokens, margin) in [(8_000, 1.0), (10_000, 0.8), (10_000, 0.7)] {
            let tmp = TempDir::new().unwrap();
            let config_path = tmp.path().join("config.toml");
            std::fs::write(
                &config_path,
                format!(
                    "[consolidation]
max_input_tokens = {tokens}
                     input_token_safety_margin = {margin}
"
                ),
            )
            .unwrap();
            let cfg = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
                .expect("a budget that clears the requirement must load");
            assert_eq!(cfg.consolidation.max_input_tokens, tokens);
        }
    }

    #[test]
    fn load_rejects_a_consolidation_output_limit_too_small_for_json() {
        let min = ai_memory_consolidate::MIN_CONSOLIDATION_MAX_OUTPUT_TOKENS;
        for value in [0, 1, min - 1] {
            let tmp = TempDir::new().unwrap();
            let config_path = tmp.path().join("config.toml");
            std::fs::write(
                &config_path,
                format!("[consolidation]\nmax_output_tokens = {value}\n"),
            )
            .unwrap();
            let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
                .expect_err("an unusable consolidation output limit must fail closed");
            assert!(
                error
                    .to_string()
                    .contains("consolidation.max_output_tokens"),
                "unexpected error for {value}: {error:#}"
            );
        }
    }

    /// #884: the input-token safety margin must stay in `(0.0, 1.0]` — a
    /// non-positive value starves every prompt and a value above 1.0 loosens
    /// the budget past the limit it exists to tighten.
    #[test]
    fn load_rejects_an_out_of_range_input_token_safety_margin() {
        for value in ["0.0", "-0.1", "1.5", "nan"] {
            let tmp = TempDir::new().unwrap();
            let config_path = tmp.path().join("config.toml");
            std::fs::write(
                &config_path,
                format!("[consolidation]\ninput_token_safety_margin = {value}\n"),
            )
            .unwrap();
            let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
                .expect_err("an out-of-range safety margin must fail closed");
            assert!(
                error
                    .to_string()
                    .contains("consolidation.input_token_safety_margin"),
                "unexpected error for {value}: {error:#}"
            );
        }
    }

    /// A valid margin survives the config round-trip and the default is 0.8.
    #[test]
    fn load_accepts_a_valid_input_token_safety_margin() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(
            &config_path,
            "[consolidation]\ninput_token_safety_margin = 0.6\n",
        )
        .unwrap();
        let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
            .expect("a margin inside (0.0, 1.0] must load");
        assert_eq!(config.consolidation.input_token_safety_margin, 0.6);
        assert_eq!(
            ConsolidationSettings::default().input_token_safety_margin,
            0.8
        );
    }

    #[test]
    fn verbatim_residue_is_opt_in_and_loads_from_consolidation_settings() {
        assert!(!ConsolidationSettings::default().verbatim_residue);
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, "[consolidation]\nverbatim_residue = true\n").unwrap();
        let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
        assert!(config.consolidation.verbatim_residue);
    }

    /// The small-context examples in `docs/install.md` and
    /// `docs/llm-providers.md` must be configs that actually load. These are
    /// the literal values those docs quote, copied by hand: keep them in step
    /// when the docs change, so an example does not go stale the way
    /// `max_input_tokens = 6500` did once the floor moved (#1234).
    #[test]
    fn documented_small_context_examples_load() {
        for (doc, tokens, output, margin) in [
            ("docs/install.md", 10_000, 1_000, 0.8),
            ("docs/install.md (8k window)", 6_700, 1_000, 1.0),
            ("docs/llm-providers.md", 10_000, 1_000, 0.8),
        ] {
            let tmp = TempDir::new().unwrap();
            let config_path = tmp.path().join("config.toml");
            std::fs::write(
                &config_path,
                format!(
                    "[consolidation]
max_input_tokens = {tokens}
max_output_tokens = {output}
input_token_safety_margin = {margin}
"
                ),
            )
            .unwrap();
            Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
                .unwrap_or_else(|error| panic!("{doc}'s example no longer loads: {error:#}"));
        }
    }

    /// A small-context provider needs both sides of the context allocation to
    /// survive the config round-trip. The budget is derived from the floor
    /// rather than written out, so the test keeps meaning "the smallest
    /// accepted budget round-trips" when the floor moves (#1234) instead of
    /// pinning a number the floor happens to allow today.
    /// `[ingest]` is read once into the validated drop list the hook router
    /// checks, and an out-of-bounds entry fails startup instead of being
    /// silently ignored (#1241).
    /// `[ingest] record_tool_names` is off unless the file turns it on.
    #[test]
    fn ingest_record_tool_names_defaults_off_and_loads_from_file() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, "").unwrap();
        let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
        assert!(!config.ingest.record_tool_names);

        std::fs::write(&config_path, "[ingest]\nrecord_tool_names = true\n").unwrap();
        let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
        assert!(config.ingest.record_tool_names);
    }

    /// The env form of `[ingest] record_tool_names`. Same child-process marker
    /// pattern as `ingest_drop_events_env_overrides_default`.
    #[test]
    fn ingest_record_tool_names_env_turns_it_on() {
        const CHILD_MARKER: &str = "AI_MEMORY_TEST_RECORD_TOOL_NAMES_CHILD";
        if std::env::var_os(CHILD_MARKER).is_some() {
            let tmp = TempDir::new().unwrap();
            let config_path = tmp.path().join("config.toml");
            std::fs::write(&config_path, "[ingest]\n").unwrap();
            let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
            assert!(config.ingest.record_tool_names);
            println!("record-tool-names-env-applied");
            return;
        }

        let output = std::process::Command::new(std::env::current_exe().unwrap())
            .arg("--exact")
            .arg("config::tests::ingest_record_tool_names_env_turns_it_on")
            .arg("--test-threads=1")
            .arg("--nocapture")
            .env(CHILD_MARKER, "1")
            .env("AI_MEMORY_INGEST__RECORD_TOOL_NAMES", "true")
            .output()
            .unwrap();
        assert!(
            output.status.success(),
            "child test failed:\nstdout: {}\nstderr: {}",
            String::from_utf8_lossy(&output.stdout),
            String::from_utf8_lossy(&output.stderr)
        );
        assert!(
            String::from_utf8_lossy(&output.stdout).contains("record-tool-names-env-applied"),
            "child stdout: {}",
            String::from_utf8_lossy(&output.stdout)
        );
    }

    #[test]
    fn ingest_drop_lists_load_into_the_router_list_and_reject_bad_entries() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(
            &config_path,
            "[ingest]\ndrop_tool_use_id_prefixes = [\"toolu_plugin_\"]\ndrop_tool_names = [\"mcp__noisy__poll\"]\n",
        )
        .unwrap();
        let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
        assert_eq!(
            config.ingest.drop_list.as_ref(),
            &ai_memory_hooks::IngestDropList::new(
                vec!["toolu_plugin_".into()],
                vec!["mcp__noisy__poll".into()],
                &[]
            )
            .unwrap()
        );

        std::fs::write(&config_path, "[ingest]\ndrop_tool_names = [\" \"]\n").unwrap();
        let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap_err();
        assert!(
            format!("{error:#}").contains("drop_tool_names"),
            "{error:#}"
        );

        // Default: empty, so nothing is dropped.
        assert_eq!(
            Config::default().ingest.drop_list.as_ref(),
            &ai_memory_hooks::IngestDropList::default()
        );
    }

    /// `[ingest] drop_events` names whole hook event kinds to drop (#1241
    /// sibling). It loads into the same validated list the hook router checks,
    /// defaults to empty (nothing dropped), and rejects a session-state kind
    /// and an unknown kind at load.
    #[test]
    fn ingest_drop_events_load_into_the_router_list_and_reject_bad_kinds() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, "[ingest]\ndrop_events = [\"pre-tool-use\"]\n").unwrap();
        let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
        // The raw value survives, and the validated list is built from it.
        assert_eq!(config.ingest.drop_events, vec!["pre-tool-use".to_string()]);
        assert_eq!(
            config.ingest.drop_list.as_ref(),
            &ai_memory_hooks::IngestDropList::new(Vec::new(), Vec::new(), &["pre-tool-use".into()])
                .unwrap()
        );

        // A session-state kind fails startup with a clear error (session start…)
        std::fs::write(
            &config_path,
            "[ingest]\ndrop_events = [\"session-start\"]\n",
        )
        .unwrap();
        let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap_err();
        assert!(
            format!("{error:#}").contains("session-start")
                && format!("{error:#}").contains("session state"),
            "{error:#}"
        );

        // …and session end.
        std::fs::write(&config_path, "[ingest]\ndrop_events = [\"session-end\"]\n").unwrap();
        let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap_err();
        assert!(
            format!("{error:#}").contains("session-end")
                && format!("{error:#}").contains("session state"),
            "{error:#}"
        );

        // An unknown kind fails startup naming the value.
        std::fs::write(&config_path, "[ingest]\ndrop_events = [\"pre-tool-us\"]\n").unwrap();
        let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap_err();
        assert!(
            format!("{error:#}").contains("pre-tool-us")
                && format!("{error:#}").contains("not a known hook event kind"),
            "{error:#}"
        );

        // Default: empty, so nothing is dropped.
        assert_eq!(Config::default().ingest.drop_events, Vec::<String>::new());
        assert_eq!(
            Config::default().ingest.drop_list.as_ref(),
            &ai_memory_hooks::IngestDropList::default()
        );
    }

    /// The env form of `[ingest] drop_events` (`AI_MEMORY_INGEST__DROP_EVENTS`,
    /// a comma-separated string) loads into the same validated list. Uses the
    /// child-process marker pattern because `std::env::set_var` is unsafe and
    /// forbidden in this crate's multi-threaded test binary.
    #[test]
    fn ingest_drop_events_env_overrides_default() {
        const CHILD_MARKER: &str = "AI_MEMORY_TEST_DROP_EVENTS_CHILD";
        if std::env::var_os(CHILD_MARKER).is_some() {
            let tmp = TempDir::new().unwrap();
            let config_path = tmp.path().join("config.toml");
            // No drop_events in the file; the env var supplies it.
            std::fs::write(&config_path, "[ingest]\n").unwrap();
            let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
            assert_eq!(
                config.ingest.drop_events,
                vec!["pre-tool-use".to_string(), "stop".to_string()]
            );
            println!("drop-events-env-applied");
            return;
        }

        let output = std::process::Command::new(std::env::current_exe().unwrap())
            .arg("--exact")
            .arg("config::tests::ingest_drop_events_env_overrides_default")
            .arg("--test-threads=1")
            .arg("--nocapture")
            .env(CHILD_MARKER, "1")
            .env("AI_MEMORY_INGEST__DROP_EVENTS", "pre-tool-use,stop")
            .output()
            .unwrap();
        assert!(
            output.status.success(),
            "child test failed:\nstdout: {}\nstderr: {}",
            String::from_utf8_lossy(&output.stdout),
            String::from_utf8_lossy(&output.stderr)
        );
        assert!(
            String::from_utf8_lossy(&output.stdout).contains("drop-events-env-applied"),
            "child stdout: {}",
            String::from_utf8_lossy(&output.stdout)
        );
    }

    #[test]
    fn load_accepts_a_small_context_consolidation_budget() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        let small = ai_memory_consolidate::MIN_CONSOLIDATION_MAX_INPUT_TOKENS;
        let output = ai_memory_consolidate::MIN_CONSOLIDATION_MAX_OUTPUT_TOKENS;
        std::fs::write(
            &config_path,
            format!("[consolidation]\nmax_input_tokens = {small}\nmax_output_tokens = {output}\n"),
        )
        .unwrap();
        let cfg = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
        assert_eq!(cfg.consolidation.max_input_tokens, small);
        assert_eq!(cfg.consolidation.max_output_tokens, output);
    }

    /// `AI_MEMORY_LLM_TIMEOUT_SECS` (figment maps it to this field) exists so
    /// slow hosted gateways can outlive the 300s default; the accepted floor
    /// mirrors that motivation — anything below one second severs every
    /// provider request before it is sent.
    #[test]
    fn load_round_trips_a_custom_llm_request_timeout() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, "llm_timeout_secs = 900\n").unwrap();
        let cfg = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
        assert_eq!(cfg.llm_timeout_secs, 900);
    }

    #[test]
    fn load_rejects_a_zero_llm_request_timeout() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, "llm_timeout_secs = 0\n").unwrap();
        let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
            .expect_err("a sub-second timeout must fail closed");
        assert!(
            error.to_string().contains("llm_timeout_secs"),
            "unexpected error: {error:#}"
        );
    }

    /// `AI_MEMORY_RERANK_TIMEOUT_SECS` (figment maps it to this field) lets a
    /// slow free-tier fallback chain finish a rerank; unset keeps the 20s
    /// budget the reranker always had.
    #[test]
    fn load_defaults_and_round_trips_the_rerank_timeout() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, "").unwrap();
        let cfg = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
        assert_eq!(
            cfg.rerank_timeout_secs,
            ai_memory_llm::reranker::RERANK_TIMEOUT.as_secs()
        );
        std::fs::write(&config_path, "rerank_timeout_secs = 60\n").unwrap();
        let cfg = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
        assert_eq!(cfg.rerank_timeout_secs, 60);
    }

    #[test]
    fn load_rejects_a_zero_rerank_timeout() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, "rerank_timeout_secs = 0\n").unwrap();
        let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
            .expect_err("a zero rerank budget must fail closed");
        assert!(
            error.to_string().contains("rerank_timeout_secs"),
            "unexpected error: {error:#}"
        );
    }

    #[test]
    fn load_round_trips_llm_headers() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(
            &config_path,
            "llm_headers = [\"x-opencode-session=ses-1\", \"x-tool: ai-memory\"]\n",
        )
        .unwrap();
        let cfg = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
        assert_eq!(
            cfg.llm_headers,
            vec!["x-opencode-session=ses-1", "x-tool: ai-memory"]
        );
    }

    #[test]
    fn llm_headers_default_to_none_configured() {
        assert!(Config::default().llm_headers.is_empty());
    }

    /// Parsed during `load` so a typo surfaces at startup rather than on the
    /// first consolidation pass, hours later.
    #[test]
    fn load_rejects_a_malformed_llm_header() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, "llm_headers = [\"no-separator-here\"]\n").unwrap();
        let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
            .expect_err("a malformed header entry must fail closed");
        assert!(
            error.to_string().contains("AI_MEMORY_LLM_HEADERS"),
            "unexpected error: {error:#}"
        );
    }

    /// A duplicate `authorization` would break provider auth rather than
    /// override it, so the boundary refuses it outright.
    #[test]
    fn load_rejects_an_llm_header_ai_memory_owns() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(
            &config_path,
            "llm_headers = [\"authorization: Bearer x\"]\n",
        )
        .unwrap();
        let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
            .expect_err("a reserved header must fail closed");
        assert!(
            format!("{error:#}").contains("set by ai-memory itself"),
            "unexpected error: {error:#}"
        );
    }

    fn load_reasoning_effort(raw: &str) -> anyhow::Result<Config> {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, format!("llm_reasoning_effort = \"{raw}\"\n")).unwrap();
        Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
    }

    #[rstest]
    #[case::none("none", ReasoningEffort::None)]
    #[case::low("low", ReasoningEffort::Low)]
    #[case::high("high", ReasoningEffort::High)]
    fn load_accepts_reasoning_effort(#[case] raw: &str, #[case] expected: ReasoningEffort) {
        let cfg = load_reasoning_effort(raw).unwrap();
        assert_eq!(cfg.llm_reasoning_effort, Some(expected));
    }

    #[rstest]
    #[case::unknown("ludicrous")]
    #[case::uppercase("HIGH")]
    fn load_rejects_invalid_reasoning_effort(#[case] raw: &str) {
        let error =
            load_reasoning_effort(raw).expect_err("invalid reasoning effort must fail closed");
        let rendered = format!("{error:#}");
        assert!(
            rendered.contains("llm_reasoning_effort") && rendered.contains("unknown variant"),
            "unexpected error: {rendered}"
        );
    }

    #[test]
    fn defaults_bound_consolidation_prompts_for_a_large_context_provider() {
        let tmp = TempDir::new().unwrap();
        let cfg = Config::load(None, Some(tmp.path().to_path_buf())).unwrap();
        assert_eq!(
            cfg.consolidation.max_input_tokens,
            ai_memory_consolidate::DEFAULT_CONSOLIDATION_MAX_INPUT_TOKENS
        );
        assert_eq!(
            cfg.consolidation.max_output_tokens,
            ai_memory_consolidate::DEFAULT_CONSOLIDATION_MAX_OUTPUT_TOKENS
        );
    }

    #[test]
    fn load_populates_home_dir_from_env() {
        let tmp = TempDir::new().unwrap();
        let cli_dir = tmp.path().join("override");
        let cfg = Config::load(None, Some(cli_dir)).unwrap();
        // `home_dir` is derived from AI_MEMORY_HOME, `$HOME`, or Windows
        // `%USERPROFILE%` at load (the single config-read path), normalized so
        // a trailing slash can't bypass the catch-all guards. Reading the env
        // in a test is allowed; this fails if the load-time assignment is
        // dropped while any of those vars is set.
        assert_eq!(
            cfg.home_dir,
            std::env::var("AI_MEMORY_HOME")
                .or_else(|_| std::env::var("HOME"))
                .or_else(|_| std::env::var("USERPROFILE"))
                .ok()
                .and_then(|h| normalize_home_dir(&h))
                .or_else(|| dirs::home_dir()
                    .as_ref()
                    .and_then(|p| p.to_str())
                    .and_then(normalize_home_dir))
        );
    }

    /// Native Windows often has `%USERPROFILE%` and no `$HOME`. The #103
    /// catch-all guard is inert when `home_dir` stays `None`, so a project
    /// whose `repo_path` is the user profile would prefix-match every cwd
    /// beneath it.
    #[test]
    fn operator_home_falls_back_to_userprofile_when_home_is_unset() {
        assert_eq!(
            resolve_operator_home(None, None, Some(r"C:\Users\tester"), None).as_deref(),
            Some(r"C:\Users\tester")
        );
        assert_eq!(
            resolve_operator_home(
                Some("/tmp/override"),
                Some("/home/u"),
                Some(r"C:\Users\tester"),
                None
            )
            .as_deref(),
            Some("/tmp/override")
        );
        assert_eq!(
            resolve_operator_home(None, Some("/home/u"), Some(r"C:\Users\tester"), None).as_deref(),
            Some("/home/u")
        );
        assert_eq!(
            resolve_operator_home(None, Some(""), Some(r"C:\Users\tester"), None).as_deref(),
            Some(r"C:\Users\tester")
        );
        let platform = PathBuf::from(r"C:\Users\from-dirs");
        assert_eq!(
            resolve_operator_home(None, None, None, Some(platform.as_path())).as_deref(),
            Some(r"C:\Users\from-dirs")
        );
    }

    #[test]
    fn normalize_home_dir_trims_trailing_separators() {
        assert_eq!(normalize_home_dir("/home/u/"), Some("/home/u".to_string()));
        assert_eq!(normalize_home_dir("/home/u"), Some("/home/u".to_string()));
        assert_eq!(
            normalize_home_dir("/home/u///"),
            Some("/home/u".to_string())
        );
        assert_eq!(
            normalize_home_dir(r"C:\Users\tester\"),
            Some("C:/Users/tester".to_string())
        );
        // Degenerate inputs yield no usable home rather than an empty or
        // root-collapsing prefix key.
        assert_eq!(normalize_home_dir("/"), None);
        assert_eq!(normalize_home_dir(""), None);
    }

    #[test]
    fn reranker_choice_is_explicit_case_insensitive_and_fail_closed() {
        for value in [None, Some(""), Some("  ")] {
            let cfg = Config {
                reranker: value.map(str::to_string),
                ..Config::default()
            };
            assert!(!cfg.reranker_choice().unwrap());
        }
        for value in ["llm", "LLM", " LlM "] {
            let cfg = Config {
                reranker: Some(value.into()),
                ..Config::default()
            };
            assert!(cfg.reranker_choice().unwrap());
        }
        let cfg = Config {
            reranker: Some("cross-encoder".into()),
            ..Config::default()
        };
        let err = cfg.reranker_choice().unwrap_err();
        assert!(err.to_string().contains("AI_MEMORY_RERANKER=cross-encoder"));
    }

    #[test]
    fn config_file_overrides_defaults() {
        let tmp = TempDir::new().unwrap();
        let cfg_path = tmp.path().join("config.toml");
        std::fs::write(
            &cfg_path,
            r#"
            bind = "0.0.0.0:9999"
            log_level = "debug"
            hook_rate_per_sec = 7.5
            hook_rate_burst = 12.0
            contradiction_band_min = 0.5
            contradiction_band_max = 0.8

            [auth]
            secure_cookie = true

            [handoff]
            claim_on_session_start = false
            create_on_session_end = false

            [maintenance]
            enabled = false
            lint_interval_secs = 3600

            [auto_improve]
            mode = "dry_run"
            require_approval = true
            on_session_end = true
            min_observations = 3
            min_session_duration_secs = 45
            min_confidence = 0.9
            max_input_tokens = 12000
            max_proposals_per_run = 2
            max_patchable_pages = 3
            max_patchable_body_chars = 4096
            max_edits_per_proposal = 4
            max_edit_content_chars = 1024
            max_changed_chars_per_proposal = 2048
            max_patch_edits_per_run = 6
            max_rejection_context = 7
            rejection_context_days = 14
            max_final_body_chars = 8192
            max_rule_page_tokens = 1000
            max_procedure_page_tokens = 1500
            include_raw_fallback = true
            proposal_actor = "review_bot"
            pending_path = "_pending/review-bot"

            [auto_improve.scheduler]
            enabled = true
            interval_secs = 1800
            max_sessions_per_tick = 4
            min_session_age_secs = 30

            [auto_improve.eval]
            enabled = true
            command = "/usr/local/bin/auto-improve-eval --json"
            timeout_secs = 9
            targets = ["_rules"]
            min_delta = 0.05
            "#,
        )
        .unwrap();
        // Use the tmp dir as the data dir so the resolved config path
        // matches what `load` derives. Passing it explicitly keeps the test
        // free of any global env.
        let cfg = Config::load(Some(&cfg_path), Some(tmp.path().to_path_buf())).unwrap();
        assert_eq!(cfg.bind, "0.0.0.0:9999");
        assert_eq!(cfg.log_level, "debug");
        assert_eq!(cfg.hook_rate_per_sec, 7.5);
        assert_eq!(cfg.hook_rate_burst, 12.0);
        assert_eq!(cfg.contradiction_band_min, 0.5);
        assert_eq!(cfg.contradiction_band_max, 0.8);
        assert!(cfg.auth.secure_cookie);
        assert!(!cfg.handoff.claim_on_session_start);
        assert!(!cfg.handoff.create_on_session_end);
        assert!(!cfg.maintenance.enabled);
        assert_eq!(cfg.maintenance.lint_interval_secs, 3600);
        assert!(cfg.auto_improve.scheduler.enabled);
        assert_eq!(cfg.auto_improve.scheduler.interval_secs, 1_800);
        assert_eq!(cfg.auto_improve.scheduler.max_sessions_per_tick, 4);
        assert_eq!(cfg.auto_improve.scheduler.min_session_age_secs, 30);
        assert!(cfg.auto_improve.on_session_end);
        assert!(cfg.auto_improve.require_approval);
        assert_eq!(cfg.auto_improve.min_observations, 3);
        assert_eq!(cfg.auto_improve.min_session_duration_secs, 45);
        assert_eq!(cfg.auto_improve.min_confidence, 0.9);
        assert_eq!(cfg.auto_improve.max_input_tokens, 12_000);
        assert_eq!(cfg.auto_improve.max_proposals_per_run, 2);
        assert_eq!(cfg.auto_improve.max_patchable_pages, 3);
        assert_eq!(cfg.auto_improve.max_patchable_body_chars, 4_096);
        assert_eq!(cfg.auto_improve.max_edits_per_proposal, 4);
        assert_eq!(cfg.auto_improve.max_edit_content_chars, 1_024);
        assert_eq!(cfg.auto_improve.max_changed_chars_per_proposal, 2_048);
        assert_eq!(cfg.auto_improve.max_patch_edits_per_run, 6);
        assert_eq!(cfg.auto_improve.max_rejection_context, 7);
        assert_eq!(cfg.auto_improve.rejection_context_days, 14);
        assert_eq!(cfg.auto_improve.max_final_body_chars, 8_192);
        assert_eq!(cfg.auto_improve.max_rule_page_tokens, 1_000);
        assert_eq!(cfg.auto_improve.max_procedure_page_tokens, 1_500);
        assert!(cfg.auto_improve.eval.enabled);
        assert_eq!(
            cfg.auto_improve.eval.command,
            "/usr/local/bin/auto-improve-eval --json"
        );
        assert_eq!(cfg.auto_improve.eval.timeout_secs, 9);
        assert_eq!(cfg.auto_improve.eval.targets, vec!["_rules"]);
        assert_eq!(cfg.auto_improve.eval.min_delta, 0.05);
        assert!(cfg.auto_improve.include_raw_fallback);
        assert_eq!(cfg.auto_improve.proposal_actor, "review_bot");
        assert_eq!(cfg.auto_improve.pending_path, "_pending/review-bot");
    }

    /// One scorer per gate: setting both is a startup error, not a config
    /// where the builtin silently loses (#1638).
    #[test]
    fn an_eval_gate_rejects_both_a_builtin_and_a_command() {
        let tmp = tempfile::TempDir::new().unwrap();
        let write = |toml: &str| {
            let path = tmp.path().join("config.toml");
            std::fs::write(&path, toml).unwrap();
            Config::load(Some(&path), Some(tmp.path().to_path_buf()))
        };
        let both = write(
            "[auto_improve.eval]\nenabled = true\nbuiltin = \"structure\"\n\
             command = \"sh score.sh\"\n",
        )
        .unwrap_err()
        .to_string();
        assert!(
            both.contains("mutually exclusive"),
            "unexpected error: {both}"
        );

        let unknown = write("[auto_improve.eval]\nenabled = true\nbuiltin = \"vibes\"\n")
            .unwrap_err()
            .to_string();
        assert!(
            unknown.contains("not a known scorer"),
            "unexpected error: {unknown}"
        );

        let builtin =
            write("[auto_improve.eval]\nenabled = true\nbuiltin = \"structure\"\n").unwrap();
        assert_eq!(builtin.auto_improve.eval.builtin, "structure");
        assert!(builtin.auto_improve.eval.command.is_empty());

        let command =
            write("[auto_improve.eval]\nenabled = true\ncommand = \"sh score.sh\"\n").unwrap();
        assert!(command.auto_improve.eval.builtin.is_empty());
    }

    #[test]
    fn profile_defaults_are_auto_and_parse_from_file_and_env() {
        use ai_memory_core::profile::{EffectiveProfileShare, ProfileEnabled, ProfileShare};
        let defaults = Config::default().profile;
        assert_eq!(defaults.enabled, ProfileEnabled::Auto);
        assert_eq!(defaults.share, ProfileShare::Auto);
        assert!(defaults.inject_on_session_start);
        assert_eq!(
            defaults.effective_share(false),
            Some(EffectiveProfileShare::Global)
        );
        assert_eq!(defaults.effective_share(true), None);

        let tmp = TempDir::new().unwrap();
        let cfg_path = tmp.path().join("config.toml");
        std::fs::write(
            &cfg_path,
            "[profile]\nenabled = true\nshare = \"workspace\"\nmin_projects = 3\n\
             inject_on_session_start = false\ndigest_max_bytes = 4000\n\
             baseline_max_bytes = 8000\napply_max_lines = 20\nllm = false\n",
        )
        .unwrap();
        let cfg = Config::load(Some(&cfg_path), Some(tmp.path().to_path_buf())).unwrap();
        assert_eq!(cfg.profile.enabled, ProfileEnabled::On);
        assert_eq!(cfg.profile.share, ProfileShare::Workspace);
        assert_eq!(cfg.profile.min_projects, 3);
        assert!(!cfg.profile.inject_on_session_start);
        assert_eq!(cfg.profile.digest_max_bytes, 4_000);
        assert_eq!(cfg.profile.baseline_max_bytes, 8_000);
        assert_eq!(cfg.profile.apply_max_lines, 20);
        assert!(!cfg.profile.llm);
        assert_eq!(
            cfg.profile.effective_share(true),
            Some(EffectiveProfileShare::Workspace)
        );

        std::fs::write(
            &cfg_path,
            "[profile]\nenabled = \"auto\"\nshare = \"off\"\n",
        )
        .unwrap();
        let cfg = Config::load(Some(&cfg_path), Some(tmp.path().to_path_buf())).unwrap();
        assert_eq!(cfg.profile.effective_share(false), None);
    }

    #[test]
    fn handoff_claim_on_session_start_defaults_to_true() {
        assert!(Config::default().handoff.claim_on_session_start);
    }

    #[test]
    fn handoff_create_on_session_end_defaults_to_true() {
        assert!(Config::default().handoff.create_on_session_end);
    }

    #[test]
    fn gemini_embedding_provider_uses_google_defaults() {
        let mut cfg = Config {
            embedding_provider: Some("gemini".into()),
            runtime_env: RuntimeEnv {
                gemini_api_key: Some(SecretString::from("test-key")),
                ..RuntimeEnv::default()
            },
            ..Config::default()
        };

        let embedder = cfg.embedder_config().unwrap().unwrap();
        assert_eq!(embedder.provider, EmbedderChoice::Google);
        assert_eq!(embedder.model, ai_memory_llm::GOOGLE_DEFAULT_EMBED_MODEL);
        assert_eq!(embedder.dim, 768);

        cfg.embedding_provider = Some("google".into());
        assert_eq!(
            cfg.embedder_config().unwrap().unwrap().provider,
            EmbedderChoice::Google
        );
    }

    #[test]
    fn openai_embedding_falls_back_to_llm_api_key_for_openrouter() {
        let cfg = Config {
            embedding_provider: Some("openai".into()),
            embedding_model: Some("text-embedding-3-small".into()),
            embedding_base_url: Some("https://openrouter.ai/api/v1".into()),
            runtime_env: RuntimeEnv {
                llm_api_key: Some(SecretString::from("sk-or-test-key")),
                ..RuntimeEnv::default()
            },
            ..Config::default()
        };

        let embedder = cfg.embedder_config().unwrap().unwrap();
        assert_eq!(embedder.provider, EmbedderChoice::OpenAi);
        assert_eq!(embedder.model, "text-embedding-3-small");
        assert_eq!(embedder.api_key.expose_secret(), "sk-or-test-key");
        assert_eq!(
            embedder.base_url.as_deref(),
            Some("https://openrouter.ai/api/v1")
        );

        // A dedicated embedding key outranks the borrowed LLM one.
        let cfg = Config {
            runtime_env: RuntimeEnv {
                embedding_api_key: Some(SecretString::from("sk-embed-key")),
                ..cfg.runtime_env.clone()
            },
            ..cfg
        };
        let embedder = cfg.embedder_config().unwrap().unwrap();
        assert_eq!(embedder.api_key.expose_secret(), "sk-embed-key");
    }

    #[test]
    fn openai_embedding_prefers_dedicated_embedding_api_key() {
        // The LLM runs on api.openai.com (OPENAI_API_KEY) while embeddings
        // run somewhere else; without a dedicated key the OpenAI one would
        // be sent to the embedding base URL and rejected.
        let cfg = Config {
            embedding_provider: Some("openai".into()),
            embedding_base_url: Some("https://api.cheap-embeddings.example/v1".into()),
            runtime_env: RuntimeEnv {
                embedding_api_key: Some(SecretString::from("sk-embed-key")),
                openai_api_key: Some(SecretString::from("sk-openai-key")),
                llm_api_key: Some(SecretString::from("sk-llm-key")),
                ..RuntimeEnv::default()
            },
            ..Config::default()
        };

        let embedder = cfg.embedder_config().unwrap().unwrap();
        assert_eq!(embedder.api_key.expose_secret(), "sk-embed-key");

        // It also works without a custom base URL, i.e. against OpenAI
        // itself, where OPENAI_API_KEY was previously the only accepted key.
        let direct = Config {
            embedding_base_url: None,
            ..cfg.clone()
        };
        assert_eq!(
            direct
                .embedder_config()
                .unwrap()
                .unwrap()
                .api_key
                .expose_secret(),
            "sk-embed-key"
        );

        // Absent, the previous precedence is untouched: OPENAI_API_KEY
        // still beats LLM_API_KEY.
        let without = Config {
            runtime_env: RuntimeEnv {
                embedding_api_key: None,
                ..cfg.runtime_env.clone()
            },
            ..cfg
        };
        assert_eq!(
            without
                .embedder_config()
                .unwrap()
                .unwrap()
                .api_key
                .expose_secret(),
            "sk-openai-key"
        );
    }

    #[test]
    fn openai_compat_embedding_is_keyless_and_requires_explicit_settings() {
        // Fully specified, no key: valid (Ollama / LM Studio).
        let cfg = Config {
            embedding_provider: Some("openai-compat".into()),
            embedding_model: Some("nomic-embed-text".into()),
            embedding_dim: Some(768),
            embedding_base_url: Some("http://localhost:11434/v1".into()),
            ..Config::default()
        };
        let embedder = cfg.embedder_config().unwrap().unwrap();
        assert_eq!(embedder.provider, EmbedderChoice::OpenAiCompat);
        assert_eq!(embedder.model, "nomic-embed-text");
        assert_eq!(embedder.dim, 768);
        assert!(embedder.api_key.expose_secret().is_empty());
        assert_eq!(
            embedder.base_url.as_deref(),
            Some("http://localhost:11434/v1")
        );

        // A gateway key rides on LLM_API_KEY when present.
        let cfg_with_key = Config {
            runtime_env: RuntimeEnv {
                llm_api_key: Some(SecretString::from("sk-or-key")),
                ..RuntimeEnv::default()
            },
            ..cfg.clone()
        };
        let embedder = cfg_with_key.embedder_config().unwrap().unwrap();
        assert_eq!(embedder.api_key.expose_secret(), "sk-or-key");

        // EMBEDDING_API_KEY takes precedence over that borrowed key, and
        // still leaves the keyless path keyless when it is unset.
        let cfg_with_embedding_key = Config {
            runtime_env: RuntimeEnv {
                embedding_api_key: Some(SecretString::from("sk-embed-key")),
                ..cfg_with_key.runtime_env.clone()
            },
            ..cfg_with_key
        };
        let embedder = cfg_with_embedding_key.embedder_config().unwrap().unwrap();
        assert_eq!(embedder.api_key.expose_secret(), "sk-embed-key");

        // Missing model / dim / base URL each fail closed.
        let missing_model = Config {
            embedding_model: None,
            ..cfg.clone()
        };
        assert!(matches!(
            missing_model.embedder_config().unwrap_err(),
            LlmError::NotConfigured(msg) if msg.contains("AI_MEMORY_EMBEDDING_MODEL")
        ));
        let missing_dim = Config {
            embedding_dim: None,
            ..cfg.clone()
        };
        assert!(matches!(
            missing_dim.embedder_config().unwrap_err(),
            LlmError::NotConfigured(msg) if msg.contains("AI_MEMORY_EMBEDDING_DIM")
        ));
        let zero_dim = Config {
            embedding_dim: Some(0),
            ..cfg.clone()
        };
        assert!(matches!(
            zero_dim.embedder_config().unwrap_err(),
            LlmError::NotConfigured(msg) if msg.contains("greater than zero")
        ));
        let missing_base = Config {
            embedding_base_url: None,
            ..cfg
        };
        assert!(matches!(
            missing_base.embedder_config().unwrap_err(),
            LlmError::NotConfigured(msg) if msg.contains("AI_MEMORY_EMBEDDING_BASE_URL")
        ));
    }

    #[test]
    fn embedding_prefixes_default_empty_and_are_not_trimmed_when_set() {
        // Unset: EmbedderConfig carries empty strings, so downstream
        // embedders see byte-identical behaviour to before this feature.
        let unset = Config {
            embedding_provider: Some("openai-compat".into()),
            embedding_model: Some("nvidia/Nemotron-3-Embed-1B-BF16".into()),
            embedding_dim: Some(2048),
            embedding_base_url: Some("http://localhost:8000/v1".into()),
            ..Config::default()
        };
        let embedder = unset.embedder_config().unwrap().unwrap();
        assert_eq!(embedder.query_prefix, "");
        assert_eq!(embedder.document_prefix, "");

        // Set: the publisher's exact strings pass through, including the
        // significant trailing space — `non_empty`'s trim would corrupt it.
        let set = Config {
            embedding_query_prefix: Some("query: ".into()),
            embedding_document_prefix: Some("passage: ".into()),
            ..unset
        };
        let embedder = set.embedder_config().unwrap().unwrap();
        assert_eq!(embedder.query_prefix, "query: ");
        assert_eq!(embedder.document_prefix, "passage: ");
    }

    /// Pure unit tests for `overlay_embedding_prefixes`: no process env or
    /// cwd mutation anywhere here (the workspace forbids `std::env::set_var`
    /// as `unsafe` under edition 2024, and `figment::Jail` calls
    /// `std::env::set_current_dir` on the real process internally, racing
    /// every other test in this multi-threaded lib test binary that
    /// relies on cwd, such as `tests/suite/backfill_e2e.rs`'s
    /// `Command::current_dir` calls). Each test builds its own minimal
    /// `Figment` in memory instead, exactly mirroring what `Config::load`
    /// does (`Serialized::defaults` as the base, optionally a lower-priority
    /// `Serialized` merge standing in for a `config.toml` value), and
    /// extracts a `Config` to assert on — the identical merge machinery the
    /// real loader uses, with the "env value" supplied as a parameter
    /// instead of read from the process.
    #[test]
    fn overlay_embedding_prefixes_preserves_trailing_whitespace() {
        // The regression this guards: figment's `Env` provider parses an
        // unquoted value with its loose-value parser, whose bare-value
        // branch calls `.trim()` — so without this overlay a real
        // `AI_MEMORY_EMBEDDING_QUERY_PREFIX="query: "` would arrive as
        // `"query:"`, silently dropping the space the model publisher
        // requires. `Serialized` bypasses that parser entirely.
        let base = Figment::from(Serialized::defaults(Config::default()));
        let overlaid = overlay_embedding_prefixes(base, Some("query: "), Some("passage: "));
        let cfg: Config = overlaid.extract().unwrap();
        assert_eq!(cfg.embedding_query_prefix.as_deref(), Some("query: "));
        assert_eq!(cfg.embedding_document_prefix.as_deref(), Some("passage: "));
    }

    #[test]
    fn overlay_embedding_prefixes_none_leaves_a_lower_layer_untouched() {
        // Simulates a `config.toml` value already merged in at lower
        // priority; passing `None` (the env var genuinely absent) must not
        // disturb it.
        let base = Figment::from(Serialized::defaults(Config::default())).merge(
            Serialized::default("embedding_query_prefix", "toml-query: "),
        );
        let overlaid = overlay_embedding_prefixes(base, None, None);
        let cfg: Config = overlaid.extract().unwrap();
        assert_eq!(cfg.embedding_query_prefix.as_deref(), Some("toml-query: "));
    }

    #[test]
    fn overlay_embedding_prefixes_some_wins_over_a_lower_layer() {
        let base = Figment::from(Serialized::defaults(Config::default())).merge(
            Serialized::default("embedding_query_prefix", "toml-query: "),
        );
        let overlaid = overlay_embedding_prefixes(base, Some("env-query: "), None);
        let cfg: Config = overlaid.extract().unwrap();
        assert_eq!(cfg.embedding_query_prefix.as_deref(), Some("env-query: "));
    }

    #[test]
    fn overlay_embedding_prefixes_empty_string_clears_a_lower_layer() {
        // Present but empty (`Some("")`) is a deliberate override — an
        // operator clearing a `config.toml` value via env without editing
        // the file — distinct from `None` (the previous test), which must
        // leave the lower layer untouched.
        let base = Figment::from(Serialized::defaults(Config::default())).merge(
            Serialized::default("embedding_query_prefix", "toml-query: "),
        );
        let overlaid = overlay_embedding_prefixes(base, Some(""), None);
        let cfg: Config = overlaid.extract().unwrap();
        assert_eq!(cfg.embedding_query_prefix.as_deref(), Some(""));
    }

    /// Exercises the real `Config::load` end to end, through an absolute
    /// `config.toml` path and data dir from a `TempDir`. TOML strings were
    /// never subject to figment's `Env`-provider trimming in the first
    /// place, so this path already worked before the fix; this guards it
    /// staying correct.
    ///
    /// This process's own environment is shared with every other test in
    /// this binary and could already carry one of the two prefix vars from
    /// the test runner's shell, which would make `Config::load` pick the
    /// env value over the TOML one below and this test would silently stop
    /// verifying the TOML-only path. Rather than assume the ambient
    /// environment is clean, the actual `Config::load` call runs in a
    /// separate child process with both vars explicitly removed via
    /// `Command::env_remove` — real isolation instead of an in-process
    /// assumption, and it does not touch this rule's target (mutating
    /// *this* process's env), since a spawned child's environment is its
    /// own.
    #[test]
    fn loader_toml_path_preserves_whitespace_with_no_env_var_set() {
        const CHILD_MARKER: &str = "AI_MEMORY_TEST_LOADER_TOML_PATH_CHILD";
        if std::env::var_os(CHILD_MARKER).is_some() {
            // Running as the child, with both prefix vars removed by the
            // parent below: do the real work and print the result for the
            // parent to assert on.
            let tmp = TempDir::new().unwrap();
            let config_path = tmp.path().join("config.toml");
            std::fs::write(
                &config_path,
                "embedding_query_prefix = \"query: \"\n\
                 embedding_document_prefix = \"passage: \"\n",
            )
            .unwrap();
            let cfg = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
            println!(
                "query={:?} document={:?}",
                cfg.embedding_query_prefix, cfg.embedding_document_prefix
            );
            return;
        }
        // Running as the parent: re-exec this same test binary, filtered
        // to just this one test, as a genuinely separate child process
        // with both prefix env vars removed.
        let exe = std::env::current_exe().expect("current test binary path");
        let output = std::process::Command::new(&exe)
            .arg("--exact")
            .arg("config::tests::loader_toml_path_preserves_whitespace_with_no_env_var_set")
            .arg("--test-threads=1")
            .arg("--nocapture")
            .env(CHILD_MARKER, "1")
            .env_remove("AI_MEMORY_EMBEDDING_QUERY_PREFIX")
            .env_remove("AI_MEMORY_EMBEDDING_DOCUMENT_PREFIX")
            .output()
            .expect("failed to spawn child test process");
        assert!(
            output.status.success(),
            "child test process failed:\nstdout: {}\nstderr: {}",
            String::from_utf8_lossy(&output.stdout),
            String::from_utf8_lossy(&output.stderr)
        );
        let stdout = String::from_utf8_lossy(&output.stdout);
        assert!(
            stdout.contains("query=Some(\"query: \")"),
            "child stdout: {stdout}"
        );
        assert!(
            stdout.contains("document=Some(\"passage: \")"),
            "child stdout: {stdout}"
        );
    }

    #[test]
    fn copilot_embedding_defaults_model_dim_and_reuses_copilot_auth() {
        let tmp = TempDir::new().unwrap();
        let cfg = Config {
            data_dir: tmp.path().to_path_buf(),
            embedding_provider: Some("copilot".into()),
            runtime_env: RuntimeEnv {
                copilot_github_token: Some(SecretString::from("ghu-test")),
                ..RuntimeEnv::default()
            },
            ..Config::default()
        };

        let embedder = cfg.embedder_config().unwrap().unwrap();
        assert_eq!(embedder.provider, EmbedderChoice::Copilot);
        assert_eq!(embedder.model, "text-embedding-3-small");
        assert_eq!(embedder.dim, 1536);
        assert!(embedder.api_key.expose_secret().is_empty());
        let auth = embedder
            .copilot_auth
            .expect("copilot embedder config carries resolved Copilot auth");
        assert_eq!(auth.token_file, tmp.path().join("auth.json"));
        assert_eq!(auth.github_token.unwrap().expose_secret(), "ghu-test");
    }

    #[test]
    fn copilot_embedding_without_credentials_still_resolves_auth_material() {
        // `embedder_config` only resolves auth *inputs*, mirroring the chat
        // provider path (`copilot_provider_uses_data_dir_token_file_and_env_token`);
        // whether a usable credential exists is checked at construction time
        // by `CopilotEmbedder::new` (`ai-memory-llm`), not here.
        let tmp = TempDir::new().unwrap();
        let cfg = Config {
            data_dir: tmp.path().to_path_buf(),
            embedding_provider: Some("copilot".into()),
            ..Config::default()
        };

        let embedder = cfg.embedder_config().unwrap().unwrap();
        let auth = embedder.copilot_auth.expect("copilot auth is resolved");
        assert!(auth.github_token.is_none());
        assert!(auth.direct_api_token.is_none());
    }

    #[test]
    fn non_copilot_embedding_leaves_copilot_auth_unresolved() {
        // Auth resolution must be gated on the embedding provider actually
        // being copilot — resolving it unconditionally would fail closed for
        // every operator who has not logged into Copilot at all.
        let cfg = Config {
            embedding_provider: Some("openai".into()),
            runtime_env: RuntimeEnv {
                openai_api_key: Some(SecretString::from("sk-embed-key")),
                ..RuntimeEnv::default()
            },
            ..Config::default()
        };

        let embedder = cfg.embedder_config().unwrap().unwrap();
        assert!(embedder.copilot_auth.is_none());
    }

    #[test]
    fn openai_embedding_does_not_use_llm_api_key_without_custom_base_url() {
        let cfg = Config {
            embedding_provider: Some("openai".into()),
            runtime_env: RuntimeEnv {
                llm_api_key: Some(SecretString::from("sk-or-test-key")),
                ..RuntimeEnv::default()
            },
            ..Config::default()
        };

        let err = cfg.embedder_config().unwrap_err();
        assert!(
            matches!(err, LlmError::NotConfigured(msg) if msg == "EMBEDDING_API_KEY or OPENAI_API_KEY")
        );

        // The error names the dedicated key, and setting it resolves the
        // same configuration.
        let with_embedding_key = Config {
            runtime_env: RuntimeEnv {
                embedding_api_key: Some(SecretString::from("sk-embed-key")),
                ..cfg.runtime_env.clone()
            },
            ..cfg
        };
        assert_eq!(
            with_embedding_key
                .embedder_config()
                .unwrap()
                .unwrap()
                .api_key
                .expose_secret(),
            "sk-embed-key"
        );
    }

    #[test]
    fn llm_provider_config_uses_typed_provider_auth() {
        let cfg = Config {
            llm_provider: Some("openai".into()),
            runtime_env: RuntimeEnv {
                openai_api_key: Some(SecretString::from("sk-test-key")),
                ..RuntimeEnv::default()
            },
            ..Config::default()
        };

        let provider = cfg.llm_provider_config().unwrap().unwrap();
        assert_eq!(provider.provider, ProviderChoice::OpenAi);
        assert_eq!(provider.model, "gpt-5.4-mini");
        assert_eq!(
            provider.auth.requirement(),
            AuthRequirement::RequiredApiKey {
                env_var: "OPENAI_API_KEY"
            }
        );
        assert_eq!(
            provider.auth.source(),
            ai_memory_llm::CredentialSource::Environment {
                name: "OPENAI_API_KEY"
            }
        );
        assert_eq!(
            provider.auth.require_api_key().unwrap().expose_secret(),
            "sk-test-key"
        );
        assert!(provider.compat_strict);
    }

    #[test]
    fn anthropic_provider_uses_documented_default_model() {
        let cfg = Config {
            llm_provider: Some("anthropic".into()),
            runtime_env: RuntimeEnv {
                anthropic_api_key: Some(SecretString::from("sk-ant-test-key")),
                ..RuntimeEnv::default()
            },
            ..Config::default()
        };

        let provider = cfg.llm_provider_config().unwrap().unwrap();
        assert_eq!(provider.provider, ProviderChoice::Anthropic);
        assert_eq!(provider.model, "claude-haiku-4-5");
    }

    #[test]
    fn llm_test_api_key_override_wins_over_env_auth() {
        let cfg = Config {
            runtime_env: RuntimeEnv {
                openai_api_key: Some(SecretString::from("env-key")),
                ..RuntimeEnv::default()
            },
            ..Config::default()
        };

        let auth = cfg.provider_auth(
            ProviderChoice::OpenAi,
            Some(SecretString::from("override-key")),
        );

        assert_eq!(auth.source(), ai_memory_llm::CredentialSource::CliOverride);
        assert_eq!(
            auth.require_api_key().unwrap().expose_secret(),
            "override-key"
        );
    }

    #[test]
    fn openai_compat_auth_remains_optional() {
        let cfg = Config::default();

        let auth = cfg.provider_auth(ProviderChoice::OpenAiCompat, None);

        assert_eq!(
            auth.requirement(),
            AuthRequirement::OptionalApiKey {
                env_var: "LLM_API_KEY"
            }
        );
        assert!(auth.optional_api_key().is_none());
    }

    #[test]
    fn openai_compat_provider_defaults_strict_and_allows_opt_out() {
        let mut cfg = Config {
            llm_provider: Some("openai-compat".into()),
            llm_model: Some("qwen3:32b".into()),
            llm_base_url: Some("http://localhost:11434/v1".into()),
            ..Config::default()
        };

        let provider = cfg.llm_provider_config().unwrap().unwrap();

        assert_eq!(provider.provider, ProviderChoice::OpenAiCompat);
        assert_eq!(provider.model, "qwen3:32b");
        assert_eq!(
            provider.base_url.as_deref(),
            Some("http://localhost:11434/v1")
        );
        assert!(provider.compat_strict);

        cfg.llm_compat_strict = false;
        let provider = cfg.llm_provider_config().unwrap().unwrap();
        assert!(!provider.compat_strict);
    }

    /// The thinking switch is opt-in: off by default (existing vLLM /
    /// Ollama / LM Studio setups are unchanged) and forwarded verbatim to
    /// the provider config when the operator turns it on.
    #[test]
    fn openai_compat_disable_thinking_defaults_off_and_is_forwarded() {
        let mut cfg = Config {
            llm_provider: Some("openai-compat".into()),
            llm_model: Some("qwen3.8-27b".into()),
            llm_base_url: Some("http://localhost:8000/v1".into()),
            ..Config::default()
        };

        let provider = cfg.llm_provider_config().unwrap().unwrap();
        assert!(!provider.compat_disable_thinking);

        cfg.llm_compat_disable_thinking = true;
        let provider = cfg.llm_provider_config().unwrap().unwrap();
        assert!(provider.compat_disable_thinking);
    }

    /// TOML key loads and stays independent from the strict-mode default.
    #[test]
    fn load_accepts_llm_compat_disable_thinking_from_toml() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, "llm_compat_disable_thinking = true\n").unwrap();
        let cfg = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
        assert!(cfg.llm_compat_disable_thinking);
        // The sibling strict knob keeps its own default — independent keys.
        assert!(cfg.llm_compat_strict);
    }

    #[test]
    fn load_defaults_llm_compat_disable_thinking_off() {
        let tmp = TempDir::new().unwrap();
        let cfg = Config::load(None, Some(tmp.path().to_path_buf())).unwrap();
        assert!(!cfg.llm_compat_disable_thinking);
    }

    #[test]
    fn openai_oauth_provider_uses_data_dir_token_file() {
        let tmp = TempDir::new().unwrap();
        let cfg = Config {
            data_dir: tmp.path().to_path_buf(),
            llm_provider: Some("openai-oauth".into()),
            ..Config::default()
        };

        let provider = cfg.llm_provider_config().unwrap().unwrap();

        assert_eq!(provider.provider, ProviderChoice::OpenAiOAuth);
        assert_eq!(provider.model, "gpt-5.5");
        assert_eq!(
            provider.auth.requirement(),
            AuthRequirement::OpenAiOAuthToken
        );
        assert_eq!(
            provider.auth.require_openai_oauth_token_file().unwrap(),
            tmp.path().join("auth.json")
        );
        assert_eq!(provider.reasoning_effort, None);
    }

    #[rstest]
    #[case::unset(None)]
    #[case::low(Some(ReasoningEffort::Low))]
    #[case::none_wire(Some(ReasoningEffort::None))]
    fn openai_oauth_provider_config_forwards_reasoning_effort(
        #[case] effort: Option<ReasoningEffort>,
    ) {
        let tmp = TempDir::new().unwrap();
        let cfg = Config {
            data_dir: tmp.path().to_path_buf(),
            llm_provider: Some("openai-oauth".into()),
            llm_reasoning_effort: effort,
            ..Config::default()
        };

        let provider = cfg.llm_provider_config().unwrap().unwrap();
        assert_eq!(provider.reasoning_effort, effort);
    }

    #[test]
    fn codex_provider_uses_codex_home_auth_and_default_model() {
        let tmp = TempDir::new().unwrap();
        let codex_home = tmp.path().join("custom-codex-home");
        let cfg = Config {
            llm_provider: Some("codex".into()),
            runtime_env: RuntimeEnv {
                codex_home: Some(codex_home.clone()),
                codex_executable: Some(PathBuf::from("codex-custom")),
                ..RuntimeEnv::default()
            },
            ..Config::default()
        };

        let provider = cfg.llm_provider_config().unwrap().unwrap();
        let auth = provider.auth.require_codex_auth().unwrap();

        assert_eq!(provider.provider, ProviderChoice::Codex);
        assert_eq!(provider.model, "gpt-5.6-luna");
        assert_eq!(auth.auth_file, codex_home.join("auth.json"));
        assert_eq!(auth.executable, Path::new("codex-custom"));
    }

    #[test]
    fn codex_provider_falls_back_to_platform_home() {
        let tmp = TempDir::new().unwrap();
        let cfg = Config {
            llm_provider: Some("codex".into()),
            runtime_env: RuntimeEnv {
                platform_home: Some(tmp.path().to_path_buf()),
                ..RuntimeEnv::default()
            },
            ..Config::default()
        };

        let provider = cfg.llm_provider_config().unwrap().unwrap();
        let auth = provider.auth.require_codex_auth().unwrap();

        assert_eq!(auth.auth_file, tmp.path().join(".codex").join("auth.json"));
        assert_eq!(auth.executable, Path::new("codex"));
    }

    #[test]
    fn provider_config_forwards_the_operator_headers() {
        let tmp = TempDir::new().unwrap();
        let cfg = Config {
            data_dir: tmp.path().to_path_buf(),
            llm_provider: Some("opencode".into()),
            llm_headers: vec!["x-opencode-session=ses-1".into()],
            ..Config::default()
        };

        let provider = cfg.llm_provider_config().unwrap().unwrap();
        assert_eq!(
            provider.extra_headers,
            ExtraHeaders::parse(["x-opencode-session=ses-1"]).unwrap()
        );
    }

    #[test]
    fn codex_auth_resolution_treats_empty_codex_home_as_unset() {
        let platform_home = Path::new("/platform/home");

        assert_eq!(
            resolve_codex_auth_file(None, Some(platform_home)),
            platform_home.join(".codex").join("auth.json")
        );
        assert_eq!(
            resolve_codex_auth_file(Some(Path::new("")), Some(platform_home)),
            platform_home.join(".codex").join("auth.json")
        );
        assert_eq!(
            resolve_codex_auth_file(Some(Path::new("/custom/codex")), Some(platform_home)),
            Path::new("/custom/codex").join("auth.json")
        );
    }

    #[test]
    fn provider_config_defaults_to_no_operator_headers() {
        let tmp = TempDir::new().unwrap();
        let cfg = Config {
            data_dir: tmp.path().to_path_buf(),
            llm_provider: Some("opencode".into()),
            ..Config::default()
        };

        let provider = cfg.llm_provider_config().unwrap().unwrap();
        assert_eq!(provider.extra_headers, ExtraHeaders::default());
    }

    #[test]
    fn copilot_provider_uses_data_dir_token_file_and_env_token() {
        let tmp = TempDir::new().unwrap();
        let cfg = Config {
            data_dir: tmp.path().to_path_buf(),
            llm_provider: Some("copilot".into()),
            runtime_env: RuntimeEnv {
                copilot_github_token: Some(SecretString::from("ghu-test")),
                ..RuntimeEnv::default()
            },
            ..Config::default()
        };

        let provider = cfg.llm_provider_config().unwrap().unwrap();
        let auth = provider.auth.require_copilot_auth().unwrap();

        assert_eq!(provider.provider, ProviderChoice::Copilot);
        assert_eq!(provider.model, "gpt-5.5");
        assert_eq!(auth.token_file, tmp.path().join("auth.json"));
        assert_eq!(auth.github_token.unwrap().expose_secret(), "ghu-test");
    }

    #[test]
    fn anthropic_oauth_provider_resolves_choice_default_model_and_credential() {
        let cfg = Config {
            llm_provider: Some("anthropic-oauth".into()),
            runtime_env: RuntimeEnv {
                anthropic_oauth_token: Some(SecretString::from("tok-oauth-test")),
                ..RuntimeEnv::default()
            },
            ..Config::default()
        };

        let provider = cfg.llm_provider_config().unwrap().unwrap();
        assert_eq!(provider.provider, ProviderChoice::AnthropicOAuth);
        assert_eq!(provider.model, "claude-sonnet-4-6");
        assert_eq!(
            provider.auth.requirement(),
            AuthRequirement::AnthropicOAuthToken
        );
        assert_eq!(
            provider
                .auth
                .require_anthropic_oauth_token()
                .unwrap()
                .expose_secret(),
            "tok-oauth-test"
        );
    }

    #[test]
    fn opencode_provider_resolves_choice_default_model_and_api_key() {
        for spelling in ["opencode", "opencode-zen", "opencode_zen"] {
            let cfg = Config {
                llm_provider: Some(spelling.into()),
                runtime_env: RuntimeEnv {
                    opencode_api_key: Some(SecretString::from("sk-opencode-test")),
                    ..RuntimeEnv::default()
                },
                ..Config::default()
            };

            let provider = cfg.llm_provider_config().unwrap().unwrap();
            assert_eq!(provider.provider, ProviderChoice::OpenCode, "{spelling}");
            assert_eq!(provider.model, "mimo-v2.6-flash", "{spelling}");
            assert!(provider.base_url.is_none(), "{spelling}");
            assert_eq!(
                provider.auth.requirement(),
                AuthRequirement::RequiredApiKey {
                    env_var: "OPENCODE_API_KEY"
                },
                "{spelling}"
            );
            assert_eq!(
                provider.auth.require_api_key().unwrap().expose_secret(),
                "sk-opencode-test",
                "{spelling}"
            );
        }
    }

    #[test]
    fn cursor_provider_resolves_choice_default_model_and_executable() {
        let cfg = Config {
            llm_provider: Some("cursor".into()),
            runtime_env: RuntimeEnv {
                cursor_executable: Some(PathBuf::from("/opt/cursor/agent")),
                ..RuntimeEnv::default()
            },
            ..Config::default()
        };

        let provider = cfg.llm_provider_config().unwrap().unwrap();
        let auth = provider.auth.require_cursor_auth().unwrap();

        assert_eq!(provider.provider, ProviderChoice::Cursor);
        assert_eq!(provider.model, CURSOR_DEFAULT_MODEL);
        assert_eq!(auth.executable, PathBuf::from("/opt/cursor/agent"));
        assert_eq!(provider.auth.requirement(), AuthRequirement::CursorCli);
    }

    /// The Cursor child reads untrusted session text: the provider config
    /// hands it the captured environment's allowlisted part only, so the
    /// server's own bearer and other providers' keys never reach it.
    #[test]
    fn cursor_provider_hands_the_child_only_allowlisted_env() {
        let entries = [
            ("HOME", "/home/op"),
            ("PATH", "/usr/bin"),
            ("CURSOR_API_KEY", "cursor-key"),
            ("AI_MEMORY_AUTH_TOKEN", "root-bearer-canary"),
            ("ANTHROPIC_API_KEY", "sk-ant-canary"),
        ];
        let cfg = Config {
            llm_provider: Some("cursor".into()),
            runtime_env: RuntimeEnv {
                temp_dir: Some(PathBuf::from("/tmp")),
                process_env: CapturedProcessEnv(
                    entries
                        .iter()
                        .map(|(name, value)| (OsString::from(name), OsString::from(value)))
                        .collect(),
                ),
                ..RuntimeEnv::default()
            },
            ..Config::default()
        };

        let auth = cfg
            .llm_provider_config()
            .unwrap()
            .unwrap()
            .auth
            .require_cursor_auth()
            .unwrap();
        let mut names: Vec<_> = auth
            .child_env_names()
            .map(|name| name.to_string_lossy().into_owned())
            .collect();
        names.sort();
        assert_eq!(names, ["CURSOR_API_KEY", "HOME", "PATH"]);
    }

    fn load_with_toml(toml: &str) -> anyhow::Result<Config> {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, toml).unwrap();
        Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
    }

    #[test]
    fn llm_fallbacks_default_to_empty_and_no_behavior_change() {
        let cfg = Config::default();
        assert!(cfg.llm_fallbacks.is_empty());
        assert!(cfg.llm_fallback_configs.is_empty());
    }

    #[test]
    fn load_rejects_an_empty_fallback_provider() {
        let error = load_with_toml("[[llm_fallbacks]]\nprovider = \"\"\nmodel = \"m\"\n")
            .expect_err("an empty provider must fail closed");
        assert!(
            format!("{error:#}").contains("llm_fallbacks[0].provider must not be empty"),
            "unexpected error: {error:#}"
        );
    }

    #[test]
    fn load_rejects_an_unknown_fallback_provider() {
        let error = load_with_toml(
            "[[llm_fallbacks]]\nprovider = \"not-a-real-provider\"\nmodel = \"m\"\n",
        )
        .expect_err("an unknown provider must fail closed");
        assert!(
            format!("{error:#}").contains("is not one of"),
            "unexpected error: {error:#}"
        );
    }

    #[test]
    fn load_rejects_an_empty_fallback_model() {
        let error = load_with_toml("[[llm_fallbacks]]\nprovider = \"gemini\"\nmodel = \"\"\n")
            .expect_err("an empty model must fail closed");
        assert!(
            format!("{error:#}").contains("llm_fallbacks[0].model must not be empty"),
            "unexpected error: {error:#}"
        );
    }

    #[test]
    fn load_rejects_a_required_api_key_provider_with_no_api_key_env() {
        let error = load_with_toml("[[llm_fallbacks]]\nprovider = \"gemini\"\nmodel = \"m\"\n")
            .expect_err("a RequiredApiKey provider needs api_key_env");
        assert!(
            format!("{error:#}").contains("requires api_key_env"),
            "unexpected error: {error:#}"
        );
    }

    /// The fallback never silently inherits the *primary*'s fixed env var
    /// (`GEMINI_API_KEY`) — it must fail closed instead of looking healthy
    /// until the primary has an outage.
    #[test]
    fn load_rejects_a_fallback_that_would_otherwise_inherit_the_primary_credential() {
        let error = load_with_toml(
            "llm_provider = \"gemini\"\n[[llm_fallbacks]]\nprovider = \"gemini\"\nmodel = \"m\"\n",
        )
        .expect_err("omitting api_key_env must not fall back to GEMINI_API_KEY");
        assert!(
            format!("{error:#}").contains("requires api_key_env"),
            "unexpected error: {error:#}"
        );
    }

    /// #762: a credential absent from the invoking shell no longer fails
    /// `load` — `ai-memory status` must work from a shell that does not hold
    /// the server's keys — but it still fails closed wherever the chain is
    /// actually needed: `serve` startup and chain construction.
    #[test]
    fn a_missing_api_key_env_value_defers_to_serve_and_the_chain() {
        let config = load_with_toml(
            "llm_provider = \"gemini\"\n\
             [[llm_fallbacks]]\nprovider = \"gemini\"\nmodel = \"m\"\n\
             api_key_env = \"AI_MEMORY_TEST_FALLBACK_UNSET_KEY_648\"\n",
        )
        .expect("a CLI that never builds the chain must load without the credential");
        let expected = "llm_fallbacks[0].api_key_env=AI_MEMORY_TEST_FALLBACK_UNSET_KEY_648 is \
                        set but the environment variable is missing or empty";

        assert!(
            config.llm_fallback_configs.is_empty(),
            "an unresolved profile must never reach the chain"
        );
        let error = config
            .require_llm_fallback_credentials()
            .expect_err("serve startup must still fail closed");
        assert_eq!(format!("{error:#}"), expected);
        let error = config
            .llm_provider_chain()
            .err()
            .expect("building the chain must fail rather than drop the fallback");
        assert!(
            error.to_string().contains(expected),
            "unexpected error: {error}"
        );
    }

    /// Deferring the credential must not defer the rest of the profile's
    /// validation: a malformed profile still fails `load` for every command.
    #[test]
    fn a_missing_api_key_env_value_does_not_hide_a_malformed_profile() {
        let error = load_with_toml(
            "[[llm_fallbacks]]\nprovider = \"openai-compat\"\nmodel = \"m\"\n\
             api_key_env = \"AI_MEMORY_TEST_FALLBACK_UNSET_KEY_762\"\n",
        )
        .expect_err("openai-compat needs a base_url whether or not the key is present");
        assert!(
            format!("{error:#}").contains("LLM_BASE_URL"),
            "unexpected error: {error:#}"
        );
    }

    /// The placeholder that validates a profile with an absent credential
    /// must be accepted by every API-key provider's constructor. If one ever
    /// checks key shape (a prefix, a length), a correct profile would fail
    /// `load` over a key the operator never set — this pins that it does not.
    #[test]
    fn every_api_key_provider_accepts_the_unresolved_placeholder() {
        for (provider, extra) in [
            ("anthropic", ""),
            ("openai", ""),
            ("gemini", ""),
            ("opencode", ""),
            (
                "openai-compat",
                "base_url = \"https://openrouter.ai/api/v1\"\n",
            ),
        ] {
            let config = load_with_toml(&format!(
                "[[llm_fallbacks]]\nprovider = \"{provider}\"\nmodel = \"m\"\n{extra}\
                 api_key_env = \"AI_MEMORY_TEST_FALLBACK_UNSET_KEY_762\"\n"
            ))
            .unwrap_or_else(|error| {
                panic!("{provider}: load must defer the credential: {error:#}")
            });
            assert_eq!(
                config.llm_fallback_unresolved.len(),
                1,
                "{provider}: the absent credential must be recorded"
            );
            assert!(
                config.llm_fallback_configs.is_empty(),
                "{provider}: the placeholder-built config must be discarded"
            );
        }
    }

    #[test]
    fn a_config_without_unresolved_fallbacks_passes_the_serve_check() {
        let config = load_with_toml("").unwrap();
        config.require_llm_fallback_credentials().unwrap();
    }

    #[test]
    fn load_rejects_an_openai_compat_fallback_with_no_base_url() {
        let error =
            load_with_toml("[[llm_fallbacks]]\nprovider = \"openai-compat\"\nmodel = \"m\"\n")
                .expect_err("openai-compat needs a base_url");
        assert!(
            format!("{error:#}").contains("LLM_BASE_URL"),
            "unexpected error: {error:#}"
        );
    }

    #[test]
    fn load_accepts_a_well_formed_fallback_profile_with_no_primary() {
        // `llm_fallbacks` is meaningful even without a primary configured
        // (it is only ever consulted through `llm_provider_chain`, which
        // returns `None` when there is no primary) — the profile itself
        // must still validate independently.
        let cfg = load_with_toml(
            "[[llm_fallbacks]]\nprovider = \"openai-compat\"\nmodel = \"m\"\n\
             base_url = \"http://127.0.0.1:9\"\n",
        )
        .unwrap();
        let fallbacks = &cfg.llm_fallback_configs;
        assert_eq!(fallbacks.len(), 1);
        assert_eq!(fallbacks[0].provider, ProviderChoice::OpenAiCompat);
        assert_eq!(fallbacks[0].model, "m");
        assert_eq!(fallbacks[0].base_url.as_deref(), Some("http://127.0.0.1:9"));
        assert!(cfg.llm_provider_chain().unwrap().is_none());
    }

    /// `fallback_provider_config` takes the resolved credential as a plain
    /// parameter (see its doc comment): the environment is read once, in
    /// `Config::load`, and passed down as data so the happy path stays
    /// directly testable without mutating process env.
    #[test]
    fn fallback_provider_config_resolves_a_directly_supplied_credential() {
        let cfg = Config::default();
        let profile = FallbackProfile {
            provider: "gemini".into(),
            model: "gemini-3.5-flash".into(),
            base_url: None,
            api_key_env: Some("GEMINI_FALLBACK_KEY".into()),
        };
        let provider_cfg = cfg
            .fallback_provider_config(0, &profile, Some(SecretString::from("sk-fallback-test")))
            .unwrap();
        assert_eq!(provider_cfg.provider, ProviderChoice::Gemini);
        assert_eq!(provider_cfg.model, "gemini-3.5-flash");
        assert_eq!(
            provider_cfg.auth.require_api_key().unwrap().expose_secret(),
            "sk-fallback-test"
        );
    }

    /// `openai-oauth`/`copilot`/`anthropic-oauth` are native credential
    /// sources: no `api_key_env` is required, and the fallback shares the
    /// same process-wide token material as the primary.
    #[test]
    fn fallback_provider_config_allows_no_api_key_env_for_a_native_credential_provider() {
        let cfg = Config::default();
        let profile = FallbackProfile {
            provider: "anthropic-oauth".into(),
            model: "claude-sonnet-4-6".into(),
            base_url: None,
            api_key_env: None,
        };
        let provider_cfg = cfg.fallback_provider_config(0, &profile, None).unwrap();
        assert_eq!(provider_cfg.provider, ProviderChoice::AnthropicOAuth);
    }

    #[test]
    fn llm_provider_chain_is_the_plain_provider_when_no_fallback_is_configured() {
        let cfg = Config {
            llm_provider: Some("openai".into()),
            runtime_env: RuntimeEnv {
                openai_api_key: Some(SecretString::from("sk-test-key")),
                ..RuntimeEnv::default()
            },
            ..Config::default()
        };
        let chain = cfg.llm_provider_chain().unwrap().unwrap();
        assert_eq!(chain.name(), "openai");
        // A plain provider reports no candidates — only a fallback chain does.
        assert!(chain.candidate_health().is_empty());
    }

    /// End-to-end happy path through `Config::load` -> `llm_provider_chain`:
    /// a keyless `openai-compat` primary plus one keyless `openai-compat`
    /// fallback (distinct base URLs, as `docs/llm-provider-fallback.md`'s
    /// example does with distinct providers) produces a `FallbackLlmProvider`
    /// exposing both candidates, in declaration order.
    #[test]
    fn llm_provider_chain_wraps_the_primary_and_every_fallback_in_order() {
        let cfg = load_with_toml(
            "llm_provider = \"openai-compat\"\n\
             llm_model = \"primary-model\"\n\
             llm_base_url = \"http://127.0.0.1:9\"\n\
             [[llm_fallbacks]]\n\
             provider = \"openai-compat\"\n\
             model = \"fallback-model\"\n\
             base_url = \"http://127.0.0.1:9\"\n",
        )
        .unwrap();

        let chain = cfg.llm_provider_chain().unwrap().unwrap();
        assert_eq!(chain.name(), "openai-compat");
        assert_eq!(chain.model(), "primary-model");
        let candidates = chain.candidate_health();
        assert_eq!(candidates.len(), 2);
        assert_eq!(candidates[0].provider, "openai-compat");
        assert_eq!(candidates[0].model, "primary-model");
        assert_eq!(candidates[1].provider, "openai-compat");
        assert_eq!(candidates[1].model, "fallback-model");
    }

    #[test]
    fn llm_provider_chain_none_when_no_llm_is_configured() {
        assert!(Config::default().llm_provider_chain().unwrap().is_none());
    }

    #[test]
    fn run_profiles_parse_from_config_and_reject_ambiguous_names_and_keys() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(
            &config_path,
            "[run.profiles.work.env]\nCLAUDE_CONFIG_DIR = '/accounts/work'\nMODEL = 'opus'\n",
        )
        .unwrap();
        let config = Config::load(Some(&config_path), Some(tmp.path().join("data"))).unwrap();
        assert_eq!(
            config.run.profiles["work"].env["CLAUDE_CONFIG_DIR"],
            "/accounts/work"
        );

        std::fs::write(&config_path, "[run.profiles.'bad name'.env]\nFOO = 'bar'\n").unwrap();
        let error = Config::load(Some(&config_path), Some(tmp.path().join("data"))).unwrap_err();
        assert!(error.to_string().contains("invalid run profile name"));

        std::fs::write(
            &config_path,
            "[run.profiles.work.env]\nPATH = '/one'\nPath = '/two'\n",
        )
        .unwrap();
        let error = Config::load(Some(&config_path), Some(tmp.path().join("data"))).unwrap_err();
        assert!(error.to_string().contains("different ASCII case"));
    }

    #[test]
    fn anthropic_oauth_provider_underscore_alias_also_resolves() {
        let cfg = Config {
            llm_provider: Some("anthropic_oauth".into()),
            runtime_env: RuntimeEnv {
                anthropic_oauth_token: Some(SecretString::from("tok-alias")),
                ..RuntimeEnv::default()
            },
            ..Config::default()
        };
        let provider = cfg.llm_provider_config().unwrap().unwrap();
        assert_eq!(provider.provider, ProviderChoice::AnthropicOAuth);
    }
}

#[test]
fn llm_provider_config_passes_base_url_to_gemini() {
    let cfg = Config {
        llm_provider: Some("gemini".into()),
        llm_base_url: Some("http://localhost:9379".into()),
        runtime_env: RuntimeEnv {
            gemini_api_key: Some(SecretString::from("dummy")),
            ..RuntimeEnv::default()
        },
        ..Config::default()
    };
    let provider = cfg.llm_provider_config().unwrap().unwrap();
    assert_eq!(provider.provider, ProviderChoice::Gemini);
    assert_eq!(provider.base_url.as_deref(), Some("http://localhost:9379"));
}

#[test]
fn llm_provider_config_gemini_uses_default_base_url_when_none_provided() {
    let cfg = Config {
        llm_provider: Some("gemini".into()),
        llm_base_url: None, // Explicitly None
        runtime_env: RuntimeEnv {
            gemini_api_key: Some(SecretString::from("dummy")),
            ..RuntimeEnv::default()
        },
        ..Config::default()
    };
    let provider = cfg.llm_provider_config().unwrap().unwrap();
    assert_eq!(provider.provider, ProviderChoice::Gemini);
    assert_eq!(provider.base_url, None);
}

// #691: `LLM_BASE_URL` is an ambient, cross-tool convention — an operator who
// once pointed it at Ollama for `openai-compat` keeps it exported. Feeding it
// to Gemini builds `http://localhost:11434/v1beta/models/<model>:generateContent`,
// which Ollama answers with a plain-text `404 page not found`; the bootstrap
// surfaces that as a 502 with no server-side log line to explain it.
#[test]
fn ambient_llm_base_url_does_not_override_gemini() {
    let cfg = Config {
        llm_provider: Some("gemini".into()),
        llm_base_url: None,
        runtime_env: RuntimeEnv {
            gemini_api_key: Some(SecretString::from("dummy")),
            llm_base_url: Some("http://localhost:11434".into()),
            ..RuntimeEnv::default()
        },
        ..Config::default()
    };
    let provider = cfg.llm_provider_config().unwrap().unwrap();
    assert_eq!(provider.provider, ProviderChoice::Gemini);
    assert_eq!(provider.base_url, None);
}

// The other half of #691: the ambient fallback exists *for* the dialects whose
// endpoint the operator supplies, and narrowing it must not take that away.
// `openai-compat` has no endpoint at all without one.
#[test]
fn ambient_llm_base_url_still_configures_openai_compat() {
    let cfg = Config {
        llm_provider: Some("openai-compat".into()),
        llm_model: Some("gemma4:26b-mlx".into()),
        llm_base_url: None,
        runtime_env: RuntimeEnv {
            llm_base_url: Some("http://localhost:11434/v1".into()),
            ..RuntimeEnv::default()
        },
        ..Config::default()
    };
    let provider = cfg.llm_provider_config().unwrap().unwrap();
    assert_eq!(provider.provider, ProviderChoice::OpenAiCompat);
    assert_eq!(
        provider.base_url.as_deref(),
        Some("http://localhost:11434/v1")
    );
}

// `opencode` defaults to Go and reaches Zen's general catalogue only through an
// override, so it is operator-chosen too.
#[test]
fn ambient_llm_base_url_still_configures_opencode() {
    let cfg = Config {
        llm_provider: Some("opencode".into()),
        runtime_env: RuntimeEnv {
            opencode_api_key: Some(SecretString::from("dummy")),
            llm_base_url: Some("https://opencode.ai/zen/v1".into()),
            ..RuntimeEnv::default()
        },
        ..Config::default()
    };
    let provider = cfg.llm_provider_config().unwrap().unwrap();
    assert_eq!(provider.provider, ProviderChoice::OpenCode);
    assert_eq!(
        provider.base_url.as_deref(),
        Some("https://opencode.ai/zen/v1")
    );
}

// --- `[sessions] idle_end_after_hours` ------------------------------

/// The key defaults to `0` (off) when absent, parses from TOML, and the
/// load-time bound rejects a year-plus value by naming the key.
#[test]
fn sessions_idle_end_defaults_off_loads_from_toml_and_rejects_out_of_range() {
    use tempfile::TempDir;
    assert_eq!(Config::default().sessions.idle_end_after_hours, 0);

    let tmp = TempDir::new().unwrap();
    let config_path = tmp.path().join("config.toml");
    // Absent key keeps the default.
    std::fs::write(&config_path, "# nothing\n").unwrap();
    let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
    assert_eq!(config.sessions.idle_end_after_hours, 0);

    // TOML parse.
    std::fs::write(&config_path, "[sessions]\nidle_end_after_hours = 24\n").unwrap();
    let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
    assert_eq!(config.sessions.idle_end_after_hours, 24);

    // Boundary: one year is accepted.
    std::fs::write(&config_path, "[sessions]\nidle_end_after_hours = 8760\n").unwrap();
    let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
    assert_eq!(config.sessions.idle_end_after_hours, 8760);

    // Above the bound the load fails and names the key.
    std::fs::write(&config_path, "[sessions]\nidle_end_after_hours = 8761\n").unwrap();
    let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
        .expect_err("above the bound must fail at load");
    assert!(
        error.to_string().contains("idle_end_after_hours"),
        "unexpected error: {error:#}"
    );
}

/// The env form `AI_MEMORY_SESSIONS__IDLE_END_AFTER_HOURS` outranks the
/// TOML value, like every other flat config key.
#[test]
fn sessions_idle_end_env_overrides_config() {
    use tempfile::TempDir;
    const CHILD_MARKER: &str = "AI_MEMORY_TEST_SESSIONS_IDLE_END_CHILD";
    if std::env::var_os(CHILD_MARKER).is_some() {
        let tmp = TempDir::new().unwrap();
        let config_path = tmp.path().join("config.toml");
        std::fs::write(&config_path, "[sessions]\nidle_end_after_hours = 24\n").unwrap();
        let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();
        assert_eq!(config.sessions.idle_end_after_hours, 48);
        println!("sessions-idle-end-env-applied");
        return;
    }

    let output = std::process::Command::new(std::env::current_exe().unwrap())
        .arg("--exact")
        .arg("config::sessions_idle_end_env_overrides_config")
        .arg("--test-threads=1")
        .arg("--nocapture")
        .env(CHILD_MARKER, "1")
        .env("AI_MEMORY_SESSIONS__IDLE_END_AFTER_HOURS", "48")
        .output()
        .unwrap();
    assert!(
        output.status.success(),
        "child test failed:\nstdout: {}\nstderr: {}",
        String::from_utf8_lossy(&output.stdout),
        String::from_utf8_lossy(&output.stderr)
    );
    assert!(
        String::from_utf8_lossy(&output.stdout).contains("sessions-idle-end-env-applied"),
        "child stdout: {}",
        String::from_utf8_lossy(&output.stdout)
    );
}

// Naming ai-memory is how an operator says they mean it: proxying Gemini stays
// possible, and the explicit setting outranks an ambient one that disagrees.
#[test]
fn explicit_llm_base_url_still_overrides_gemini_over_an_ambient_one() {
    let cfg = Config {
        llm_provider: Some("gemini".into()),
        llm_base_url: Some("https://gemini-proxy.internal".into()),
        runtime_env: RuntimeEnv {
            gemini_api_key: Some(SecretString::from("dummy")),
            llm_base_url: Some("http://localhost:11434".into()),
            ..RuntimeEnv::default()
        },
        ..Config::default()
    };
    let provider = cfg.llm_provider_config().unwrap().unwrap();
    assert_eq!(
        provider.base_url.as_deref(),
        Some("https://gemini-proxy.internal")
    );
}

// `llm-test` is the tool an operator reaches for to reproduce what `serve`
// does. It resolved base_url through its own copy of the old chain, so before
// this fix it hit the ambient endpoint too — and agreed with the broken server
// instead of exposing it.
#[test]
fn llm_test_base_url_resolves_per_provider_like_serve_does() {
    let cfg = Config {
        llm_base_url: None,
        runtime_env: RuntimeEnv {
            llm_base_url: Some("http://localhost:11434".into()),
            ..RuntimeEnv::default()
        },
        ..Config::default()
    };
    assert_eq!(cfg.llm_test_base_url(ProviderChoice::Gemini), None);
    assert_eq!(
        cfg.llm_test_base_url(ProviderChoice::OpenAiCompat)
            .as_deref(),
        Some("http://localhost:11434")
    );
}