pi/core/

settings.rs

//! Global and project settings: wire types, migrations, trust-gated merge, and
//! atomic persistence.
//!
//! Ports `.references/pi/packages/coding-agent/src/core/settings-manager.ts`.
//!
//! Settings documents are carried as raw [`Map<String, Value>`] inside
//! [`SettingsManager`] so unknown keys, wrong-typed values, and explicit
//! `null` survive load → merge → save exactly like TypeScript. Typed
//! [`Settings`] / nested wire structs are a tolerant view; a known key with
//! the wrong JSON type reads as `None` in the view while remaining on disk.
//!
//! Persistence re-reads under the S0 [`LockGuard`], overlays only modified
//! top-level (and nested) keys, pretty-prints with two-space indent, and does
//! not force a trailing newline. A scope with a parse error refuses to save.
//! Project data is fully gated when untrusted; the refusal error is exact.

use std::collections::{BTreeMap, BTreeSet};
use std::env;
use std::fs;
use std::path::{Path, PathBuf};
use std::sync::Mutex;

use pi_agent::QueueMode;
use pi_ai::{ModelThinkingLevel, Transport};
use serde_json::{Map, Value};
use thiserror::Error;
use uuid::Uuid;

use super::config::{CONFIG_DIR_NAME, expand_tilde_path, get_agent_dir, resolve_path};
use super::lockfile::LockGuard;
use super::trust::DefaultProjectTrust;

/// Default tokens reserved for prompt + response during compaction.
pub const DEFAULT_COMPACTION_RESERVE_TOKENS: u64 = 16384;
/// Default recent-message tokens kept after compaction.
pub const DEFAULT_COMPACTION_KEEP_RECENT_TOKENS: u64 = 20000;
/// Default tokens reserved for branch-summary generation.
pub const DEFAULT_BRANCH_SUMMARY_RESERVE_TOKENS: u64 = 16384;
/// Default automatic-retry attempt count.
pub const DEFAULT_RETRY_MAX_RETRIES: u64 = 3;
/// Default automatic-retry base backoff delay in milliseconds.
pub const DEFAULT_RETRY_BASE_DELAY_MS: u64 = 2000;
/// Default maximum server-requested retry delay in milliseconds.
pub const DEFAULT_PROVIDER_MAX_RETRY_DELAY_MS: u64 = 60000;
/// Default HTTP header/body idle timeout (`http-dispatcher.ts`).
pub const DEFAULT_HTTP_IDLE_TIMEOUT_MS: u64 = 300_000;
/// Default preferred inline image width in terminal cells.
pub const DEFAULT_IMAGE_WIDTH_CELLS: u64 = 60;
/// Default maximum visible autocomplete items.
pub const DEFAULT_AUTOCOMPLETE_MAX_VISIBLE: u64 = 5;
/// Default markdown code block indent.
pub const DEFAULT_CODE_BLOCK_INDENT: &str = "  ";

const U64_MAX_F64: f64 = 18_446_744_073_709_551_616.0;
/// `i64::MIN` as an exact `f64` (exactly `-2^63`).
const I64_MIN_F64: f64 = -9_223_372_036_854_775_808.0;

const KNOWN_SETTINGS_KEYS: &[&str] = &[
    "lastChangelogVersion",
    "defaultProvider",
    "defaultModel",
    "defaultThinkingLevel",
    "transport",
    "steeringMode",
    "followUpMode",
    "theme",
    "compaction",
    "branchSummary",
    "retry",
    "hideThinkingBlock",
    "showCacheMissNotices",
    "externalEditor",
    "shellPath",
    "quietStartup",
    "defaultProjectTrust",
    "shellCommandPrefix",
    "npmCommand",
    "collapseChangelog",
    "enableInstallTelemetry",
    "enableAnalytics",
    "trackingId",
    "packages",
    "extensions",
    "skills",
    "prompts",
    "themes",
    "enableSkillCommands",
    "terminal",
    "images",
    "enabledModels",
    "doubleEscapeAction",
    "treeFilterMode",
    "thinkingBudgets",
    "editorPaddingX",
    "outputPad",
    "autocompleteMaxVisible",
    "showHardwareCursor",
    "markdown",
    "warnings",
    "sessionDir",
    "httpProxy",
    "httpIdleTimeoutMs",
    "websocketConnectTimeoutMs",
];

const PACKAGE_SOURCE_FILTER_KEYS: &[&str] = &[
    "source",
    "autoload",
    "extensions",
    "skills",
    "prompts",
    "themes",
];

/// Settings document scope: the global agent file or the project file.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum SettingsScope {
    /// `{agentDir}/settings.json`.
    Global,
    /// `{cwd}/.pi/settings.json`.
    Project,
}

/// One error recorded by [`SettingsManager`], tagged with its scope.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct SettingsError {
    /// Scope that produced the error.
    pub scope: SettingsScope,
    /// Underlying error message.
    pub message: String,
}

/// Errors thrown synchronously by [`SettingsManager`] methods.
#[derive(Debug, Error)]
pub enum SettingsManagerError {
    /// Project write attempted while the project is not trusted.
    #[error("Project is not trusted; refusing to write project settings")]
    ProjectNotTrusted,
    /// Invalid value passed to, or stored in, a numeric setting.
    #[error("Invalid {setting} setting: {value}")]
    InvalidSetting {
        /// Wire name of the setting.
        setting: &'static str,
        /// JavaScript `String(value)` rendering of the offending value.
        value: String,
    },
}

/// Options for [`SettingsManager::create`] / [`from_storage`] / [`in_memory`].
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct SettingsManagerCreateOptions {
    /// Whether project settings are trusted and loaded. Defaults to `true`.
    pub project_trusted: bool,
}

impl Default for SettingsManagerCreateOptions {
    fn default() -> Self {
        Self {
            project_trusted: true,
        }
    }
}

impl SettingsManagerCreateOptions {
    /// Default options (project trusted).
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Set whether the project is trusted.
    #[must_use]
    pub const fn project_trusted(mut self, project_trusted: bool) -> Self {
        self.project_trusted = project_trusted;
        self
    }
}

/// Action for double-escape with an empty editor (`doubleEscapeAction`).
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum DoubleEscapeAction {
    /// Fork the session.
    Fork,
    /// Open the session tree (default).
    #[default]
    Tree,
    /// Do nothing.
    None,
}

impl DoubleEscapeAction {
    /// Wire string used in settings JSON.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Fork => "fork",
            Self::Tree => "tree",
            Self::None => "none",
        }
    }

    fn parse(value: &str) -> Option<Self> {
        match value {
            "fork" => Some(Self::Fork),
            "tree" => Some(Self::Tree),
            "none" => Some(Self::None),
            _ => None,
        }
    }
}

/// Default filter when opening `/tree` (`treeFilterMode`).
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum TreeFilterMode {
    /// No filtering (default).
    #[default]
    Default,
    /// Hide tool messages.
    NoTools,
    /// Show only user messages.
    UserOnly,
    /// Show only labeled entries.
    LabeledOnly,
    /// Show everything.
    All,
}

impl TreeFilterMode {
    /// Wire string used in settings JSON.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Default => "default",
            Self::NoTools => "no-tools",
            Self::UserOnly => "user-only",
            Self::LabeledOnly => "labeled-only",
            Self::All => "all",
        }
    }

    fn parse(value: &str) -> Option<Self> {
        match value {
            "default" => Some(Self::Default),
            "no-tools" => Some(Self::NoTools),
            "user-only" => Some(Self::UserOnly),
            "labeled-only" => Some(Self::LabeledOnly),
            "all" => Some(Self::All),
            _ => None,
        }
    }
}

/// Horizontal chat-message output padding (`outputPad`, wire `0 | 1`).
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum OutputPad {
    /// No padding.
    Zero,
    /// One cell of padding (default).
    #[default]
    One,
}

impl OutputPad {
    /// Wire number used in settings JSON.
    #[must_use]
    pub const fn as_u64(self) -> u64 {
        match self {
            Self::Zero => 0,
            Self::One => 1,
        }
    }
}

/// Nested `compaction` settings object.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct CompactionSettings {
    /// Whether automatic compaction is enabled (default: true).
    pub enabled: Option<bool>,
    /// Tokens reserved for prompt + LLM response (default: 16384).
    pub reserve_tokens: Option<u64>,
    /// Recent-message tokens kept (default: 20000).
    pub keep_recent_tokens: Option<u64>,
    /// Unknown nested keys preserved from the raw document.
    pub extra: Map<String, Value>,
}

/// Nested `branchSummary` settings object.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct BranchSummarySettings {
    /// Tokens reserved for prompt + LLM response (default: 16384).
    pub reserve_tokens: Option<u64>,
    /// Skip the "Summarize branch?" prompt, defaulting to no summary.
    pub skip_prompt: Option<bool>,
    /// Unknown nested keys preserved from the raw document.
    pub extra: Map<String, Value>,
}

/// Nested `retry.provider` settings object.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct ProviderRetrySettings {
    /// SDK/provider request timeout in milliseconds.
    pub timeout_ms: Option<u64>,
    /// SDK/provider retry attempts.
    pub max_retries: Option<u64>,
    /// Max server-requested delay before failing (default: 60000).
    pub max_retry_delay_ms: Option<u64>,
    /// Unknown nested keys preserved from the raw document.
    pub extra: Map<String, Value>,
}

/// Nested `retry` settings object.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct RetrySettings {
    /// Whether automatic retry is enabled (default: true).
    pub enabled: Option<bool>,
    /// Retry attempts (default: 3).
    pub max_retries: Option<u64>,
    /// Base delay for exponential backoff in milliseconds (default: 2000).
    pub base_delay_ms: Option<u64>,
    /// Provider-level retry overrides.
    pub provider: Option<ProviderRetrySettings>,
    /// Unknown nested keys preserved from the raw document.
    pub extra: Map<String, Value>,
}

/// Nested `terminal` settings object.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct TerminalSettings {
    /// Show inline images when the terminal supports them (default: true).
    pub show_images: Option<bool>,
    /// Preferred inline image width in terminal cells (default: 60).
    pub image_width_cells: Option<u64>,
    /// Clear empty rows when content shrinks (default: false).
    pub clear_on_shrink: Option<bool>,
    /// OSC 9;4 terminal progress indicators (default: false).
    pub show_terminal_progress: Option<bool>,
    /// Unknown nested keys preserved from the raw document.
    pub extra: Map<String, Value>,
}

/// Nested `images` settings object.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct ImageSettings {
    /// Resize images to 2000x2000 max for model compatibility (default: true).
    pub auto_resize: Option<bool>,
    /// Prevent all images from being sent to providers (default: false).
    pub block_images: Option<bool>,
    /// Unknown nested keys preserved from the raw document.
    pub extra: Map<String, Value>,
}

/// Nested `thinkingBudgets` settings object with custom token budgets.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct ThinkingBudgetsSettings {
    /// Budget for the minimal thinking level.
    pub minimal: Option<u64>,
    /// Budget for the low thinking level.
    pub low: Option<u64>,
    /// Budget for the medium thinking level.
    pub medium: Option<u64>,
    /// Budget for the high thinking level.
    pub high: Option<u64>,
    /// Unknown nested keys preserved from the raw document.
    pub extra: Map<String, Value>,
}

/// Nested `markdown` settings object.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct MarkdownSettings {
    /// Code block indent (default: two spaces).
    pub code_block_indent: Option<String>,
    /// Unknown nested keys preserved from the raw document.
    pub extra: Map<String, Value>,
}

/// Nested `warnings` settings object.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct WarningSettings {
    /// Warn about Anthropic extra usage (default: true).
    pub anthropic_extra_usage: Option<bool>,
    /// Unknown nested keys preserved from the raw document.
    pub extra: Map<String, Value>,
}

/// Package source for npm/git packages (`packages` array elements).
#[derive(Clone, Debug, PartialEq)]
pub enum PackageSource {
    /// Load all resources from the package (string form).
    Source(String),
    /// Object form with resource filtering.
    Filtered(PackageSourceFilter),
}

/// Object form of [`PackageSource`].
#[derive(Clone, Debug, Default, PartialEq)]
pub struct PackageSourceFilter {
    /// Package source specifier (npm/git/local path).
    pub source: String,
    /// When false, only explicit resource patterns are applied.
    pub autoload: Option<bool>,
    /// Extension file/directory patterns to load.
    pub extensions: Option<Vec<String>>,
    /// Skill file/directory patterns to load.
    pub skills: Option<Vec<String>>,
    /// Prompt template path patterns to load.
    pub prompts: Option<Vec<String>>,
    /// Theme path patterns to load.
    pub themes: Option<Vec<String>>,
    /// Unknown nested keys preserved from the raw document.
    pub extra: Map<String, Value>,
}

impl PackageSource {
    /// Tolerant conversion from a raw JSON value.
    #[must_use]
    pub fn from_value(value: &Value) -> Option<Self> {
        match value {
            Value::String(source) => Some(Self::Source(source.clone())),
            Value::Object(map) => {
                let source = map.get("source").and_then(Value::as_str)?.to_owned();
                Some(Self::Filtered(PackageSourceFilter {
                    source,
                    autoload: map.get("autoload").and_then(Value::as_bool),
                    extensions: string_array(map.get("extensions")),
                    skills: string_array(map.get("skills")),
                    prompts: string_array(map.get("prompts")),
                    themes: string_array(map.get("themes")),
                    extra: unknown_fields(map, PACKAGE_SOURCE_FILTER_KEYS),
                }))
            }
            _ => None,
        }
    }

    /// Serialize to the raw JSON wire form.
    #[must_use]
    pub fn to_value(&self) -> Value {
        match self {
            Self::Source(source) => Value::String(source.clone()),
            Self::Filtered(filter) => {
                let mut map = filter.extra.clone();
                map.insert("source".to_owned(), Value::String(filter.source.clone()));
                insert_opt_bool(&mut map, "autoload", filter.autoload);
                insert_opt_strings(&mut map, "extensions", filter.extensions.as_deref());
                insert_opt_strings(&mut map, "skills", filter.skills.as_deref());
                insert_opt_strings(&mut map, "prompts", filter.prompts.as_deref());
                insert_opt_strings(&mut map, "themes", filter.themes.as_deref());
                Value::Object(map)
            }
        }
    }
}

