forge_workspace/

config.rs

//! `forge.toml` schema + loader.
//!
//! **Org model.** Projects are grouped under `[[orgs]]` (Stargate,
//! Gateway, Personal, etc.). Each org carries the `accounts = [...]`
//! pin shared by all its projects, replacing the per-project pin
//! that lived here before. Projects within an org keep a flat list
//! via `[[orgs.projects]]`. A launch with no project named opens every
//! project whose seat the store records as open, resuming the session
//! forge stored for each unless `--new` is passed; the alphabetically
//! first project is the fallback target when no project is named and no
//! picker chooses one.
//!
//! **Selection policy.** The gateway's declared-model walk: over the
//! org's `accounts` primaries and `fallback_accounts`, the first
//! account that declares the project's `model`, preferring ready over
//! saturated and keeping bailed last (saturated then leads to a
//! cooling filter). Utilization is never compared between accounts; it
//! collapses to one boolean per account. Every spawn in an org takes
//! the same walk, so there is no per-session spread.

use std::collections::{BTreeMap, HashMap};
use std::fs;
use std::path::{Path, PathBuf};
use std::time::Duration;

use forge_primitives::GotifyConfig;
use forge_primitives::account::Provider;
use forge_primitives::browser::ProfileKey;
use forge_primitives::permission::PermissionMode;
use forge_primitives::slack::SlackConfig;
use forge_primitives::{ClientConfig, ServerConfig};
use serde::Deserialize;

use crate::error::WorkspaceError;

/// `[huggingface]`: the token a gated Hub repository needs. The speaking
/// model's own repository is open, so an absent token changes nothing.
#[derive(Clone, Default, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct HuggingfaceSettings {
    #[serde(default)]
    pub token: Option<String>,
}

/// Hand-written because the token is a credential.
impl std::fmt::Debug for HuggingfaceSettings {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("HuggingfaceSettings")
            .field("token", &self.token.as_ref().map(|_| "[redacted]"))
            .finish()
    }
}

/// Optional `[vault]` section: the Vaultwarden account the vault family
/// talks to. Both `url` and `email` are required when the section is
/// present; there is no built-in default, because `forge.toml` is the one
/// source of truth for the account.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(deny_unknown_fields)]
pub(crate) struct VaultSection {
    #[serde(default)]
    pub url: Option<String>,
    #[serde(default)]
    pub email: Option<String>,
    /// Minutes without a vault call after which the session locks itself.
    /// Absent means no idle lock, which is what forge did before this key.
    #[serde(default)]
    pub idle_minutes: Option<u64>,
}

/// The validated `[vault]` section.
#[derive(Clone, PartialEq, Eq)]
pub(crate) struct VaultConfig {
    pub url: String,
    pub email: String,
    /// `None` when `idle_minutes` is unset: no idle lock.
    pub idle_minutes: Option<u64>,
}

/// Hand-written because the email is the account's identity and the salt the
/// master key derives with.
impl std::fmt::Debug for VaultConfig {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("VaultConfig")
            .field("url", &self.url)
            .field("email", &"[redacted]")
            .field("idle_minutes", &self.idle_minutes)
            .finish()
    }
}

impl VaultSection {
    /// Validate the section, naming the first missing key by name so a
    /// half-written table fails the load rather than a tool call.
    pub(crate) fn into_config(self) -> Result<Option<VaultConfig>, String> {
        let url = self.url.unwrap_or_default().trim().to_owned();
        let email = self.email.unwrap_or_default().trim().to_owned();
        if url.is_empty() {
            return Err("`url` is required when `[vault]` is present".to_owned());
        }
        if !url.starts_with("https://") {
            return Err("`url` must be an https:// URL; http is refused".to_owned());
        }
        if email.is_empty() {
            return Err("`email` is required when `[vault]` is present".to_owned());
        }
        // Zero would read as "lock instantly", which no one means; the way to
        // have no idle lock is to leave the key out.
        if self.idle_minutes == Some(0) {
            return Err("`idle_minutes` must be at least 1; omit it for no idle lock".to_owned());
        }
        Ok(Some(VaultConfig { url, email, idle_minutes: self.idle_minutes }))
    }
}

/// The whole `forge.toml`. Unknown keys are rejected so a mistyped
/// section name fails the load instead of being ignored.
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct ForgeToml {
    #[serde(default)]
    orgs: Vec<OrgEntry>,
    #[serde(default)]
    accounts: Vec<AccountEntry>,
    /// Optional `[models."<name>"]` tables - parameters a model name
    /// carries to every spawn. Absent means no model parameters are
    /// stamped and the CLI's own resolution stands.
    #[serde(default)]
    models: HashMap<String, ModelSettings>,
    /// Optional `[handoff]` section - when forge replaces a session with a
    /// fresh one that continues from a brief. Absent means the defaults,
    /// which is on at 85% with a compaction backstop of 1.
    #[serde(default)]
    handoff: HandoffSettings,
    /// Optional `[dictate]` section - local dictation. Absent section
    /// -> disabled, which is what keeps a 3 GB model download opt-in.
    #[serde(default)]
    dictate: crate::dictate::DictateSettings,
    /// Optional `[tts]` section - speech out. Absent section -> disabled,
    /// which keeps the model install opt-in.
    #[serde(default)]
    tts: crate::tts::TtsSettings,
    /// Optional `[huggingface]` section - the token a gated Hub repository
    /// needs. Absent section leaves every Hub read untokened.
    #[serde(default)]
    huggingface: HuggingfaceSettings,
    /// Optional `[gotify]` section - the inbound-notification server
    /// connection. Absent section → `None` → the Gotify subsystem
    /// stays dormant.
    #[serde(default)]
    gotify: Option<GotifyConfig>,
    /// Optional `[systemone]` section - the decision-model endpoint the
    /// session tools ask. Absent or `enabled = false` → `None` → the
    /// tools are never injected.
    #[serde(default)]
    systemone: Option<forge_system_one::SystemOneSection>,
    /// Optional `[vault]` section - the Vaultwarden account the vault
    /// family talks to. Absent -> the family is not injected.
    #[serde(default)]
    vault: Option<VaultSection>,
    /// Optional `[[slack]]` sections - one entry per workspace. Absent or
    /// empty → the connector stays dormant.
    #[serde(default)]
    slack: Vec<SlackConfig>,
    /// Optional `[plugins]` section - opt-in plugin auto-update.
    /// Absent section → all defaults, which leaves auto-update off.
    #[serde(default)]
    plugins: PluginSettings,
    /// Optional `[gateway]` section - the inference listener's port.
    #[serde(default)]
    gateway: Option<GatewaySettings>,
    /// Optional `[server]` section - the socket's listener. Absent
    /// section means its defaults, which is on and on loopback.
    #[serde(default)]
    server: ServerConfig,
    /// Optional `[client]` section - the sets a client draws with. Absent
    /// section means every name unset, which is the built-in.
    #[serde(default)]
    client: ClientConfig,
    /// Optional `[browser]` section - how the server's browser hosts encode
    /// and when an idle profile closes. Absent section keeps the defaults.
    #[serde(default)]
    browser: BrowserSettings,
    /// Optional `[terminal]` section - the shell a seat's terminal runs, how
    /// much scrollback it keeps, and when an idle one closes. Absent section
    /// keeps the defaults.
    #[serde(default)]
    terminal: TerminalSettings,
    /// Optional `[documents]` section - the ceiling on one handed
    /// document. Absent section keeps the 10 MiB default.
    #[serde(default)]
    documents: DocumentsSettings,
    /// Optional `[usage]` section - the background poller's refresh
    /// interval. Absent section keeps the 60 s default.
    #[serde(default)]
    usage: UsageSettings,
    /// Optional `[sessions]` section - whether a dead durable seat comes
    /// back. Absent section keeps the defaults, which heal it.
    #[serde(default)]
    sessions: SessionsSection,
    /// Optional top-level `[env]` table - the BASE every session
    /// starts from, overridden per key by `[accounts.env]` and then by
    /// the project's env. Merged into `LoadedAccount.env` at
    /// load; the project layer is applied at spawn. Absent -> empty.
    #[serde(default)]
    env: HashMap<String, String>,
}

/// Hand-written so the global env's values stay out of it; the sections it
/// holds redact themselves.
impl std::fmt::Debug for ForgeToml {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let env: BTreeMap<&str, &str> =
            self.env.keys().map(|key| (key.as_str(), "[redacted]")).collect();
        f.debug_struct("ForgeToml")
            .field("orgs", &self.orgs)
            .field("accounts", &self.accounts)
            .field("models", &self.models)
            .field("handoff", &self.handoff)
            .field("dictate", &self.dictate)
            .field("tts", &self.tts)
            .field("huggingface", &self.huggingface)
            .field("gotify", &self.gotify)
            .field("systemone", &self.systemone)
            .field("vault", &self.vault)
            .field("slack", &self.slack)
            .field("plugins", &self.plugins)
            .field("gateway", &self.gateway)
            .field("server", &self.server)
            .field("client", &self.client)
            .field("browser", &self.browser)
            .field("terminal", &self.terminal)
            .field("documents", &self.documents)
            .field("usage", &self.usage)
            .field("sessions", &self.sessions)
            .field("env", &env)
            .finish()
    }
}

/// The ceiling a handed document has to fit under when the
/// `[documents] max_size_mib` key is absent, in MiB.
pub const DEFAULT_DOCUMENT_MAX_MIB: u64 = 10;

/// The highest `[documents] max_size_mib` forge accepts, in MiB. A document
/// crosses the socket base64-encoded, a third larger, and the desktop
/// client's frame cap is 256 MiB (`client/src-tauri`'s `MAX_FRAME_BYTES`):
/// 190 MiB raw lands at ~253.3 MiB, inside the cap with room for the
/// answer's other fields.
pub const DOCUMENT_MAX_MIB_LIMIT: u64 = 190;

/// The interval the background usage poller refreshes on when the
/// `[usage] poll_seconds` key is absent, in seconds. 60 s stays clear of
/// the OAuth usage endpoint's 429 throttle under multi-instance polling
/// while bounding how stale the account-usage cache can be.
pub const DEFAULT_USAGE_POLL_SECONDS: u64 = 60;

/// Whether a dead durable seat comes back when `[sessions] heal` is absent.
pub const DEFAULT_HEAL: bool = true;

/// The restart count when `[sessions] heal_attempts` is absent: three
/// restarts, which caps what a deterministic fault can burn.
pub const DEFAULT_HEAL_ATTEMPTS: usize = 3;

/// The waits before each restart when `[sessions] heal_backoff` is absent,
/// in seconds: 5 s, 30 s, then 2 min.
pub const DEFAULT_HEAL_BACKOFF_SECONDS: [u64; 3] = [5, 30, 120];

/// How long a restarted seat must stay up before its death count resets
/// when `[sessions] heal_stable` is absent, in seconds.
pub const DEFAULT_HEAL_STABLE_SECONDS: u64 = 600;

/// One `[usage]` table. Unknown fields are rejected so a mistyped
/// key fails the load instead of being ignored.
#[derive(Debug, Default, Deserialize)]
#[serde(deny_unknown_fields)]
struct UsageSettings {
    /// How often the background poller refreshes account usage, in
    /// seconds. The default is [`DEFAULT_USAGE_POLL_SECONDS`], and the
    /// key exists for the machine that wants a different one.
    #[serde(default)]
    poll_seconds: Option<u64>,
}

impl UsageSettings {
    /// The resolved interval. 0 is refused rather than obeyed: a
    /// zero-second interval would probe continuously.
    fn resolved_poll_interval(&self, path: &Path) -> Result<Duration, WorkspaceError> {
        match self.poll_seconds {
            None => Ok(Duration::from_secs(DEFAULT_USAGE_POLL_SECONDS)),
            Some(0) => Err(WorkspaceError::UsagePollIntervalInvalid { path: path.to_path_buf() }),
            Some(seconds) => Ok(Duration::from_secs(seconds)),
        }
    }
}

/// The validated `[sessions]` table: whether a dead durable seat comes
/// back, how many restarts it gets, the wait before each, and how long a
/// restarted seat must stay up before its count resets.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SessionsConfig {
    pub heal: bool,
    pub heal_attempts: usize,
    pub heal_backoff: Vec<Duration>,
    pub heal_stable: Duration,
}

impl Default for SessionsConfig {
    fn default() -> Self {
        Self {
            heal: DEFAULT_HEAL,
            heal_attempts: DEFAULT_HEAL_ATTEMPTS,
            heal_backoff: DEFAULT_HEAL_BACKOFF_SECONDS
                .iter()
                .copied()
                .map(Duration::from_secs)
                .collect(),
            heal_stable: Duration::from_secs(DEFAULT_HEAL_STABLE_SECONDS),
        }
    }
}

/// One `[sessions]` table. Unknown fields are rejected so a mistyped key
/// fails the load instead of being ignored.
#[derive(Debug, Default, Deserialize)]
#[serde(deny_unknown_fields)]
struct SessionsSection {
    #[serde(default)]
    heal: Option<bool>,
    #[serde(default)]
    heal_attempts: Option<usize>,
    #[serde(default)]
    heal_backoff: Option<Vec<String>>,
    #[serde(default)]
    heal_stable: Option<String>,
}

impl SessionsSection {
    /// Resolve the section, refusing the counts and durations that would
    /// silently mean something other than they say.
    fn into_config(self, path: &Path) -> Result<SessionsConfig, WorkspaceError> {
        let heal_attempts = match self.heal_attempts {
            None => DEFAULT_HEAL_ATTEMPTS,
            Some(0) => {
                return Err(WorkspaceError::SessionsHealAttemptsInvalid {
                    path: path.to_path_buf(),
                });
            }
            Some(attempts) => attempts,
        };
        let mut heal_backoff = match &self.heal_backoff {
            None => DEFAULT_HEAL_BACKOFF_SECONDS.iter().copied().map(Duration::from_secs).collect(),
            Some(entries) if entries.is_empty() => {
                return Err(WorkspaceError::SessionsBackoffEmpty { path: path.to_path_buf() });
            }
            Some(entries) => entries
                .iter()
                .map(|value| {
                    parse_session_duration(value).map_err(|()| {
                        WorkspaceError::SessionsDurationInvalid {
                            path: path.to_path_buf(),
                            key: "heal_backoff",
                            value: value.clone(),
                        }
                    })
                })
                .collect::<Result<Vec<_>, _>>()?,
        };
        if let Some(last) = heal_backoff.last().copied() {
            while heal_backoff.len() < heal_attempts {
                heal_backoff.push(last);
            }
        }
        let heal_stable = match &self.heal_stable {
            None => Duration::from_secs(DEFAULT_HEAL_STABLE_SECONDS),
            Some(value) => parse_session_duration(value).map_err(|()| {
                WorkspaceError::SessionsDurationInvalid {
                    path: path.to_path_buf(),
                    key: "heal_stable",
                    value: value.clone(),
                }
            })?,
        };
        Ok(SessionsConfig {
            heal: self.heal.unwrap_or(DEFAULT_HEAL),
            heal_attempts,
            heal_backoff,
            heal_stable,
        })
    }
}

/// A `[sessions]` duration as the file writes it: digits and one unit,
/// `ms`, `s`, `m` or `h`. A bare number is refused rather than guessed.
fn parse_session_duration(value: &str) -> Result<Duration, ()> {
    let value = value.trim();
    for (suffix, millis_per_unit) in [("ms", 1_u64), ("s", 1_000), ("m", 60_000), ("h", 3_600_000)]
    {
        if let Some(digits) = value.strip_suffix(suffix) {
            let amount: u64 = digits.parse().map_err(|_| ())?;
            let millis = amount.checked_mul(millis_per_unit).ok_or(())?;
            return Ok(Duration::from_millis(millis));
        }
    }
    Err(())
}

/// The file's spelling of a resolved `[sessions]` duration, for the
/// settings page: the largest unit that divides it exactly.
pub(crate) fn format_session_duration(duration: Duration) -> String {
    let millis = duration.as_millis();
    if millis > 0 && millis % 3_600_000 == 0 {
        format!("{}h", millis / 3_600_000)
    } else if millis > 0 && millis % 60_000 == 0 {
        format!("{}m", millis / 60_000)
    } else if millis % 1_000 == 0 {
        format!("{}s", millis / 1_000)
    } else {
        format!("{millis}ms")
    }
}

/// The `[browser]` table: how the server's browser hosts encode, and when an
/// idle profile closes. Unknown fields are rejected so a mistyped key fails
/// the load instead of being ignored.
#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Eq)]
#[serde(default, deny_unknown_fields)]
pub struct BrowserSettings {
    /// Frames encoded per second; faster paints are coalesced. 1 to 120.
    pub fps: u16,
    /// Lossy WebP quality, 0 to 100. A key frame is lossless regardless.
    pub quality: u8,
    /// Minutes a profile no viewer has used may sit before it closes.
    pub idle_minutes: u64,
}

impl Default for BrowserSettings {
    fn default() -> Self {
        Self { fps: 30, quality: 75, idle_minutes: 30 }
    }
}

/// The `[terminal]` table: the shell a seat's terminal runs, how much
/// scrollback the model keeps, and when an idle terminal closes. Unknown
/// fields are rejected so a mistyped key fails the load instead of being
/// ignored.
#[derive(Clone, Debug, Deserialize, PartialEq, Eq)]
#[serde(default, deny_unknown_fields)]
pub struct TerminalSettings {
    /// The shell to run. Empty means `$SHELL`, falling back to `/bin/zsh`
    /// on macOS.
    pub shell: String,
    /// The scrollback the model keeps, in lines. 0 keeps none.
    pub scrollback_lines: usize,
    /// Minutes an untouched, unattached terminal may sit before it closes.
    /// 0 is off.
    pub idle_minutes: u64,
}

impl Default for TerminalSettings {
    fn default() -> Self {
        Self { shell: default_terminal_shell(), scrollback_lines: 2000, idle_minutes: 0 }
    }
}

/// The shell a terminal runs when `[terminal] shell` names none: the
/// person's own `$SHELL`, or the platform's login shell.
fn default_terminal_shell() -> String {
    std::env::var("SHELL").ok().filter(|shell| !shell.trim().is_empty()).unwrap_or_else(|| {
        if cfg!(target_os = "macos") { "/bin/zsh" } else { "/bin/sh" }.to_owned()
    })
}

/// One `[documents]` table. Unknown fields are rejected so a mistyped
/// key fails the load instead of being ignored.
#[derive(Debug, Default, Deserialize)]
#[serde(deny_unknown_fields)]
struct DocumentsSettings {
    /// The ceiling on one handed document, in MiB. The default is
    /// [`DEFAULT_DOCUMENT_MAX_MIB`], and the key exists for the machine
    /// that wants a different one.
    #[serde(default)]
    max_size_mib: Option<u64>,
}

impl DocumentsSettings {
    /// The resolved ceiling in bytes. 0 and a magnitude a byte count
    /// cannot hold are refused rather than obeyed, and so is a value past
    /// [`DOCUMENT_MAX_MIB_LIMIT`]: each would mean something other than a
    /// ceiling a client can receive.
    fn resolved_max_bytes(&self, path: &Path) -> Result<u64, WorkspaceError> {
        match self.max_size_mib {
            None => Ok(DEFAULT_DOCUMENT_MAX_MIB * 1024 * 1024),
            Some(mib) if mib > DOCUMENT_MAX_MIB_LIMIT => {
                Err(WorkspaceError::DocumentCeilingTooLarge {
                    path: path.to_path_buf(),
                    value: mib,
                })
            }
            Some(mib) => mib.checked_mul(1024 * 1024).filter(|bytes| *bytes > 0).ok_or_else(|| {
                WorkspaceError::DocumentCeilingInvalid { path: path.to_path_buf(), value: mib }
            }),
        }
    }
}

/// One `[gateway]` table. Unknown fields are rejected so a mistyped
/// key fails the load instead of being ignored.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct GatewaySettings {
    /// The inference listener's port. Fixed by default.
    #[serde(default)]
    port: Option<u16>,
    /// How many consecutive 429s from one account fire a rotation.
    #[serde(default)]
    streak_count: Option<u32>,
    /// The window the 429 streak is counted over, in seconds.
    #[serde(default)]
    streak_window_secs: Option<u64>,
    /// The cooldown when no reset time is known, in seconds.
    #[serde(default)]
    no_reset_cooldown_secs: Option<u64>,
}

impl GatewaySettings {
    /// The resolved port, refusing 0: the port is fixed by design, and
    /// a 0 here would ask the OS for an ephemeral port no child was
    /// ever told about.
    fn resolved_port(&self, path: &Path) -> Result<u16, WorkspaceError> {
        match self.port {
            Some(0) => Err(WorkspaceError::GatewayPortInvalid { path: path.to_path_buf() }),
            Some(port) => Ok(port),
            None => Ok(DEFAULT_GATEWAY_PORT),
        }
    }