/// Typed view over a settings document.
///
/// Every field mirrors the TypeScript `Settings` interface. Unknown keys are
/// preserved in [`Self::extra`]; a known key whose stored value has the wrong
/// JSON type reads as `None` here while remaining untouched on disk.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct Settings {
    /// Last changelog version acknowledged by the user.
    pub last_changelog_version: Option<String>,
    /// Default provider identifier.
    pub default_provider: Option<String>,
    /// Default model identifier.
    pub default_model: Option<String>,
    /// Default thinking level (wire includes `"off"`).
    pub default_thinking_level: Option<ModelThinkingLevel>,
    /// Streaming transport preference (default: auto).
    pub transport: Option<Transport>,
    /// Steering queue drain mode (default: one-at-a-time).
    pub steering_mode: Option<QueueMode>,
    /// Follow-up queue drain mode (default: one-at-a-time).
    pub follow_up_mode: Option<QueueMode>,
    /// Theme name or path.
    pub theme: Option<String>,
    /// Compaction settings.
    pub compaction: Option<CompactionSettings>,
    /// Branch-summary settings.
    pub branch_summary: Option<BranchSummarySettings>,
    /// Retry settings.
    pub retry: Option<RetrySettings>,
    /// Hide thinking blocks in the transcript (default: false).
    pub hide_thinking_block: Option<bool>,
    /// Show prompt-cache-miss transcript notices (default: false).
    pub show_cache_miss_notices: Option<bool>,
    /// Command for the Ctrl+G external editor; takes precedence over VISUAL/EDITOR.
    pub external_editor: Option<String>,
    /// Custom shell path; supports leading `~` expansion.
    pub shell_path: Option<String>,
    /// Suppress startup output (default: false).
    pub quiet_startup: Option<bool>,
    /// Default project trust decision; honored from the global file only.
    pub default_project_trust: Option<DefaultProjectTrust>,
    /// Prefix prepended to every bash command.
    pub shell_command_prefix: Option<String>,
    /// argv-style command used for npm lookup/install operations.
    pub npm_command: Option<Vec<String>>,
    /// Show condensed changelog after update (default: false).
    pub collapse_changelog: Option<bool>,
    /// Anonymous version/update ping after updates (default: true).
    pub enable_install_telemetry: Option<bool>,
    /// Opt-in analytics data sharing (default: false).
    pub enable_analytics: Option<bool>,
    /// Analytics tracking identifier, generated on first analytics opt-in.
    pub tracking_id: Option<String>,
    /// npm/git package sources.
    pub packages: Option<Vec<PackageSource>>,
    /// Local extension file paths or directories.
    pub extensions: Option<Vec<String>>,
    /// Local skill file paths or directories.
    pub skills: Option<Vec<String>>,
    /// Local prompt template paths or directories.
    pub prompts: Option<Vec<String>>,
    /// Local theme file paths or directories.
    pub themes: Option<Vec<String>>,
    /// Register skills as `/skill:name` commands (default: true).
    pub enable_skill_commands: Option<bool>,
    /// Terminal settings.
    pub terminal: Option<TerminalSettings>,
    /// Image settings.
    pub images: Option<ImageSettings>,
    /// Model patterns for cycling (same format as `--models`).
    pub enabled_models: Option<Vec<String>>,
    /// Double-escape action with empty editor (default: tree).
    pub double_escape_action: Option<DoubleEscapeAction>,
    /// Default `/tree` filter.
    pub tree_filter_mode: Option<TreeFilterMode>,
    /// Custom token budgets for thinking levels.
    pub thinking_budgets: Option<ThinkingBudgetsSettings>,
    /// Horizontal input-editor padding (default: 0).
    pub editor_padding_x: Option<u64>,
    /// Horizontal chat-output padding (default: 1).
    pub output_pad: Option<OutputPad>,
    /// Max visible autocomplete items (default: 5).
    pub autocomplete_max_visible: Option<u64>,
    /// Show the terminal cursor while still positioning it for IME.
    pub show_hardware_cursor: Option<bool>,
    /// Markdown rendering settings.
    pub markdown: Option<MarkdownSettings>,
    /// Warning toggles.
    pub warnings: Option<WarningSettings>,
    /// Custom session storage directory (same format as `--session-dir`).
    pub session_dir: Option<String>,
    /// Proxy URL applied as `HTTP_PROXY`/`HTTPS_PROXY` for managed HTTP clients.
    pub http_proxy: Option<String>,
    /// HTTP header/body idle timeout in milliseconds; 0 disables.
    pub http_idle_timeout_ms: Option<u64>,
    /// WebSocket connect/open handshake timeout in milliseconds; 0 disables.
    pub websocket_connect_timeout_ms: Option<u64>,
    /// Unknown top-level keys preserved from the raw document.
    pub extra: Map<String, Value>,
}

impl Settings {
    /// Build the tolerant typed view over a raw settings object.
    #[must_use]
    pub fn from_map(map: &Map<String, Value>) -> Self {
        Self {
            last_changelog_version: string_field(map, "lastChangelogVersion"),
            default_provider: string_field(map, "defaultProvider"),
            default_model: string_field(map, "defaultModel"),
            default_thinking_level: parse_thinking_level(map.get("defaultThinkingLevel")),
            transport: parse_transport(map.get("transport")),
            steering_mode: parse_queue_mode(map.get("steeringMode")),
            follow_up_mode: parse_queue_mode(map.get("followUpMode")),
            theme: string_field(map, "theme"),
            compaction: nested_field(map, "compaction", CompactionSettings::from_map),
            branch_summary: nested_field(map, "branchSummary", BranchSummarySettings::from_map),
            retry: nested_field(map, "retry", RetrySettings::from_map),
            hide_thinking_block: bool_field(map, "hideThinkingBlock"),
            show_cache_miss_notices: bool_field(map, "showCacheMissNotices"),
            external_editor: string_field(map, "externalEditor"),
            shell_path: string_field(map, "shellPath"),
            quiet_startup: bool_field(map, "quietStartup"),
            default_project_trust: parse_default_project_trust(map.get("defaultProjectTrust")),
            shell_command_prefix: string_field(map, "shellCommandPrefix"),
            npm_command: string_array(map.get("npmCommand")),
            collapse_changelog: bool_field(map, "collapseChangelog"),
            enable_install_telemetry: bool_field(map, "enableInstallTelemetry"),
            enable_analytics: bool_field(map, "enableAnalytics"),
            tracking_id: string_field(map, "trackingId"),
            packages: map
                .get("packages")
                .and_then(Value::as_array)
                .map(|items| items.iter().filter_map(PackageSource::from_value).collect()),
            extensions: string_array(map.get("extensions")),
            skills: string_array(map.get("skills")),
            prompts: string_array(map.get("prompts")),
            themes: string_array(map.get("themes")),
            enable_skill_commands: bool_field(map, "enableSkillCommands"),
            terminal: nested_field(map, "terminal", TerminalSettings::from_map),
            images: nested_field(map, "images", ImageSettings::from_map),
            enabled_models: string_array(map.get("enabledModels")),
            double_escape_action: map
                .get("doubleEscapeAction")
                .and_then(Value::as_str)
                .and_then(DoubleEscapeAction::parse),
            tree_filter_mode: map
                .get("treeFilterMode")
                .and_then(Value::as_str)
                .and_then(TreeFilterMode::parse),
            thinking_budgets: nested_field(
                map,
                "thinkingBudgets",
                ThinkingBudgetsSettings::from_map,
            ),
            editor_padding_x: number_to_u64(map.get("editorPaddingX")),
            output_pad: parse_output_pad(map.get("outputPad")),
            autocomplete_max_visible: number_to_u64(map.get("autocompleteMaxVisible")),
            show_hardware_cursor: bool_field(map, "showHardwareCursor"),
            markdown: nested_field(map, "markdown", MarkdownSettings::from_map),
            warnings: nested_field(map, "warnings", WarningSettings::from_map),
            session_dir: string_field(map, "sessionDir"),
            http_proxy: string_field(map, "httpProxy"),
            http_idle_timeout_ms: map.get("httpIdleTimeoutMs").and_then(parse_timeout_ms),
            websocket_connect_timeout_ms: map
                .get("websocketConnectTimeoutMs")
                .and_then(parse_timeout_ms),
            extra: unknown_fields(map, KNOWN_SETTINGS_KEYS),
        }
    }

    /// Serialize the typed view back to a raw settings object.
    ///
    /// `extra` keys are written first, then known keys, so a manually built
    /// `Settings` with a colliding `extra` key keeps the typed field's value.
    #[must_use]
    pub fn to_map(&self) -> Map<String, Value> {
        let mut map = self.extra.clone();
        self.insert_scalar_fields(&mut map);
        self.insert_nested_fields(&mut map);
        self.insert_resource_fields(&mut map);
        map
    }

    fn insert_scalar_fields(&self, map: &mut Map<String, Value>) {
        insert_opt_string(
            map,
            "lastChangelogVersion",
            self.last_changelog_version.as_deref(),
        );
        insert_opt_string(map, "defaultProvider", self.default_provider.as_deref());
        insert_opt_string(map, "defaultModel", self.default_model.as_deref());
        insert_opt_value(
            map,
            "defaultThinkingLevel",
            self.default_thinking_level.map(thinking_level_value),
        );
        insert_opt_value(map, "transport", self.transport.map(transport_value));
        insert_opt_value(
            map,
            "steeringMode",
            self.steering_mode.map(queue_mode_value),
        );
        insert_opt_value(
            map,
            "followUpMode",
            self.follow_up_mode.map(queue_mode_value),
        );
        insert_opt_string(map, "theme", self.theme.as_deref());
        insert_opt_bool(map, "hideThinkingBlock", self.hide_thinking_block);
        insert_opt_bool(map, "showCacheMissNotices", self.show_cache_miss_notices);
        insert_opt_string(map, "externalEditor", self.external_editor.as_deref());
        insert_opt_string(map, "shellPath", self.shell_path.as_deref());
        insert_opt_bool(map, "quietStartup", self.quiet_startup);
        insert_opt_value(
            map,
            "defaultProjectTrust",
            self.default_project_trust
                .map(|trust| Value::String(trust.as_str().to_owned())),
        );
        insert_opt_string(
            map,
            "shellCommandPrefix",
            self.shell_command_prefix.as_deref(),
        );
        insert_opt_bool(map, "collapseChangelog", self.collapse_changelog);
        insert_opt_bool(map, "enableInstallTelemetry", self.enable_install_telemetry);
        insert_opt_bool(map, "enableAnalytics", self.enable_analytics);
        insert_opt_string(map, "trackingId", self.tracking_id.as_deref());
        insert_opt_bool(map, "enableSkillCommands", self.enable_skill_commands);
        insert_opt_value(
            map,
            "doubleEscapeAction",
            self.double_escape_action
                .map(|action| Value::String(action.as_str().to_owned())),
        );
        insert_opt_value(
            map,
            "treeFilterMode",
            self.tree_filter_mode
                .map(|mode| Value::String(mode.as_str().to_owned())),
        );
        insert_opt_u64(map, "editorPaddingX", self.editor_padding_x);
        insert_opt_value(
            map,
            "outputPad",
            self.output_pad.map(|pad| Value::from(pad.as_u64())),
        );
        insert_opt_u64(map, "autocompleteMaxVisible", self.autocomplete_max_visible);
        insert_opt_bool(map, "showHardwareCursor", self.show_hardware_cursor);
        insert_opt_string(map, "sessionDir", self.session_dir.as_deref());
        insert_opt_string(map, "httpProxy", self.http_proxy.as_deref());
        insert_opt_u64(map, "httpIdleTimeoutMs", self.http_idle_timeout_ms);
        insert_opt_u64(
            map,
            "websocketConnectTimeoutMs",
            self.websocket_connect_timeout_ms,
        );
    }

    fn insert_nested_fields(&self, map: &mut Map<String, Value>) {
        insert_opt_value(
            map,
            "compaction",
            self.compaction
                .as_ref()
                .map(|value| Value::Object(value.to_map())),
        );
        insert_opt_value(
            map,
            "branchSummary",
            self.branch_summary
                .as_ref()
                .map(|value| Value::Object(value.to_map())),
        );
        insert_opt_value(
            map,
            "retry",
            self.retry
                .as_ref()
                .map(|value| Value::Object(value.to_map())),
        );
        insert_opt_value(
            map,
            "terminal",
            self.terminal
                .as_ref()
                .map(|value| Value::Object(value.to_map())),
        );
        insert_opt_value(
            map,
            "images",
            self.images
                .as_ref()
                .map(|value| Value::Object(value.to_map())),
        );
        insert_opt_value(
            map,
            "thinkingBudgets",
            self.thinking_budgets
                .as_ref()
                .map(|value| Value::Object(value.to_map())),
        );
        insert_opt_value(
            map,
            "markdown",
            self.markdown
                .as_ref()
                .map(|value| Value::Object(value.to_map())),
        );
        insert_opt_value(
            map,
            "warnings",
            self.warnings
                .as_ref()
                .map(|value| Value::Object(value.to_map())),
        );
    }

    fn insert_resource_fields(&self, map: &mut Map<String, Value>) {
        insert_opt_strings(map, "npmCommand", self.npm_command.as_deref());
        insert_opt_value(
            map,
            "packages",
            self.packages.as_ref().map(|packages| {
                Value::Array(packages.iter().map(PackageSource::to_value).collect())
            }),
        );
        insert_opt_strings(map, "extensions", self.extensions.as_deref());
        insert_opt_strings(map, "skills", self.skills.as_deref());
        insert_opt_strings(map, "prompts", self.prompts.as_deref());
        insert_opt_strings(map, "themes", self.themes.as_deref());
        insert_opt_strings(map, "enabledModels", self.enabled_models.as_deref());
    }
}

impl CompactionSettings {
    fn from_map(map: &Map<String, Value>) -> Self {
        Self {
            enabled: bool_field(map, "enabled"),
            reserve_tokens: number_to_u64(map.get("reserveTokens")),
            keep_recent_tokens: number_to_u64(map.get("keepRecentTokens")),
            extra: unknown_fields(map, &["enabled", "reserveTokens", "keepRecentTokens"]),
        }
    }

    fn to_map(&self) -> Map<String, Value> {
        let mut map = self.extra.clone();
        insert_opt_bool(&mut map, "enabled", self.enabled);
        insert_opt_u64(&mut map, "reserveTokens", self.reserve_tokens);
        insert_opt_u64(&mut map, "keepRecentTokens", self.keep_recent_tokens);
        map
    }
}

impl BranchSummarySettings {
    fn from_map(map: &Map<String, Value>) -> Self {
        Self {
            reserve_tokens: number_to_u64(map.get("reserveTokens")),
            skip_prompt: bool_field(map, "skipPrompt"),
            extra: unknown_fields(map, &["reserveTokens", "skipPrompt"]),
        }
    }

    fn to_map(&self) -> Map<String, Value> {
        let mut map = self.extra.clone();
        insert_opt_u64(&mut map, "reserveTokens", self.reserve_tokens);
        insert_opt_bool(&mut map, "skipPrompt", self.skip_prompt);
        map
    }
}

impl ProviderRetrySettings {
    fn from_map(map: &Map<String, Value>) -> Self {
        Self {
            timeout_ms: number_to_u64(map.get("timeoutMs")),
            max_retries: number_to_u64(map.get("maxRetries")),
            max_retry_delay_ms: number_to_u64(map.get("maxRetryDelayMs")),
            extra: unknown_fields(map, &["timeoutMs", "maxRetries", "maxRetryDelayMs"]),
        }
    }

    fn to_map(&self) -> Map<String, Value> {
        let mut map = self.extra.clone();
        insert_opt_u64(&mut map, "timeoutMs", self.timeout_ms);
        insert_opt_u64(&mut map, "maxRetries", self.max_retries);
        insert_opt_u64(&mut map, "maxRetryDelayMs", self.max_retry_delay_ms);
        map
    }
}

impl RetrySettings {
    fn from_map(map: &Map<String, Value>) -> Self {
        Self {
            enabled: bool_field(map, "enabled"),
            max_retries: number_to_u64(map.get("maxRetries")),
            base_delay_ms: number_to_u64(map.get("baseDelayMs")),
            provider: nested_field(map, "provider", ProviderRetrySettings::from_map),
            extra: unknown_fields(map, &["enabled", "maxRetries", "baseDelayMs", "provider"]),
        }
    }

    fn to_map(&self) -> Map<String, Value> {
        let mut map = self.extra.clone();
        insert_opt_bool(&mut map, "enabled", self.enabled);
        insert_opt_u64(&mut map, "maxRetries", self.max_retries);
        insert_opt_u64(&mut map, "baseDelayMs", self.base_delay_ms);
        insert_opt_value(
            &mut map,
            "provider",
            self.provider
                .as_ref()
                .map(|value| Value::Object(value.to_map())),
        );
        map
    }
}

impl TerminalSettings {
    fn from_map(map: &Map<String, Value>) -> Self {
        Self {
            show_images: bool_field(map, "showImages"),
            image_width_cells: number_to_u64(map.get("imageWidthCells")),
            clear_on_shrink: bool_field(map, "clearOnShrink"),
            show_terminal_progress: bool_field(map, "showTerminalProgress"),
            extra: unknown_fields(
                map,
                &[
                    "showImages",
                    "imageWidthCells",
                    "clearOnShrink",
                    "showTerminalProgress",
                ],
            ),
        }
    }

    fn to_map(&self) -> Map<String, Value> {
        let mut map = self.extra.clone();
        insert_opt_bool(&mut map, "showImages", self.show_images);
        insert_opt_u64(&mut map, "imageWidthCells", self.image_width_cells);
        insert_opt_bool(&mut map, "clearOnShrink", self.clear_on_shrink);
        insert_opt_bool(
            &mut map,
            "showTerminalProgress",
            self.show_terminal_progress,
        );
        map
    }
}

impl ImageSettings {
    fn from_map(map: &Map<String, Value>) -> Self {
        Self {
            auto_resize: bool_field(map, "autoResize"),
            block_images: bool_field(map, "blockImages"),
            extra: unknown_fields(map, &["autoResize", "blockImages"]),
        }
    }

    fn to_map(&self) -> Map<String, Value> {
        let mut map = self.extra.clone();
        insert_opt_bool(&mut map, "autoResize", self.auto_resize);
        insert_opt_bool(&mut map, "blockImages", self.block_images);
        map
    }
}