    /// The resolved rotation numbers, refusing 0 on any of them: each
    /// 0 would silently disable the mechanism it configures, which
    /// reads as a bug rather than a choice. A magnitude above u32
    /// seconds is refused the same way - silently mapping it to the
    /// default is the substitution this refusal exists to prevent.
    fn resolved_rotation(
        &self,
        path: &Path,
    ) -> Result<forge_gateway::rotation::RotationNumbers, WorkspaceError> {
        fn refused_u32(
            path: &Path,
            key: &'static str,
            value: Option<u32>,
            default: u32,
        ) -> Result<u32, WorkspaceError> {
            match value {
                Some(0) => {
                    Err(WorkspaceError::GatewayRotationInvalid { path: path.to_path_buf(), key })
                }
                Some(v) => Ok(v),
                None => Ok(default),
            }
        }
        fn refused_duration(
            path: &Path,
            key: &'static str,
            value: Option<u64>,
            default: Duration,
        ) -> Result<Duration, WorkspaceError> {
            match value {
                Some(0) => {
                    Err(WorkspaceError::GatewayRotationInvalid { path: path.to_path_buf(), key })
                }
                Some(v) => u32::try_from(v).map(u64::from).map(Duration::from_secs).map_err(|_| {
                    WorkspaceError::GatewayRotationInvalid { path: path.to_path_buf(), key }
                }),
                None => Ok(default),
            }
        }
        let defaults = forge_gateway::rotation::RotationNumbers::default();
        Ok(forge_gateway::rotation::RotationNumbers {
            streak_count: refused_u32(
                path,
                "streak_count",
                self.streak_count,
                defaults.streak_count,
            )?,
            streak_window: refused_duration(
                path,
                "streak_window_secs",
                self.streak_window_secs,
                defaults.streak_window,
            )?,
            no_reset_cooldown: refused_duration(
                path,
                "no_reset_cooldown_secs",
                self.no_reset_cooldown_secs,
                defaults.no_reset_cooldown,
            )?,
        })
    }
}

impl ProjectEntry {
    /// The resolved mode for the project. Absent is `auto`, not "no
    /// override": under account rotation a session can start on any
    /// account in its org's pool, so the project is the stable scope
    /// and a forge default is what keeps its sessions consistent.
    fn permission_mode(
        &self,
        path: &std::path::Path,
        name: &str,
    ) -> Result<PermissionMode, WorkspaceError> {
        match self.permission_mode.as_deref() {
            None => Ok(PermissionMode::Auto),
            Some(raw) => PermissionMode::from_wire(raw).ok_or_else(|| {
                WorkspaceError::ProjectInvalidPermissionMode {
                    path: path.to_path_buf(),
                    name: name.to_owned(),
                    value: raw.to_owned(),
                }
            }),
        }
    }
}

/// One `[[orgs]]` entry. Unknown keys are rejected: a misspelled
/// `fallback_accounts` parses clean as "no fallbacks" otherwise, which
/// is a silent behaviour change from a typo.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct OrgEntry {
    name: String,
    /// Account `display_name`s every project in this org is allowed
    /// to spawn under. Required; cross-validated against `[[accounts]]`.
    accounts: Vec<String>,
    /// Fallback `display_name`s used when every pinned account is
    /// unavailable. Absent -> empty. Validated against `[[accounts]]`
    /// exactly like `accounts`.
    #[serde(default)]
    fallback_accounts: Vec<String>,
    /// The org's browser profile name; `<org>/<name>`. Absent is `default`.
    #[serde(default)]
    browser_profile: Option<String>,
    /// The Slack workspace every project in the org inherits. Absent
    /// leaves each project to bind its own or none.
    #[serde(default)]
    slack: Option<SlackBinding>,
    #[serde(default)]
    projects: Vec<ProjectEntry>,
}

/// `[orgs.slack]` or `[orgs.projects.slack]`: the one `[[slack]]` label a
/// scope's sessions act in.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct SlackBinding {
    workspace: String,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct ProjectEntry {
    name: String,
    path: String,
    /// The project's model: fills the CLI's model slots at spawn
    /// (`ANTHROPIC_DEFAULT_*_MODEL`, `ANTHROPIC_SMALL_FAST_MODEL`,
    /// `CLAUDE_CODE_SUBAGENT_MODEL`). Required to be declared by at
    /// least one account in the org.
    #[serde(default)]
    model: Option<String>,
    /// CLI permission mode stamped onto every session this project
    /// spawns. Absent resolves to `auto`.
    #[serde(default)]
    permission_mode: Option<String>,
    /// Cap on this project's concurrently live dynamic workers.
    /// Absent keeps the default.
    #[serde(default)]
    max_workers: Option<usize>,
    /// Per-project environment entries, layered over the account's
    /// env at spawn.
    #[serde(default)]
    env: HashMap<String, String>,
    /// Path to a `KEY=value` file whose entries join this project's
    /// env, so a secret can live outside forge.toml. Read once at
    /// load, like every other value here, so rotating it needs a
    /// forge restart.
    #[serde(default)]
    env_file: Option<String>,
    /// Extra roots the document read accepts beyond the session's own
    /// tree, so a project's documents can live outside its repo (a
    /// vault, a shared spec directory). Each entry is absolute or
    /// starts with `~`; a relative one is a load error. Absent ->
    /// empty.
    #[serde(default)]
    document_roots: Vec<String>,
    /// This project's handoff trigger, layered over the top-level table.
    /// Every key is optional, so a project sets the one it disagrees on.
    #[serde(default)]
    handoff: Option<HandoffSettings>,
    /// This project's browser profile name; `<org>/<name>`. Absent keeps
    /// the org's.
    #[serde(default)]
    browser_profile: Option<String>,
    /// This project's Slack workspace, overriding the org's. Absent keeps
    /// the org's binding.
    #[serde(default)]
    slack: Option<SlackBinding>,
}

/// Hand-written because a project's env may carry secrets, which the
/// derived output would print.
impl std::fmt::Debug for ProjectEntry {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let env: BTreeMap<&str, &str> =
            self.env.keys().map(|key| (key.as_str(), "[redacted]")).collect();
        f.debug_struct("ProjectEntry")
            .field("name", &self.name)
            .field("path", &self.path)
            .field("model", &self.model)
            .field("permission_mode", &self.permission_mode)
            .field("max_workers", &self.max_workers)
            .field("env", &env)
            .field("env_file", &self.env_file)
            .field("document_roots", &self.document_roots)
            .field("handoff", &self.handoff)
            .field("browser_profile", &self.browser_profile)
            .field("slack", &self.slack)
            .finish()
    }
}

/// Unknown fields are rejected so a near-miss key (`providers`) fails
/// loudly instead of loading and leaving the account probing the wrong
/// endpoint until preflight hangs on it.
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct AccountEntry {
    display_name: String,
    /// Which backend this account talks to. Required: an account that
    /// does not say probes the wrong endpoint and bails at preflight,
    /// so silence is the dangerous answer. Held as `Option` only so the
    /// absent case can name the account; `None` is a load error.
    provider: Option<forge_primitives::account::Provider>,
    /// The flat base URL. Required for base-url providers; an
    /// Anthropic account may omit it (the gateway constant is its
    /// upstream).
    #[serde(default)]
    base_url: Option<String>,
    /// The credential the gateway forwards, mapped onto the right
    /// variable per provider. Required.
    #[serde(default)]
    token: Option<String>,
    /// The canonical model names the account serves. Required
    /// non-empty.
    #[serde(default)]
    models: Vec<String>,
    /// Canonical name -> upstream slug, only where the spellings
    /// differ.
    #[serde(default)]
    model_slugs: HashMap<String, String>,
    /// Canonical name -> the other names a request may arrive under for
    /// that model.
    #[serde(default)]
    model_aliases: HashMap<String, Vec<String>>,
    /// Provider-behaviour extras only - timeouts, context caps,
    /// fallback switches. Base-url and credential keys are rejected:
    /// they are the flat keys' job.
    #[serde(default)]
    env: HashMap<String, String>,
}

/// Hand-written because the flat token and the env map are credentials.
impl std::fmt::Debug for AccountEntry {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let env: BTreeMap<&str, &str> =
            self.env.keys().map(|key| (key.as_str(), "[redacted]")).collect();
        f.debug_struct("AccountEntry")
            .field("display_name", &self.display_name)
            .field("provider", &self.provider)
            .field("base_url", &self.base_url)
            .field("token", &self.token.as_ref().map(|_| "[redacted]"))
            .field("models", &self.models)
            .field("model_slugs", &self.model_slugs)
            .field("model_aliases", &self.model_aliases)
            .field("env", &env)
            .finish()
    }
}

// The loaded account shape lives in forge-primitives: the gateway
// builds its account state from it, so it crosses a crate boundary.
// Re-exported here so `crate::config::LoadedAccount` keeps resolving.
pub(crate) use forge_primitives::account::LoadedAccount;

/// The `[plugins]` section. Unknown fields are rejected so a mistyped
/// key cannot silently leave auto-update doing nothing.
#[derive(Debug, Clone, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct PluginSettings {
    /// Update every installed plugin once at forge boot - the switch
    /// alone governs, there is no per-marketplace or per-plugin opt-out.
    /// Off by default: an auto-applied plugin update can break a
    /// load-bearing session mid-day, so forge only ever moves a plugin
    /// the user opted in.
    #[serde(default)]
    pub auto_update: bool,
}

/// Cap on a project's concurrently live dynamic workers when its
/// `max_workers` override is absent.
pub(crate) const DEFAULT_MAX_WORKERS_PER_PROJECT: usize = 2;

/// The `[models."<name>"]` table: the parameters a model name carries to
/// every spawn, keyed by the canonical name forge.toml already pins
/// projects to. Model-shaped values live here rather than in code, so
/// changing a model is a config edit. Unknown fields are rejected so a
/// mistyped key cannot silently leave a parameter unset.
#[derive(Debug, Clone, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct ModelSettings {
    /// The window, in tokens, the CLI's auto-compaction triggers against,
    /// stamped onto the child as `CLAUDE_CODE_AUTO_COMPACT_WINDOW`. It is
    /// set below the model's context so the compact request has room to
    /// fit - compaction fires near a window's top, and the request itself
    /// needs headroom beyond that. Absent leaves the CLI's own resolution
    /// in place.
    #[serde(default)]
    pub auto_compact_window: Option<i64>,
}

/// The share of the window a session hands off at when the key is absent.
pub const DEFAULT_HANDOFF_AT_PERCENT: u8 = 85;

/// The compaction count the backstop hands off at when the key is absent.
/// One is the first compaction: the fill trigger should have fired before it,
/// and a session that reaches two is the alarm the record exists for.
pub const DEFAULT_HANDOFF_AFTER_COMPACTIONS: u32 = 1;

/// The `[handoff]` table, top-level or per project. Every key is optional so
/// a project's table can set the one it disagrees on and inherit the rest.
#[derive(Debug, Clone, Copy, Deserialize, Default, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct HandoffSettings {
    /// `false` turns the automatic trigger off and leaves `/handoff` alone.
    #[serde(default)]
    pub enabled: Option<bool>,
    /// The share of the CLI's effective window the fill trigger fires at.
    /// Widened past `u8` so a value above 255 gets this crate's own refusal
    /// rather than serde's, and validation bounds what survives to 1..=100.
    #[serde(default)]
    pub at_percent: Option<u32>,
    /// The compaction count the backstop fires at.
    #[serde(default)]
    pub after_compactions: Option<u32>,
}

/// The trigger a session reads, with the project's table over the top-level
/// one and the defaults under both.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct HandoffPolicy {
    pub enabled: bool,
    pub at_percent: u8,
    pub after_compactions: u32,
}

impl Default for HandoffPolicy {
    fn default() -> Self {
        Self {
            enabled: true,
            at_percent: DEFAULT_HANDOFF_AT_PERCENT,
            after_compactions: DEFAULT_HANDOFF_AFTER_COMPACTIONS,
        }
    }
}

impl HandoffPolicy {
    pub fn resolve(global: &HandoffSettings, project: Option<&HandoffSettings>) -> Self {
        Self {
            enabled: project
                .and_then(|settings| settings.enabled)
                .or(global.enabled)
                .unwrap_or(true),
            at_percent: u8::try_from(
                project
                    .and_then(|settings| settings.at_percent)
                    .or(global.at_percent)
                    .unwrap_or(u32::from(DEFAULT_HANDOFF_AT_PERCENT)),
            )
            .unwrap_or(DEFAULT_HANDOFF_AT_PERCENT),
            after_compactions: project
                .and_then(|settings| settings.after_compactions)
                .or(global.after_compactions)
                .unwrap_or(DEFAULT_HANDOFF_AFTER_COMPACTIONS),
        }
    }
}

/// Refuse a trigger that can never fire or fires on every turn. `scope` names
/// the table the value came from, so the error says which one to edit.
fn validate_handoff_settings(
    settings: &HandoffSettings,
    path: &Path,
    scope: &str,
) -> Result<(), WorkspaceError> {
    if let Some(value) = settings.at_percent
        && !(1..=100).contains(&value)
    {
        return Err(WorkspaceError::HandoffAtPercentInvalid {
            path: path.to_path_buf(),
            scope: scope.to_owned(),
            value,
        });
    }
    if settings.after_compactions == Some(0) {
        return Err(WorkspaceError::HandoffAfterCompactionsInvalid {
            path: path.to_path_buf(),
            scope: scope.to_owned(),
        });
    }
    Ok(())
}

pub(crate) struct LoadedConfig {
    pub projects: Vec<LoadedProject>,
    /// The top-level `[env]` layer, after the gateway keys were dropped at
    /// load. Kept whole so the settings page can draw the layer itself
    /// rather than re-reading one account's merged env.
    pub global_env: HashMap<String, String>,
    /// Each org's resolved browser profile name, keyed by org name: what
    /// the boot's profile resolver reads to place an org's browsers.
    pub org_browser_profiles: HashMap<String, String>,
    /// Each org's own `[orgs.slack]` binding, keyed by org name. A project
    /// may override it; the resolved per-project binding is on the project.
    pub org_slack: HashMap<String, String>,
    /// Index into `projects` for the fallback target: the
    /// alphabetically-first project. Read only when no project is named and
    /// no picker selects one; a named project and the picker both override
    /// it.
    pub default_index: usize,
    pub accounts: Vec<LoadedAccount>,
    /// `[models."<name>"]` tables, keyed by the spelling a project's
    /// `model` pins. Absent tables mean a spawn stamps no model
    /// parameters.
    pub models: HashMap<String, ModelSettings>,
    /// `[handoff]` section knobs, unresolved: a project's own table layers
    /// over these, and the defaults sit under both.
    pub handoff: HandoffSettings,
    /// `[dictate]` section knobs. Absent section means dictation is
    /// off and preflight skips it entirely.
    pub dictate: crate::dictate::DictateSettings,
    /// `[tts]` section knobs. Absent section means the speaking role is
    /// off and nothing synthesises.
    pub tts: crate::tts::TtsSettings,
    /// `[huggingface]` token, or the default when the section is absent.
    pub huggingface: HuggingfaceSettings,
    /// `[gotify]` server connection, or `None` when the section is
    /// absent (Gotify disabled).
    pub gotify: Option<GotifyConfig>,
    /// `[systemone]` decision-model endpoint, or `None` when the
    /// section is absent or disabled (the tools are not injected).
    pub systemone: Option<forge_system_one::SystemOneConfig>,
    /// `[vault]` account, or `None` when the section is absent (the family
    /// is not injected).
    pub vault: Option<VaultConfig>,
    /// `[[slack]]` workspaces. An absent or empty list leaves the
    /// connector dormant, the way an absent `[gotify]` does.
    pub slack: Vec<SlackConfig>,
    /// `[plugins]` section knobs. Absent section means auto-update is
    /// off.
    pub plugins: PluginSettings,
    /// The port the gateway's inference listener binds. Absent
    /// `[gateway]` section keeps the default.
    pub gateway_port: u16,
    /// The gateway's rotation numbers. Absent keys keep the defaults.
    pub gateway_rotation: forge_gateway::rotation::RotationNumbers,
    /// `[server]` section knobs. Absent section means the listener's
    /// defaults: on, on loopback.
    pub server: ServerConfig,
    /// `[client]` section knobs. Absent section means every name unset,
    /// which is the built-in rather than a pin.
    pub client: ClientConfig,
    /// `[browser]` section knobs, resolved: the encoding rate and quality,
    /// and the idle release's bound. Absent section keeps the defaults.
    pub browser: BrowserSettings,
    /// `[terminal]` section knobs, resolved: the shell to run, the
    /// scrollback bound and the idle clock. Absent section keeps the
    /// defaults.
    pub terminal: TerminalSettings,
    /// The ceiling on one handed document, in bytes: `[documents]
    /// max_size_mib` resolved, 10 MiB when the key is absent. Read by the
    /// document read, which refuses over it.
    pub document_max_bytes: u64,
    /// The background usage poller's interval: `[usage] poll_seconds`
    /// resolved, 60 seconds when the key is absent. Bounds how stale the
    /// account-usage cache is.
    pub usage_poll_interval: Duration,
    /// `[sessions]` section knobs, resolved. Absent section keeps the
    /// defaults, which heal a dead durable seat.
    pub sessions: SessionsConfig,
    /// The fingerprint of the raw file text this load read, which the
    /// settings document carries and a save compares against.
    pub raw_fingerprint: String,
}

/// Hand-written so a field added later cannot print through it until it
/// is deliberately listed. Its credential carriers - the accounts' and
/// projects' env stamps, gotify's token, systemone's key - are redacted
/// by the structs they live on.
impl std::fmt::Debug for LoadedConfig {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("LoadedConfig")
            .field("projects", &self.projects)
            .field("global_env", &self.global_env.keys().map(String::as_str).collect::<Vec<_>>())
            .field("org_browser_profiles", &self.org_browser_profiles)
            .field("org_slack", &self.org_slack)
            .field("default_index", &self.default_index)
            .field("accounts", &self.accounts)
            .field("models", &self.models)
            .field("handoff", &self.handoff)
            .field("dictate", &self.dictate)
            .field("tts", &self.tts)
            .field("huggingface", &self.huggingface)
            .field("gotify", &self.gotify)
            .field("systemone", &self.systemone)
            .field("vault", &self.vault)
            .field("slack", &self.slack)
            .field("plugins", &self.plugins)
            .field("gateway_port", &self.gateway_port)
            .field("gateway_rotation", &self.gateway_rotation)
            .field("server", &self.server)
            .field("client", &self.client)
            .field("browser", &self.browser)
            .field("terminal", &self.terminal)
            .field("document_max_bytes", &self.document_max_bytes)
            .field("usage_poll_interval", &self.usage_poll_interval)
            .field("sessions", &self.sessions)
            .field("raw_fingerprint", &self.raw_fingerprint)
            .finish()
    }
}

/// What one `forge.toml` reload changed, in the terms the boot's log line
/// reads: the tables whose new values are live from their next use, and the
/// keys whose values are stored but need a restart.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct ConfigReload {
    /// The concrete key paths whose new value applies without a restart.
    pub changed: Vec<String>,
    /// The concrete key paths whose value is stored but needs one.
    pub restart_only: Vec<String>,
}

impl ConfigReload {
    /// Whether any reported key sits under `prefix`, for the consumers that
    /// act on a whole table (`accounts.`, `gateway.`).
    pub fn moved(&self, prefix: &str) -> bool {
        self.changed.iter().chain(&self.restart_only).any(|path| path.starts_with(prefix))
    }
}

impl LoadedConfig {
    /// The reload summary between this load and `next`, read from the one
    /// class catalogue the settings page draws its chips from.
    pub(crate) fn diff(&self, next: &Self) -> ConfigReload {
        crate::settings::diff(self, next)
    }
}

/// The label a scope's `slack` binding resolves to, or a load error naming
/// the label asked for and the ones that exist: a binding to a workspace
/// forge does not have would leave every Slack tool dead at runtime.
fn slack_binding_label(
    binding: &SlackBinding,
    scope: &str,
    labels: &std::collections::BTreeSet<String>,
    path: &std::path::Path,
) -> Result<String, WorkspaceError> {
    let label = binding.workspace.trim();
    if labels.contains(label) {
        return Ok(label.to_owned());
    }
    let configured = if labels.is_empty() {
        "none".to_owned()
    } else {
        labels.iter().cloned().collect::<Vec<_>>().join(", ")
    };
    Err(WorkspaceError::ConfigInvalid {
        path: path.to_path_buf(),
        message: format!(
            "{scope} slack: no [[slack]] workspace named '{label}'; configured: {configured}"
        ),
    })
}