impl ThinkingBudgetsSettings {
    fn from_map(map: &Map<String, Value>) -> Self {
        Self {
            minimal: number_to_u64(map.get("minimal")),
            low: number_to_u64(map.get("low")),
            medium: number_to_u64(map.get("medium")),
            high: number_to_u64(map.get("high")),
            extra: unknown_fields(map, &["minimal", "low", "medium", "high"]),
        }
    }

    fn to_map(&self) -> Map<String, Value> {
        let mut map = self.extra.clone();
        insert_opt_u64(&mut map, "minimal", self.minimal);
        insert_opt_u64(&mut map, "low", self.low);
        insert_opt_u64(&mut map, "medium", self.medium);
        insert_opt_u64(&mut map, "high", self.high);
        map
    }
}

impl MarkdownSettings {
    fn from_map(map: &Map<String, Value>) -> Self {
        Self {
            code_block_indent: string_field(map, "codeBlockIndent"),
            extra: unknown_fields(map, &["codeBlockIndent"]),
        }
    }

    fn to_map(&self) -> Map<String, Value> {
        let mut map = self.extra.clone();
        insert_opt_string(
            &mut map,
            "codeBlockIndent",
            self.code_block_indent.as_deref(),
        );
        map
    }
}

impl WarningSettings {
    fn from_map(map: &Map<String, Value>) -> Self {
        Self {
            anthropic_extra_usage: bool_field(map, "anthropicExtraUsage"),
            extra: unknown_fields(map, &["anthropicExtraUsage"]),
        }
    }

    fn to_map(&self) -> Map<String, Value> {
        let mut map = self.extra.clone();
        insert_opt_bool(&mut map, "anthropicExtraUsage", self.anthropic_extra_usage);
        map
    }
}

/// Fully-resolved compaction configuration.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ResolvedCompactionSettings {
    /// Whether automatic compaction is enabled.
    pub enabled: bool,
    /// Tokens reserved for prompt + LLM response.
    pub reserve_tokens: u64,
    /// Recent-message tokens kept.
    pub keep_recent_tokens: u64,
}

/// Fully-resolved branch-summary configuration.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ResolvedBranchSummarySettings {
    /// Tokens reserved for prompt + LLM response.
    pub reserve_tokens: u64,
    /// Whether the "Summarize branch?" prompt is skipped.
    pub skip_prompt: bool,
}

/// Fully-resolved retry configuration.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ResolvedRetrySettings {
    /// Whether automatic retry is enabled.
    pub enabled: bool,
    /// Retry attempts.
    pub max_retries: u64,
    /// Base delay for exponential backoff in milliseconds.
    pub base_delay_ms: u64,
}

/// Fully-resolved provider retry configuration.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ResolvedProviderRetrySettings {
    /// SDK/provider request timeout in milliseconds.
    pub timeout_ms: Option<u64>,
    /// SDK/provider retry attempts.
    pub max_retries: Option<u64>,
    /// Max server-requested delay before failing.
    pub max_retry_delay_ms: u64,
}

/// Storage backend for settings documents.
///
/// Ports the TypeScript `SettingsStorage` interface: `with_lock` hands the
/// current raw document text (or `None` when the file does not exist) to `f`;
/// the callback returns the next text to persist, or `Ok(None)` to perform no
/// write. A callback `Err` aborts without writing.
pub trait SettingsStorage: Send + Sync {
    /// Run `f` under the scope's exclusive lock.
    ///
    /// # Errors
    ///
    /// Returns the lock, read, write, or callback error message.
    fn with_lock(
        &mut self,
        scope: SettingsScope,
        f: &mut dyn FnMut(Option<String>) -> Result<Option<String>, String>,
    ) -> Result<(), String>;
}

/// File-backed storage: `{agentDir}/settings.json` and `{cwd}/.pi/settings.json`.
///
/// Mirrors TypeScript `FileSettingsStorage`:
/// - the settings file itself is locked (`settings.json.lock` sibling)
/// - a missing file is read without acquiring the lock when no write happens
/// - the parent directory is created only when content is actually written
#[derive(Debug)]
pub struct FileSettingsStorage {
    global_settings_path: PathBuf,
    project_settings_path: PathBuf,
}

impl FileSettingsStorage {
    /// Create storage rooted at `cwd` (project) and `agent_dir` (global).
    #[must_use]
    pub fn new(cwd: impl AsRef<Path>, agent_dir: impl AsRef<Path>) -> Self {
        let resolved_cwd = resolve_path(path_to_string(cwd.as_ref()));
        let resolved_agent_dir = resolve_path(path_to_string(agent_dir.as_ref()));
        Self {
            global_settings_path: resolved_agent_dir.join("settings.json"),
            project_settings_path: resolved_cwd.join(CONFIG_DIR_NAME).join("settings.json"),
        }
    }

    /// Path of the global settings file.
    #[must_use]
    pub fn global_settings_path(&self) -> &Path {
        &self.global_settings_path
    }

    /// Path of the project settings file.
    #[must_use]
    pub fn project_settings_path(&self) -> &Path {
        &self.project_settings_path
    }

    fn path_for(&self, scope: SettingsScope) -> &Path {
        match scope {
            SettingsScope::Global => &self.global_settings_path,
            SettingsScope::Project => &self.project_settings_path,
        }
    }
}

impl SettingsStorage for FileSettingsStorage {
    fn with_lock(
        &mut self,
        scope: SettingsScope,
        f: &mut dyn FnMut(Option<String>) -> Result<Option<String>, String>,
    ) -> Result<(), String> {
        let path = self.path_for(scope).to_path_buf();
        let dir = path
            .parent()
            .map_or_else(|| PathBuf::from("."), Path::to_path_buf);

        let file_exists = path.exists();
        let mut guard = if file_exists {
            Some(LockGuard::acquire(&path).map_err(|error| error.to_string())?)
        } else {
            None
        };
        let current =
            if file_exists {
                Some(fs::read_to_string(&path).map_err(|error| {
                    format!("Failed to read settings {}: {error}", path.display())
                })?)
            } else {
                None
            };
        let next = f(current)?;
        if let Some(next) = next {
            if !dir.exists() {
                fs::create_dir_all(&dir).map_err(|error| {
                    format!(
                        "Failed to create settings directory {}: {error}",
                        dir.display()
                    )
                })?;
            }
            if guard.is_none() {
                guard = Some(LockGuard::acquire(&path).map_err(|error| error.to_string())?);
            }
            fs::write(&path, next)
                .map_err(|error| format!("Failed to write settings {}: {error}", path.display()))?;
        }
        drop(guard);
        Ok(())
    }
}

/// In-memory storage backend (no file I/O).
#[derive(Debug, Default)]
pub struct InMemorySettingsStorage {
    global: Option<String>,
    project: Option<String>,
}

impl InMemorySettingsStorage {
    /// Create empty in-memory storage.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }
}

impl SettingsStorage for InMemorySettingsStorage {
    fn with_lock(
        &mut self,
        scope: SettingsScope,
        f: &mut dyn FnMut(Option<String>) -> Result<Option<String>, String>,
    ) -> Result<(), String> {
        let slot = match scope {
            SettingsScope::Global => &mut self.global,
            SettingsScope::Project => &mut self.project,
        };
        let next = f(slot.clone())?;
        if let Some(next) = next {
            *slot = Some(next);
        }
        Ok(())
    }
}

/// Settings manager: loads, migrates, merges, and persists global and
/// trust-gated project settings.
///
/// Internally documents are raw JSON objects; merges and migrations operate at
/// the JSON level exactly like the TypeScript implementation. Writes are
/// performed synchronously inside setters; storage errors are recorded and
/// surfaced through [`Self::drain_errors`]. The only methods that return
/// errors are project writes while untrusted and the timeout getter/setter
/// validations.
pub struct SettingsManager {
    storage: Box<dyn SettingsStorage>,
    global_settings: Map<String, Value>,
    project_settings: Map<String, Value>,
    settings: Map<String, Value>,
    project_trusted: bool,
    modified_fields: BTreeSet<String>,
    modified_nested_fields: BTreeMap<String, BTreeSet<String>>,
    modified_project_fields: BTreeSet<String>,
    modified_project_nested_fields: BTreeMap<String, BTreeSet<String>>,
    global_settings_load_error: Option<String>,
    project_settings_load_error: Option<String>,
    errors: Vec<SettingsError>,
    /// Serializes in-process writes so [`Self::flush`] can wait for them.
    write_mutex: Mutex<()>,
}

impl SettingsManager {
    fn new(
        storage: Box<dyn SettingsStorage>,
        global_settings: Map<String, Value>,
        project_settings: Map<String, Value>,
        global_load_error: Option<String>,
        project_load_error: Option<String>,
        initial_errors: Vec<SettingsError>,
        project_trusted: bool,
    ) -> Self {
        let settings = deep_merge_settings(&global_settings, &project_settings);
        Self {
            storage,
            global_settings,
            project_settings,
            settings,
            project_trusted,
            modified_fields: BTreeSet::new(),
            modified_nested_fields: BTreeMap::new(),
            modified_project_fields: BTreeSet::new(),
            modified_project_nested_fields: BTreeMap::new(),
            global_settings_load_error: global_load_error,
            project_settings_load_error: project_load_error,
            errors: initial_errors,
            write_mutex: Mutex::new(()),
        }
    }

    /// Create a manager backed by settings files under `agent_dir`
    /// (default: [`get_agent_dir`]) and `{cwd}/.pi`.
    #[must_use]
    pub fn create(
        cwd: impl AsRef<Path>,
        agent_dir: Option<impl AsRef<Path>>,
        options: SettingsManagerCreateOptions,
    ) -> Self {
        let agent_dir = agent_dir.map_or_else(get_agent_dir, |dir| dir.as_ref().to_path_buf());
        Self::from_storage(Box::new(FileSettingsStorage::new(cwd, agent_dir)), options)
    }

    /// Create a manager from an arbitrary storage backend.
    #[must_use]
    pub fn from_storage(
        mut storage: Box<dyn SettingsStorage>,
        options: SettingsManagerCreateOptions,
    ) -> Self {
        let project_trusted = options.project_trusted;
        let (global_settings, global_error) =
            Self::try_load_from_storage(storage.as_mut(), SettingsScope::Global, true);
        let (project_settings, project_error) =
            Self::try_load_from_storage(storage.as_mut(), SettingsScope::Project, project_trusted);
        let mut initial_errors = Vec::new();
        if let Some(message) = &global_error {
            initial_errors.push(SettingsError {
                scope: SettingsScope::Global,
                message: message.clone(),
            });
        }
        if let Some(message) = &project_error {
            initial_errors.push(SettingsError {
                scope: SettingsScope::Project,
                message: message.clone(),
            });
        }
        Self::new(
            storage,
            global_settings,
            project_settings,
            global_error,
            project_error,
            initial_errors,
            project_trusted,
        )
    }

    /// Create an in-memory manager (no file I/O) seeded with `settings`.
    #[must_use]
    pub fn in_memory(settings: &Settings, options: SettingsManagerCreateOptions) -> Self {
        let mut storage = InMemorySettingsStorage::new();
        let mut initial = settings.to_map();
        migrate_settings(&mut initial);
        let seed =
            serde_json::to_string_pretty(&Value::Object(initial)).unwrap_or_else(|_| "{}".into());
        let _ = storage.with_lock(SettingsScope::Global, &mut |_| Ok(Some(seed.clone())));
        Self::from_storage(Box::new(storage), options)
    }

    fn load_from_storage(
        storage: &mut dyn SettingsStorage,
        scope: SettingsScope,
        project_trusted: bool,
    ) -> Result<Map<String, Value>, String> {
        if scope == SettingsScope::Project && !project_trusted {
            return Ok(Map::new());
        }
        let mut content: Option<String> = None;
        storage.with_lock(scope, &mut |current| {
            content = current;
            Ok(None)
        })?;
        // `if (!content) return {}` — missing *or empty* file loads as empty.
        let Some(text) = content.filter(|text| !text.is_empty()) else {
            return Ok(Map::new());
        };
        parse_settings_text(&text)
    }

    fn try_load_from_storage(
        storage: &mut dyn SettingsStorage,
        scope: SettingsScope,
        project_trusted: bool,
    ) -> (Map<String, Value>, Option<String>) {
        match Self::load_from_storage(storage, scope, project_trusted) {
            Ok(settings) => (settings, None),
            Err(message) => (Map::new(), Some(message)),
        }
    }

    /// Typed view of the global settings document.
    #[must_use]
    pub fn get_global_settings(&self) -> Settings {
        Settings::from_map(&self.global_settings)
    }

    /// Typed view of the project settings document (empty while untrusted).
    #[must_use]
    pub fn get_project_settings(&self) -> Settings {
        Settings::from_map(&self.project_settings)
    }

    /// Whether the project is currently trusted.
    #[must_use]
    pub const fn is_project_trusted(&self) -> bool {
        self.project_trusted
    }

    /// Change project trust. `false` discards project data; `true` reloads it.
    pub fn set_project_trusted(&mut self, trusted: bool) {
        if self.project_trusted == trusted {
            return;
        }
        self.project_trusted = trusted;
        self.modified_project_fields.clear();
        self.modified_project_nested_fields.clear();
        if !trusted {
            self.project_settings = Map::new();
            self.project_settings_load_error = None;
            self.settings = deep_merge_settings(&self.global_settings, &self.project_settings);
            return;
        }
        let (project_settings, project_error) =
            Self::try_load_from_storage(self.storage.as_mut(), SettingsScope::Project, true);
        self.project_settings = project_settings;
        self.project_settings_load_error.clone_from(&project_error);
        if let Some(message) = project_error {
            self.record_error(SettingsScope::Project, message);
        }
        self.settings = deep_merge_settings(&self.global_settings, &self.project_settings);
    }

    /// Reload both scopes from storage, discarding pending modifications.
    pub fn reload(&mut self) {
        let (global_settings, global_error) =
            Self::try_load_from_storage(self.storage.as_mut(), SettingsScope::Global, true);
        match global_error {
            None => {
                self.global_settings = global_settings;
                self.global_settings_load_error = None;
            }
            Some(message) => {
                self.global_settings_load_error = Some(message.clone());
                self.record_error(SettingsScope::Global, message);
            }
        }
        self.modified_fields.clear();
        self.modified_nested_fields.clear();
        self.modified_project_fields.clear();
        self.modified_project_nested_fields.clear();
        let (project_settings, project_error) = Self::try_load_from_storage(
            self.storage.as_mut(),
            SettingsScope::Project,
            self.project_trusted,
        );
        match project_error {
            None => {
                self.project_settings = project_settings;
                self.project_settings_load_error = None;
            }
            Some(message) => {
                self.project_settings_load_error = Some(message.clone());
                self.record_error(SettingsScope::Project, message);
            }
        }
        self.settings = deep_merge_settings(&self.global_settings, &self.project_settings);
    }

    /// Apply additional overrides on top of the merged settings.
    ///
    /// Overrides are not persisted and are discarded by the next save (TS parity).
    pub fn apply_overrides(&mut self, overrides: &Map<String, Value>) {
        self.settings = deep_merge_settings(&self.settings, overrides);
    }

    /// Wait for any in-process write to finish.
    ///
    /// Setters acquire the same mutex around persistence, so this blocks until
    /// concurrent writers (if any) complete, matching TypeScript `flush` after
    /// the write queue drains.
    pub fn flush(&self) {
        let _guard = match self.write_mutex.lock() {
            Ok(guard) => guard,
            Err(poisoned) => poisoned.into_inner(),
        };
    }

    /// Take all recorded errors, leaving the error list empty.
    #[must_use]
    pub fn drain_errors(&mut self) -> Vec<SettingsError> {
        std::mem::take(&mut self.errors)
    }

    fn record_error(&mut self, scope: SettingsScope, message: String) {
        self.errors.push(SettingsError { scope, message });
    }

    fn clear_modified_scope(&mut self, scope: SettingsScope) {
        match scope {
            SettingsScope::Global => {
                self.modified_fields.clear();
                self.modified_nested_fields.clear();
            }
            SettingsScope::Project => {
                self.modified_project_fields.clear();
                self.modified_project_nested_fields.clear();
            }
        }
    }

    fn assert_project_trusted_for_write(&self) -> Result<(), SettingsManagerError> {
        if self.project_trusted {
            Ok(())
        } else {
            Err(SettingsManagerError::ProjectNotTrusted)
        }
    }

    fn persist_scoped_settings(
        &mut self,
        scope: SettingsScope,
        snapshot_settings: &Map<String, Value>,
        modified_fields: &BTreeSet<String>,
        modified_nested_fields: &BTreeMap<String, BTreeSet<String>>,
    ) -> Result<(), String> {
        if scope == SettingsScope::Project && !self.project_trusted {
            return Err(SettingsManagerError::ProjectNotTrusted.to_string());
        }
        let _write_guard = match self.write_mutex.lock() {
            Ok(guard) => guard,
            Err(poisoned) => poisoned.into_inner(),
        };
        self.storage.with_lock(scope, &mut |current| {
            let current_file_settings = match current {
                Some(text) if !text.is_empty() => parse_settings_text(&text)?,
                _ => Map::new(),
            };
            let mut merged_settings = current_file_settings.clone();
            for field in modified_fields {
                let value = snapshot_settings.get(field);
                match (modified_nested_fields.get(field), value) {
                    (Some(nested_modified), Some(Value::Object(in_memory_nested))) => {
                        let mut merged_nested = match current_file_settings.get(field) {
                            Some(Value::Object(base_nested)) => base_nested.clone(),
                            _ => Map::new(),
                        };
                        for nested_key in nested_modified {
                            match in_memory_nested.get(nested_key) {
                                Some(nested_value) => {
                                    merged_nested.insert(nested_key.clone(), nested_value.clone());
                                }
                                None => {
                                    merged_nested.remove(nested_key);
                                }
                            }
                        }
                        merged_settings.insert(field.clone(), Value::Object(merged_nested));
                    }
                    _ => match value {
                        Some(value) => {
                            merged_settings.insert(field.clone(), value.clone());
                        }
                        None => {
                            merged_settings.remove(field);
                        }
                    },
                }
            }
            serde_json::to_string_pretty(&Value::Object(merged_settings))
                .map(Some)
                .map_err(|error| error.to_string())
        })
    }

    fn save(&mut self) {
        self.settings = deep_merge_settings(&self.global_settings, &self.project_settings);
        if self.global_settings_load_error.is_some() {
            return;
        }
        let snapshot = self.global_settings.clone();
        let modified_fields = self.modified_fields.clone();
        let modified_nested_fields = self.modified_nested_fields.clone();
        match self.persist_scoped_settings(
            SettingsScope::Global,
            &snapshot,
            &modified_fields,
            &modified_nested_fields,
        ) {
            Ok(()) => self.clear_modified_scope(SettingsScope::Global),
            Err(message) => self.record_error(SettingsScope::Global, message),
        }
    }

    fn save_project_settings(
        &mut self,
        settings: Map<String, Value>,
    ) -> Result<(), SettingsManagerError> {
        self.assert_project_trusted_for_write()?;
        self.project_settings = settings;
        self.settings = deep_merge_settings(&self.global_settings, &self.project_settings);
        if self.project_settings_load_error.is_some() {
            return Ok(());
        }
        let snapshot = self.project_settings.clone();
        let modified_fields = self.modified_project_fields.clone();
        let modified_nested_fields = self.modified_project_nested_fields.clone();
        match self.persist_scoped_settings(
            SettingsScope::Project,
            &snapshot,
            &modified_fields,
            &modified_nested_fields,
        ) {
            Ok(()) => {
                self.clear_modified_scope(SettingsScope::Project);
                Ok(())
            }
            Err(message) => {
                self.record_error(SettingsScope::Project, message);
                Ok(())
            }
        }
    }

    fn update_project_settings(
        &mut self,
        field: &'static str,
        update: impl FnOnce(&mut Map<String, Value>),
    ) -> Result<(), SettingsManagerError> {
        self.assert_project_trusted_for_write()?;
        let mut project_settings = self.project_settings.clone();
        update(&mut project_settings);
        self.modified_project_fields.insert(field.to_owned());
        self.save_project_settings(project_settings)
    }

    fn set_global_field(&mut self, field: &'static str, value: Value) {
        self.global_settings.insert(field.to_owned(), value);
        self.modified_fields.insert(field.to_owned());
        self.save();
    }

    fn set_global_optional_field(&mut self, field: &'static str, value: Option<Value>) {
        match value {
            Some(value) => {
                self.global_settings.insert(field.to_owned(), value);
            }
            None => {
                self.global_settings.remove(field);
            }
        }
        self.modified_fields.insert(field.to_owned());
        self.save();
    }

    fn set_global_nested_field(
        &mut self,
        field: &'static str,
        nested_key: &'static str,
        value: Value,
    ) {
        let mut nested = match self.global_settings.get_mut(field) {
            Some(Value::Object(object)) => std::mem::take(object),
            _ => Map::new(),
        };
        nested.insert(nested_key.to_owned(), value);
        self.global_settings
            .insert(field.to_owned(), Value::Object(nested));
        self.modified_fields.insert(field.to_owned());
        self.modified_nested_fields
            .entry(field.to_owned())
            .or_default()
            .insert(nested_key.to_owned());
        self.save();
    }

    fn merged_bool(&self, key: &str) -> Option<bool> {
        self.settings.get(key).and_then(Value::as_bool)
    }

    fn merged_nested_bool(&self, key: &str, nested_key: &str) -> Option<bool> {
        self.settings
            .get(key)
            .and_then(Value::as_object)?
            .get(nested_key)?
            .as_bool()
    }

    fn merged_nested_u64(&self, key: &str, nested_key: &str) -> Option<u64> {
        number_to_u64(
            self.settings
                .get(key)
                .and_then(Value::as_object)?
                .get(nested_key),
        )
    }

    fn merged_string_array(&self, key: &str) -> Vec<String> {
        string_array(self.settings.get(key)).unwrap_or_default()
    }

    // -- Changelog / session -------------------------------------------------

    /// `lastChangelogVersion` from merged settings.
    #[must_use]
    pub fn get_last_changelog_version(&self) -> Option<String> {
        string_field(&self.settings, "lastChangelogVersion")
    }

    /// Set `lastChangelogVersion` (global).
    pub fn set_last_changelog_version(&mut self, version: &str) {
        self.set_global_field("lastChangelogVersion", Value::String(version.to_owned()));
    }

    /// `sessionDir` with `~` expansion; empty string returned verbatim.
    #[must_use]
    pub fn get_session_dir(&self) -> Option<String> {
        normalize_optional_path(self.settings.get("sessionDir"))
    }

    // -- Model ----------------------------------------------------------------

    /// `defaultProvider` from merged settings.
    #[must_use]
    pub fn get_default_provider(&self) -> Option<String> {
        string_field(&self.settings, "defaultProvider")
    }

    /// `defaultModel` from merged settings.
    #[must_use]
    pub fn get_default_model(&self) -> Option<String> {
        string_field(&self.settings, "defaultModel")
    }

    /// Set `defaultProvider` (global).
    pub fn set_default_provider(&mut self, provider: &str) {
        self.set_global_field("defaultProvider", Value::String(provider.to_owned()));
    }

    /// Set `defaultModel` (global).
    pub fn set_default_model(&mut self, model_id: &str) {
        self.set_global_field("defaultModel", Value::String(model_id.to_owned()));
    }

    /// Set both `defaultProvider` and `defaultModel` with one save (global).
    pub fn set_default_model_and_provider(&mut self, provider: &str, model_id: &str) {
        self.global_settings.insert(
            "defaultProvider".to_owned(),
            Value::String(provider.to_owned()),
        );
        self.global_settings.insert(
            "defaultModel".to_owned(),
            Value::String(model_id.to_owned()),
        );
        self.modified_fields.insert("defaultProvider".to_owned());
        self.modified_fields.insert("defaultModel".to_owned());
        self.save();
    }

    /// `defaultThinkingLevel` from merged settings.
    #[must_use]
    pub fn get_default_thinking_level(&self) -> Option<ModelThinkingLevel> {
        parse_thinking_level(self.settings.get("defaultThinkingLevel"))
    }

    /// Set `defaultThinkingLevel` (global).
    pub fn set_default_thinking_level(&mut self, level: ModelThinkingLevel) {
        self.set_global_field("defaultThinkingLevel", thinking_level_value(level));
    }

    /// `enabledModels` from merged settings.
    #[must_use]
    pub fn get_enabled_models(&self) -> Option<Vec<String>> {
        string_array(self.settings.get("enabledModels"))
    }

    /// Set `enabledModels`; `None` removes the key (global).
    pub fn set_enabled_models(&mut self, patterns: Option<Vec<String>>) {
        self.set_global_optional_field(
            "enabledModels",
            patterns
                .map(|patterns| Value::Array(patterns.into_iter().map(Value::String).collect())),
        );
    }

    /// `thinkingBudgets` from merged settings.
    #[must_use]
    pub fn get_thinking_budgets(&self) -> Option<ThinkingBudgetsSettings> {
        nested_field(
            &self.settings,
            "thinkingBudgets",
            ThinkingBudgetsSettings::from_map,
        )
    }

    // -- Modes ----------------------------------------------------------------

    /// Steering queue drain mode (default: one-at-a-time).
    #[must_use]
    pub fn get_steering_mode(&self) -> QueueMode {
        parse_queue_mode(self.settings.get("steeringMode")).unwrap_or_default()
    }

    /// Set `steeringMode` (global).
    pub fn set_steering_mode(&mut self, mode: QueueMode) {
        self.set_global_field("steeringMode", queue_mode_value(mode));
    }

    /// Follow-up queue drain mode (default: one-at-a-time).
    #[must_use]
    pub fn get_follow_up_mode(&self) -> QueueMode {
        parse_queue_mode(self.settings.get("followUpMode")).unwrap_or_default()
    }

    /// Set `followUpMode` (global).
    pub fn set_follow_up_mode(&mut self, mode: QueueMode) {
        self.set_global_field("followUpMode", queue_mode_value(mode));
    }

    /// Streaming transport preference (default: auto).
    #[must_use]
    pub fn get_transport(&self) -> Transport {
        parse_transport(self.settings.get("transport")).unwrap_or(Transport::Auto)
    }

    /// Set `transport` (global).
    pub fn set_transport(&mut self, transport: Transport) {
        self.set_global_field("transport", transport_value(transport));
    }

    // -- Theme ----------------------------------------------------------------

    /// Raw `theme` setting when it is a string.
    #[must_use]
    pub fn get_theme_setting(&self) -> Option<String> {
        string_field(&self.settings, "theme")
    }

    /// Theme name; `None` when unset or path-like (contains `/`).
    #[must_use]
    pub fn get_theme(&self) -> Option<String> {
        self.get_theme_setting()
            .filter(|theme| !theme.contains('/'))
    }

    /// Set `theme` (global).
    pub fn set_theme(&mut self, theme: &str) {
        self.set_global_field("theme", Value::String(theme.to_owned()));
    }

    /// `themes` resource paths from merged settings.
    #[must_use]
    pub fn get_theme_paths(&self) -> Vec<String> {
        self.merged_string_array("themes")
    }

    /// Set `themes` resource paths (global).
    pub fn set_theme_paths(&mut self, paths: Vec<String>) {
        self.set_global_field(
            "themes",
            Value::Array(paths.into_iter().map(Value::String).collect()),
        );
    }

    /// Set `themes` resource paths in the project file.
    ///
    /// # Errors
    ///
    /// Returns [`SettingsManagerError::ProjectNotTrusted`] when untrusted.
    pub fn set_project_theme_paths(
        &mut self,
        paths: Vec<String>,
    ) -> Result<(), SettingsManagerError> {
        self.update_project_settings("themes", |settings| {
            settings.insert(
                "themes".to_owned(),
                Value::Array(paths.into_iter().map(Value::String).collect()),
            );
        })
    }

    // -- Compaction / branch summary ------------------------------------------

    /// `compaction.enabled` (default: true).
    #[must_use]
    pub fn get_compaction_enabled(&self) -> bool {
        self.merged_nested_bool("compaction", "enabled")
            .unwrap_or(true)
    }

    /// Set `compaction.enabled` (global, nested merge).
    pub fn set_compaction_enabled(&mut self, enabled: bool) {
        self.set_global_nested_field("compaction", "enabled", Value::Bool(enabled));
    }

    /// `compaction.reserveTokens` (default: 16384).
    #[must_use]
    pub fn get_compaction_reserve_tokens(&self) -> u64 {
        self.merged_nested_u64("compaction", "reserveTokens")
            .unwrap_or(DEFAULT_COMPACTION_RESERVE_TOKENS)
    }

    /// `compaction.keepRecentTokens` (default: 20000).
    #[must_use]
    pub fn get_compaction_keep_recent_tokens(&self) -> u64 {
        self.merged_nested_u64("compaction", "keepRecentTokens")
            .unwrap_or(DEFAULT_COMPACTION_KEEP_RECENT_TOKENS)
    }

    /// Fully-resolved compaction settings.
    #[must_use]
    pub fn get_compaction_settings(&self) -> ResolvedCompactionSettings {
        ResolvedCompactionSettings {
            enabled: self.get_compaction_enabled(),
            reserve_tokens: self.get_compaction_reserve_tokens(),
            keep_recent_tokens: self.get_compaction_keep_recent_tokens(),
        }
    }

    /// Fully-resolved branch-summary settings.
    #[must_use]
    pub fn get_branch_summary_settings(&self) -> ResolvedBranchSummarySettings {
        ResolvedBranchSummarySettings {
            reserve_tokens: self
                .merged_nested_u64("branchSummary", "reserveTokens")
                .unwrap_or(DEFAULT_BRANCH_SUMMARY_RESERVE_TOKENS),
            skip_prompt: self.get_branch_summary_skip_prompt(),
        }
    }

    /// `branchSummary.skipPrompt` (default: false).
    #[must_use]
    pub fn get_branch_summary_skip_prompt(&self) -> bool {
        self.merged_nested_bool("branchSummary", "skipPrompt")
            .unwrap_or(false)
    }

    // -- Retry / HTTP ---------------------------------------------------------

    /// `retry.enabled` (default: true).
    #[must_use]
    pub fn get_retry_enabled(&self) -> bool {
        self.merged_nested_bool("retry", "enabled").unwrap_or(true)
    }

    /// Set `retry.enabled` (global, nested merge).
    pub fn set_retry_enabled(&mut self, enabled: bool) {
        self.set_global_nested_field("retry", "enabled", Value::Bool(enabled));
    }

    /// Fully-resolved automatic retry settings.
    #[must_use]
    pub fn get_retry_settings(&self) -> ResolvedRetrySettings {
        ResolvedRetrySettings {
            enabled: self.get_retry_enabled(),
            max_retries: self
                .merged_nested_u64("retry", "maxRetries")
                .unwrap_or(DEFAULT_RETRY_MAX_RETRIES),
            base_delay_ms: self
                .merged_nested_u64("retry", "baseDelayMs")
                .unwrap_or(DEFAULT_RETRY_BASE_DELAY_MS),
        }
    }

    /// Fully-resolved provider retry settings (`maxRetryDelayMs` default 60000).
    #[must_use]
    pub fn get_provider_retry_settings(&self) -> ResolvedProviderRetrySettings {
        let provider = self
            .settings
            .get("retry")
            .and_then(Value::as_object)
            .and_then(|retry| retry.get("provider").and_then(Value::as_object));
        ResolvedProviderRetrySettings {
            timeout_ms: provider.and_then(|p| number_to_u64(p.get("timeoutMs"))),
            max_retries: provider.and_then(|p| number_to_u64(p.get("maxRetries"))),
            max_retry_delay_ms: provider
                .and_then(|p| number_to_u64(p.get("maxRetryDelayMs")))
                .unwrap_or(DEFAULT_PROVIDER_MAX_RETRY_DELAY_MS),
        }
    }

    /// `httpIdleTimeoutMs` (default: 300000).
    ///
    /// # Errors
    ///
    /// Returns [`SettingsManagerError::InvalidSetting`] when a stored value is
    /// present but not a usable timeout.
    pub fn get_http_idle_timeout_ms(&self) -> Result<u64, SettingsManagerError> {
        Ok(
            parse_timeout_setting(self.settings.get("httpIdleTimeoutMs"), "httpIdleTimeoutMs")?
                .unwrap_or(DEFAULT_HTTP_IDLE_TIMEOUT_MS),
        )
    }