/// The port the gateway's listener binds when `[gateway] port` is
/// absent. Fixed, not OS-assigned: every session's base URL names it,
/// so a drift would point children at an address nothing serves.
pub const DEFAULT_GATEWAY_PORT: u16 = 8787;

#[derive(Clone)]
pub(crate) struct LoadedProject {
    pub name: String,
    pub path: PathBuf,
    /// Original path string from `forge.toml`, preserved for display
    /// (e.g. `~/Projects/forge` with `~` un-expanded). Use `path` for
    /// filesystem access; this for human-readable output.
    pub display_path: String,
    /// Name of the org this project belongs to (matches
    /// `LoadedOrg.name`). The spawn resolves the org's pin and walk
    /// order through this back-reference.
    pub org: String,
    /// Cached pinned account list from the project's org. Duplicated
    /// here so callers don't need to walk the org list on every
    /// resolution.
    pub accounts: Vec<String>,
    /// Cached fallback list from the project's org, alongside
    /// `accounts`. Absent key -> empty.
    pub fallback_accounts: Vec<String>,
    /// The project's model: fills the CLI's model slots at spawn
    /// (`ANTHROPIC_DEFAULT_*_MODEL`, `ANTHROPIC_SMALL_FAST_MODEL`,
    /// `CLAUDE_CODE_SUBAGENT_MODEL`) and is the model the walk matches
    /// accounts on. A project that declares none cannot spawn.
    pub model: Option<String>,
    /// Per-project environment from the entry's env table, layered
    /// over the account's env at spawn. An `ANTHROPIC_BASE_URL` or
    /// `ANTHROPIC_AUTH_TOKEN` here desyncs forge's own accounting -
    /// the usage probe and the selection walk both read the ACCOUNT
    /// map, so they measure a different endpoint.
    pub env: HashMap<String, String>,
    /// The `env_file` path the entry declared, kept for the settings page;
    /// its entries are already folded into `env`.
    pub env_file: Option<String>,
    /// Cap on this project's live dynamic workers; `None` keeps the
    /// default. See `ProjectEntry::max_workers`.
    pub max_workers: Option<usize>,
    /// CLI permission mode stamped onto every session this project
    /// spawns. Resolved once at load; absent key resolves to `auto`.
    pub permission_mode: PermissionMode,
    /// The extra roots the document read accepts beyond a session's own
    /// tree: the entry's `document_roots` with `~` expanded. Empty for a
    /// project that declares none.
    pub document_roots: Vec<PathBuf>,
    /// This project's handoff table, unresolved; `None` inherits the
    /// top-level one entirely.
    pub handoff: Option<HandoffSettings>,
    /// The browser profile this project's sessions drive: the project's
    /// override, else the org's, else `<org>/default`.
    pub browser_profile: ProfileKey,
    /// The `[[slack]]` label this project's sessions act in: the
    /// project's binding, else the org's. `None` leaves the Slack tools
    /// refusing with the key to add.
    pub slack_workspace: Option<String>,
}

/// Hand-written because a project's env may carry secrets (`env_file`
/// exists so one can live outside forge.toml), which the derived output
/// would print.
impl std::fmt::Debug for LoadedProject {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let env: BTreeMap<&str, &str> =
            self.env.keys().map(|key| (key.as_str(), "[redacted]")).collect();
        f.debug_struct("LoadedProject")
            .field("name", &self.name)
            .field("path", &self.path)
            .field("display_path", &self.display_path)
            .field("org", &self.org)
            .field("accounts", &self.accounts)
            .field("fallback_accounts", &self.fallback_accounts)
            .field("model", &self.model)
            .field("env", &env)
            .field("env_file", &self.env_file)
            .field("max_workers", &self.max_workers)
            .field("permission_mode", &self.permission_mode)
            .field("document_roots", &self.document_roots)
            .field("handoff", &self.handoff)
            .field("browser_profile", &self.browser_profile)
            .field("slack_workspace", &self.slack_workspace)
            .finish()
    }
}

/// Complete `[env]` < `[accounts.env]` < the project's env,
/// narrowest winning per key, over the already-merged `account_env`.
/// Applied here rather than at load because one account serves many
/// projects, so merging earlier would leak a project's keys into every
/// other project on that account.
pub(crate) fn session_env(
    project: &LoadedProject,
    account_env: &HashMap<String, String>,
) -> HashMap<String, String> {
    let mut env = account_env.clone();
    env.extend(project.env.iter().map(|(k, v)| (k.clone(), v.clone())));
    env
}

/// A seat's children's environment: the server's own first, then the
/// account and project tables over it.
///
/// **The `claude` child gets this by inheritance; a terminal's shell does
/// not**, because its spawner hands it a map instead of inheriting and
/// overriding. Without the server's own set the shell has no `HOME` and
/// the shell integration reads the person's rc from nowhere.
pub(crate) fn seat_env(
    project: &LoadedProject,
    account_env: &HashMap<String, String>,
) -> HashMap<String, String> {
    let mut env: HashMap<String, String> = std::env::vars().collect();
    env.extend(session_env(project, account_env));
    env
}

/// Sorted key NAMES a project contributes - never values; these tables
/// hold tokens.
pub(crate) fn applied_env_keys(project: &LoadedProject) -> String {
    let mut keys: Vec<&str> = project.env.keys().map(String::as_str).collect();
    keys.sort_unstable();
    keys.join(", ")
}

impl LoadedConfig {
    pub(crate) fn default_project(&self) -> &LoadedProject {
        &self.projects[self.default_index]
    }

    /// Empty `LoadedConfig` for the `testing` feature's
    /// `Workspace::testing_stub`. Production code paths that need a
    /// project (e.g. `default_project`) will panic when called on
    /// this value - tests that only need `domain_handles` access
    /// never reach those paths.
    #[cfg(any(test, feature = "testing"))]
    pub(crate) fn empty_for_test() -> Self {
        Self {
            projects: Vec::new(),
            global_env: HashMap::new(),
            org_browser_profiles: HashMap::new(),
            org_slack: HashMap::new(),
            default_index: 0,
            accounts: Vec::new(),
            models: HashMap::new(),
            handoff: HandoffSettings::default(),
            dictate: crate::dictate::DictateSettings::default(),
            tts: crate::tts::TtsSettings::default(),
            huggingface: HuggingfaceSettings::default(),
            gotify: None,
            vault: None,
            systemone: None,
            slack: Vec::new(),
            plugins: PluginSettings::default(),
            gateway_port: DEFAULT_GATEWAY_PORT,
            gateway_rotation: forge_gateway::rotation::RotationNumbers::default(),
            server: ServerConfig::default(),
            client: ClientConfig::default(),
            browser: BrowserSettings::default(),
            terminal: TerminalSettings::default(),
            document_max_bytes: DEFAULT_DOCUMENT_MAX_MIB * 1024 * 1024,
            usage_poll_interval: Duration::from_secs(DEFAULT_USAGE_POLL_SECONDS),
            sessions: SessionsConfig::default(),
            raw_fingerprint: String::new(),
        }
    }
}

/// The subdirectory holding every file forge itself owns (config,
/// state, cron, lock), kept apart from claude's own top-level
/// config-dir files. Pure path join; call [`ensure_forge_data_dir`]
/// when the directory has to exist before writing into it.
pub(crate) fn forge_data_dir(config_dir: &Path) -> PathBuf {
    config_dir.join("forge")
}

/// [`forge_data_dir`] with a `create_dir_all`, returning the path.
pub(crate) fn ensure_forge_data_dir(config_dir: &Path) -> std::io::Result<PathBuf> {
    let dir = forge_data_dir(config_dir);
    fs::create_dir_all(&dir)?;
    Ok(dir)
}

/// Read `forge/forge.toml`. Returns the path read plus its raw
/// contents.
fn read_config(config_dir: &Path) -> Result<(PathBuf, String), WorkspaceError> {
    let path = forge_data_dir(config_dir).join("forge.toml");
    match fs::read_to_string(&path) {
        Ok(raw) => Ok((path, raw)),
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
            Err(WorkspaceError::ConfigMissing { path })
        }
        Err(e) => Err(WorkspaceError::ConfigInvalid { path, message: format!("io error: {e}") }),
    }
}

/// The `[server]` section, refusing the two ports that cannot work: 0, which
/// is OS-assigned and so unguessable, and the gateway's own port, where the
/// listener that binds second loses at boot.
///
/// A disabled listener is not validated at all. Nothing will bind that port,
/// so a stale one left in a hand-authored file is not worth refusing the
/// boot over.
fn resolve_server(
    server: ServerConfig,
    gateway_port: u16,
    path: &Path,
) -> Result<ServerConfig, WorkspaceError> {
    if !server.enabled {
        return Ok(server);
    }
    if server.port == 0 {
        return Err(WorkspaceError::ServerPortInvalid { path: path.to_path_buf() });
    }
    if server.port == gateway_port {
        return Err(WorkspaceError::ServerPortTakenByGateway {
            path: path.to_path_buf(),
            port: gateway_port,
        });
    }
    Ok(server)
}

/// The `[client]` section: an unset name is not an error and not a
/// fallback, it means the built-in. A set one has to be a name forge ships,
/// because a key that is quietly ignored reads as the key not working.
fn resolve_client(client: ClientConfig, path: &Path) -> Result<ClientConfig, WorkspaceError> {
    for (key, value, shipped) in [
        ("mark", client.mark.as_deref(), forge_primitives::client::MARK_NAMES),
        ("theme", client.theme.as_deref(), forge_primitives::client::THEME_NAMES),
        ("font", client.font.as_deref(), forge_primitives::client::FONT_NAMES),
    ] {
        if let Some(value) = value
            && !shipped.contains(&value)
        {
            return Err(WorkspaceError::ClientNameUnknown {
                path: path.to_path_buf(),
                key,
                value: value.to_owned(),
            });
        }
    }
    Ok(client)
}

/// Where a parse failure sits in the document, from the byte span the error
/// carries: ` at line N, column M in <key>`, or empty when it names no span -
/// no position rather than a confident line 1.
///
/// The key is the text left of that line's `=` when that text is shaped
/// like a bare key (serde's own words do not name it for a value error, and
/// the snippet that used to is gone). A line with no `=` - a malformed
/// array element, a bare value - names nothing rather than quoting whatever
/// sits there as a key: the text right of the `=` is the value, and it
/// never prints.
fn parse_position(raw: &str, span: Option<std::ops::Range<usize>>) -> String {
    let Some(span) = span else { return String::new() };
    let Some(upto) = raw.get(..span.start) else { return String::new() };
    let line = upto.matches('\n').count() + 1;
    let column = upto.rsplit('\n').next().map_or(0, |tail| tail.chars().count()) + 1;
    let key = raw
        .lines()
        .nth(line - 1)
        .and_then(|text| text.split_once('='))
        .map(|(head, _)| head.trim())
        .filter(|head| !head.is_empty() && head.chars().all(is_bare_key_char));
    match key {
        Some(key) => format!(" at line {line}, column {column} in `{key}`"),
        None => format!(" at line {line}, column {column}"),
    }
}

/// A TOML bare-key character (`a-z A-Z 0-9 _ - .`).
fn is_bare_key_char(ch: char) -> bool {
    ch.is_ascii_alphanumeric() || ch == '_' || ch == '-' || ch == '.'
}

/// The error's own words with any double-quoted run scrubbed: serde renders
/// a mismatched value as `invalid type: string "…"`, and a value in this
/// file can be a token (#2267). A key is backtick-quoted and stays legible.
fn scrub_quoted(message: &str) -> String {
    let mut out = String::with_capacity(message.len());
    let mut rest = message;
    loop {
        let Some((before, after)) = rest.split_once('"') else {
            out.push_str(rest);
            return out;
        };
        out.push_str(before);
        out.push_str("[redacted]");
        // Drop the quoted run; an unterminated quote takes the tail with it
        // rather than printing a value whose end nobody found.
        match after.split_once('"') {
            Some((_, tail)) => rest = tail,
            None => return out,
        }
    }
}

/// Load + validate `forge.toml`. Returns the parsed orgs + projects
/// with `~` expanded.
pub(crate) fn load_from_dir(config_dir: &Path) -> Result<LoadedConfig, WorkspaceError> {
    let (path, raw) = read_config(config_dir)?;
    load_from_text(path, &raw)
}