    /// Set `httpIdleTimeoutMs` (global); the value is floored.
    ///
    /// # Errors
    ///
    /// Returns [`SettingsManagerError::InvalidSetting`] when non-finite or negative.
    pub fn set_http_idle_timeout_ms(
        &mut self,
        timeout_ms: f64,
    ) -> Result<(), SettingsManagerError> {
        if !timeout_ms.is_finite() || timeout_ms < 0.0 {
            return Err(SettingsManagerError::InvalidSetting {
                setting: "httpIdleTimeoutMs",
                value: js_number_to_string(timeout_ms),
            });
        }
        self.set_global_field("httpIdleTimeoutMs", json_floored_number(timeout_ms));
        Ok(())
    }

    /// `websocketConnectTimeoutMs`; `None` when unset.
    ///
    /// # Errors
    ///
    /// Returns [`SettingsManagerError::InvalidSetting`] when a stored value is
    /// present but not a usable timeout.
    pub fn get_web_socket_connect_timeout_ms(&self) -> Result<Option<u64>, SettingsManagerError> {
        parse_timeout_setting(
            self.settings.get("websocketConnectTimeoutMs"),
            "websocketConnectTimeoutMs",
        )
    }

    // -- UI flags -------------------------------------------------------------

    /// `hideThinkingBlock` (default: false).
    #[must_use]
    pub fn get_hide_thinking_block(&self) -> bool {
        self.merged_bool("hideThinkingBlock").unwrap_or(false)
    }

    /// `showCacheMissNotices` (default: false).
    #[must_use]
    pub fn get_show_cache_miss_notices(&self) -> bool {
        self.merged_bool("showCacheMissNotices").unwrap_or(false)
    }

    /// External editor command: configured → VISUAL → EDITOR → notepad/nano.
    #[must_use]
    pub fn get_external_editor_command(&self) -> String {
        if let Some(configured) = string_field(&self.settings, "externalEditor")
            && !configured.trim().is_empty()
        {
            return configured;
        }
        if let Some(editor) = env::var("VISUAL").ok().filter(|value| !value.is_empty()) {
            return editor;
        }
        if let Some(editor) = env::var("EDITOR").ok().filter(|value| !value.is_empty()) {
            return editor;
        }
        if cfg!(windows) {
            "notepad".to_owned()
        } else {
            "nano".to_owned()
        }
    }

    /// Set `hideThinkingBlock` (global).
    pub fn set_hide_thinking_block(&mut self, hide: bool) {
        self.set_global_field("hideThinkingBlock", Value::Bool(hide));
    }

    /// Set `showCacheMissNotices` (global).
    pub fn set_show_cache_miss_notices(&mut self, show: bool) {
        self.set_global_field("showCacheMissNotices", Value::Bool(show));
    }

    /// `quietStartup` (default: false).
    #[must_use]
    pub fn get_quiet_startup(&self) -> bool {
        self.merged_bool("quietStartup").unwrap_or(false)
    }

    /// Set `quietStartup` (global).
    pub fn set_quiet_startup(&mut self, quiet: bool) {
        self.set_global_field("quietStartup", Value::Bool(quiet));
    }

    /// `doubleEscapeAction` (default: tree).
    #[must_use]
    pub fn get_double_escape_action(&self) -> DoubleEscapeAction {
        self.settings
            .get("doubleEscapeAction")
            .and_then(Value::as_str)
            .and_then(DoubleEscapeAction::parse)
            .unwrap_or_default()
    }

    /// Set `doubleEscapeAction` (global).
    pub fn set_double_escape_action(&mut self, action: DoubleEscapeAction) {
        self.set_global_field(
            "doubleEscapeAction",
            Value::String(action.as_str().to_owned()),
        );
    }

    /// `treeFilterMode`; an unrecognized stored value yields `default`.
    #[must_use]
    pub fn get_tree_filter_mode(&self) -> TreeFilterMode {
        self.settings
            .get("treeFilterMode")
            .and_then(Value::as_str)
            .and_then(TreeFilterMode::parse)
            .unwrap_or_default()
    }

    /// Set `treeFilterMode` (global).
    pub fn set_tree_filter_mode(&mut self, mode: TreeFilterMode) {
        self.set_global_field("treeFilterMode", Value::String(mode.as_str().to_owned()));
    }

    /// `showHardwareCursor`; falls back to `PI_HARDWARE_CURSOR === "1"`.
    #[must_use]
    pub fn get_show_hardware_cursor(&self) -> bool {
        self.merged_bool("showHardwareCursor")
            .unwrap_or_else(|| env_flag("PI_HARDWARE_CURSOR"))
    }

    /// Set `showHardwareCursor` (global).
    pub fn set_show_hardware_cursor(&mut self, enabled: bool) {
        self.set_global_field("showHardwareCursor", Value::Bool(enabled));
    }

    /// `editorPaddingX` (default: 0; the setter clamps to 0..=3).
    #[must_use]
    pub fn get_editor_padding_x(&self) -> u64 {
        number_to_u64(self.settings.get("editorPaddingX")).unwrap_or(0)
    }

    /// Set `editorPaddingX` (global), clamped to `0..=3` after flooring.
    pub fn set_editor_padding_x(&mut self, padding: f64) {
        self.set_global_field(
            "editorPaddingX",
            js_clamped_floored_number(padding, 0.0, 3.0),
        );
    }

    /// `outputPad`; only an exact numeric `0` yields [`OutputPad::Zero`].
    #[must_use]
    pub fn get_output_pad(&self) -> OutputPad {
        let is_zero = self
            .settings
            .get("outputPad")
            .and_then(Value::as_f64)
            .is_some_and(|value| js_number_eq(value, 0.0));
        if is_zero {
            OutputPad::Zero
        } else {
            OutputPad::One
        }
    }

    /// Set `outputPad` (global).
    pub fn set_output_pad(&mut self, padding: OutputPad) {
        self.set_global_field("outputPad", Value::from(padding.as_u64()));
    }

    /// `autocompleteMaxVisible` (default: 5; the setter clamps to 3..=20).
    #[must_use]
    pub fn get_autocomplete_max_visible(&self) -> u64 {
        number_to_u64(self.settings.get("autocompleteMaxVisible"))
            .unwrap_or(DEFAULT_AUTOCOMPLETE_MAX_VISIBLE)
    }

    /// Set `autocompleteMaxVisible` (global), clamped to `3..=20` after flooring.
    pub fn set_autocomplete_max_visible(&mut self, max_visible: f64) {
        self.set_global_field(
            "autocompleteMaxVisible",
            js_clamped_floored_number(max_visible, 3.0, 20.0),
        );
    }

    // -- Shell / npm ----------------------------------------------------------

    /// `shellPath` with `~` expansion; empty string returned verbatim.
    #[must_use]
    pub fn get_shell_path(&self) -> Option<String> {
        normalize_optional_path(self.settings.get("shellPath"))
    }

    /// Set `shellPath`; `None` removes the key (global).
    pub fn set_shell_path(&mut self, path: Option<String>) {
        self.set_global_optional_field("shellPath", path.map(Value::String));
    }

    /// `shellCommandPrefix` from merged settings.
    #[must_use]
    pub fn get_shell_command_prefix(&self) -> Option<String> {
        string_field(&self.settings, "shellCommandPrefix")
    }

    /// Set `shellCommandPrefix`; `None` removes the key (global).
    pub fn set_shell_command_prefix(&mut self, prefix: Option<String>) {
        self.set_global_optional_field("shellCommandPrefix", prefix.map(Value::String));
    }

    /// `npmCommand` argv from merged settings.
    #[must_use]
    pub fn get_npm_command(&self) -> Option<Vec<String>> {
        string_array(self.settings.get("npmCommand"))
    }

    /// Set `npmCommand`; `None` removes the key (global).
    pub fn set_npm_command(&mut self, command: Option<Vec<String>>) {
        self.set_global_optional_field(
            "npmCommand",
            command.map(|command| Value::Array(command.into_iter().map(Value::String).collect())),
        );
    }

    // -- Trust / telemetry ----------------------------------------------------

    /// `defaultProjectTrust` from the **global** settings only.
    #[must_use]
    pub fn get_default_project_trust(&self) -> DefaultProjectTrust {
        DefaultProjectTrust::parse(
            self.global_settings
                .get("defaultProjectTrust")
                .and_then(Value::as_str),
        )
    }

    /// Set `defaultProjectTrust` (global).
    pub fn set_default_project_trust(&mut self, default_project_trust: DefaultProjectTrust) {
        self.set_global_field(
            "defaultProjectTrust",
            Value::String(default_project_trust.as_str().to_owned()),
        );
    }

    /// `collapseChangelog` (default: false).
    #[must_use]
    pub fn get_collapse_changelog(&self) -> bool {
        self.merged_bool("collapseChangelog").unwrap_or(false)
    }

    /// Set `collapseChangelog` (global).
    pub fn set_collapse_changelog(&mut self, collapse: bool) {
        self.set_global_field("collapseChangelog", Value::Bool(collapse));
    }

    /// `enableInstallTelemetry` (default: true).
    #[must_use]
    pub fn get_enable_install_telemetry(&self) -> bool {
        self.merged_bool("enableInstallTelemetry").unwrap_or(true)
    }

    /// Set `enableInstallTelemetry` (global).
    pub fn set_enable_install_telemetry(&mut self, enabled: bool) {
        self.set_global_field("enableInstallTelemetry", Value::Bool(enabled));
    }

    /// `enableAnalytics` (default: false).
    #[must_use]
    pub fn get_enable_analytics(&self) -> bool {
        self.merged_bool("enableAnalytics").unwrap_or(false)
    }

    /// `trackingId` from merged settings.
    #[must_use]
    pub fn get_tracking_id(&self) -> Option<String> {
        string_field(&self.settings, "trackingId")
    }

    /// Set analytics opt-in; generates a `UUIDv4` tracking id on first opt-in.
    pub fn set_enable_analytics(&mut self, enabled: bool) {
        self.global_settings
            .insert("enableAnalytics".to_owned(), Value::Bool(enabled));
        self.modified_fields.insert("enableAnalytics".to_owned());
        let has_tracking_id = self
            .global_settings
            .get("trackingId")
            .is_some_and(js_truthy);
        if enabled && !has_tracking_id {
            self.global_settings.insert(
                "trackingId".to_owned(),
                Value::String(Uuid::new_v4().to_string()),
            );
            self.modified_fields.insert("trackingId".to_owned());
        }
        self.save();
    }

    // -- Resources ------------------------------------------------------------

    /// `packages` from merged settings.
    #[must_use]
    pub fn get_packages(&self) -> Vec<PackageSource> {
        self.settings
            .get("packages")
            .and_then(Value::as_array)
            .map(|items| items.iter().filter_map(PackageSource::from_value).collect())
            .unwrap_or_default()
    }

    /// Set `packages` (global).
    pub fn set_packages(&mut self, packages: &[PackageSource]) {
        self.set_global_field(
            "packages",
            Value::Array(packages.iter().map(PackageSource::to_value).collect()),
        );
    }

    /// Set `packages` in the project file.
    ///
    /// # Errors
    ///
    /// Returns [`SettingsManagerError::ProjectNotTrusted`] when untrusted.
    pub fn set_project_packages(
        &mut self,
        packages: &[PackageSource],
    ) -> Result<(), SettingsManagerError> {
        self.update_project_settings("packages", |settings| {
            settings.insert(
                "packages".to_owned(),
                Value::Array(packages.iter().map(PackageSource::to_value).collect()),
            );
        })
    }

    /// `extensions` resource paths from merged settings.
    #[must_use]
    pub fn get_extension_paths(&self) -> Vec<String> {
        self.merged_string_array("extensions")
    }

    /// Set `extensions` resource paths (global).
    pub fn set_extension_paths(&mut self, paths: Vec<String>) {
        self.set_global_field(
            "extensions",
            Value::Array(paths.into_iter().map(Value::String).collect()),
        );
    }

    /// Set `extensions` resource paths in the project file.
    ///
    /// # Errors
    ///
    /// Returns [`SettingsManagerError::ProjectNotTrusted`] when untrusted.
    pub fn set_project_extension_paths(
        &mut self,
        paths: Vec<String>,
    ) -> Result<(), SettingsManagerError> {
        self.update_project_settings("extensions", |settings| {
            settings.insert(
                "extensions".to_owned(),
                Value::Array(paths.into_iter().map(Value::String).collect()),
            );
        })
    }

    /// `skills` resource paths from merged settings.
    #[must_use]
    pub fn get_skill_paths(&self) -> Vec<String> {
        self.merged_string_array("skills")
    }

    /// Set `skills` resource paths (global).
    pub fn set_skill_paths(&mut self, paths: Vec<String>) {
        self.set_global_field(
            "skills",
            Value::Array(paths.into_iter().map(Value::String).collect()),
        );
    }

    /// Set `skills` resource paths in the project file.
    ///
    /// # Errors
    ///
    /// Returns [`SettingsManagerError::ProjectNotTrusted`] when untrusted.
    pub fn set_project_skill_paths(
        &mut self,
        paths: Vec<String>,
    ) -> Result<(), SettingsManagerError> {
        self.update_project_settings("skills", |settings| {
            settings.insert(
                "skills".to_owned(),
                Value::Array(paths.into_iter().map(Value::String).collect()),
            );
        })
    }

    /// `prompts` resource paths from merged settings.
    #[must_use]
    pub fn get_prompt_template_paths(&self) -> Vec<String> {
        self.merged_string_array("prompts")
    }

    /// Set `prompts` resource paths (global).
    pub fn set_prompt_template_paths(&mut self, paths: Vec<String>) {
        self.set_global_field(
            "prompts",
            Value::Array(paths.into_iter().map(Value::String).collect()),
        );
    }

    /// Set `prompts` resource paths in the project file.
    ///
    /// # Errors
    ///
    /// Returns [`SettingsManagerError::ProjectNotTrusted`] when untrusted.
    pub fn set_project_prompt_template_paths(
        &mut self,
        paths: Vec<String>,
    ) -> Result<(), SettingsManagerError> {
        self.update_project_settings("prompts", |settings| {
            settings.insert(
                "prompts".to_owned(),
                Value::Array(paths.into_iter().map(Value::String).collect()),
            );
        })
    }

    /// `enableSkillCommands` (default: true).
    #[must_use]
    pub fn get_enable_skill_commands(&self) -> bool {
        self.merged_bool("enableSkillCommands").unwrap_or(true)
    }

    /// Set `enableSkillCommands` (global).
    pub fn set_enable_skill_commands(&mut self, enabled: bool) {
        self.set_global_field("enableSkillCommands", Value::Bool(enabled));
    }

    // -- Terminal / images ----------------------------------------------------

    /// `terminal.showImages` (default: true).
    #[must_use]
    pub fn get_show_images(&self) -> bool {
        self.merged_nested_bool("terminal", "showImages")
            .unwrap_or(true)
    }

    /// Set `terminal.showImages` (global, nested merge).
    pub fn set_show_images(&mut self, show: bool) {
        self.set_global_nested_field("terminal", "showImages", Value::Bool(show));
    }

    /// `terminal.imageWidthCells` (default: 60; floored, min 1).
    #[must_use]
    pub fn get_image_width_cells(&self) -> u64 {
        let value = self
            .settings
            .get("terminal")
            .and_then(Value::as_object)
            .and_then(|terminal| terminal.get("imageWidthCells"));
        let Some(number) = value.and_then(Value::as_f64) else {
            return DEFAULT_IMAGE_WIDTH_CELLS;
        };
        if !number.is_finite() {
            return DEFAULT_IMAGE_WIDTH_CELLS;
        }
        floor_max_to_u64(number, 1)
    }

    /// Set `terminal.imageWidthCells` (global, nested merge); floored, min 1.
    pub fn set_image_width_cells(&mut self, width: f64) {
        self.set_global_nested_field(
            "terminal",
            "imageWidthCells",
            js_min_floored_number(width, 1.0),
        );
    }

    /// `terminal.clearOnShrink`; falls back to `PI_CLEAR_ON_SHRINK === "1"`.
    #[must_use]
    pub fn get_clear_on_shrink(&self) -> bool {
        self.merged_nested_bool("terminal", "clearOnShrink")
            .unwrap_or_else(|| env_flag("PI_CLEAR_ON_SHRINK"))
    }

    /// Set `terminal.clearOnShrink` (global, nested merge).
    pub fn set_clear_on_shrink(&mut self, enabled: bool) {
        self.set_global_nested_field("terminal", "clearOnShrink", Value::Bool(enabled));
    }

    /// `terminal.showTerminalProgress` (default: false).
    #[must_use]
    pub fn get_show_terminal_progress(&self) -> bool {
        self.merged_nested_bool("terminal", "showTerminalProgress")
            .unwrap_or(false)
    }

    /// Set `terminal.showTerminalProgress` (global, nested merge).
    pub fn set_show_terminal_progress(&mut self, enabled: bool) {
        self.set_global_nested_field("terminal", "showTerminalProgress", Value::Bool(enabled));
    }

    /// `images.autoResize` (default: true).
    #[must_use]
    pub fn get_image_auto_resize(&self) -> bool {
        self.merged_nested_bool("images", "autoResize")
            .unwrap_or(true)
    }

    /// Set `images.autoResize` (global, nested merge).
    pub fn set_image_auto_resize(&mut self, enabled: bool) {
        self.set_global_nested_field("images", "autoResize", Value::Bool(enabled));
    }

    /// `images.blockImages` (default: false).
    #[must_use]
    pub fn get_block_images(&self) -> bool {
        self.merged_nested_bool("images", "blockImages")
            .unwrap_or(false)
    }

    /// Set `images.blockImages` (global, nested merge).
    pub fn set_block_images(&mut self, blocked: bool) {
        self.set_global_nested_field("images", "blockImages", Value::Bool(blocked));
    }

    // -- Markdown / warnings --------------------------------------------------

    /// `markdown.codeBlockIndent` (default: two spaces).
    #[must_use]
    pub fn get_code_block_indent(&self) -> String {
        self.settings
            .get("markdown")
            .and_then(Value::as_object)
            .and_then(|markdown| markdown.get("codeBlockIndent"))
            .and_then(Value::as_str)
            .map_or_else(|| DEFAULT_CODE_BLOCK_INDENT.to_owned(), str::to_owned)
    }

    /// `warnings` object (empty when absent).
    #[must_use]
    pub fn get_warnings(&self) -> WarningSettings {
        nested_field(&self.settings, "warnings", WarningSettings::from_map).unwrap_or_default()
    }

    /// Set `warnings` (global, full overlay).
    pub fn set_warnings(&mut self, warnings: &WarningSettings) {
        self.set_global_field("warnings", Value::Object(warnings.to_map()));
    }
}

// ---------------------------------------------------------------------------
// Helpers: parse, merge, migrate, wire conversions
// ---------------------------------------------------------------------------

fn path_to_string(path: &Path) -> String {
    path.to_string_lossy().into_owned()
}

fn env_flag(name: &str) -> bool {
    env::var(name).is_ok_and(|value| value == "1")
}

fn string_field(map: &Map<String, Value>, key: &str) -> Option<String> {
    map.get(key).and_then(Value::as_str).map(str::to_owned)
}

fn bool_field(map: &Map<String, Value>, key: &str) -> Option<bool> {
    map.get(key).and_then(Value::as_bool)
}

fn nested_field<T>(
    map: &Map<String, Value>,
    key: &str,
    from: impl FnOnce(&Map<String, Value>) -> T,
) -> Option<T> {
    map.get(key).and_then(Value::as_object).map(from)
}

fn string_array(value: Option<&Value>) -> Option<Vec<String>> {
    value.and_then(Value::as_array).map(|items| {
        items
            .iter()
            .filter_map(|item| item.as_str().map(str::to_owned))
            .collect()
    })
}

fn unknown_fields(map: &Map<String, Value>, known: &[&str]) -> Map<String, Value> {
    map.iter()
        .filter(|(key, _)| !known.contains(&key.as_str()))
        .map(|(key, value)| (key.clone(), value.clone()))
        .collect()
}

fn insert_opt_value(map: &mut Map<String, Value>, key: &str, value: Option<Value>) {
    if let Some(value) = value {
        map.insert(key.to_owned(), value);
    }
}

fn insert_opt_string(map: &mut Map<String, Value>, key: &str, value: Option<&str>) {
    insert_opt_value(map, key, value.map(|text| Value::String(text.to_owned())));
}

fn insert_opt_bool(map: &mut Map<String, Value>, key: &str, value: Option<bool>) {
    insert_opt_value(map, key, value.map(Value::Bool));
}

fn insert_opt_u64(map: &mut Map<String, Value>, key: &str, value: Option<u64>) {
    insert_opt_value(map, key, value.map(Value::from));
}

fn insert_opt_strings(map: &mut Map<String, Value>, key: &str, values: Option<&[String]>) {
    insert_opt_value(
        map,
        key,
        values.map(|values| Value::Array(values.iter().cloned().map(Value::String).collect())),
    );
}

fn number_to_u64(value: Option<&Value>) -> Option<u64> {
    let value = value?;
    if let Some(unsigned) = value.as_u64() {
        return Some(unsigned);
    }
    let number = value.as_f64()?;
    finite_floor_to_u64(number)
}

fn js_number_eq(lhs: f64, rhs: f64) -> bool {
    lhs.partial_cmp(&rhs) == Some(std::cmp::Ordering::Equal)
}

fn js_truthy(value: &Value) -> bool {
    match value {
        Value::Null => false,
        Value::Bool(flag) => *flag,
        Value::Number(number) => number.as_f64().is_some_and(|n| !js_number_eq(n, 0.0)),
        Value::String(text) => !text.is_empty(),
        Value::Array(_) | Value::Object(_) => true,
    }
}

fn js_number_to_string(value: f64) -> String {
    if value.is_nan() {
        return "NaN".to_owned();
    }
    if value.is_infinite() {
        return if value.is_sign_positive() {
            "Infinity".to_owned()
        } else {
            "-Infinity".to_owned()
        };
    }
    if js_number_eq(value, 0.0) {
        return "0".to_owned();
    }
    format!("{value}")
}

fn js_value_to_string(value: &Value) -> String {
    match value {
        Value::Null => "null".to_owned(),
        Value::Bool(flag) => flag.to_string(),
        Value::Number(number) => {
            if let Some(signed) = number.as_i64() {
                signed.to_string()
            } else if let Some(unsigned) = number.as_u64() {
                unsigned.to_string()
            } else {
                number
                    .as_f64()
                    .map_or_else(|| "0".to_owned(), js_number_to_string)
            }
        }
        Value::String(text) => text.clone(),
        Value::Array(items) => items
            .iter()
            .map(|item| match item {
                Value::Null => String::new(),
                other => js_value_to_string(other),
            })
            .collect::<Vec<_>>()
            .join(","),
        Value::Object(_) => "[object Object]".to_owned(),
    }
}

/// Floor `value` and encode as a JSON number without float→int casts.
///
/// Non-finite inputs become JSON `null` (matching `JSON.stringify(NaN|±Infinity)`).
fn json_floored_number(value: f64) -> Value {
    let floored = value.floor();
    if !floored.is_finite() {
        return Value::Null;
    }
    if floored >= 0.0 {
        match finite_floor_to_u64(floored) {
            Some(unsigned) => Value::from(unsigned),
            None => Value::Null,
        }
    } else {
        match finite_floor_to_i64(floored) {
            Some(signed) => Value::from(signed),
            None => Value::Null,
        }
    }
}

fn js_clamped_floored_number(value: f64, min: f64, max: f64) -> Value {
    let floored = value.floor();
    if floored.is_nan() {
        return Value::Null;
    }
    // NaN already filtered; clamp is safe.
    let clamped = floored.clamp(min, max);
    json_floored_number(clamped)
}

fn js_min_floored_number(value: f64, min: f64) -> Value {
    let floored = value.floor();
    if floored.is_nan() {
        return Value::Null;
    }
    if !floored.is_finite() {
        // +Inf → stringify null; -Inf → min
        return if floored.is_sign_positive() {
            Value::Null
        } else {
            json_floored_number(min)
        };
    }
    json_floored_number(floored.max(min))
}

fn floor_max_to_u64(value: f64, min: u64) -> u64 {
    let Ok(min_f) = min.to_string().parse::<f64>() else {
        return min;
    };
    let floored = value.floor().max(min_f);
    match finite_floor_to_u64(floored) {
        Some(result) => result,
        None => min,
    }
}

fn parse_timeout_ms(value: &Value) -> Option<u64> {
    match value {
        Value::String(text) => {
            let trimmed = text.trim();
            if trimmed.eq_ignore_ascii_case("disabled") {
                return Some(0);
            }
            if trimmed.is_empty() {
                return None;
            }
            js_number_from_string(trimmed).and_then(finite_floor_to_u64)
        }
        Value::Number(number) => number.as_f64().and_then(finite_floor_to_u64),
        _ => None,
    }
}

fn parse_timeout_setting(
    value: Option<&Value>,
    setting: &'static str,
) -> Result<Option<u64>, SettingsManagerError> {
    match value {
        None => Ok(None),
        Some(value) => match parse_timeout_ms(value) {
            Some(ms) => Ok(Some(ms)),
            None => Err(SettingsManagerError::InvalidSetting {
                setting,
                value: js_value_to_string(value),
            }),
        },
    }
}

/// Floor a non-negative finite `f64` to `u64` via decimal text (no float cast).
fn finite_floor_to_u64(value: f64) -> Option<u64> {
    if !value.is_finite() || value < 0.0 {
        return None;
    }
    let floored = value.floor();
    if floored >= U64_MAX_F64 {
        return Some(u64::MAX);
    }
    // Integer-valued f64 in the safe range formats as a plain digit string.
    let text = format!("{floored:.0}");
    text.parse::<u64>().ok()
}

/// Floor a non-positive finite `f64` to `i64` via decimal text (no float cast).
fn finite_floor_to_i64(value: f64) -> Option<i64> {
    if !value.is_finite() {
        return None;
    }
    let floored = value.floor();
    // i64::MIN is exactly -2^63, representable in f64.
    if floored < I64_MIN_F64 {
        return Some(i64::MIN);
    }
    if floored > 0.0 {
        // Positive values use the u64 path elsewhere; keep signed path defensive.
        let text = format!("{floored:.0}");
        return text.parse::<i64>().ok();
    }
    let text = format!("{floored:.0}");
    text.parse::<i64>().ok()
}

fn js_number_from_string(text: &str) -> Option<f64> {
    if text.is_empty() {
        return Some(0.0);
    }
    let (negative, rest) = match text.strip_prefix('-') {
        Some(rest) => (true, rest),
        None => (false, text.strip_prefix('+').unwrap_or(text)),
    };
    let magnitude = if rest == "Infinity" {
        Some(f64::INFINITY)
    } else if let Some(digits) = rest.strip_prefix("0x").or_else(|| rest.strip_prefix("0X")) {
        parse_radix(digits, 16)
    } else if let Some(digits) = rest.strip_prefix("0o").or_else(|| rest.strip_prefix("0O")) {
        parse_radix(digits, 8)
    } else if let Some(digits) = rest.strip_prefix("0b").or_else(|| rest.strip_prefix("0B")) {
        parse_radix(digits, 2)
    } else if is_js_decimal(rest) {
        rest.parse::<f64>().ok()
    } else {
        None
    }?;
    Some(if negative { -magnitude } else { magnitude })
}

/// Parse a radix integer string into `f64` using only `From<u32>` (no casts).
fn parse_radix(digits: &str, radix: u32) -> Option<f64> {
    if digits.is_empty() {
        return None;
    }
    let mut value = 0.0_f64;
    let radix_f = f64::from(radix);
    for ch in digits.chars() {
        let digit = ch.to_digit(radix)?;
        value = value.mul_add(radix_f, f64::from(digit));
    }
    Some(value)
}

fn is_js_decimal(text: &str) -> bool {
    let (mantissa, exponent) = match text.find(['e', 'E']) {
        Some(index) => (&text[..index], Some(&text[index + 1..])),
        None => (text, None),
    };
    if let Some(exp) = exponent {
        let exp_digits = exp.strip_prefix(['+', '-']).unwrap_or(exp);
        if exp_digits.is_empty() || !exp_digits.bytes().all(|b| b.is_ascii_digit()) {
            return false;
        }
    }
    let mut seen_digit = false;
    let mut seen_dot = false;
    for ch in mantissa.chars() {
        if ch == '.' {
            if seen_dot {
                return false;
            }
            seen_dot = true;
        } else if ch.is_ascii_digit() {
            seen_digit = true;
        } else {
            return false;
        }
    }
    seen_digit
}

fn parse_thinking_level(value: Option<&Value>) -> Option<ModelThinkingLevel> {
    match value?.as_str()? {
        "off" => Some(ModelThinkingLevel::Off),
        "minimal" => Some(ModelThinkingLevel::Minimal),
        "low" => Some(ModelThinkingLevel::Low),
        "medium" => Some(ModelThinkingLevel::Medium),
        "high" => Some(ModelThinkingLevel::High),
        "xhigh" => Some(ModelThinkingLevel::Xhigh),
        "max" => Some(ModelThinkingLevel::Max),
        _ => None,
    }
}

fn thinking_level_value(level: ModelThinkingLevel) -> Value {
    Value::String(
        match level {
            ModelThinkingLevel::Off => "off",
            ModelThinkingLevel::Minimal => "minimal",
            ModelThinkingLevel::Low => "low",
            ModelThinkingLevel::Medium => "medium",
            ModelThinkingLevel::High => "high",
            ModelThinkingLevel::Xhigh => "xhigh",
            ModelThinkingLevel::Max => "max",
        }
        .to_owned(),
    )
}

fn parse_transport(value: Option<&Value>) -> Option<Transport> {
    match value?.as_str()? {
        "sse" => Some(Transport::Sse),
        "websocket" => Some(Transport::Websocket),
        "websocket-cached" => Some(Transport::WebsocketCached),
        "auto" => Some(Transport::Auto),
        _ => None,
    }
}

fn transport_value(transport: Transport) -> Value {
    Value::String(
        match transport {
            Transport::Sse => "sse",
            Transport::Websocket => "websocket",
            Transport::WebsocketCached => "websocket-cached",
            Transport::Auto => "auto",
        }
        .to_owned(),
    )
}

fn parse_queue_mode(value: Option<&Value>) -> Option<QueueMode> {
    match value?.as_str()? {
        "all" => Some(QueueMode::All),
        "one-at-a-time" => Some(QueueMode::OneAtATime),
        _ => None,
    }
}

fn queue_mode_value(mode: QueueMode) -> Value {
    Value::String(
        match mode {
            QueueMode::All => "all",
            QueueMode::OneAtATime => "one-at-a-time",
        }
        .to_owned(),
    )
}

fn parse_default_project_trust(value: Option<&Value>) -> Option<DefaultProjectTrust> {
    match value?.as_str()? {
        "ask" => Some(DefaultProjectTrust::Ask),
        "always" => Some(DefaultProjectTrust::Always),
        "never" => Some(DefaultProjectTrust::Never),
        _ => None,
    }
}

fn parse_output_pad(value: Option<&Value>) -> Option<OutputPad> {
    let number = value?.as_f64()?;
    if js_number_eq(number, 0.0) {
        Some(OutputPad::Zero)
    } else if js_number_eq(number, 1.0) {
        Some(OutputPad::One)
    } else {
        None
    }
}

fn normalize_optional_path(value: Option<&Value>) -> Option<String> {
    let raw = value?.as_str()?;
    if raw.is_empty() {
        return Some(raw.to_owned());
    }
    Some(path_to_string(&expand_tilde_path(raw)))
}

fn parse_settings_text(text: &str) -> Result<Map<String, Value>, String> {
    let value: Value = serde_json::from_str(text).map_err(|error| error.to_string())?;
    match value {
        Value::Object(mut map) => {
            migrate_settings(&mut map);
            Ok(map)
        }
        Value::Array(items) => {
            // TS spreads a top-level array at each use site; we spread at load.
            Ok(spread_array(&items))
        }
        other => Err(format!(
            "Cannot use 'in' operator to search for 'queueMode' in {}",
            js_value_to_string(&other)
        )),
    }
}

fn spread_array(items: &[Value]) -> Map<String, Value> {
    items
        .iter()
        .enumerate()
        .map(|(index, value)| (index.to_string(), value.clone()))
        .collect()
}