/// Load + validate raw `forge.toml` text, with the path its errors name. The
/// settings save validates a candidate through here before it replaces the
/// file, so the file a save writes is one a boot would accept.
pub(crate) fn load_from_text(path: PathBuf, raw: &str) -> Result<LoadedConfig, WorkspaceError> {
    let parsed: ForgeToml = toml::from_str(raw).map_err(|source| WorkspaceError::ConfigParse {
        at: parse_position(raw, source.span()),
        message: scrub_quoted(source.message()),
        path: path.clone(),
    })?;

    // The boot's SlackWorkspaces build runs these checks; a reload goes
    // through the same loader, so it must refuse the same file a restart
    // would.
    crate::slack::validate_configs(&parsed.slack).map_err(|message| {
        WorkspaceError::ConfigInvalid { path: path.clone(), message: format!("slack: {message}") }
    })?;

    if parsed.tts.language.is_some() {
        tracing::warn!(
            target: "forge_workspace::config",
            event_name = "tts_language_key_ignored",
            "[tts] language is no longer read; the voice id is the language choice and the 54 \
             voices cover eight languages, so the key and its value can be deleted",
        );
    }

    if parsed.dictate.device.is_some() {
        tracing::warn!(
            target: "forge_workspace::config",
            event_name = "dictate_device_key_ignored",
            "[dictate] device is no longer read; capture moved to the client, which picks \
             its own machine's input, so the key and its value can be deleted",
        );
    }

    if parsed.orgs.is_empty() {
        return Err(WorkspaceError::NoOrgsConfigured { path });
    }
    if parsed.accounts.is_empty() {
        return Err(WorkspaceError::NoAccountsConfigured { path });
    }

    // Global `[env]` is the BASE each account's effective env starts
    // from; the account's own `[accounts.env]` extends it, so account
    // keys override global keys.
    let mut global_env = parsed.env;

    // Validate accounts first - orgs cross-reference them.
    let mut seen_account_names: std::collections::HashSet<String> =
        std::collections::HashSet::new();
    // Collected rather than reported one at a time: a first run after
    // the key became required trips every account at once, and naming
    // one per boot is that many edit-and-restart cycles.
    let missing_provider: Vec<String> = parsed
        .accounts
        .iter()
        .filter(|entry| entry.provider.is_none())
        .map(|entry| entry.display_name.clone())
        .collect();
    if !missing_provider.is_empty() {
        return Err(WorkspaceError::AccountsMissingProvider { path, names: missing_provider });
    }

    let mut accounts: Vec<LoadedAccount> = Vec::with_capacity(parsed.accounts.len());
    for mut entry in parsed.accounts {
        if !seen_account_names.insert(entry.display_name.clone()) {
            return Err(WorkspaceError::DuplicateAccount { path, name: entry.display_name });
        }
        let Some(provider) = entry.provider else {
            return Err(WorkspaceError::AccountsMissingProvider {
                path,
                names: vec![entry.display_name],
            });
        };
        // The four gateway keys are the flat keys' and the stamp's
        // alone. They are dropped from every env layer here, blank or
        // not, before the layers merge: the stamp covers the child's
        // env only, while the pool keeps this one, and the forward leg
        // reads the upstream and the credential out of what the pool
        // holds. A base URL left in would send real traffic, with the
        // real credential attached, to an endpoint the config never
        // named as an account.
        let gateway_keys = [
            "ANTHROPIC_BASE_URL",
            "ANTHROPIC_AUTH_TOKEN",
            "CLAUDE_CODE_OAUTH_TOKEN",
            "ANTHROPIC_API_KEY",
        ];
        let mut dropped: Vec<&str> = Vec::new();
        for key in gateway_keys {
            for env in [&mut global_env, &mut entry.env] {
                if env.remove(key).is_some() {
                    dropped.push(key);
                }
            }
        }
        if !dropped.is_empty() {
            dropped.dedup();
            tracing::warn!(
                target: "forge_workspace::config",
                event_name = "gateway_keys_dropped_from_env_layer",
                account = %entry.display_name,
                keys = %dropped.join(", "),
                "gateway keys in an env layer are dropped, not refused: the flat \
                 base_url and token keys own them, and the spawn stamp owns the child",
            );
        }
        let mut env = global_env.clone();
        env.extend(entry.env);
        // The flat credential: mapped onto the provider's own variable
        // below, which is what the probe, the gateway forward and the
        // child stamp all read.
        let token = match entry.token.as_deref().map(str::trim) {
            Some(t) if !t.is_empty() => t.to_owned(),
            _ => {
                return Err(WorkspaceError::AccountTokenRequired {
                    path,
                    name: entry.display_name,
                });
            }
        };
        if entry.models.is_empty() {
            return Err(WorkspaceError::AccountModelsRequired { path, name: entry.display_name });
        }
        for (slug_key, slug_value) in &entry.model_slugs {
            if !entry.models.contains(slug_key) {
                return Err(WorkspaceError::AccountSlugUndeclared { path, slug: slug_key.clone() });
            }
            if slug_value.trim().is_empty() {
                return Err(WorkspaceError::AccountSlugBlank { path, slug: slug_key.clone() });
            }
        }
        for (alias_key, alias_values) in &entry.model_aliases {
            if !entry.models.contains(alias_key) {
                return Err(WorkspaceError::AccountAliasUndeclared {
                    path,
                    alias: alias_key.clone(),
                });
            }
            if alias_values.is_empty() {
                return Err(WorkspaceError::AccountAliasEmpty { path, alias: alias_key.clone() });
            }
        }
        let base_url =
            entry.base_url.as_deref().map(str::trim).filter(|v| !v.is_empty()).map(str::to_owned);
        // A base-url provider probes `{base_url}/...`, so an absent key
        // would leave the probe pointed at Anthropic's host with the
        // wrong bearer. Refuse at load rather than at preflight.
        if provider.uses_base_url() && base_url.is_none() {
            return Err(WorkspaceError::AccountProviderNeedsBaseUrl {
                path,
                name: entry.display_name,
            });
        }
        // The key probe is `{base}/v1/key`, so a base that is the bare
        // host resolves to `openrouter.ai/v1/key` - which answers 200
        // with a marketing page. 200 is the one status the probe reads
        // as success, so it would reach the decode arm, retry to the
        // iteration cap and bail the account, stopping forge from
        // starting. Refuse the base here, where the message can say so.
        if provider == Provider::Openrouter
            && !base_url.as_deref().is_some_and(|v| v.trim_end_matches('/').ends_with("/api"))
        {
            return Err(WorkspaceError::OpenrouterBaseUrlNotApiRoot {
                path,
                name: entry.display_name,
            });
        }
        // Legal but self-inconsistent: the base is still stamped on the
        // spawned session, so chat goes to that endpoint while usage
        // probes the official API with the setup token.
        if provider == Provider::Anthropic && base_url.is_some() {
            tracing::warn!(
                target: "forge_workspace::config",
                account = %entry.display_name,
                "anthropic account declares a base_url; sessions will use that endpoint \
                 while usage probes the official API",
            );
        }
        // Map the flat keys onto the provider's variables - what the
        // probe, the gateway forward and the child stamp all read.
        if let Some(base_url) = &base_url {
            env.insert("ANTHROPIC_BASE_URL".to_owned(), base_url.clone());
        }
        let credential_variable = forge_gateway::binding::credential_variable_for(provider);
        env.insert(credential_variable.to_owned(), token);
        accounts.push(LoadedAccount {
            display_name: entry.display_name,
            provider,
            base_url,
            models: entry.models,
            model_slugs: entry.model_slugs,
            model_aliases: entry.model_aliases,
            env,
        });
    }

    // Validate orgs + build the flat project list.
    let slack_labels: std::collections::BTreeSet<String> =
        parsed.slack.iter().map(|config| config.workspace.trim().to_owned()).collect();
    let mut seen_org_names: std::collections::HashSet<String> = std::collections::HashSet::new();
    let mut seen_project_names: std::collections::HashSet<String> =
        std::collections::HashSet::new();
    let mut projects: Vec<LoadedProject> = Vec::new();
    let mut org_browser_profiles: HashMap<String, String> = HashMap::new();
    let mut org_slack_bindings: HashMap<String, String> = HashMap::new();
    for org_entry in parsed.orgs {
        if !seen_org_names.insert(org_entry.name.clone()) {
            return Err(WorkspaceError::DuplicateOrg { path, name: org_entry.name });
        }
        if org_entry.accounts.is_empty() {
            return Err(WorkspaceError::EmptyOrgAccounts { path, org: org_entry.name });
        }
        for account in org_entry.accounts.iter().chain(&org_entry.fallback_accounts) {
            if !seen_account_names.contains(account) {
                let mut valid: Vec<&str> = seen_account_names.iter().map(String::as_str).collect();
                valid.sort_unstable();
                return Err(WorkspaceError::UnknownOrgAccount {
                    path,
                    org: org_entry.name,
                    account: account.clone(),
                    valid: valid.join(", "),
                });
            }
        }
        if org_entry.projects.is_empty() {
            return Err(WorkspaceError::EmptyOrg { path, org: org_entry.name });
        }
        let org_profile = match org_entry.browser_profile.as_deref() {
            Some(name) => ProfileKey::of(&org_entry.name, name).map_err(|why| {
                WorkspaceError::ConfigInvalid {
                    path: path.clone(),
                    message: format!("[[orgs]] browser_profile: {why}"),
                }
            })?,
            None => ProfileKey::of(&org_entry.name, "default").map_err(|why| {
                WorkspaceError::ConfigInvalid {
                    path: path.clone(),
                    message: format!("[[orgs]] name: {why}"),
                }
            })?,
        };
        org_browser_profiles.insert(org_entry.name.clone(), org_profile.name().to_owned());
        let org_slack = org_entry
            .slack
            .as_ref()
            .map(|binding| slack_binding_label(binding, "[[orgs]]", &slack_labels, &path))
            .transpose()?;
        if let Some(workspace) = &org_slack {
            org_slack_bindings.insert(org_entry.name.clone(), workspace.clone());
        }
        for project_entry in org_entry.projects {
            if !seen_project_names.insert(project_entry.name.clone()) {
                return Err(WorkspaceError::DuplicateProject { path, name: project_entry.name });
            }
            let permission_mode = project_entry.permission_mode(&path, &project_entry.name)?;
            let document_roots = project_entry
                .document_roots
                .iter()
                .map(|root| {
                    // A bare `~` is home, the same intent as `~/`; anything
                    // else that does not come out absolute is refused.
                    let expanded = if root == "~" {
                        dirs::home_dir()
                    } else {
                        Some(expand_home(root)).filter(|path| path.is_absolute())
                    };
                    expanded.ok_or_else(|| WorkspaceError::ProjectDocumentRootRelative {
                        path: path.clone(),
                        name: project_entry.name.clone(),
                        root: root.clone(),
                    })
                })
                .collect::<Result<Vec<_>, _>>()?;
            let env = resolve_project_env(
                &project_entry.name,
                project_entry.env,
                project_entry.env_file.clone(),
            );
            if let Some(settings) = &project_entry.handoff {
                validate_handoff_settings(
                    settings,
                    &path,
                    &format!("project \"{}\"", project_entry.name),
                )?;
            }
            let slack_workspace = match &project_entry.slack {
                Some(binding) => {
                    Some(slack_binding_label(binding, "[[orgs.projects]]", &slack_labels, &path)?)
                }
                None => org_slack.clone(),
            };
            let browser_profile = match project_entry.browser_profile.as_deref() {
                Some(name) => ProfileKey::of(&org_entry.name, name).map_err(|why| {
                    WorkspaceError::ConfigInvalid {
                        path: path.clone(),
                        message: format!("[[orgs.projects]] browser_profile: {why}"),
                    }
                })?,
                None => org_profile.clone(),
            };
            projects.push(LoadedProject {
                name: project_entry.name.clone(),
                path: expand_home(&project_entry.path),
                display_path: project_entry.path,
                org: org_entry.name.clone(),
                accounts: org_entry.accounts.clone(),
                fallback_accounts: org_entry.fallback_accounts.clone(),
                model: project_entry.model.clone(),
                env,
                env_file: project_entry.env_file.clone(),
                max_workers: project_entry.max_workers,
                permission_mode,
                document_roots,
                handoff: project_entry.handoff,
                browser_profile,
                slack_workspace,
            });
            // The project model must be served by at least one account
            // the org can reach: a typo would boot clean, stamp all the
            // CLI slots, and then 503 every session's first request.
            if let Some(model) = &project_entry.model {
                let served =
                    org_entry.accounts.iter().chain(&org_entry.fallback_accounts).any(|name| {
                        accounts.iter().any(|a| {
                            a.display_name == *name
                                && forge_gateway::account::account_serves(
                                    &a.models,
                                    &a.model_aliases,
                                    model,
                                )
                        })
                    });
                if !served {
                    return Err(WorkspaceError::ProjectModelUndeclared {
                        path,
                        name: project_entry.name.clone(),
                        model: model.clone(),
                    });
                }
            }
        }
    }

    if projects.is_empty() {
        return Err(WorkspaceError::NoProjectsConfigured { path });
    }

    // Default project resolution (used by `forge` without argv when
    // the launchpad picker isn't available - fixture tests, smoke
    // tests, etc.; the production path lands on the launchpad
    // picker first): the alphabetically-first project.
    let default_index = {
        let mut alpha: Vec<usize> = (0..projects.len()).collect();
        alpha.sort_by(|a, b| projects[*a].name.cmp(&projects[*b].name));
        alpha[0]
    };

    let gateway_port = match &parsed.gateway {
        Some(gateway) => gateway.resolved_port(&path)?,
        None => DEFAULT_GATEWAY_PORT,
    };
    let gateway_rotation = match &parsed.gateway {
        Some(gateway) => gateway.resolved_rotation(&path)?,
        None => forge_gateway::rotation::RotationNumbers::default(),
    };
    let server = resolve_server(parsed.server, gateway_port, &path)?;
    let document_max_bytes = parsed.documents.resolved_max_bytes(&path)?;
    let usage_poll_interval = parsed.usage.resolved_poll_interval(&path)?;
    let sessions = parsed.sessions.into_config(&path)?;
    // **A [browser] value outside its range is refused, not clamped**: a
    // quality of 140 is a typo, and silently encoding at 100 would hide it.
    let browser = parsed.browser;
    if browser.fps == 0 || browser.fps > 120 {
        return Err(WorkspaceError::ConfigInvalid {
            path,
            message: format!("[browser] fps must be 1 to 120, not {}", browser.fps),
        });
    }
    if browser.quality > 100 {
        return Err(WorkspaceError::ConfigInvalid {
            path,
            message: format!("[browser] quality must be 0 to 100, not {}", browser.quality),
        });
    }
    let terminal = parsed.terminal;
    if terminal.shell.trim().is_empty() {
        return Err(WorkspaceError::ConfigInvalid {
            path,
            message: "[terminal] shell must name a shell; remove the key to use $SHELL".to_owned(),
        });
    }
    // A listener that never binds never hands a client its names either, so
    // a stale key there is not worth refusing the boot over - the call the
    // pre-split section made for every key at once.
    let client = if server.enabled { resolve_client(parsed.client, &path)? } else { parsed.client };

    validate_handoff_settings(&parsed.handoff, &path, "the top level")?;

    let systemone = match parsed.systemone {
        Some(section) => {
            section.into_config().map_err(|message| WorkspaceError::ConfigInvalid {
                path: path.clone(),
                message: format!("[systemone] {message}"),
            })?
        }
        None => None,
    };
    let vault = match parsed.vault {
        Some(section) => {
            section.into_config().map_err(|message| WorkspaceError::ConfigInvalid {
                path: path.clone(),
                message: format!("[vault] {message}"),
            })?
        }
        None => None,
    };

    // Per-model parameters are read by the exact spelling a project's
    // `model` pins - not by what accounts declare - so a name no project
    // pins is a statement nothing will act on. Warned rather than refused:
    // a project may pin the model on a later edit, and the table entry is
    // how it would be there waiting.
    let pinned: std::collections::HashSet<&str> =
        projects.iter().filter_map(|project| project.model.as_deref()).collect();
    for (model, parameters) in &parsed.models {
        if !pinned.contains(model.as_str()) {
            tracing::warn!(
                target: "forge_workspace::config",
                event_name = "model_parameters_unpinned",
                model = %model,
                "the [models] table names a model no project pins; nothing will read it",
            );
        }
        if let Some(window) = parameters.auto_compact_window
            && window <= 0
        {
            return Err(WorkspaceError::ModelAutoCompactWindowInvalid {
                path,
                model: model.clone(),
                value: window,
            });
        }
    }

    // A speaking model nothing installs is a boot failure, the way an
    // unknown `[dictate]` model key is.
    if let Err(reason) = parsed.tts.configured_variant() {
        return Err(WorkspaceError::ConfigInvalid { path, message: reason });
    }

    Ok(LoadedConfig {
        projects,
        global_env,
        org_browser_profiles,
        org_slack: org_slack_bindings,
        default_index,
        accounts,
        models: parsed.models,
        handoff: parsed.handoff,
        dictate: parsed.dictate,
        tts: parsed.tts,
        huggingface: parsed.huggingface,
        gotify: parsed.gotify,
        systemone,
        vault,
        slack: parsed.slack,
        plugins: parsed.plugins,
        gateway_port,
        gateway_rotation,
        server,
        client,
        browser,
        terminal,
        document_max_bytes,
        usage_poll_interval,
        sessions,
        raw_fingerprint: fingerprint_of(raw),
    })
}

/// A stable 64-bit fingerprint of the file's raw text, in hex. The settings
/// page carries the fingerprint it loaded and a save is refused when the file
/// has moved since.
pub(crate) fn fingerprint_of(raw: &str) -> String {
    let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
    for byte in raw.as_bytes() {
        hash ^= u64::from(*byte);
        hash = hash.wrapping_mul(0x0000_0100_0000_01b3);
    }
    format!("{hash:016x}")
}

/// A project's env: the `env_file` entries with the inline `env` table
/// layered over them, since the inline form is the more explicit
/// statement of the two.
/// Trim the setup token a project's env declares: the spawned child
/// reads that map verbatim, so a padded value would fail to
/// authenticate. The account layers never reach here with one - the
/// load drops the gateway keys before they merge.
fn trim_setup_token<S: std::hash::BuildHasher>(env: &mut HashMap<String, String, S>) {
    if let Some(token) = env.get_mut(forge_gateway::CLAUDE_CODE_OAUTH_TOKEN_ENV) {
        *token = token.trim().to_owned();
    }
}

fn resolve_project_env(
    project: &str,
    env: HashMap<String, String>,
    env_file: Option<String>,
) -> HashMap<String, String> {
    let mut merged = env_file.map(|path| read_env_file(project, &path)).unwrap_or_default();
    merged.extend(env);
    trim_setup_token(&mut merged);
    merged
}

/// Parse `KEY=value` lines, skipping blanks and `#` comments. Every way
/// this can go wrong warns and yields the keys it did read - a project's
/// env file is not worth refusing to boot over, and a partial read is
/// visible in the per-spawn applied record's key list.
fn read_env_file(project: &str, raw_path: &str) -> HashMap<String, String> {
    let mut env = HashMap::new();
    let skipped = |reason: &str, detail: &str| {
        tracing::warn!(
            target: "forge_workspace::config",
            event_name = "project_env_file_skipped",
            project,
            path = raw_path,
            reason,
            detail,
            "the project's env_file entry did not fully apply",
        );
    };

    let path = expand_home(raw_path);
    if !path.is_absolute() {
        // A relative path resolves against the process working
        // directory, so the same config would read a different file per
        // launch directory (HR#14). Skipping is failing the operation;
        // what the rule forbids is substituting a cwd-derived answer.
        skipped("not-absolute", "use an absolute or ~/ path");
        return env;
    }
    let text = match fs::read_to_string(&path) {
        Ok(text) => text,
        Err(err) => {
            let reason =
                if err.kind() == std::io::ErrorKind::NotFound { "missing" } else { "unreadable" };
            skipped(reason, &err.to_string());
            return env;
        }
    };
    for (number, line) in text.lines().enumerate() {
        let line = line.trim();
        if line.is_empty() || line.starts_with('#') {
            continue;
        }
        match line.split_once('=') {
            Some((key, value)) if !key.trim().is_empty() => {
                // Strip one matching pair of surrounding quotes, as
                // dotenv and direnv do. TOML forces quoting, so a value
                // moved out of the project's env table arrives with
                // them, and keeping them yields a token silently longer
                // than intended that fails far from the cause.
                let value = value.trim();
                let value = value
                    .strip_prefix('"')
                    .and_then(|inner| inner.strip_suffix('"'))
                    .or_else(|| value.strip_prefix('\'').and_then(|inner| inner.strip_suffix('\'')))
                    .unwrap_or(value);
                env.insert(key.trim().to_owned(), value.to_owned());
            }
            _ => skipped("malformed-line", &format!("line {}", number + 1)),
        }
    }
    env
}

pub(crate) fn expand_home(path: &str) -> PathBuf {
    if let Some(stripped) = path.strip_prefix("~/")
        && let Some(home) = dirs::home_dir()
    {
        return home.join(stripped);
    }
    PathBuf::from(path)
}

#[cfg(test)]
mod tests {
    use super::*;
    use forge_primitives::server::DEFAULT_SERVER_PORT;
    use std::fs;
    use std::net::{IpAddr, Ipv4Addr};
    use tempfile::tempdir;

    /// Resolve a project by name for the `session_env` calls below.
    fn named<'a>(config: &'a LoadedConfig, name: &str) -> &'a LoadedProject {
        config.projects.iter().find(|p| p.name == name).expect("declared project")
    }

    /// Write `forge/forge.toml` (the production location).
    fn write_config(dir: &std::path::Path, contents: &str) {
        let forge = ensure_forge_data_dir(dir).expect("forge/ dir");
        fs::write(forge.join("forge.toml"), contents).expect("write forge/forge.toml");
    }

    fn minimal_config() -> &'static str {
        r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#
    }

    /// One logged event: its level and the `event_name` it carries. A
    /// config that declares something forge ignores must warn at WARN with
    /// its own name, and the level is half of that: these targets are not
    /// raised by the default filters, so a warn demoted to debug is a warn
    /// that stopped being seen.
    #[derive(Default, Clone)]
    struct WarnedEvents(std::sync::Arc<std::sync::Mutex<Vec<(tracing::Level, String)>>>);

    struct CollectEventName(String);

    impl tracing::field::Visit for CollectEventName {
        fn record_debug(&mut self, field: &tracing::field::Field, value: &dyn std::fmt::Debug) {
            if field.name() == "event_name" {
                self.0 = format!("{value:?}").trim_matches('"').to_owned();
            }
        }
    }

    impl<S: tracing::Subscriber> tracing_subscriber::Layer<S> for WarnedEvents {
        fn on_event(
            &self,
            event: &tracing::Event<'_>,
            _ctx: tracing_subscriber::layer::Context<'_, S>,
        ) {
            let mut visitor = CollectEventName(String::new());
            event.record(&mut visitor);
            if !visitor.0.is_empty() {
                self.0.lock().expect("capture").push((*event.metadata().level(), visitor.0));
            }
        }
    }

    impl WarnedEvents {
        /// Whether `event` was logged, at WARN.
        fn warns(&self, event: &str) -> bool {
            self.0
                .lock()
                .expect("capture")
                .iter()
                .any(|(level, name)| name == event && *level == tracing::Level::WARN)
        }

        /// Every event name logged, in order.
        fn names(&self) -> Vec<String> {
            self.0.lock().expect("capture").iter().map(|(_, name)| name.clone()).collect()
        }
    }

    /// Load `dir`, capturing every `event_name` the load logs.
    fn load_capturing(
        dir: &std::path::Path,
    ) -> (Result<LoadedConfig, WorkspaceError>, WarnedEvents) {
        use tracing_subscriber::layer::SubscriberExt;
        let logged = WarnedEvents::default();
        let subscriber = tracing_subscriber::registry().with(logged.clone());
        let loaded = tracing::subscriber::with_default(subscriber, || load_from_dir(dir));
        (loaded, logged)
    }

    /// `[gateway] port = 0` is refused at load: the port is fixed, and
    /// a 0 would ask the OS for an ephemeral port no child was told
    /// about.
    #[test]
    fn gateway_port_zero_is_refused_at_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[gateway]
port = 0
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("port 0 must not load");
        assert!(
            err.to_string().contains("port 0"),
            "the error names the unusable port, got: {err}",
        );
    }

    #[test]
    fn gateway_port_defaults_when_the_section_is_absent() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("absent section loads");
        assert_eq!(config.gateway_port, DEFAULT_GATEWAY_PORT);
    }

    #[test]
    fn gateway_rotation_numbers_default_when_keys_are_absent() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("absent keys load");
        assert_eq!(config.gateway_rotation, forge_gateway::rotation::RotationNumbers::default(),);
    }

    #[test]
    fn gateway_rotation_numbers_parse_from_the_section() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[gateway]
streak_count = 3
streak_window_secs = 45
no_reset_cooldown_secs = 90
"#,
        );
        let config = load_from_dir(dir.path()).expect("section loads");
        assert_eq!(config.gateway_rotation.streak_count, 3);
        assert_eq!(config.gateway_rotation.streak_window, Duration::from_secs(45));
        assert_eq!(config.gateway_rotation.no_reset_cooldown, Duration::from_secs(90));
    }

    /// The document ceiling's default, stated where the key lives: an absent
    /// `[documents]` section means 10 MiB.
    #[test]
    fn document_ceiling_defaults_when_the_section_is_absent() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("absent section loads");
        assert_eq!(config.document_max_bytes, 10 * 1024 * 1024, "the 10 MiB default");
    }

    #[test]
    fn document_ceiling_parses_from_the_section() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[documents]
max_size_mib = 3
"#,
        );
        let config = load_from_dir(dir.path()).expect("section loads");
        assert_eq!(config.document_max_bytes, 3 * 1024 * 1024);
    }

    /// `max_size_mib = 0` is refused at load: it would refuse every document
    /// the moment one is handed, which reads as a bug rather than a choice.
    #[test]
    fn document_ceiling_zero_is_refused_at_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[documents]
max_size_mib = 0
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("0 must not load");
        assert!(
            err.to_string().contains("max_size_mib = 0"),
            "the error names the unusable key, got: {err}",
        );
    }

    /// **A ceiling past what the wire can carry is refused at load, with
    /// the reason in the error.** A document crosses the socket
    /// base64-encoded and the desktop client's frame cap is 256 MiB, so a
    /// ceiling above [`DOCUMENT_MAX_MIB_LIMIT`] would read, raise, and then
    /// die at the client - after a full read the reader never sees. The
    /// limit itself is usable.
    #[test]
    fn a_document_ceiling_past_the_wire_cap_is_refused_at_load() {
        assert_eq!(
            DOCUMENT_MAX_MIB_LIMIT, 190,
            "the most the 256 MiB frame cap carries once a document crosses base64-encoded",
        );
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!("{}\n[documents]\nmax_size_mib = 191\n", minimal_config()),
        );
        let err = load_from_dir(dir.path()).expect_err("over the wire cap must not load");
        let said = err.to_string();
        assert!(said.contains("max_size_mib = 191"), "the error names the value: {said}");
        assert!(said.contains("256 MiB"), "and the reason names the frame cap: {said}");

        write_config(
            dir.path(),
            &format!(
                "{}\n[documents]\nmax_size_mib = {DOCUMENT_MAX_MIB_LIMIT}\n",
                minimal_config()
            ),
        );
        let config = load_from_dir(dir.path()).expect("the limit itself is usable");
        assert_eq!(config.document_max_bytes, DOCUMENT_MAX_MIB_LIMIT * 1024 * 1024);
    }

    /// The usage poller's interval default, stated where the key lives: an
    /// absent `[usage]` section means 60 s.
    #[test]
    fn usage_poll_interval_defaults_when_the_section_is_absent() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("absent section loads");
        assert_eq!(config.usage_poll_interval, Duration::from_secs(60), "the 60 s default");
    }

    #[test]
    fn usage_poll_interval_parses_from_the_section() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), &format!("{}\n[usage]\npoll_seconds = 30\n", minimal_config()));
        let config = load_from_dir(dir.path()).expect("section loads");
        assert_eq!(config.usage_poll_interval, Duration::from_secs(30));
    }

    /// `poll_seconds = 0` is refused at load: a zero interval would probe
    /// continuously.
    #[test]
    fn usage_poll_interval_zero_is_refused_at_load() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), &format!("{}\n[usage]\npoll_seconds = 0\n", minimal_config()));
        let err = load_from_dir(dir.path()).expect_err("0 must not load");
        assert!(
            err.to_string().contains("[usage] poll_seconds"),
            "the error names the unusable key, got: {err}",
        );
    }

    #[test]
    fn usage_section_rejects_an_unknown_key() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), &format!("{}\n[usage]\npoll_second = 30\n", minimal_config()));
        let err = load_from_dir(dir.path()).expect_err("a near-miss key must not load");
        assert!(
            err.to_string().contains("poll_second"),
            "the error names the offending key, got: {err}",
        );
    }

    /// An absent `[sessions]` table takes the four settled defaults: healing
    /// on, three restarts at 5 s, 30 s and 2 min, and a 10 min stable window.
    #[test]
    fn sessions_default_when_the_section_is_absent() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("absent section loads");
        assert!(config.sessions.heal, "a durable seat heals unless it is turned off");
        assert_eq!(config.sessions.heal_attempts, 3, "three restarts");
        assert_eq!(
            config.sessions.heal_backoff,
            vec![Duration::from_secs(5), Duration::from_secs(30), Duration::from_secs(120)],
            "5 s, 30 s then 2 min",
        );
        assert_eq!(config.sessions.heal_stable, Duration::from_secs(600), "10 minutes");
    }

    #[test]
    fn sessions_section_reads_its_keys() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!(
                "{}\n[sessions]\nheal = false\nheal_attempts = 2\nheal_backoff = [\"1s\", \
                 \"90s\"]\nheal_stable = \"30m\"\n",
                minimal_config()
            ),
        );
        let config = load_from_dir(dir.path()).expect("section loads");
        assert!(!config.sessions.heal);
        assert_eq!(config.sessions.heal_attempts, 2);
        assert_eq!(
            config.sessions.heal_backoff,
            vec![Duration::from_secs(1), Duration::from_secs(90)],
        );
        assert_eq!(config.sessions.heal_stable, Duration::from_secs(1800));
    }

    /// A backoff list shorter than the attempt count repeats its last
    /// interval, so one entry covers every restart.
    #[test]
    fn sessions_backoff_repeats_its_last_interval() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!(
                "{}\n[sessions]\nheal_attempts = 3\nheal_backoff = [\"7s\"]\n",
                minimal_config()
            ),
        );
        let config = load_from_dir(dir.path()).expect("section loads");
        assert_eq!(config.sessions.heal_backoff, vec![Duration::from_secs(7); 3]);
    }

    /// Zero restart attempts would leave a dead seat dead while claiming
    /// healing is on, so it is refused by name.
    #[test]
    fn sessions_heal_attempts_zero_is_refused_at_load() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), &format!("{}\n[sessions]\nheal_attempts = 0\n", minimal_config()));
        let err = load_from_dir(dir.path()).expect_err("0 attempts must not load");
        assert!(
            err.to_string().contains("sessions.heal_attempts"),
            "the error names the unusable key, got: {err}",
        );
    }

    /// A duration with no unit is a typo, not seconds: reading "10" as 10 s
    /// would silently heal slower or faster than the file says.
    #[test]
    fn sessions_duration_without_a_unit_is_refused_at_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!("{}\n[sessions]\nheal_stable = \"10\"\n", minimal_config()),
        );
        let err = load_from_dir(dir.path()).expect_err("a bare number must not load");
        assert!(
            err.to_string().contains("sessions.heal_stable"),
            "the error names the unusable key, got: {err}",
        );
    }

    /// On unless it is turned off, and on loopback: "on by default" must
    /// not mean every machine starts listening on a network interface.
    #[test]
    fn server_section_defaults_to_enabled_on_loopback() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("absent section loads");
        assert!(config.server.enabled, "the listener is on unless it is turned off");
        // Two assertions, two changes: one drifts the const from the number
        // the book's table documents, the other lets the Default impl drift
        // from the const.
        assert_eq!(DEFAULT_SERVER_PORT, 8790, "the number the book's [server] table documents");
        assert_eq!(config.server.port, DEFAULT_SERVER_PORT, "an absent section takes that port");
        assert_eq!(config.server.bind, IpAddr::V4(Ipv4Addr::LOCALHOST));
    }

    #[test]
    fn server_section_reads_its_keys() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!(
                "{}\n[server]\nenabled = false\nport = 9100\nbind = \"10.0.0.5\"\n",
                minimal_config()
            ),
        );
        let config = load_from_dir(dir.path()).expect("section loads");
        assert!(!config.server.enabled);
        assert_eq!(config.server.port, 9100);
        assert_eq!(config.server.bind, "10.0.0.5".parse::<IpAddr>().expect("ip"));
    }

    /// An absent `[client]` leaves every name unset, and unset means the
    /// built-in rather than a pinned value.
    #[test]
    fn client_section_reads_its_keys() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!(
                "{}\n[client]\nmark = \"klin\"\ntheme = \"dark\"\nfont = \"system\"\n",
                minimal_config()
            ),
        );
        let config = load_from_dir(dir.path()).expect("section loads");
        assert_eq!(config.client.mark.as_deref(), Some("klin"));
        assert_eq!(config.client.theme.as_deref(), Some("dark"));
        assert_eq!(config.client.font.as_deref(), Some("system"));

        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("absent section loads");
        assert_eq!(config.client.mark, None, "an unset key is the built-in, not a pinned value");
        assert_eq!(config.client.theme, None);
        assert_eq!(config.client.font, None, "and the built-in face is what an unset font draws");
    }

    /// **`[browser]` carries the encoding and the idle release.** An absent
    /// section is the documented pair of defaults; a key outside its range
    /// is refused rather than clamped, because a quality of 140 is a typo
    /// and silently encoding at 100 would hide it.
    #[test]
    fn browser_section_reads_its_keys_and_refuses_a_bad_range() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!(
                "{}\n[browser]\nfps = 30\nquality = 90\nidle_minutes = 45\n",
                minimal_config()
            ),
        );
        let config = load_from_dir(dir.path()).expect("section loads");
        assert_eq!(config.browser.fps, 30);
        assert_eq!(config.browser.quality, 90);
        assert_eq!(config.browser.idle_minutes, 45);

        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("absent section loads");
        assert_eq!(
            config.browser,
            BrowserSettings::default(),
            "an absent section is the documented defaults",
        );
        assert_eq!(config.browser.fps, 30, "the documented default frames a second");

        for (key, value) in [("fps", "0"), ("fps", "121"), ("quality", "101")] {
            let dir = tempdir().expect("tempdir");
            write_config(
                dir.path(),
                &format!("{}\n[browser]\n{key} = {value}\n", minimal_config()),
            );
            let Err(refused) = load_from_dir(dir.path()) else {
                panic!("{key} = {value} is outside its range and must be refused");
            };
            let rendered = format!("{refused}");
            assert!(rendered.contains("[browser]"), "{rendered}");
        }
    }

    /// **A profile key resolves per project**: the org's `browser_profile`
    /// is the fallback, a project's own key replaces it, and an org that
    /// declares neither resolves to `<org>/default`.
    #[test]
    fn an_org_profile_is_the_fallback_and_a_project_override_wins() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[accounts]]
display_name = "main"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[[orgs]]
name = "Busytools"
accounts = ["main"]
browser_profile = "work"

  [[orgs.projects]]
  name = "forge"
  path = "/tmp/forge"

  [[orgs.projects]]
  name = "apply"
  path = "/tmp/apply"
  browser_profile = "job"

[[orgs]]
name = "Personal"
accounts = ["main"]

  [[orgs.projects]]
  name = "notes"
  path = "/tmp/notes"
"#,
        );
        let loaded = load_from_dir(dir.path()).expect("the config loads");
        let key = |name: &str| {
            loaded
                .projects
                .iter()
                .find(|project| project.name == name)
                .map(|project| project.browser_profile.as_str().to_owned())
                .expect("the project")
        };
        assert_eq!(key("forge"), "Busytools/work", "the org's profile is the fallback");
        assert_eq!(key("apply"), "Busytools/job", "a project override replaces it");
        let personal = loaded
            .projects
            .iter()
            .find(|project| project.org == "Personal")
            .expect("the personal project");
        assert_eq!(personal.browser_profile.as_str(), "Personal/default", "no key is default");
        assert_eq!(
            loaded.org_browser_profiles.get("Busytools").map(String::as_str),
            Some("work"),
            "the org map carries what the boot's resolver reads",
        );
        assert_eq!(
            loaded.org_browser_profiles.get("Personal").map(String::as_str),
            Some("default"),
        );
    }

    #[test]
    fn an_invalid_profile_name_fails_the_load_and_names_the_key() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[accounts]]
display_name = "main"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[[orgs]]
name = "Busytools"
accounts = ["main"]
browser_profile = "two words"

  [[orgs.projects]]
  name = "forge"
  path = "/tmp/forge"
"#,
        );
        let why = load_from_dir(dir.path()).expect_err("the load refuses");
        let text = format!("{why}");
        assert!(text.contains("browser_profile"), "the key is named: {text}");
        assert!(text.contains("two words"), "the value is named: {text}");
    }

    /// The idle default is half an hour, and the grace key is gone: the
    /// next spawn is what picks a closed profile up, so there is no owner
    /// left to warn and nothing for a second clock to do.
    #[test]
    fn the_browser_idle_default_is_thirty_minutes_and_grace_is_gone() {
        let settings = BrowserSettings::default();
        assert_eq!(settings.idle_minutes, 30);
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), &format!("{}\n[browser]\ngrace_minutes = 5\n", minimal_config()));
        let why = load_from_dir(dir.path()).expect_err("a removed key is refused");
        assert!(format!("{why}").contains("grace_minutes"), "the key is named: {why}");
    }

    /// A section that never binds cannot stop the boot: a stale port on a
    /// disabled listener is the config's business only if something would
    /// use it, and nothing will. Nor are the client's names read: a listener
    /// that never binds never hands a client its settings either, which is
    /// the call the pre-split section made for every key at once.
    #[test]
    fn a_disabled_server_section_is_not_validated() {
        for port in [0, DEFAULT_GATEWAY_PORT] {
            let dir = tempdir().expect("tempdir");
            write_config(
                dir.path(),
                &format!("{}\n[server]\nenabled = false\nport = {port}\n", minimal_config()),
            );
            let config =
                load_from_dir(dir.path()).expect("a disabled listener must not fail the load");
            assert!(!config.server.enabled, "the section stays disabled at port {port}");
        }

        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!(
                "{}\n[server]\nenabled = false\n[client]\nmark = \"anvilish\"\n",
                minimal_config()
            ),
        );
        let config = load_from_dir(dir.path()).expect("a disabled listener never reads a name");
        assert_eq!(config.client.mark.as_deref(), Some("anvilish"), "the name is carried as given");
    }

    #[test]
    fn a_near_miss_key_fails_loudly_in_both_sections() {
        for (section, key) in [("[server]", "portt"), ("[client]", "themes")] {
            let err = toml::from_str::<ForgeToml>(&format!("{section}\n{key} = 0\n"))
                .expect_err("a near-miss key must fail loudly");
            assert!(err.to_string().contains(key), "{section} ignored {key}: {err}");
        }
    }

    /// A browser is pointed at this port by hand, so an OS-assigned one
    /// is unguessable rather than merely unhelpful.
    #[test]
    fn server_port_zero_is_refused_at_load() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), &format!("{}\n[server]\nport = 0\n", minimal_config()));
        let err = load_from_dir(dir.path()).expect_err("port 0 must not load");
        assert!(
            err.to_string().contains("server port 0"),
            "the error names the unusable port, got: {err}",
        );
    }

    /// Compared against the gateway's resolved port rather than its
    /// default: whichever listener binds second loses, and the listener
    /// being on by default means the loss reads as the listener broken.
    #[test]
    fn server_port_on_the_gateway_port_is_refused_at_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!("{}\n[gateway]\nport = 9100\n\n[server]\nport = 9100\n", minimal_config()),
        );
        let err = load_from_dir(dir.path()).expect_err("the gateway's port must not load");
        let message = err.to_string();
        assert!(
            message.contains("9100") && message.contains("gateway"),
            "the error names the port and what it collides with, got: {message}",
        );
    }

    /// A name picks from the set forge ships, and a name outside it stops
    /// the boot rather than falling back to the built-in: a setting that is
    /// quietly ignored reads as the key not working.
    #[test]
    fn a_client_name_outside_the_shipped_set_is_refused_at_load() {
        let load = |key: &str, value: &str| {
            let dir = tempdir().expect("tempdir");
            write_config(
                dir.path(),
                &format!("{}\n[client]\n{key} = \"{value}\"\n", minimal_config()),
            );
            let loaded = load_from_dir(dir.path());
            (dir, loaded)
        };
        let named = |config: &crate::config::LoadedConfig, key: &str| match key {
            "mark" => config.client.mark.clone(),
            "font" => config.client.font.clone(),
            _ => config.client.theme.clone(),
        };

        // Every name key validates the same way, so one walk covers them
        // rather than three near-identical tests.
        for (key, shipped, unknown) in
            [("mark", "klin", "anvilish"), ("theme", "dark", "light"), ("font", "system", "comic")]
        {
            let (_dir, loaded) = load(key, shipped);
            let config = loaded.expect("a shipped name loads");
            assert_eq!(
                named(&config, key).as_deref(),
                Some(shipped),
                "{key} keeps the name it was given",
            );

            let (_dir, loaded) = load(key, unknown);
            let err = loaded.expect_err("a name forge does not ship must not load");
            let message = err.to_string();
            assert!(
                message.contains(key) && message.contains(unknown),
                "the error names the key and the name it refused, got: {message}",
            );
        }
    }

    /// **A retired section is an unknown key now.** The ghosts are gone, so
    /// a stale synced forge.toml fails the load naming the section rather
    /// than being accepted and silently ignored.
    #[test]
    fn retired_top_level_sections_are_refused() {
        let cases = [
            ("web", "\n[web]\nenabled = false\nport = 9100\n"),
            ("workers", "\n[workers]\nmax_workers = 4\n"),
            ("projects", "\n[projects.forge]\nmodel = \"claude-sonnet-5\"\n"),
            ("selection", "\n[selection]\npolicy = \"round_robin\"\n"),
            ("ui", "\n[ui]\nlaunchpad_spinner = \"braille\"\n"),
            (
                "resume_lead",
                "\n[[orgs.projects]]\nname = \"notes\"\npath = \"/tmp\"\nresume_lead = true\n",
            ),
        ];
        for (label, stanza) in cases {
            let dir = tempdir().expect("tempdir");
            write_config(dir.path(), &format!("{}{stanza}", minimal_config()));
            let error =
                load_from_dir(dir.path()).expect_err("a retired key or section must not load");
            let message = error.to_string();
            assert!(message.contains(label), "the refusal names {label}, got: {message}");
        }
    }

    #[test]
    fn gateway_rotation_zero_keys_are_refused_at_load() {
        // An absurd magnitude is refused with the same error: silently
        // mapping it to the default would substitute the user's value.
        let values = [
            ("streak_count", "0"),
            ("streak_window_secs", "0"),
            ("streak_window_secs", "99999999999"),
            ("no_reset_cooldown_secs", "0"),
            ("no_reset_cooldown_secs", "99999999999"),
        ];
        for (key, value) in values {
            let dir = tempdir().expect("tempdir");
            write_config(
                dir.path(),
                &format!(
                    r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[gateway]
{key} = {value}
"#
                ),
            );
            let err = load_from_dir(dir.path()).expect_err("an unusable key must not load");
            assert!(err.to_string().contains(key), "the error names the unusable key, got: {err}");
        }
    }

    #[test]
    fn parses_the_flat_base_url_and_token_onto_the_provider_variables() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Codex"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[[accounts]]
display_name = "Codex"
token = "unused"
models = ["claude-sonnet-5"]
provider = "codex"
base_url = "http://localhost:18765"
"#,
        );
        let config = load_from_dir(dir.path()).expect("happy path");
        let account = &config.accounts[0];
        assert_eq!(account.display_name, "Codex");
        assert_eq!(
            account.env.get("ANTHROPIC_BASE_URL").map(String::as_str),
            Some("http://localhost:18765"),
            "the flat base_url stamps the provider's base-url variable",
        );
        assert_eq!(
            account.env.get("ANTHROPIC_AUTH_TOKEN").map(String::as_str),
            Some("unused"),
            "the flat token stamps the provider's credential variable",
        );
    }

    #[test]
    fn account_without_provider_fails_the_load_naming_the_account() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("absent provider must not load");
        let message = err.to_string();
        assert!(
            message.contains("Stargate"),
            "the error has to name the offending account, got: {message}",
        );
        assert!(
            message.contains("anthropic") && message.contains("codex"),
            "the error has to list the accepted providers, got: {message}",
        );
    }

    #[test]
    fn codex_provider_without_a_base_url_fails_the_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Codex"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[[accounts]]
display_name = "Codex"
token = "t"
models = ["claude-sonnet-5"]
provider = "codex"
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("codex without a base url must not load");
        let message = err.to_string();
        assert!(
            message.contains("Codex") && message.contains("base_url"),
            "the error has to name the account and the missing key, got: {message}",
        );
    }

    /// `https://openrouter.ai/v1/key` answers 200 with a marketing page,
    /// and 200 is the one status the probe treats as success, so a bare
    /// host reaches the decode arm, retries twelve times and bails the
    /// account - which stops forge starting. Catch the base at load
    /// instead, where the user can act on it.
    #[test]
    fn a_blank_slug_value_fails_the_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Codex"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[[accounts]]
display_name = "Codex"
token = "t"
models = ["claude-sonnet-5"]
provider = "codex"
base_url = "http://localhost:18765"
[accounts.model_slugs]
"claude-sonnet-5" = "   "
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("a blank slug value must not load");
        let message = err.to_string();
        assert!(message.contains("blank slug"), "the error names the blank slug, got: {message}");
    }

    #[test]
    fn a_project_model_no_account_declares_fails_the_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Codex"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "gpt-5.6-luna"
[[accounts]]
display_name = "Codex"
token = "t"
models = ["claude-sonnet-5"]
provider = "codex"
base_url = "http://localhost:18765"
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("an undeclared project model must not load");
        let message = err.to_string();
        assert!(
            message.contains("gpt-5.6-luna") && message.contains("forge"),
            "the error names the project and the model, got: {message}",
        );
    }

    #[test]
    fn a_project_model_an_org_account_declares_loads() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Codex"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-sonnet-5"
[[accounts]]
display_name = "Codex"
token = "t"
models = ["claude-sonnet-5"]
provider = "codex"
base_url = "http://localhost:18765"
"#,
        );
        let config = load_from_dir(dir.path()).expect("a declared model loads");
        assert_eq!(config.projects[0].model.as_deref(), Some("claude-sonnet-5"));
    }

    #[test]
    fn a_project_model_that_is_an_alias_loads() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Granite"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-opus-5"
[[accounts]]
display_name = "Granite"
token = "t"
models = ["claude-opus-5[1m]"]
provider = "anthropic"
[accounts.model_aliases]
"claude-opus-5[1m]" = ["claude-opus-5"]
"#,
        );
        let config = load_from_dir(dir.path()).expect("an aliased project model loads");
        assert_eq!(config.projects[0].model.as_deref(), Some("claude-opus-5"));
    }

    #[test]
    fn a_project_model_that_is_neither_declared_nor_an_alias_fails_the_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Granite"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-sonnet-5"
[[accounts]]
display_name = "Granite"
token = "t"
models = ["claude-opus-5[1m]"]
provider = "anthropic"
[accounts.model_aliases]
"claude-opus-5[1m]" = ["claude-opus-5"]
"#,
        );
        let err = load_from_dir(dir.path())
            .expect_err("holding aliases must not make the account serve everything");
        let message = err.to_string();
        assert!(
            message.contains("claude-sonnet-5"),
            "the error names the undeclared model, got: {message}",
        );
    }

    #[test]
    fn an_alias_for_an_undeclared_model_fails_the_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Granite"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[[accounts]]
display_name = "Granite"
token = "t"
models = ["claude-opus-5[1m]"]
provider = "anthropic"
[accounts.model_aliases]
"claude-opus-5" = ["claude-opus-5[1m]"]
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("an undeclared alias key must not load");
        let message = err.to_string();
        assert!(
            message.contains("'claude-opus-5'"),
            "the error quotes the undeclared alias key, not the declared marker, got: {message}",
        );
    }

    #[test]
    fn an_empty_alias_list_fails_the_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Granite"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[[accounts]]
display_name = "Granite"
token = "t"
models = ["claude-opus-5[1m]"]
provider = "anthropic"
[accounts.model_aliases]
"claude-opus-5[1m]" = []
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("an empty alias list must not load");
        let message = err.to_string();
        assert!(
            message.contains("empty alias list"),
            "the error says the list is empty, got: {message}",
        );
    }

    #[test]
    fn openrouter_base_url_without_the_api_suffix_fails_the_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Router"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[[accounts]]