/// One-level object merge with array replacement (ports `deepMergeSettings`).
fn deep_merge_settings(
    base: &Map<String, Value>,
    overrides: &Map<String, Value>,
) -> Map<String, Value> {
    let mut result = base.clone();
    for (key, override_value) in overrides {
        let merged_value = match (base.get(key), override_value) {
            (Some(Value::Object(base_object)), Value::Object(override_object)) => {
                let mut merged = base_object.clone();
                for (nested_key, nested_value) in override_object {
                    merged.insert(nested_key.clone(), nested_value.clone());
                }
                Value::Object(merged)
            }
            _ => override_value.clone(),
        };
        result.insert(key.clone(), merged_value);
    }
    result
}

/// Migrate legacy settings keys in the exact TypeScript order.
fn migrate_settings(settings: &mut Map<String, Value>) {
    // 1. queueMode → steeringMode (only when steeringMode absent).
    if settings.contains_key("queueMode")
        && !settings.contains_key("steeringMode")
        && let Some(value) = settings.remove("queueMode")
    {
        settings.insert("steeringMode".to_owned(), value);
    }

    // 2. websockets boolean → transport (only when transport absent).
    if !settings.contains_key("transport")
        && let Some(Value::Bool(websockets)) = settings.get("websockets").cloned()
    {
        settings.remove("websockets");
        settings.insert(
            "transport".to_owned(),
            Value::String(if websockets {
                "websocket".to_owned()
            } else {
                "sse".to_owned()
            }),
        );
    }

    // 3. skills object → enableSkillCommands hoist + customDirectories array.
    if let Some(Value::Object(skills_object)) = settings.get("skills").cloned() {
        if let Some(enable) = skills_object.get("enableSkillCommands")
            && !settings.contains_key("enableSkillCommands")
        {
            settings.insert("enableSkillCommands".to_owned(), enable.clone());
        }
        match skills_object.get("customDirectories") {
            Some(Value::Array(dirs)) if !dirs.is_empty() => {
                settings.insert("skills".to_owned(), Value::Array(dirs.clone()));
            }
            _ => {
                settings.remove("skills");
            }
        }
    }

    // 4. retry.maxDelayMs → retry.provider.maxRetryDelayMs.
    if let Some(Value::Object(retry_object)) = settings.get("retry").cloned() {
        let mut retry_object = retry_object;
        let max_delay = retry_object
            .get("maxDelayMs")
            .filter(|value| value.is_number())
            .cloned();
        if let Some(max_delay_value) = max_delay {
            let provider_object_like: Option<Map<String, Value>> =
                match retry_object.get("provider") {
                    Some(Value::Object(map)) => Some(map.clone()),
                    Some(Value::Array(items)) => Some(spread_array(items)),
                    _ => None,
                };
            let current_max = provider_object_like
                .as_ref()
                .and_then(|provider| provider.get("maxRetryDelayMs"));
            let needs_migration = matches!(
                (provider_object_like.is_some(), current_max),
                (false, _) | (true, None | Some(Value::Null))
            );
            if needs_migration {
                let mut provider = provider_object_like.unwrap_or_default();
                provider.insert("maxRetryDelayMs".to_owned(), max_delay_value);
                retry_object.insert("provider".to_owned(), Value::Object(provider));
            }
        }
        retry_object.remove("maxDelayMs");
        settings.insert("retry".to_owned(), Value::Object(retry_object));
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;
    use std::time::{SystemTime, UNIX_EPOCH};

    type TestResult = Result<(), String>;

    fn unique_temp_dir(label: &str) -> Result<PathBuf, String> {
        let nanos = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .map_err(|error| error.to_string())?
            .as_nanos();
        let dir = env::temp_dir().join(format!("pi-settings-{label}-{nanos}"));
        fs::create_dir_all(&dir).map_err(|error| error.to_string())?;
        Ok(dir)
    }

    fn write_settings_file(path: &Path, contents: &str) -> Result<(), String> {
        if let Some(parent) = path.parent() {
            fs::create_dir_all(parent).map_err(|error| error.to_string())?;
        }
        fs::write(path, contents).map_err(|error| error.to_string())
    }

    fn read_text(path: &Path) -> Result<String, String> {
        fs::read_to_string(path).map_err(|error| error.to_string())
    }

    fn parse_file(path: &Path) -> Result<Value, String> {
        let text = read_text(path)?;
        serde_json::from_str(&text).map_err(|error| error.to_string())
    }

    fn make_dirs(label: &str) -> Result<(PathBuf, PathBuf, PathBuf), String> {
        let root = unique_temp_dir(label)?;
        let agent = root.join("agent");
        let project = root.join("project");
        fs::create_dir_all(&agent).map_err(|error| error.to_string())?;
        fs::create_dir_all(&project).map_err(|error| error.to_string())?;
        Ok((root, agent, project))
    }

    fn create_manager(project: &Path, agent: &Path, trusted: bool) -> SettingsManager {
        SettingsManager::create(
            project,
            Some(agent),
            SettingsManagerCreateOptions::default().project_trusted(trusted),
        )
    }

    #[test]
    fn defaults_on_empty_settings() -> TestResult {
        let manager = SettingsManager::in_memory(
            &Settings::default(),
            SettingsManagerCreateOptions::default(),
        );
        assert_eq!(manager.get_transport(), Transport::Auto);
        assert_eq!(manager.get_steering_mode(), QueueMode::OneAtATime);
        assert_eq!(manager.get_follow_up_mode(), QueueMode::OneAtATime);
        assert!(manager.get_compaction_enabled());
        assert_eq!(manager.get_compaction_reserve_tokens(), 16384);
        assert_eq!(manager.get_compaction_keep_recent_tokens(), 20000);
        let branch = manager.get_branch_summary_settings();
        assert_eq!(branch.reserve_tokens, 16384);
        assert!(!branch.skip_prompt);
        let retry = manager.get_retry_settings();
        assert!(retry.enabled);
        assert_eq!(retry.max_retries, 3);
        assert_eq!(retry.base_delay_ms, 2000);
        assert_eq!(
            manager.get_provider_retry_settings().max_retry_delay_ms,
            60000
        );
        let idle = manager
            .get_http_idle_timeout_ms()
            .map_err(|error| error.to_string())?;
        assert_eq!(idle, 300_000);
        assert_eq!(manager.get_image_width_cells(), 60);
        assert_eq!(manager.get_editor_padding_x(), 0);
        assert_eq!(manager.get_output_pad(), OutputPad::One);
        assert_eq!(manager.get_autocomplete_max_visible(), 5);
        assert_eq!(manager.get_code_block_indent(), "  ");
        assert_eq!(manager.get_tree_filter_mode(), TreeFilterMode::Default);
        assert_eq!(manager.get_double_escape_action(), DoubleEscapeAction::Tree);
        assert!(manager.get_enable_install_telemetry());
        assert!(!manager.get_enable_analytics());
        assert!(manager.get_enable_skill_commands());
        assert!(manager.get_show_images());
        assert!(manager.get_image_auto_resize());
        assert!(!manager.get_block_images());
        assert!(!manager.get_show_terminal_progress());
        assert!(!manager.get_quiet_startup());
        assert!(!manager.get_hide_thinking_block());
        assert!(!manager.get_show_cache_miss_notices());
        assert!(!manager.get_collapse_changelog());
        assert_eq!(
            manager.get_default_project_trust(),
            DefaultProjectTrust::Ask
        );
        assert!(manager.get_theme().is_none());
        if env::var_os("PI_CLEAR_ON_SHRINK").is_none() {
            assert!(!manager.get_clear_on_shrink());
        }
        if env::var_os("PI_HARDWARE_CURSOR").is_none() {
            assert!(!manager.get_show_hardware_cursor());
        }
        if env::var_os("VISUAL").is_none() && env::var_os("EDITOR").is_none() {
            assert_eq!(
                manager.get_external_editor_command(),
                if cfg!(windows) { "notepad" } else { "nano" }
            );
        }
        Ok(())
    }

    #[test]
    fn hardware_cursor_setting_precedes_environment_fallback() {
        let mut manager = SettingsManager::in_memory(
            &Settings::default(),
            SettingsManagerCreateOptions::default(),
        );
        assert_eq!(
            manager.get_show_hardware_cursor(),
            env::var("PI_HARDWARE_CURSOR").is_ok_and(|value| value == "1")
        );

        manager.set_show_hardware_cursor(false);
        assert!(!manager.get_show_hardware_cursor());
        manager.set_show_hardware_cursor(true);
        assert!(manager.get_show_hardware_cursor());
    }

    #[test]
    fn clamps_and_floor_behaviors() -> TestResult {
        let mut manager = SettingsManager::in_memory(
            &Settings::default(),
            SettingsManagerCreateOptions::default(),
        );
        manager.set_editor_padding_x(9.7);
        assert_eq!(manager.get_editor_padding_x(), 3);
        manager.set_editor_padding_x(-2.3);
        assert_eq!(manager.get_editor_padding_x(), 0);
        manager.set_autocomplete_max_visible(100.0);
        assert_eq!(manager.get_autocomplete_max_visible(), 20);
        manager.set_autocomplete_max_visible(2.0);
        assert_eq!(manager.get_autocomplete_max_visible(), 3);
        manager.set_autocomplete_max_visible(7.9);
        assert_eq!(manager.get_autocomplete_max_visible(), 7);
        manager.set_image_width_cells(0.2);
        assert_eq!(manager.get_image_width_cells(), 1);
        manager.set_image_width_cells(80.9);
        assert_eq!(manager.get_image_width_cells(), 80);
        manager
            .set_http_idle_timeout_ms(1500.7)
            .map_err(|error| error.to_string())?;
        let idle = manager
            .get_http_idle_timeout_ms()
            .map_err(|error| error.to_string())?;
        assert_eq!(idle, 1500);
        let error = match manager.set_http_idle_timeout_ms(-1.0) {
            Ok(()) => return Err("expected negative rejection".into()),
            Err(error) => error,
        };
        assert_eq!(error.to_string(), "Invalid httpIdleTimeoutMs setting: -1");
        let error = match manager.set_http_idle_timeout_ms(f64::NAN) {
            Ok(()) => return Err("expected nan rejection".into()),
            Err(error) => error,
        };
        assert_eq!(error.to_string(), "Invalid httpIdleTimeoutMs setting: NaN");
        let error = match manager.set_http_idle_timeout_ms(f64::INFINITY) {
            Ok(()) => return Err("expected inf rejection".into()),
            Err(error) => error,
        };
        assert_eq!(
            error.to_string(),
            "Invalid httpIdleTimeoutMs setting: Infinity"
        );
        Ok(())
    }

    #[test]
    fn http_timeout_parsing_and_exact_errors() -> TestResult {
        let (_root, agent, project) = make_dirs("timeout-parse")?;
        write_settings_file(
            &agent.join("settings.json"),
            r#"{
  "httpIdleTimeoutMs": "disabled",
  "websocketConnectTimeoutMs": "5000"
}"#,
        )?;
        let manager = create_manager(&project, &agent, true);
        assert_eq!(
            manager
                .get_http_idle_timeout_ms()
                .map_err(|e| e.to_string())?,
            0
        );
        assert_eq!(
            manager
                .get_web_socket_connect_timeout_ms()
                .map_err(|e| e.to_string())?,
            Some(5000)
        );

        write_settings_file(
            &agent.join("settings.json"),
            r#"{ "websocketConnectTimeoutMs": "abc" }"#,
        )?;
        let manager = create_manager(&project, &agent, true);
        let Err(error) = manager.get_web_socket_connect_timeout_ms() else {
            return Err("expected invalid stored timeout".into());
        };
        assert_eq!(
            error.to_string(),
            "Invalid websocketConnectTimeoutMs setting: abc"
        );
        Ok(())
    }

    #[test]
    fn migrations_exact_order_and_conditions() -> TestResult {
        let (_root, agent, project) = make_dirs("migrations")?;
        write_settings_file(
            &agent.join("settings.json"),
            r#"{
  "queueMode": "all",
  "websockets": false,
  "skills": {
    "enableSkillCommands": false,
    "customDirectories": ["/x"]
  },
  "retry": {
    "maxDelayMs": 7000
  }
}"#,
        )?;
        let mut manager = create_manager(&project, &agent, true);
        assert_eq!(manager.get_steering_mode(), QueueMode::All);
        assert_eq!(manager.get_transport(), Transport::Sse);
        assert_eq!(manager.get_skill_paths(), vec!["/x".to_owned()]);
        assert!(!manager.get_enable_skill_commands());
        assert_eq!(
            manager.get_provider_retry_settings().max_retry_delay_ms,
            7000
        );
        manager.set_quiet_startup(true);
        let value = parse_file(&agent.join("settings.json"))?;
        assert_eq!(value["steeringMode"], "all");
        assert!(value.get("queueMode").is_none());
        assert_eq!(value["transport"], "sse");
        assert!(value.get("websockets").is_none());
        assert_eq!(
            value["skills"],
            Value::Array(vec![Value::String("/x".into())])
        );
        assert_eq!(value["enableSkillCommands"], false);
        assert_eq!(value["retry"]["provider"]["maxRetryDelayMs"], 7000);
        assert!(value["retry"].get("maxDelayMs").is_none());
        assert_eq!(value["quietStartup"], true);

        // Both present: queueMode kept; websockets kept.
        write_settings_file(
            &agent.join("settings.json"),
            r#"{
  "queueMode": "all",
  "steeringMode": "one-at-a-time",
  "websockets": true,
  "transport": "sse",
  "skills": { "customDirectories": [] },
  "enableSkillCommands": true,
  "retry": { "maxDelayMs": 5000, "provider": { "maxRetryDelayMs": 1000 } }
}"#,
        )?;
        let mut manager = create_manager(&project, &agent, true);
        assert_eq!(manager.get_steering_mode(), QueueMode::OneAtATime);
        assert_eq!(manager.get_transport(), Transport::Sse);
        assert!(manager.get_skill_paths().is_empty());
        assert!(manager.get_enable_skill_commands());
        assert_eq!(
            manager.get_provider_retry_settings().max_retry_delay_ms,
            1000
        );
        manager.set_theme("dark");
        let value = parse_file(&agent.join("settings.json"))?;
        assert_eq!(value["queueMode"], "all");
        assert_eq!(value["websockets"], true);
        assert!(value.get("skills").is_none());
        assert!(value["retry"].get("maxDelayMs").is_none());
        assert_eq!(value["retry"]["provider"]["maxRetryDelayMs"], 1000);

        // null maxRetryDelayMs migrates; empty customDirectories deletes skills.
        write_settings_file(
            &agent.join("settings.json"),
            r#"{
  "retry": { "maxDelayMs": 5000, "provider": { "maxRetryDelayMs": null } }
}"#,
        )?;
        let manager = create_manager(&project, &agent, true);
        assert_eq!(
            manager.get_provider_retry_settings().max_retry_delay_ms,
            5000
        );
        Ok(())
    }

    #[test]
    fn unknown_keys_roundtrip_top_and_nested() -> TestResult {
        let (_root, agent, project) = make_dirs("unknown")?;
        write_settings_file(
            &agent.join("settings.json"),
            r#"{
  "futureThing": { "a": 1 },
  "compaction": { "enabled": false, "futureNested": [1, 2] },
  "theme": "dark"
}"#,
        )?;
        let mut manager = create_manager(&project, &agent, true);
        let view = manager.get_global_settings();
        assert!(view.extra.contains_key("futureThing"));
        assert_eq!(
            view.compaction
                .as_ref()
                .and_then(|c| c.extra.get("futureNested")),
            Some(&Value::Array(vec![Value::from(1), Value::from(2)]))
        );
        manager.set_quiet_startup(true);
        let value = parse_file(&agent.join("settings.json"))?;
        assert_eq!(value["futureThing"]["a"], 1);
        assert_eq!(value["compaction"]["enabled"], false);
        assert_eq!(
            value["compaction"]["futureNested"],
            Value::Array(vec![Value::from(1), Value::from(2)])
        );
        assert_eq!(value["theme"], "dark");
        assert_eq!(value["quietStartup"], true);
        Ok(())
    }

    #[test]
    fn arrays_replace_and_nested_objects_merge_one_level() -> TestResult {
        let (_root, agent, project) = make_dirs("arrays")?;
        write_settings_file(
            &agent.join("settings.json"),
            r#"{
  "extensions": ["g1", "g2"],
  "retry": { "enabled": false, "provider": { "timeoutMs": 5 } },
  "terminal": { "showImages": false, "imageWidthCells": 80 }
}"#,
        )?;
        write_settings_file(
            &project.join(".pi").join("settings.json"),
            r#"{
  "extensions": ["p1"],
  "retry": { "provider": { "maxRetries": 2 } },
  "terminal": { "showImages": true }
}"#,
        )?;
        let manager = create_manager(&project, &agent, true);
        assert_eq!(manager.get_extension_paths(), vec!["p1".to_owned()]);
        assert!(!manager.get_retry_enabled());
        let provider = manager.get_provider_retry_settings();
        assert_eq!(provider.max_retries, Some(2));
        assert_eq!(provider.timeout_ms, None);
        assert!(manager.get_show_images());
        assert_eq!(manager.get_image_width_cells(), 80);
        Ok(())
    }

    #[test]
    fn parse_error_refuses_save_without_clobber() -> TestResult {
        let (_root, agent, project) = make_dirs("parse-error")?;
        let bad = "{ not json";
        write_settings_file(&agent.join("settings.json"), bad)?;
        let mut manager = create_manager(&project, &agent, true);
        let errors = manager.drain_errors();
        assert_eq!(errors.len(), 1);
        assert_eq!(errors[0].scope, SettingsScope::Global);
        manager.set_theme("dark");
        // In-memory view updates, but file is not clobbered.
        assert_eq!(manager.get_theme().as_deref(), Some("dark"));
        assert_eq!(read_text(&agent.join("settings.json"))?, bad);

        // Recovery: rewrite valid file and reload.
        write_settings_file(&agent.join("settings.json"), r#"{ "theme": "light" }"#)?;
        manager.reload();
        assert!(manager.drain_errors().is_empty());
        assert_eq!(manager.get_theme().as_deref(), Some("light"));
        manager.set_quiet_startup(true);
        let value = parse_file(&agent.join("settings.json"))?;
        assert_eq!(value["theme"], "light");
        assert_eq!(value["quietStartup"], true);
        Ok(())
    }

    #[test]
    fn concurrent_external_changes_are_merged() -> TestResult {
        let (_root, agent, project) = make_dirs("external")?;
        write_settings_file(
            &agent.join("settings.json"),
            r#"{
  "theme": "dark",
  "customUnknown": 1,
  "compaction": {
    "enabled": false,
    "reserveTokens": 999,
    "futureNested": "keep"
  }
}"#,
        )?;
        let mut manager = create_manager(&project, &agent, true);

        // External process rewrite after load.
        write_settings_file(
            &agent.join("settings.json"),
            r#"{
  "theme": "light",
  "customUnknown": 1,
  "externalNew": true,
  "compaction": {
    "enabled": false,
    "reserveTokens": 12345,
    "futureNested": "keep"
  }
}"#,
        )?;
        manager.set_default_model("gpt-5");
        manager.set_compaction_enabled(true);
        let value = parse_file(&agent.join("settings.json"))?;
        assert_eq!(value["theme"], "light");
        assert_eq!(value["externalNew"], true);
        assert_eq!(value["customUnknown"], 1);
        assert_eq!(value["defaultModel"], "gpt-5");
        assert_eq!(value["compaction"]["enabled"], true);
        assert_eq!(value["compaction"]["reserveTokens"], 12345);
        assert_eq!(value["compaction"]["futureNested"], "keep");
        // In-memory snapshot still has the pre-external reserveTokens.
        assert_eq!(manager.get_compaction_reserve_tokens(), 999);
        Ok(())
    }

    #[test]
    fn project_write_when_untrusted_fails_exact() -> TestResult {
        let (_root, agent, project) = make_dirs("trust")?;
        write_settings_file(
            &project.join(".pi").join("settings.json"),
            r#"{ "extensions": ["/secret"] }"#,
        )?;
        let mut manager = create_manager(&project, &agent, false);
        assert!(!manager.is_project_trusted());
        assert!(manager.get_extension_paths().is_empty());
        assert!(manager.drain_errors().is_empty());
        let error = match manager.set_project_skill_paths(vec!["s".into()]) {
            Ok(()) => return Err("expected trust error".into()),
            Err(error) => error,
        };
        assert_eq!(
            error.to_string(),
            "Project is not trusted; refusing to write project settings"
        );
        assert!(
            !project.join(".pi").join("settings.json").exists()
                || read_text(&project.join(".pi").join("settings.json"))?
                    == r#"{ "extensions": ["/secret"] }"#
        );

        manager.set_project_trusted(true);
        assert_eq!(manager.get_extension_paths(), vec!["/secret".to_owned()]);
        manager.set_project_trusted(false);
        assert!(manager.get_extension_paths().is_empty());
        Ok(())
    }

    #[test]
    fn project_resource_setters_write_project_file_only() -> TestResult {
        let (_root, agent, project) = make_dirs("project-set")?;
        write_settings_file(
            &project.join(".pi").join("settings.json"),
            r#"{ "futureKey": 7 }"#,
        )?;
        let mut manager = create_manager(&project, &agent, true);
        manager
            .set_project_extension_paths(vec!["./ext".into()])
            .map_err(|e| e.to_string())?;
        manager
            .set_project_skill_paths(vec!["./skill".into()])
            .map_err(|e| e.to_string())?;
        manager
            .set_project_prompt_template_paths(vec!["./prompt".into()])
            .map_err(|e| e.to_string())?;
        manager
            .set_project_theme_paths(vec!["./theme".into()])
            .map_err(|e| e.to_string())?;
        manager
            .set_project_packages(&[PackageSource::Source("npm:pkg".into())])
            .map_err(|e| e.to_string())?;

        assert!(!agent.join("settings.json").exists());
        let value = parse_file(&project.join(".pi").join("settings.json"))?;
        assert_eq!(value["futureKey"], 7);
        assert_eq!(
            value["extensions"],
            Value::Array(vec![Value::String("./ext".into())])
        );
        assert_eq!(
            value["skills"],
            Value::Array(vec![Value::String("./skill".into())])
        );
        assert_eq!(
            value["prompts"],
            Value::Array(vec![Value::String("./prompt".into())])
        );
        assert_eq!(
            value["themes"],
            Value::Array(vec![Value::String("./theme".into())])
        );
        assert_eq!(
            value["packages"],
            Value::Array(vec![Value::String("npm:pkg".into())])
        );
        assert_eq!(manager.get_extension_paths(), vec!["./ext".to_owned()]);
        assert_eq!(manager.get_skill_paths(), vec!["./skill".to_owned()]);
        assert_eq!(
            manager.get_prompt_template_paths(),
            vec!["./prompt".to_owned()]
        );
        assert_eq!(manager.get_theme_paths(), vec!["./theme".to_owned()]);
        assert_eq!(
            manager.get_packages(),
            vec![PackageSource::Source("npm:pkg".into())]
        );

        // Project load error: silent refuse.
        write_settings_file(&project.join(".pi").join("settings.json"), "{ bad")?;
        let mut manager = create_manager(&project, &agent, true);
        let errors = manager.drain_errors();
        assert_eq!(errors.len(), 1);
        assert_eq!(errors[0].scope, SettingsScope::Project);
        manager
            .set_project_extension_paths(vec!["x".into()])
            .map_err(|e| e.to_string())?;
        assert_eq!(
            read_text(&project.join(".pi").join("settings.json"))?,
            "{ bad"
        );
        Ok(())
    }

    #[test]
    fn no_trailing_newline_and_pretty_format() -> TestResult {
        let (_root, agent, project) = make_dirs("newline")?;
        let mut manager = create_manager(&project, &agent, true);
        manager.set_theme("dark");
        manager.set_quiet_startup(true);
        let text = read_text(&agent.join("settings.json"))?;
        assert!(
            !text.ends_with('\n'),
            "must not force trailing newline: {text:?}"
        );
        let expected = serde_json::to_string_pretty(&serde_json::json!({
            "quietStartup": true,
            "theme": "dark"
        }))
        .map_err(|e| e.to_string())?;
        assert_eq!(text, expected);
        Ok(())
    }

    #[test]
    fn theme_path_hiding() {
        let mut manager = SettingsManager::in_memory(
            &Settings::default(),
            SettingsManagerCreateOptions::default(),
        );
        manager.set_theme("foo/bar");
        assert_eq!(manager.get_theme_setting().as_deref(), Some("foo/bar"));
        assert!(manager.get_theme().is_none());
        manager.set_theme("plain");
        assert_eq!(manager.get_theme().as_deref(), Some("plain"));
    }

    #[test]
    fn analytics_tracking_id_lifecycle() -> TestResult {
        let mut manager = SettingsManager::in_memory(
            &Settings::default(),
            SettingsManagerCreateOptions::default(),
        );
        assert!(manager.get_tracking_id().is_none());
        manager.set_enable_analytics(true);
        let first = manager
            .get_tracking_id()
            .ok_or_else(|| "expected generated tracking id".to_owned())?;
        assert!(Uuid::parse_str(&first).is_ok());
        manager.set_enable_analytics(false);
        manager.set_enable_analytics(true);
        assert_eq!(manager.get_tracking_id().as_deref(), Some(first.as_str()));

        let seed = Settings {
            tracking_id: Some("fixed-id".into()),
            enable_analytics: Some(false),
            ..Settings::default()
        };
        let mut manager =
            SettingsManager::in_memory(&seed, SettingsManagerCreateOptions::default());
        manager.set_enable_analytics(true);
        assert_eq!(manager.get_tracking_id().as_deref(), Some("fixed-id"));
        Ok(())
    }

    #[test]
    fn default_project_trust_is_global_only() -> TestResult {
        let (_root, agent, project) = make_dirs("dpt")?;
        write_settings_file(
            &project.join(".pi").join("settings.json"),
            r#"{ "defaultProjectTrust": "always" }"#,
        )?;
        let manager = create_manager(&project, &agent, true);
        assert_eq!(
            manager.get_default_project_trust(),
            DefaultProjectTrust::Ask
        );

        write_settings_file(
            &agent.join("settings.json"),
            r#"{ "defaultProjectTrust": "always" }"#,
        )?;
        let manager = create_manager(&project, &agent, true);
        assert_eq!(
            manager.get_default_project_trust(),
            DefaultProjectTrust::Always
        );

        write_settings_file(
            &agent.join("settings.json"),
            r#"{ "defaultProjectTrust": "bogus" }"#,
        )?;
        let manager = create_manager(&project, &agent, true);
        assert_eq!(
            manager.get_default_project_trust(),
            DefaultProjectTrust::Ask
        );
        Ok(())
    }

    #[test]
    fn session_dir_normalization() -> TestResult {
        let (_root, agent, project) = make_dirs("session-dir")?;
        write_settings_file(
            &agent.join("settings.json"),
            r#"{ "sessionDir": "/abs/path" }"#,
        )?;
        let manager = create_manager(&project, &agent, true);
        assert_eq!(manager.get_session_dir().as_deref(), Some("/abs/path"));
        write_settings_file(&agent.join("settings.json"), r#"{ "sessionDir": "" }"#)?;
        let manager = create_manager(&project, &agent, true);
        assert_eq!(manager.get_session_dir().as_deref(), Some(""));
        Ok(())
    }

    #[test]
    fn apply_overrides_remerged_on_save() {
        let mut manager = SettingsManager::in_memory(
            &Settings::default(),
            SettingsManagerCreateOptions::default(),
        );
        let mut overrides = Map::new();
        overrides.insert("theme".into(), Value::String("override".into()));
        manager.apply_overrides(&overrides);
        assert_eq!(manager.get_theme().as_deref(), Some("override"));
        manager.set_quiet_startup(true);
        // save re-merges global+project, discarding overrides.
        assert!(manager.get_theme().is_none());
        assert!(manager.get_quiet_startup());
    }

    #[test]
    fn reload_picks_up_external_changes() -> TestResult {
        let (_root, agent, project) = make_dirs("reload")?;
        write_settings_file(&agent.join("settings.json"), r#"{ "theme": "dark" }"#)?;
        let mut manager = create_manager(&project, &agent, true);
        assert_eq!(manager.get_theme().as_deref(), Some("dark"));
        write_settings_file(&agent.join("settings.json"), r#"{ "theme": "light" }"#)?;
        assert_eq!(manager.get_theme().as_deref(), Some("dark"));
        manager.reload();
        assert_eq!(manager.get_theme().as_deref(), Some("light"));
        Ok(())
    }

    #[test]
    fn in_memory_storage_roundtrip() -> TestResult {
        let mut storage = InMemorySettingsStorage::new();
        storage.with_lock(SettingsScope::Global, &mut |_| {
            Ok(Some(r#"{"theme":"dark"}"#.to_owned()))
        })?;
        let mut manager = SettingsManager::from_storage(
            Box::new(storage),
            SettingsManagerCreateOptions::default(),
        );
        assert_eq!(manager.get_theme().as_deref(), Some("dark"));
        manager.set_theme("light");
        assert_eq!(
            manager.get_global_settings().theme.as_deref(),
            Some("light")
        );
        Ok(())
    }

    #[test]
    fn missing_file_load_creates_no_lock_artifact() -> TestResult {
        let (root, agent, project) = make_dirs("lock-artifact")?;
        let manager = create_manager(&project, &agent, true);
        assert!(!agent.join("settings.json.lock").exists());
        drop(manager);
        assert!(!agent.join("settings.json").exists());
        assert!(!agent.join("settings.json.lock").exists());

        // Write creates parent dirs for a nested agent path.
        let nested_agent = root.join("nested").join("agent");
        let mut manager = create_manager(&project, &nested_agent, true);
        manager.set_theme("dark");
        assert!(nested_agent.join("settings.json").exists());
        assert!(!nested_agent.join("settings.json.lock").exists());
        Ok(())
    }

    #[test]
    fn output_pad_strict_zero() -> TestResult {
        let (_root, agent, project) = make_dirs("output-pad")?;
        write_settings_file(&agent.join("settings.json"), r#"{ "outputPad": 0 }"#)?;
        let manager = create_manager(&project, &agent, true);
        assert_eq!(manager.get_output_pad(), OutputPad::Zero);
        write_settings_file(&agent.join("settings.json"), r#"{ "outputPad": 2 }"#)?;
        let manager = create_manager(&project, &agent, true);
        assert_eq!(manager.get_output_pad(), OutputPad::One);
        write_settings_file(&agent.join("settings.json"), r#"{ "outputPad": "0" }"#)?;
        let manager = create_manager(&project, &agent, true);
        assert_eq!(manager.get_output_pad(), OutputPad::One);
        Ok(())
    }

    #[test]
    fn package_sources_typed_roundtrip() {
        let mut manager = SettingsManager::in_memory(
            &Settings::default(),
            SettingsManagerCreateOptions::default(),
        );
        let packages = vec![
            PackageSource::Source("npm:a".into()),
            PackageSource::Filtered(PackageSourceFilter {
                source: "git:b".into(),
                autoload: Some(false),
                extensions: Some(vec!["e".into()]),
                skills: None,
                prompts: None,
                themes: None,
                extra: {
                    let mut extra = Map::new();
                    extra.insert("future".into(), Value::from(1));
                    extra
                },
            }),
        ];
        manager.set_packages(&packages);
        assert_eq!(manager.get_packages(), packages);
        let view = manager.get_global_settings();
        assert_eq!(view.packages, Some(packages));
    }

    #[test]
    fn set_default_model_and_provider_marks_both() -> TestResult {
        let (_root, agent, project) = make_dirs("both")?;
        let mut manager = create_manager(&project, &agent, true);
        manager.set_default_model_and_provider("openai", "gpt-5");
        let value = parse_file(&agent.join("settings.json"))?;
        assert_eq!(value["defaultProvider"], "openai");
        assert_eq!(value["defaultModel"], "gpt-5");
        Ok(())
    }

    #[test]
    fn typed_settings_from_map_to_map_preserves_extra() {
        let mut map = Map::new();
        map.insert("theme".into(), Value::String("dark".into()));
        map.insert("future".into(), Value::from(42));
        let settings = Settings::from_map(&map);
        assert_eq!(settings.theme.as_deref(), Some("dark"));
        assert_eq!(settings.extra.get("future"), Some(&Value::from(42)));
        let roundtrip = settings.to_map();
        assert_eq!(roundtrip.get("theme"), Some(&Value::String("dark".into())));
        assert_eq!(roundtrip.get("future"), Some(&Value::from(42)));
    }
}