display_name = "Router"
token = "t"
models = ["claude-sonnet-5"]
provider = "openrouter"
base_url = "https://openrouter.ai"
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("a bare host must not load");
        let message = err.to_string();
        assert!(
            message.contains("Router"),
            "the error has to name the offending account, got: {message}",
        );
        assert!(
            message.contains("/api"),
            "the error has to say what the base url is expected to end in, got: {message}",
        );
    }

    #[test]
    fn openrouter_base_url_with_the_api_suffix_loads() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Router"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[[accounts]]
display_name = "Router"
token = "t"
models = ["claude-sonnet-5"]
provider = "openrouter"
base_url = "https://openrouter.ai/api/"
"#,
        );
        load_from_dir(dir.path()).expect("a trailing slash after /api is still the api base");
    }

    #[test]
    fn account_rejects_an_unknown_key() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
providers = "anthropic"
"#,
        );
        // A near-miss key is the failure `provider` exists to prevent:
        // without the reject it loads, probes the wrong endpoint and
        // hangs preflight.
        let err = load_from_dir(dir.path()).expect_err("a mistyped account key must not load");
        let message = err.to_string();
        assert!(
            message.contains("providers"),
            "the error has to name the offending key, got: {message}",
        );
    }

    #[test]
    fn project_entry_rejects_an_unknown_key() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
gatewy = true
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        // The near-miss matters: a project key that loaded as nothing
        // would silently drop whatever behaviour it configured.
        let err = load_from_dir(dir.path()).expect_err("a mistyped project key must not load");
        let message = err.to_string();
        assert!(
            message.contains("gatewy"),
            "the error has to name the offending key, got: {message}",
        );
    }

    #[test]
    fn slack_section_parses_and_rejects_an_unknown_key() {
        let toml = r#"
[[slack]]
workspace = "acme"
token = "xoxp-test"
poll_seconds = 45
dm_poll_seconds = 120
thread_idle_days = 30
stale_after_hours = 6
"#;
        let parsed: ForgeToml = toml::from_str(toml).expect("slack section parses");
        assert_eq!(parsed.slack.len(), 1);
        assert_eq!(parsed.slack[0].workspace, "acme");
        assert_eq!(parsed.slack[0].poll_seconds, 45);
        assert_eq!(parsed.slack[0].dm_poll_seconds, 120);
        assert_eq!(parsed.slack[0].thread_idle_days, 30);
        assert_eq!(parsed.slack[0].stale_after_hours, 6);

        let bad = r#"
[[slack]]
workspace = "acme"
token = "xoxp-test"
poll_second = 45
"#;
        let err = toml::from_str::<ForgeToml>(bad).expect_err("a near-miss key must fail loudly");
        assert!(err.to_string().contains("poll_second"), "got: {err}");
    }

    #[test]
    fn slack_poll_seconds_defaults_to_five() {
        let toml = "[[slack]]\nworkspace = \"a\"\ntoken = \"x\"\n";
        let parsed: ForgeToml = toml::from_str(toml).expect("parses without poll_seconds");
        assert_eq!(parsed.slack[0].poll_seconds, 5);
    }

    #[test]
    fn slack_dm_poll_seconds_defaults_to_a_hundred_and_fifty() {
        let toml = "[[slack]]\nworkspace = \"a\"\ntoken = \"x\"\n";
        let parsed: ForgeToml = toml::from_str(toml).expect("parses without dm_poll_seconds");
        assert_eq!(
            parsed.slack[0].dm_poll_seconds, 150,
            "the DM class shares the token's allowance with the conversation sweep",
        );
    }

    #[test]
    fn slack_thread_idle_days_defaults_to_fourteen() {
        let toml = "[[slack]]\nworkspace = \"a\"\ntoken = \"x\"\n";
        let parsed: ForgeToml = toml::from_str(toml).expect("parses without thread_idle_days");
        assert_eq!(parsed.slack[0].thread_idle_days, 14);
    }

    #[test]
    fn slack_stale_after_hours_defaults_to_twenty_four() {
        let toml = "[[slack]]\nworkspace = \"a\"\ntoken = \"x\"\n";
        let parsed: ForgeToml = toml::from_str(toml).expect("parses without stale_after_hours");
        assert_eq!(parsed.slack[0].stale_after_hours, 24);
    }

    /// The loader runs the checks the boot's Slack build runs, so a reload
    /// cannot accept a list a restart refuses.
    #[test]
    fn load_refuses_a_slack_list_the_boot_would_refuse() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Acct"]
[[orgs.projects]]
name = "forge"
path = "/tmp/forge"
[[accounts]]
display_name = "Acct"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
[[slack]]
workspace = "same"
token = "x"
[[slack]]
workspace = "same"
token = "y"
"#,
        );

        let error = load_from_dir(dir.path()).expect_err("duplicate labels are refused");
        assert!(matches!(error, WorkspaceError::ConfigInvalid { .. }), "{error}");
        assert!(error.to_string().contains("share the label"), "{error}");
    }

    /// A project's own binding is the narrower statement, so it wins over
    /// the org's: the org key exists to save every project repeating one.
    #[test]
    fn a_projects_slack_binding_overrides_its_orgs() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Busytools"
accounts = ["Acct"]
[orgs.slack]
workspace = "org-wide"

[[orgs.projects]]
name = "forge"
path = "/tmp/forge"
[orgs.projects.slack]
workspace = "project-one"

[[accounts]]
display_name = "Acct"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
[[slack]]
workspace = "org-wide"
token = "x"
[[slack]]
workspace = "project-one"
token = "y"
"#,
        );

        let config = load_from_dir(dir.path()).expect("both labels exist");
        assert_eq!(
            named(&config, "forge").slack_workspace.as_deref(),
            Some("project-one"),
            "the project's binding is the one its sessions resolve",
        );
    }

    /// The org key's whole point: a project that names nothing inherits it.
    #[test]
    fn an_org_binding_reaches_a_project_that_names_none() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Busytools"
accounts = ["Acct"]
[orgs.slack]
workspace = "org-wide"

[[orgs.projects]]
name = "forge"
path = "/tmp/forge"

[[orgs.projects]]
name = "busymail"
path = "/tmp/busymail"

[[accounts]]
display_name = "Acct"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
[[slack]]
workspace = "org-wide"
token = "x"
"#,
        );

        let config = load_from_dir(dir.path()).expect("the org's label exists");
        assert_eq!(named(&config, "forge").slack_workspace.as_deref(), Some("org-wide"));
        assert_eq!(named(&config, "busymail").slack_workspace.as_deref(), Some("org-wide"));
    }

    /// A binding that names no `[[slack]]` entry would boot with every
    /// Slack tool dead, so it is refused, naming the label it asked for and
    /// the ones that exist.
    #[test]
    fn a_project_binding_naming_an_unknown_label_is_refused_with_both_names() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Busytools"
accounts = ["Acct"]
[[orgs.projects]]
name = "forge"
path = "/tmp/forge"
[orgs.projects.slack]
workspace = "typo"

[[accounts]]
display_name = "Acct"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
[[slack]]
workspace = "real-one"
token = "x"
"#,
        );

        let error = load_from_dir(dir.path()).expect_err("an unknown label is refused");
        let message = error.to_string();
        assert!(message.contains("[[orgs.projects]] slack"), "names the scope: {message}");
        assert!(message.contains("'typo'"), "names the label it asked for: {message}");
        assert!(message.contains("real-one"), "names the labels that exist: {message}");
    }

    #[test]
    fn an_org_binding_naming_an_unknown_label_is_refused_with_both_names() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Busytools"
accounts = ["Acct"]
[orgs.slack]
workspace = "typo"
[[orgs.projects]]
name = "forge"
path = "/tmp/forge"

[[accounts]]
display_name = "Acct"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
[[slack]]
workspace = "real-one"
token = "x"
"#,
        );

        let error = load_from_dir(dir.path()).expect_err("an unknown label is refused");
        let message = error.to_string();
        assert!(message.contains("[[orgs]] slack"), "names the scope: {message}");
        assert!(message.contains("'typo'"), "names the label it asked for: {message}");
        assert!(message.contains("real-one"), "names the labels that exist: {message}");
    }

    /// A padded label is the same label: `[[slack]]` labels are matched
    /// trimmed, so a binding is too, and the stored value is the trimmed
    /// one every later lookup uses.
    #[test]
    fn a_slack_binding_label_is_trimmed_before_it_is_matched() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Busytools"
accounts = ["Acct"]
[[orgs.projects]]
name = "forge"
path = "/tmp/forge"
[orgs.projects.slack]
workspace = "  acme  "

[[accounts]]
display_name = "Acct"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
[[slack]]
workspace = "acme"
token = "x"
"#,
        );

        let config = load_from_dir(dir.path()).expect("the padded label matches");
        assert_eq!(
            named(&config, "forge").slack_workspace.as_deref(),
            Some("acme"),
            "the stored label is the trimmed one the clients are keyed by",
        );
    }

    /// A binding with no `[[slack]]` section at all is still refused, and
    /// the message says there is nothing to bind to rather than printing an
    /// empty list.
    #[test]
    fn a_binding_with_no_slack_entries_says_none_are_configured() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Busytools"
accounts = ["Acct"]
[[orgs.projects]]
name = "forge"
path = "/tmp/forge"
[orgs.projects.slack]
workspace = "acme"

[[accounts]]
display_name = "Acct"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );

        let error = load_from_dir(dir.path()).expect_err("there is no label to bind to");
        assert!(
            error.to_string().contains("configured: none"),
            "the message says the file configures no workspace: {error}",
        );
    }

    #[test]
    fn a_whitespace_only_base_url_is_not_a_base_url() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Codex"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[[accounts]]
display_name = "Codex"
token = "t"
models = ["claude-sonnet-5"]
provider = "codex"
base_url = "   "
"#,
        );
        let err =
            load_from_dir(dir.path()).expect_err("a blank base url must not satisfy the check");
        assert!(err.to_string().contains("base_url"), "got: {err}");
    }

    #[test]
    fn account_without_env_table_stamps_the_derived_credential() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("happy path");
        let account = &config.accounts[0];
        // The flat token maps onto the provider's credential variable -
        // the only key an account without [accounts.env] carries.
        assert_eq!(
            account.env.get("CLAUDE_CODE_OAUTH_TOKEN").map(String::as_str),
            Some("t"),
            "the flat token lands on the provider's credential variable",
        );
        assert_eq!(account.env.len(), 1, "nothing else is injected");
    }

    /// A gateway key declared in an env layer is dropped rather than
    /// refused, and dropped from every layer, so it cannot reach the
    /// pool. The stamp covers the child's env only, and the pool's env
    /// is what the forward leg reads the upstream and the credential
    /// out of: a base URL left there would send real traffic, with the
    /// real credential attached, somewhere the config never named.
    #[test]
    fn a_gateway_key_in_an_env_layer_never_reaches_the_account_env() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[env]
ANTHROPIC_BASE_URL = "https://proxy.example"
ANTHROPIC_API_KEY = "sk-global"

[[orgs]]
name = "Personal"
accounts = ["Personal", "Scratch"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[[accounts]]
display_name = "Personal"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
[accounts.env]
ANTHROPIC_AUTH_TOKEN = "t2"
ANTHROPIC_API_KEY = "   "
[[accounts]]
display_name = "Scratch"
token = "t3"
models = ["claude-sonnet-5"]
provider = "codex"
base_url = "http://localhost:18765"
"#,
        );
        let config = load_from_dir(dir.path()).expect("a gateway env key is not refused");
        let personal = config.accounts.iter().find(|a| a.display_name == "Personal").expect("one");
        for key in ["ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_API_KEY"] {
            assert!(
                !personal.env.contains_key(key),
                "{key} must not survive into the account env the pool and the forward leg read",
            );
        }
        assert_eq!(
            personal.env.get("CLAUDE_CODE_OAUTH_TOKEN").map(String::as_str),
            Some("t"),
            "the flat token still lands on the account's own variable",
        );
        // The scrub runs before the flat keys are mapped, so a base-url
        // account keeps its own endpoint rather than losing it too.
        let scratch = config.accounts.iter().find(|a| a.display_name == "Scratch").expect("one");
        assert_eq!(
            scratch.env.get("ANTHROPIC_BASE_URL").map(String::as_str),
            Some("http://localhost:18765"),
            "the flat base_url is mapped after the scrub, so it still lands",
        );
    }

    /// A `{:?}` on the loaded config or on the raw `ForgeToml` must
    /// print no credential: the global env, the accounts' env stamps and
    /// flat token, a project's env values, the gotify client token and the
    /// systemone api key all stay out of it.
    #[test]
    fn a_credential_never_reaches_the_config_debug_output() {
        let toml = r#"
[env]
MY_GLOBAL_SECRET = "global-supersecret"

[[orgs]]
name = "Personal"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[orgs.projects.env]
CLAUDE_CODE_OAUTH_TOKEN = "project-supersecret"

[[accounts]]
display_name = "Stargate"
token = "account-supersecret"
models = ["claude-sonnet-5"]
provider = "anthropic"
[accounts.env]
MY_ACCOUNT_SECRET = "account-env-supersecret"

[gotify]
url = "https://notifier.example"
client_token = "gotify-supersecret"

[systemone]
base_url = "https://api.typesafe.ai"
api_key = "systemone-supersecret"
model = "jev-latest"
"#;
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), toml);
        let config = load_from_dir(dir.path()).expect("the config loads");
        let parsed: ForgeToml = toml::from_str(toml).expect("the raw config parses");
        for rendered in [format!("{config:?}"), format!("{parsed:?}")] {
            for (carrier, secret) in [
                ("the global env value", "global-supersecret"),
                ("the account env value", "account-env-supersecret"),
                ("the account's credential stamp", "account-supersecret"),
                ("a project env value", "project-supersecret"),
                ("the gotify client token", "gotify-supersecret"),
                ("the systemone api key", "systemone-supersecret"),
            ] {
                assert!(!rendered.contains(secret), "{carrier} leaked: {rendered}");
            }
            for (carrier, readable) in [
                ("the org name", "Personal"),
                ("the account name", "Stargate"),
                ("the project name", "forge"),
                ("the gotify url", "notifier.example"),
                ("the systemone base url", "api.typesafe.ai"),
            ] {
                assert!(rendered.contains(readable), "{carrier} must stay readable: {rendered}");
            }
        }
    }

    #[test]
    fn an_account_without_a_token_fails_the_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Codex"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[[accounts]]
display_name = "Codex"
models = ["claude-sonnet-5"]
provider = "codex"
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("a tokenless account must not load");
        let message = err.to_string();
        assert!(
            message.contains("Codex") && message.contains("token"),
            "the error names the account and the missing key, got: {message}",
        );
    }

    #[test]
    fn an_account_without_models_fails_the_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Codex"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[[accounts]]
display_name = "Codex"
token = "t"
provider = "codex"
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("a modelless account must not load");
        let message = err.to_string();
        assert!(
            message.contains("models"),
            "the error names the missing declaration, got: {message}",
        );
    }

    #[test]
    fn a_slug_for_an_undeclared_model_fails_the_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Codex"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[[accounts]]
display_name = "Codex"
token = "t"
models = ["claude-sonnet-5"]
provider = "codex"
base_url = "http://localhost:18765"
[accounts.model_slugs]
"deepseek/deepseek-v4.1-flash" = "deepseek/deepseek-v4.1-flash"
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("an undeclared slug key must not load");
        let message = err.to_string();
        assert!(
            message.contains("deepseek/deepseek-v4.1-flash"),
            "the error names the undeclared slug key, got: {message}",
        );
    }

    #[test]
    fn project_permission_mode_defaults_to_auto_when_absent() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("absent key must not block the load");
        assert_eq!(
            config.projects[0].permission_mode,
            PermissionMode::Auto,
            "a project with no per-project keys at all still lands on auto",
        );
    }

    #[test]
    fn project_permission_mode_defaults_to_auto_when_the_table_omits_it() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
max_workers = 2
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let config = load_from_dir(dir.path()).expect("a table without the key loads");
        assert_eq!(
            config.projects[0].permission_mode,
            PermissionMode::Auto,
            "a project whose table omits the key gets auto, not the launcher default",
        );
    }

    #[test]
    fn project_permission_mode_parses_an_explicit_value() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
permission_mode = "bypassPermissions"
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let config = load_from_dir(dir.path()).expect("happy path");
        assert_eq!(
            config.projects[0].permission_mode,
            PermissionMode::BypassPermissions,
            "a valid mode lands on the LoadedProject verbatim",
        );
    }

    #[test]
    fn project_permission_mode_accepts_the_snake_case_alias() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
permission_mode = "bypass_permissions"
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let config = load_from_dir(dir.path()).expect("the from_wire aliases still work");
        assert_eq!(
            config.projects[0].permission_mode,
            PermissionMode::BypassPermissions,
            "the alias set must not shrink now the key moved tables",
        );
    }

    #[test]
    fn project_with_invalid_permission_mode_fails_naming_the_accepted_set() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
permission_mode = "yolo"
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("an invalid mode must not load");
        let message = err.to_string();
        assert!(
            message.contains("yolo") && message.contains("forge"),
            "the error has to name the offending value and project, got: {message}",
        );
        assert!(
            message.contains("bypassPermissions") && message.contains("acceptEdits"),
            "the error has to list the accepted values, got: {message}",
        );
    }

    #[test]
    fn mistyped_permission_mode_key_is_still_rejected() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
permissionmode = "bypassPermissions"
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("a mistyped project key must not load");
        assert!(
            err.to_string().contains("permissionmode"),
            "deny_unknown_fields has to catch the near-miss, got: {err}",
        );
    }

    /// The four sections that used to ignore an unknown key. A
    /// misspelled `fallback_accounts` parses clean as "no fallbacks",
    /// which is a silent behaviour change from a typo rather than a
    /// refused boot.
    #[test]
    fn mistyped_keys_are_rejected_in_every_section() {
        let base = minimal_config();
        // (label, config text with the near-miss, the key the error must name)
        let cases = [
            ("top level", format!("mistyped = 1\n{base}"), "mistyped"),
            (
                "an org entry",
                base.replacen(
                    "accounts = [\"Stargate\"]",
                    "accounts = [\"Stargate\"]\nfallback_account = \"Stargate\"",
                    1,
                ),
                "fallback_account",
            ),
            (
                "[gotify]",
                format!("{base}\n[gotify]\nurl = \"https://notifier\"\nclient_tokens = \"t\"\n"),
                "client_tokens",
            ),
            (
                "[systemone]",
                format!(
                    "{base}\n[systemone]\nendpoint = \"https://api.typesafe.ai\"\nbase_url = \"https://api.typesafe.ai\"\nmodel = \"jev-latest\"\n"
                ),
                "endpoint",
            ),
            (
                "[client]",
                format!("{base}\n[client]\nbrowser_idle_minutes = 45\n"),
                "browser_idle_minutes",
            ),
        ];
        // Collected rather than asserted one at a time: a section that
        // started ignoring keys again should be named alongside the
        // rest, not hide behind the first.
        let mut failures: Vec<String> = Vec::new();
        for (label, text, needle) in cases {
            let dir = tempdir().expect("tempdir");
            write_config(dir.path(), &text);
            match load_from_dir(dir.path()) {
                Ok(_) => failures.push(format!("{label}: loaded with `{needle}` in it")),
                Err(err) if !err.to_string().contains(needle) => {
                    failures.push(format!("{label}: error does not name `{needle}`: {err}"));
                }
                Err(_) => {}
            }
        }
        assert!(
            failures.is_empty(),
            "every near-miss is refused and named:\n{}",
            failures.join("\n")
        );
    }

    #[test]
    fn parses_top_level_env_table() {
        let raw =
            format!("[env]\nCLAUDE_CODE_AUTO_COMPACT_WINDOW = \"950000\"\n{}", minimal_config());
        let parsed: ForgeToml = toml::from_str(&raw).expect("parse top-level [env]");
        assert_eq!(
            parsed.env.get("CLAUDE_CODE_AUTO_COMPACT_WINDOW").map(String::as_str),
            Some("950000"),
        );
    }

    #[test]
    fn absent_top_level_env_table_is_empty() {
        let parsed: ForgeToml = toml::from_str(minimal_config()).expect("parse without [env]");
        assert!(parsed.env.is_empty(), "no [env] -> empty map");
    }

    #[test]
    fn global_env_lands_in_account_without_its_own_env() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[env]
CLAUDE_CODE_AUTO_COMPACT_WINDOW = "950000"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let config = load_from_dir(dir.path()).expect("happy path");
        let account = &config.accounts[0];
        assert_eq!(
            account.env.get("CLAUDE_CODE_AUTO_COMPACT_WINDOW").map(String::as_str),
            Some("950000"),
            "global [env] key merged into an account with no [accounts.env]",
        );
    }

    #[test]
    fn account_env_overrides_global_env_per_key() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[env]
CLAUDE_CODE_AUTO_COMPACT_WINDOW = "950000"
[[orgs]]
name = "Personal"
accounts = ["Codex", "Gateway"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[[accounts]]
display_name = "Codex"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
[accounts.env]
CLAUDE_CODE_AUTO_COMPACT_WINDOW = "372000"
[[accounts]]
display_name = "Gateway"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let config = load_from_dir(dir.path()).expect("happy path");
        let codex = config.accounts.iter().find(|a| a.display_name == "Codex").expect("Codex");
        let gateway =
            config.accounts.iter().find(|a| a.display_name == "Gateway").expect("Gateway");
        assert_eq!(
            codex.env.get("CLAUDE_CODE_AUTO_COMPACT_WINDOW").map(String::as_str),
            Some("372000"),
            "per-account [accounts.env] overrides the global [env] key",
        );
        assert_eq!(
            gateway.env.get("CLAUDE_CODE_AUTO_COMPACT_WINDOW").map(String::as_str),
            Some("950000"),
            "an account with no override inherits the global [env] key",
        );
    }

    #[test]
    fn whitespace_padded_setup_token_is_trimmed_once_at_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[orgs.projects.env]
CLAUDE_CODE_OAUTH_TOKEN = "  sk-ant-oat01-project  "

[[accounts]]
display_name = "Stargate"
token = "  sk-ant-oat01-stargate  "
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let config = load_from_dir(dir.path()).expect("happy path");
        let account = &config.accounts[0];
        // The probe reads this map through `token_bearer` and the spawn
        // path stamps it onto the child verbatim; both must see the
        // same credential.
        assert_eq!(
            account.env.get("CLAUDE_CODE_OAUTH_TOKEN").map(String::as_str),
            Some("sk-ant-oat01-stargate"),
            "the setup token is trimmed where it enters the config",
        );
        assert_eq!(
            forge_gateway::token_bearer(&account.env),
            Some("sk-ant-oat01-stargate"),
            "the probe reads the same trimmed credential the child gets",
        );
        assert_eq!(
            config.projects[0].env.get("CLAUDE_CODE_OAUTH_TOKEN").map(String::as_str),
            Some("sk-ant-oat01-project"),
            "the project env layer is trimmed at load too - it reaches the child unmerged",
        );
    }

    #[test]
    fn no_global_env_leaves_account_env_untouched() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Codex"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[[accounts]]
display_name = "Codex"
token = "t"
models = ["claude-sonnet-5"]
provider = "codex"
base_url = "http://localhost:18765"
"#,
        );
        let config = load_from_dir(dir.path()).expect("happy path");
        let account = &config.accounts[0];
        assert_eq!(account.env.len(), 2, "no [env] -> env is exactly the derived stamps");
        assert_eq!(
            account.env.get("ANTHROPIC_BASE_URL").map(String::as_str),
            Some("http://localhost:18765"),
        );
        assert_eq!(account.env.get("ANTHROPIC_AUTH_TOKEN").map(String::as_str), Some("t"),);
    }

    /// One key per precedence boundary, so a test can assert a single
    /// boundary and a future reordering of the merge fails on exactly
    /// the boundary it broke.
    fn precedence_config() -> &'static str {
        r#"
[env]
ALL_THREE = "global"
GLOBAL_PROJECT = "global"
GLOBAL_ONLY = "global"

[[orgs]]
name = "Personal"
accounts = ["Codex"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
env = { ALL_THREE = "project", GLOBAL_PROJECT = "project", PROJECT_ONLY = "project" }

[[accounts]]
display_name = "Codex"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
[accounts.env]
ALL_THREE = "account"
"#
    }

    /// `session_env` for the fixture's single project + account.
    fn precedence_env() -> HashMap<String, String> {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), precedence_config());
        let config = load_from_dir(dir.path()).expect("precedence fixture loads");
        let account = &config.accounts[0];
        session_env(named(&config, "forge"), &account.env)
    }

    /// Every near-miss shape for declaring project env. Each loads
    /// clean and applies nothing without the `deny_unknown_fields`
    /// attributes; the point of the table is that they are all one
    /// class rather than five separate bugs.
    #[test]
    fn near_miss_env_declarations_are_rejected() {
        // (label, stanza appended to the base config, text the error must name)
        let cases = [("mistyped inner table", "envs = { K = \"v\" }\n", "envs")];
        for (label, stanza, needle) in cases {
            let dir = tempdir().expect("tempdir");
            write_config(dir.path(), &format!("{}\n{stanza}", minimal_config()));
            let msg = load_from_dir(dir.path()).expect_err(label).to_string();
            assert!(msg.contains(needle), "{label}: error must name `{needle}`, got: {msg}");
        }
    }

    /// Write an env file and a config pointing at it. Returns the dir
    /// so it outlives the load.
    fn config_with_env_file(contents: &str, inline: &str) -> tempfile::TempDir {
        let dir = tempdir().expect("tempdir");
        let file = dir.path().join("secrets.env");
        fs::write(&file, contents).expect("write env file");
        // The inline parameter is an `env` entry fragment when set: the
        // collocated shape carries the env inline table on the entry.
        let inline_line =
            if inline.is_empty() { String::new() } else { format!("\nenv = {{ {inline} }}") };
        write_config(
            dir.path(),
            &format!(
                r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
env_file = "{file}"{inline_line}
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
                file = file.display()
            ),
        );
        dir
    }

    #[test]
    fn env_file_entries_join_the_project_env() {
        let dir = config_with_env_file(
            "# a comment\n\nAIRMAIL_TOKEN = tok-from-file\nQUOTED = \"in-quotes\"\n\
             SINGLE = 'in-singles'\nUNMATCHED = \"dangling\n",
            "",
        );
        let config = load_from_dir(dir.path()).expect("happy path");
        let env = &config.projects[0].env;
        assert_eq!(
            env.get("AIRMAIL_TOKEN").map(String::as_str),
            Some("tok-from-file"),
            "comments and blank lines skipped, the key lands",
        );
        // Quoted is the shape a value moved out of forge.toml arrives in.
        assert_eq!(env.get("QUOTED").map(String::as_str), Some("in-quotes"));
        assert_eq!(env.get("SINGLE").map(String::as_str), Some("in-singles"));
        assert_eq!(
            env.get("UNMATCHED").map(String::as_str),
            Some("\"dangling"),
            "an unmatched quote is part of the value, not a delimiter",
        );
    }

    #[test]
    fn the_inline_table_wins_over_the_env_file_per_key() {
        let dir = config_with_env_file(
            "SHARED = from-file\nFILE_ONLY = from-file\n",
            "SHARED = \"from-inline\"",
        );
        let config = load_from_dir(dir.path()).expect("happy path");
        let env = &config.projects[0].env;
        assert_eq!(env.get("SHARED").map(String::as_str), Some("from-inline"));
        assert_eq!(env.get("FILE_ONLY").map(String::as_str), Some("from-file"));
    }

    #[test]
    fn a_missing_env_file_leaves_the_project_env_empty_and_still_loads() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!(
                r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
env_file = "{}/nope.env"
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
                dir.path().display()
            ),
        );
        let config = load_from_dir(dir.path()).expect("a missing env file must not fail the load");
        assert!(config.projects[0].env.is_empty(), "and contributes no keys");
    }

    #[test]
    fn a_malformed_line_is_skipped_and_the_rest_applies() {
        let dir = config_with_env_file("GOOD = yes\nthis line has no equals\nALSO = fine\n", "");
        let config = load_from_dir(dir.path()).expect("happy path");
        let env = &config.projects[0].env;
        assert_eq!(env.get("GOOD").map(String::as_str), Some("yes"));
        assert_eq!(env.get("ALSO").map(String::as_str), Some("fine"));
        assert_eq!(env.len(), 2, "only the malformed line is dropped: {env:?}");
    }

    #[test]
    fn parses_project_env_table() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
env = { AIRMAIL_MCP_URL = "https://mail.example/mcp" }
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let config = load_from_dir(dir.path()).expect("happy path");
        let project = &config.projects[0];
        assert_eq!(
            project.env.get("AIRMAIL_MCP_URL").map(String::as_str),
            Some("https://mail.example/mcp"),
            "the project env block lands on the named project",
        );
    }

    /// An env block naming a project that no `[[orgs.projects]]`
    /// declares is the same typo class as an org naming an undeclared
    /// account, which `load_from_dir` already refuses to boot on. A
    /// silently-ignored env block is the failure mode #551 exists to
    /// kill, so it must not load.
    /// One assertion per precedence boundary, so a reordering fails on
    /// the boundary it broke rather than on a single opaque test.
    #[test]
    fn project_env_wins_each_precedence_boundary() {
        let env = precedence_env();
        assert_eq!(
            env.get("ALL_THREE").map(String::as_str),
            Some("project"),
            "a key in all three layers resolves to the project value",
        );
        assert_eq!(
            env.get("GLOBAL_PROJECT").map(String::as_str),
            Some("project"),
            "global + project, account silent -> project wins",
        );
        assert_eq!(
            env.get("PROJECT_ONLY").map(String::as_str),
            Some("project"),
            "a project-only key reaches the session",
        );
        assert_eq!(
            env.get("GLOBAL_ONLY").map(String::as_str),
            Some("global"),
            "and the global layer still arrives, so the above are overrides not absences",
        );
    }

    /// **A seat's children start from the server's own environment.** The
    /// `claude` child inherits it; a terminal's shell is handed a map, so
    /// without this set it has no `HOME` and the shell integration reads the
    /// person's rc from nowhere. The config tables still win over it.
    #[test]
    fn seat_env_carries_the_servers_own_environment_below_the_config_tables() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), precedence_config());
        let config = load_from_dir(dir.path()).expect("precedence fixture loads");
        let account = &config.accounts[0];
        let env = seat_env(named(&config, "forge"), &account.env);
        let home = std::env::var("HOME").expect("the test process has a HOME");
        assert_eq!(env.get("HOME"), Some(&home), "the server's own HOME survives");
        assert_eq!(
            env.get("ALL_THREE").map(String::as_str),
            Some("project"),
            "and the project's table still overrides it",
        );
    }

    /// Two projects on one account, one declaring env. The other must
    /// not receive it.
    #[test]
    fn one_projects_env_does_not_reach_another_on_the_same_account() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Codex"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
env = { AIRMAIL_TOKEN = "forge-only-secret" }
[[orgs.projects]]
name = "airmail"
path = "~/Projects/airmail"

[[accounts]]
display_name = "Codex"
token = "t"
models = ["claude-sonnet-5"]
provider = "codex"
base_url = "http://localhost:18765"
"#,
        );
        let config = load_from_dir(dir.path()).expect("happy path");
        let account = &config.accounts[0];

        let forge_env = session_env(named(&config, "forge"), &account.env);
        assert_eq!(
            forge_env.get("AIRMAIL_TOKEN").map(String::as_str),
            Some("forge-only-secret"),
            "the declaring project gets its own key",
        );

        let airmail_env = session_env(named(&config, "airmail"), &account.env);
        assert!(
            !airmail_env.contains_key("AIRMAIL_TOKEN"),
            "another project on the SAME account must not receive it, got: {airmail_env:?}",
        );
        assert_eq!(
            airmail_env, account.env,
            "a project declaring no env gets exactly the account env, nothing borrowed",
        );
    }

    /// The collocation's load-bearing mechanic: each block-form env
    /// attaches to the most recent `[[orgs.projects]]` header, so two
    /// env blocks under two entries land on their OWN projects. The
    /// single-project form cannot pin this - with one project there is
    /// nothing to mis-attach to.
    #[test]
    fn two_block_form_envs_attach_to_their_own_entries() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Codex"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[orgs.projects.env]
FORGE_KEY = "forge-secret"
[[orgs.projects]]
name = "airmail"
path = "~/Projects/airmail"

[orgs.projects.env]
AIRMAIL_KEY = "airmail-secret"
[[accounts]]
display_name = "Codex"
token = "t"
models = ["claude-sonnet-5"]
provider = "codex"
base_url = "http://localhost:18765"
"#,
        );
        let config = load_from_dir(dir.path()).expect("happy path");
        let forge = config.projects.iter().find(|p| p.name == "forge").expect("forge");
        let airmail = config.projects.iter().find(|p| p.name == "airmail").expect("airmail");
        assert_eq!(
            forge.env.get("FORGE_KEY").map(String::as_str),
            Some("forge-secret"),
            "the first entry's env block attaches to the first project",
        );
        assert!(
            !forge.env.contains_key("AIRMAIL_KEY"),
            "the second block must not leak onto the first project: {:?}",
            forge.env,
        );
        assert_eq!(
            airmail.env.get("AIRMAIL_KEY").map(String::as_str),
            Some("airmail-secret"),
            "the second entry's env block attaches to the second project",
        );
        assert!(
            !airmail.env.contains_key("FORGE_KEY"),
            "the first block must not leak onto the second project: {:?}",
            airmail.env,
        );
    }

    #[test]
    fn parses_gotify_block() {
        let dir = tempdir().expect("tempdir");
        let raw = format!(
            "{}\n[gotify]\nurl = \"https://g.example\"\nclient_token = \"Cabc\"\n",
            minimal_config()
        );
        write_config(dir.path(), &raw);
        let config = load_from_dir(dir.path()).expect("happy path");
        assert_eq!(
            config.gotify,
            Some(forge_primitives::GotifyConfig {
                url: "https://g.example".to_owned(),
                client_token: "Cabc".to_owned(),
            })
        );
    }

    /// The `[dictate]` plumbing leg, which the section's own serde tests
    /// cannot reach: a `parsed.dictate` never threaded into
    /// `LoadedConfig` leaves dictation off however the user writes
    /// forge.toml, and every one of those tests still passes.
    #[test]
    fn the_dictate_section_reaches_the_loaded_config() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!("{}\n[dictate]\nenabled = true\nlanguage = \"en\"\n", minimal_config()),
        );
        let config = load_from_dir(dir.path()).expect("happy path");
        assert!(config.dictate.enabled, "an explicit `enabled = true` must survive the load");
        assert_eq!(config.dictate.language.as_deref(), Some("en"));

        let bare = tempdir().expect("tempdir");
        write_config(bare.path(), minimal_config());
        let config = load_from_dir(bare.path()).expect("happy path");
        assert!(!config.dictate.enabled, "an absent section must leave dictation off");
    }

    /// The speaking model and the voice reach the loaded config, and a model
    /// nothing installs refuses the boot by the name the file used.
    #[test]
    fn the_tts_model_and_voice_reach_the_loaded_config() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!(
                "{}\n[tts]\nspeaking_model = \"hexgrad/Kokoro-82M\"\nvoice = \"bf_emma\"\n",
                minimal_config()
            ),
        );
        let config = load_from_dir(dir.path()).expect("happy path");
        assert_eq!(config.tts.speaking_model.as_deref(), Some("hexgrad/Kokoro-82M"));
        assert_eq!(config.tts.voice.as_deref(), Some("bf_emma"));

        let unknown = tempdir().expect("tempdir");
        write_config(
            unknown.path(),
            &format!("{}\n[tts]\nspeaking_model = \"hexgrad/Kokoro-90M\"\n", minimal_config()),
        );
        let error = load_from_dir(unknown.path()).expect_err("an unknown model fails the load");
        let text = error.to_string();
        assert!(text.contains("hexgrad/Kokoro-90M"), "got: {text}");
        assert!(text.contains("speaking_model"), "got: {text}");
    }

    #[test]
    fn absent_gotify_block_is_none() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("happy path");
        assert_eq!(config.gotify, None);
    }

    #[test]
    fn parses_systemone_block() {
        let dir = tempdir().expect("tempdir");
        let raw = format!(
            "{}\n[systemone]\nbase_url = \"https://api.typesafe.ai\"\napi_key = \"ts-key\"\nmodel = \"jev-latest\"\ntimeout_ms = 15000\n",
            minimal_config()
        );
        write_config(dir.path(), &raw);
        let config = load_from_dir(dir.path()).expect("happy path");
        assert_eq!(
            config.systemone,
            Some(forge_system_one::SystemOneConfig {
                base_url: "https://api.typesafe.ai".to_owned(),
                api_key: Some("ts-key".to_owned()),
                model: "jev-latest".to_owned(),
                timeout_ms: 15_000,
            })
        );
    }

    #[test]
    fn absent_systemone_block_is_none() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("happy path");
        assert_eq!(config.systemone, None);
    }

    #[test]
    fn disabled_systemone_block_is_none() {
        let dir = tempdir().expect("tempdir");
        let raw = format!(
            "{}\n[systemone]\nenabled = false\nbase_url = \"https://api.typesafe.ai\"\nmodel = \"jev-latest\"\n",
            minimal_config()
        );
        write_config(dir.path(), &raw);
        let config = load_from_dir(dir.path()).expect("a disabled section loads");
        assert_eq!(config.systemone, None);
    }

    #[test]
    fn enabled_systemone_without_base_url_is_refused() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!("{}\n[systemone]\nmodel = \"jev-latest\"\n", minimal_config()),
        );
        let err = load_from_dir(dir.path()).expect_err("an enabled section needs a base_url");
        assert!(err.to_string().contains("[systemone] `base_url` is required"), "{err}");
    }

    #[test]
    fn systemone_without_model_is_refused() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!("{}\n[systemone]\nbase_url = \"https://api.typesafe.ai\"\n", minimal_config()),
        );
        let err = load_from_dir(dir.path()).expect_err("an enabled section needs a model");
        assert!(err.to_string().contains("[systemone] `model` is required"), "{err}");
    }

    #[test]
    fn zero_systemone_timeout_is_refused() {
        let dir = tempdir().expect("tempdir");
        let raw = format!(
            "{}\n[systemone]\nbase_url = \"https://api.typesafe.ai\"\nmodel = \"jev-latest\"\ntimeout_ms = 0\n",
            minimal_config()
        );
        write_config(dir.path(), &raw);
        let err = load_from_dir(dir.path()).expect_err("a zero timeout is refused");
        assert!(
            err.to_string().contains("[systemone] `timeout_ms` must be greater than zero"),
            "{err}"
        );
    }

    /// The account's email is the salt the master key derives with, so it is
    /// not printed in a Debug line about the section.
    #[test]
    fn the_vault_config_debug_redacts_the_email() {
        let config = VaultConfig {
            url: "https://vault.example.com".to_owned(),
            email: "me@example.com".to_owned(),
            idle_minutes: None,
        };

        let text = format!("{config:?}");

        assert!(!text.contains("me@example.com"), "{text}");
        assert!(text.contains("https://vault.example.com"), "{text}");
    }

    #[test]
    fn parses_a_vault_block() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!(
                "{}\n[vault]\nurl = \"https://bitwarden.hub\"\nemail = \"hi@vedhavyas.dev\"\nidle_minutes = 30\n",
                minimal_config()
            ),
        );
        let config = load_from_dir(dir.path()).expect("a complete section loads");
        let vault = config.vault.expect("the section reaches the loaded config");
        assert_eq!(vault.url, "https://bitwarden.hub");
        assert_eq!(vault.email, "hi@vedhavyas.dev");
        assert_eq!(vault.idle_minutes, Some(30));
    }

    #[test]
    fn an_absent_idle_bound_is_no_idle_lock() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!(
                "{}\n[vault]\nurl = \"https://bitwarden.hub\"\nemail = \"hi@vedhavyas.dev\"\n",
                minimal_config()
            ),
        );
        let config = load_from_dir(dir.path()).expect("a complete section loads");
        assert_eq!(config.vault.expect("the section reaches the loaded config").idle_minutes, None,);
    }

    #[test]
    fn a_zero_idle_bound_is_refused() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!(
                "{}\n[vault]\nurl = \"https://bitwarden.hub\"\nemail = \"hi@vedhavyas.dev\"\nidle_minutes = 0\n",
                minimal_config()
            ),
        );
        let err = load_from_dir(dir.path()).expect_err("zero would lock instantly");
        assert!(err.to_string().contains("`idle_minutes` must be at least 1"), "{err}");
    }

    #[test]
    fn absent_vault_block_is_none() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("happy path");
        assert_eq!(config.vault, None, "an absent section injects no vault tools");
    }

    #[test]
    fn a_plain_http_vault_url_is_refused() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!(
                "{}\n[vault]\nurl = \"http://bitwarden.hub\"\nemail = \"hi@vedhavyas.dev\"\n",
                minimal_config()
            ),
        );
        let err = load_from_dir(dir.path()).expect_err("http is refused");
        assert!(err.to_string().contains("https://"), "{err}");
    }

    #[test]
    fn vault_without_url_is_refused() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!("{}\n[vault]\nemail = \"hi@vedhavyas.dev\"\n", minimal_config()),
        );
        let err = load_from_dir(dir.path()).expect_err("a section needs a url");
        assert!(err.to_string().contains("[vault] `url` is required"), "{err}");
    }

    #[test]
    fn vault_without_email_is_refused() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!("{}\n[vault]\nurl = \"https://bitwarden.hub\"\n", minimal_config()),
        );
        let err = load_from_dir(dir.path()).expect_err("a section needs an email");
        assert!(err.to_string().contains("[vault] `email` is required"), "{err}");
    }

    #[test]
    fn the_plugins_section_reaches_the_loaded_config() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), &format!("{}\n[plugins]\nauto_update = true\n", minimal_config()));
        let config = load_from_dir(dir.path()).expect("happy path");
        assert!(config.plugins.auto_update);
    }

    #[test]
    fn a_stale_plugins_key_fails_the_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!(
                "{}\n[plugins]\nauto_update = true\ntrusted_marketplaces = \
                 [\"claude-plugins-official\"]\n",
                minimal_config()
            ),
        );
        assert!(
            load_from_dir(dir.path()).is_err(),
            "removed keys are rejected, not silently ignored"
        );
    }

    #[test]
    fn absent_plugins_section_auto_update_is_off() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("happy path");
        assert!(!config.plugins.auto_update);
    }

    #[test]
    fn an_unknown_plugins_key_fails_the_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &format!("{}\n[plugins]\ntrust_markets = [\"x\"]\n", minimal_config()),
        );
        let error = load_from_dir(dir.path()).expect_err("unknown key must fail loudly");
        assert!(error.to_string().contains("trust_markets"), "names the key: {error}");
    }

    #[test]
    fn the_projects_max_workers_key_reaches_the_loaded_project() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
max_workers = 4

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let config = load_from_dir(dir.path()).expect("happy path");
        assert_eq!(config.default_project().max_workers, Some(4));
    }

    #[test]
    fn absent_max_workers_leaves_the_project_at_the_default() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("happy path");
        assert_eq!(config.default_project().max_workers, None);
    }

    #[test]
    fn a_negative_max_workers_fails_the_load() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
max_workers = -1

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let error = load_from_dir(dir.path()).expect_err("a bad value must fail loudly");
        assert!(error.to_string().contains("max_workers"), "names the key: {error}");
    }

    #[test]
    fn forge_data_dir_is_the_forge_subfolder() {
        let dir = tempdir().expect("tempdir");
        assert_eq!(forge_data_dir(dir.path()), dir.path().join("forge"));
    }

    #[test]
    fn ensure_forge_data_dir_creates_the_subfolder() {
        let dir = tempdir().expect("tempdir");
        let created = ensure_forge_data_dir(dir.path()).expect("create forge/");
        assert_eq!(created, dir.path().join("forge"));
        assert!(created.is_dir(), "forge/ exists after ensure");
    }

    #[test]
    fn parses_minimal_config() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("happy path");
        assert_eq!(config.projects.len(), 1);
        assert_eq!(config.default_project().name, "forge");
        assert_eq!(config.default_project().org, "Personal");
        assert_eq!(config.default_project().accounts, vec!["Stargate"]);
    }

    #[test]
    fn missing_file_returns_config_missing() {
        let dir = tempdir().expect("tempdir");
        let err = load_from_dir(dir.path()).expect_err("missing should error");
        assert!(matches!(err, WorkspaceError::ConfigMissing { .. }));
    }

    #[test]
    fn reads_forge_toml_from_forge_subfolder() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("loads from forge/");
        assert_eq!(config.default_project().name, "forge");
    }

    #[test]
    fn malformed_toml_returns_config_parse() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), "not valid = = toml");
        let err = load_from_dir(dir.path()).expect_err("malformed should error");
        assert!(matches!(err, WorkspaceError::ConfigParse { .. }));
    }

    /// **A parse failure prints neither the line it failed on nor the value
    /// it read** (#2267): the error used to render `toml`'s snippet of the
    /// offending line, so a mistyped key on the token's own line echoed the
    /// token to stderr on the next boot. The key, the reason and the
    /// position are the three things a reader fixes it with; the value is
    /// not one of them.
    #[test]
    fn a_parse_failure_never_prints_the_value() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            "[[accounts]]\ndisplay_name = \"Stargate\"\nclient_tokenn = \"hunter2secret\"\n",
        );
        let err = load_from_dir(dir.path()).expect_err("the near-miss key fails loudly");
        let said = err.to_string();
        assert!(said.contains("client_tokenn"), "the key still names what to fix: {said}");
        assert!(!said.contains("hunter2secret"), "the value on the line never prints: {said}");
        assert!(said.contains("line 3"), "the position says where: {said}");
    }

    /// The other shape the snippet padded out: serde's own words quote the
    /// VALUE of a type mismatch (`invalid type: string "…"`), and those
    /// words survive the snippet's removal - so they are scrubbed too, while
    /// a key name (backtick-quoted) stays legible.
    #[test]
    fn a_type_mismatch_never_prints_the_value_either() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), "[server]\nport = \"hunter2secret\"\n");
        let err = load_from_dir(dir.path()).expect_err("a string port fails to parse");
        let said = err.to_string();
        assert!(!said.contains("hunter2secret"), "the mismatched value never prints: {said}");
        assert!(said.contains("invalid type"), "and the reason the parse failed survives: {said}");
        assert!(said.contains("line 2"), "with the position: {said}");
    }

    /// The position counts characters, not bytes, and a key is named only
    /// when the line actually has one: a malformed array element or a bare
    /// value has no `=` (or its head is not key-shaped), and quoting
    /// whatever sits there would put a value back in the message - the leak
    /// this change exists to close.
    #[test]
    fn the_position_counts_characters_and_names_only_a_key_line() {
        assert_eq!(parse_position("port = \"x\"\n", Some(8..9)), " at line 1, column 9 in `port`");
        // A multi-byte character before the span: `é` is two bytes and one
        // column, and its line has no bare key, so no key prints either.
        assert_eq!(parse_position("caf\u{e9} = 1\n", Some(8..9)), " at line 1, column 8",);
        // A line with no `=`, and a head that is not key-shaped: nothing is
        // named rather than a value quoted as a key.
        assert_eq!(parse_position("[[accounts]]\n", Some(2..3)), " at line 1, column 3");
        assert_eq!(parse_position("\"sk-secret=\" = 1\n", Some(15..16)), " at line 1, column 16",);
    }

    /// An unterminated quote takes its tail with it: the tail is the value
    /// whose end nobody found.
    #[test]
    fn the_scrub_drops_an_unterminated_tail() {
        assert_eq!(
            scrub_quoted("invalid type: string \"hunter2secret"),
            "invalid type: string [redacted]",
        );
    }

    #[test]
    fn no_orgs_errors() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("missing orgs should error");
        assert!(matches!(err, WorkspaceError::NoOrgsConfigured { .. }));
    }

    #[test]
    fn empty_org_errors() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Empty"
accounts = ["Stargate"]

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("org without projects should error");
        assert!(matches!(err, WorkspaceError::EmptyOrg { org, .. } if org == "Empty"));
    }

    #[test]
    fn empty_org_accounts_errors() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = []

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("empty accounts should error");
        assert!(matches!(err, WorkspaceError::EmptyOrgAccounts { org, .. } if org == "Personal"));
    }

    #[test]
    fn unknown_org_account_errors() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate", "Bogus"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("unknown account should error");
        match err {
            WorkspaceError::UnknownOrgAccount { org, account, .. } => {
                assert_eq!(org, "Personal");
                assert_eq!(account, "Bogus");
            }
            other => panic!("expected UnknownOrgAccount, got {other:?}"),
        }
    }

    #[test]
    fn org_fallback_accounts_parse_and_inherit_to_projects() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Tiered"
accounts = ["Codex"]
fallback_accounts = ["Router"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[orgs]]
name = "Plain"
accounts = ["Codex"]

[[orgs.projects]]
name = "spare"
path = "~/Projects/spare"

[[accounts]]
display_name = "Codex"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[[accounts]]
display_name = "Router"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let config = load_from_dir(dir.path()).expect("fallback_accounts parse");
        let forge = named(&config, "forge");
        assert_eq!(forge.fallback_accounts, vec!["Router"]);
        let spare = named(&config, "spare");
        assert!(
            spare.fallback_accounts.is_empty(),
            "absent fallback_accounts -> empty vec, not an error",
        );
    }

    #[test]
    fn unknown_fallback_account_errors() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
fallback_accounts = ["Bogus"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("unknown fallback should error");
        match err {
            WorkspaceError::UnknownOrgAccount { org, account, .. } => {
                assert_eq!(org, "Personal");
                assert_eq!(account, "Bogus");
            }
            other => panic!("expected UnknownOrgAccount, got {other:?}"),
        }
    }

    #[test]
    fn duplicate_org_name_errors() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "aware"
path = "~/Projects/aware"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("duplicate org should error");
        assert!(matches!(err, WorkspaceError::DuplicateOrg { name, .. } if name == "Personal"));
    }

    #[test]
    fn duplicate_project_name_errors() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Stargate"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/stargate-forge"

[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("duplicate project should error");
        assert!(matches!(err, WorkspaceError::DuplicateProject { name, .. } if name == "forge"));
    }

    #[test]
    fn default_project_picks_the_alphabetically_first_project() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "zebra"
path = "~/Projects/zebra"
[[orgs.projects]]
name = "alpha"
path = "~/Projects/alpha"
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let config = load_from_dir(dir.path()).expect("happy path");
        assert_eq!(config.default_project().name, "alpha");
    }

    /// The renamed key's predecessor is refused by name, so a stale config
    /// cannot boot with its pin silently dropped by an ignored field.
    #[test]
    fn a_stale_auto_start_key_is_refused_by_name() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
auto_start = true
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let error = load_from_dir(dir.path()).expect_err("the old key is no longer read");
        let rendered = format!("{error}");
        assert!(
            rendered.contains("auto_start"),
            "the refusal names the key the user has to rename: {rendered}",
        );
    }

    #[test]
    fn missing_accounts_returns_no_accounts_configured() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("missing accounts should error");
        assert!(matches!(err, WorkspaceError::NoAccountsConfigured { .. }));
    }

    /// The `[models."<name>"]` table parses by the spelling a project's
    /// `model` pins and reaches the loaded config; an absent table leaves
    /// the map empty, so every spawn stays on the CLI's own resolution.
    #[test]
    fn parses_the_models_table_by_name() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "deepseek-v4.1-flash"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["deepseek-v4.1-flash"]
provider = "openrouter"
base_url = "https://openrouter.ai/api"

[models."deepseek-v4.1-flash"]
auto_compact_window = 983040
"#,
        );
        let config = load_from_dir(dir.path()).expect("the table loads");
        let parameters =
            config.models.get("deepseek-v4.1-flash").expect("the model's table is keyed by name");
        assert_eq!(parameters.auto_compact_window, Some(983_040), "the window parses as declared");

        let bare = tempdir().expect("tempdir");
        write_config(
            bare.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let config = load_from_dir(bare.path()).expect("no table loads too");
        assert!(config.models.is_empty(), "an absent [models] table loads as no parameters");
    }

    /// A window that is not positive is refused by name, pointing at the
    /// model whose entry carries it: a zero or negative window would leave
    /// the CLI compacting on every turn.
    #[test]
    fn a_non_positive_auto_compact_window_errors() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["deepseek-v4.1-flash"]
provider = "openrouter"
base_url = "https://openrouter.ai/api"

[models."deepseek-v4.1-flash"]
auto_compact_window = 0
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("a zero window should error");
        let message = err.to_string();
        assert!(
            matches!(
                err,
                WorkspaceError::ModelAutoCompactWindowInvalid { ref model, value: 0, .. }
                    if model == "deepseek-v4.1-flash"
            ),
            "the refusal names the model, got: {message}",
        );
        assert!(
            message.contains("auto_compact_window")
                && message.contains("positive window in tokens"),
            "and says what to fix, got: {message}",
        );
    }

    /// A project's table carries only what it disagrees on, and every key it
    /// leaves out is an absent value rather than a default baked in at parse
    /// time - that absence is what lets the top-level table show through.
    #[test]
    fn a_project_handoff_table_carries_only_its_own_keys() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
[orgs.projects.handoff]
enabled = false

[[orgs.projects]]
name = "companies"
path = "~/Projects/companies"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[handoff]
at_percent = 95
"#,
        );
        let config = load_from_dir(dir.path()).expect("the tables load");
        let forge = named(&config, "forge").handoff.expect("forge carries a table");
        assert_eq!(forge.enabled, Some(false), "its own key is read");
        assert_eq!(forge.at_percent, None, "and the key it omits stays absent");
        assert_eq!(forge.after_compactions, None, "so the global value shows through");
        assert!(
            named(&config, "companies").handoff.is_none(),
            "a project with no table inherits rather than carrying an empty one",
        );
        assert_eq!(config.handoff.at_percent, Some(95), "the top-level table is read");
        assert_eq!(config.handoff.enabled, None, "and defaults by absence");
    }

    /// A share at either end of the range is a trigger that never fires or
    /// one that fires on the first turn, and a value past 255 is refused
    /// here rather than by serde, so it is refused by name with the fix.
    #[test]
    fn a_handoff_percent_outside_the_window_is_refused() {
        for value in [0u32, 101, 300] {
            let dir = tempdir().expect("tempdir");
            write_config(
                dir.path(),
                &minimal_config().replace(
                    "[[accounts]]",
                    &format!("[handoff]\nat_percent = {value}\n\n[[accounts]]"),
                ),
            );
            let err = load_from_dir(dir.path()).expect_err("the share is refused");
            let message = err.to_string();
            assert!(
                matches!(
                    err,
                    WorkspaceError::HandoffAtPercentInvalid { value: refused, ref scope, .. }
                        if refused == value && scope == "the top level"
                ),
                "the refusal names the table and the value, got: {message}",
            );
            assert!(
                message.contains("between 1 and 100") && message.contains("85% default"),
                "and says what to fix, got: {message}",
            );
        }
    }

    /// The backstop's zero would swap the seat on every turn, which is not
    /// what the key means, and the project's own table is the one named.
    #[test]
    fn a_project_handoff_backstop_of_zero_is_refused() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            &minimal_config().replace(
                "[[accounts]]",
                "[orgs.projects.handoff]\nafter_compactions = 0\n\n[[accounts]]",
            ),
        );
        let err = load_from_dir(dir.path()).expect_err("the backstop is refused");
        let message = err.to_string();
        assert!(
            matches!(
                err,
                WorkspaceError::HandoffAfterCompactionsInvalid { ref scope, .. }
                    if scope == "project \"forge\""
            ),
            "the refusal names the project's table, got: {message}",
        );
        assert!(
            message.contains("at least 1") && message.contains("1 default"),
            "and says what to fix, got: {message}",
        );
    }

    #[test]
    fn duplicate_account_display_name_errors() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]
[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("duplicate account should error");
        assert!(matches!(err, WorkspaceError::DuplicateAccount { name, .. } if name == "Stargate"));
    }

    /// Every key the load ignores is warned about, at WARN, by its own
    /// event name. A config that declares something forge no longer
    /// reads must not go quiet, and the level is half of that: these
    /// targets are not raised by the default filters, so a warn demoted
    /// to debug is a warn that stopped being seen.
    #[test]
    fn every_ignored_key_warns() {
        let cases = [
            (
                "[dictate] device",
                "\n[dictate]\ndevice = \"shure-id\"\n",
                "dictate_device_key_ignored",
            ),
            ("[tts] language", "\n[tts]\nlanguage = \"en\"\n", "tts_language_key_ignored"),
            (
                "a gateway key in an env layer",
                "\n[env]\nANTHROPIC_BASE_URL = \"https://proxy.example\"\n",
                "gateway_keys_dropped_from_env_layer",
            ),
            (
                "a [models] entry for a model nobody pins",
                "\n[models.\"nobody-pins-this\"]\nauto_compact_window = 100\n",
                "model_parameters_unpinned",
            ),
        ];
        for (label, stanza, event) in cases {
            let dir = tempdir().expect("tempdir");
            write_config(dir.path(), &format!("{}{stanza}", minimal_config()));
            let (loaded, logged) = load_capturing(dir.path());
            assert!(loaded.is_ok(), "{label} still loads");
            assert!(
                logged.warns(event),
                "{label} warns at WARN with {event}; saw {:?}",
                logged.names(),
            );
        }
    }

    /// The `[models]` table is read by the exact spelling a project's
    /// `model` pins, not by what accounts declare: the pinned spelling is
    /// the entry that acts and warns nothing, and the account-facing
    /// spelling of the same model warns even though an account declares it.
    #[test]
    fn a_models_table_keys_on_the_spelling_a_project_pins() {
        let config_for = |table_key: &str| {
            format!(
                r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-opus-5"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-opus-5[1m]"]
provider = "anthropic"

[accounts.model_aliases]
"claude-opus-5[1m]" = ["claude-opus-5"]

[models."{table_key}"]
auto_compact_window = 983040
"#
            )
        };

        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), &config_for("claude-opus-5"));
        let (loaded, logged) = load_capturing(dir.path());
        let config = loaded.expect("the pinned spelling loads");
        assert_eq!(
            config
                .models
                .get("claude-opus-5")
                .and_then(|parameters| parameters.auto_compact_window),
            Some(983_040),
            "the entry the project pins is the one read",
        );
        assert!(
            !logged.warns("model_parameters_unpinned"),
            "and it warns nothing: {:?}",
            logged.names(),
        );

        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), &config_for("claude-opus-5[1m]"));
        let (loaded, logged) = load_capturing(dir.path());
        assert!(loaded.is_ok(), "the account-facing spelling still loads");
        assert!(
            logged.warns("model_parameters_unpinned"),
            "an entry no project pins warns even though an account declares it: {:?}",
            logged.names(),
        );
    }

    /// A mistyped key inside a `[models]` table is refused at load rather
    /// than silently applying nothing.
    #[test]
    fn a_mistyped_models_key_is_refused() {
        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
model = "claude-sonnet-5"

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"

[models."claude-sonnet-5"]
auto_compact_windows = 983040
"#,
        );
        let err = load_from_dir(dir.path()).expect_err("a mistyped key should be a parse failure");
        let message = err.to_string();
        assert!(
            message.contains("auto_compact_windows"),
            "the refusal names the key that was not recognized, got: {message}",
        );
    }

    /// A relative `document_roots` entry is refused at load, naming the key
    /// and the entry: a relative root would resolve against whatever
    /// working directory the read happened in, which is nobody's answer.
    /// `~user/Madness` is the same refusal, and the sentence names the
    /// remedy it accepts (`~` and `~/`).
    #[test]
    fn a_relative_document_root_is_refused_at_load_naming_key_and_entry() {
        for entry in ["Madness", "~user/Madness"] {
            let dir = tempdir().expect("tempdir");
            write_config(
                dir.path(),
                &format!(
                    r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
document_roots = ["~/Madness", "{entry}"]

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
                ),
            );

            let refusal = load_from_dir(dir.path()).expect_err("a relative entry is a load error");
            assert!(
                matches!(refusal, WorkspaceError::ProjectDocumentRootRelative { .. }),
                "{entry}: {refusal:?}"
            );
            let why = refusal.to_string();
            assert!(why.contains("document_roots"), "{entry}: names the key: {why}");
            assert!(why.contains(&format!("'{entry}'")), "{entry}: names the entry: {why}");
            assert!(why.contains("'forge'"), "{entry}: and the project it sits on: {why}");
            assert!(why.contains("start with ~/"), "{entry}: and the remedy it accepts: {why}");
        }
    }

    /// `document_roots` defaults to empty; an entry expands `~` and a bare
    /// `~` is home, while an absolute one stays as itself.
    #[test]
    fn document_roots_default_to_empty_and_expand_home() {
        let dir = tempdir().expect("tempdir");
        write_config(dir.path(), minimal_config());
        let config = load_from_dir(dir.path()).expect("loads");
        assert!(named(&config, "forge").document_roots.is_empty(), "absent key, no roots");

        let dir = tempdir().expect("tempdir");
        write_config(
            dir.path(),
            r#"
[[orgs]]
name = "Personal"
accounts = ["Stargate"]

[[orgs.projects]]
name = "forge"
path = "~/Projects/forge"
document_roots = ["~/Madness", "/opt/vault", "~"]

[[accounts]]
display_name = "Stargate"
token = "t"
models = ["claude-sonnet-5"]
provider = "anthropic"
"#,
        );
        let config = load_from_dir(dir.path()).expect("loads");
        let home = dirs::home_dir().expect("home");
        assert_eq!(
            named(&config, "forge").document_roots,
            vec![home.join("Madness"), PathBuf::from("/opt/vault"), home],
            "entries expand ~ and ~/, and keep absolutes as themselves",
        );
    }
}