pitchfork_cli/

pitchfork_toml.rs

use crate::daemon_id::DaemonId;
use crate::deprecated_at;
use crate::error::{ConfigParseError, DependencyError, FileError, find_similar_daemon};
use crate::settings::SettingsPartial;
use crate::settings::settings;
use crate::state_file::StateFile;
use crate::{Result, env};
use indexmap::IndexMap;
use miette::Context;
use once_cell::sync::Lazy;
use schemars::JsonSchema;
use std::collections::{HashMap, HashSet};
use std::path::{Path, PathBuf};
use std::sync::Mutex as StdMutex;
use std::time::SystemTime;

// Re-export config value types so existing `use crate::pitchfork_toml::X` paths keep working.
pub use crate::config_types::{
    CpuLimit, CronRetrigger, Dir, HealthCmd, HealthHttp, HealthPort, MemoryLimit, OnOutputHook,
    PitchforkTomlAuto, PitchforkTomlCron, PitchforkTomlHooks, PortBump, PortConfig, ProxyConfig,
    ProxyIdleTimeout, ProxyTlsMode, ReadyCmd, ReadyHttp, ReadyOutput, ReadyPort, Retry, StopConfig,
    StopSignal, WatchMode,
};

/// Raw slug entry as read from TOML (uses String for dir path).
/// Format in global config:
/// ```toml
/// [slugs]
/// api = { dir = "/home/user/my-api", daemon = "server" }
/// docs = { dir = "/home/user/docs-site" }  # daemon defaults to slug name
/// ```
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, JsonSchema)]
pub struct SlugEntryRaw {
    /// Project directory containing the pitchfork.toml
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub dir: Option<String>,
    /// Namespace reference (alternative to dir)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub namespace: Option<String>,
    /// Daemon name within that project (defaults to slug name if omitted)
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub daemon: Option<String>,
}

/// Resolved slug entry with PathBuf.
#[derive(Debug, Clone)]
pub struct SlugEntry {
    /// Project directory containing the pitchfork.toml
    pub dir: Option<PathBuf>,
    /// Namespace reference (alternative to dir)
    pub namespace: Option<String>,
    /// Daemon name within that project (defaults to slug name if omitted)
    pub daemon: Option<String>,
}

impl SlugEntry {
    /// Resolve the project directory.
    /// If `dir` is set, use it. Otherwise look up `namespace` in the global namespace registry.
    pub fn resolve_dir(&self) -> Option<PathBuf> {
        self.dir.clone().or_else(|| {
            self.namespace.as_ref().and_then(|ns| {
                let namespaces = PitchforkToml::read_global_namespaces();
                namespaces.get(ns).map(|entry| entry.dir.clone())
            })
        })
    }

    /// Resolve the namespace name.
    /// If `namespace` is set, use it. Otherwise derive from `dir` via `namespace_for_dir`.
    pub fn resolve_namespace(&self) -> Option<String> {
        self.namespace.clone().or_else(|| {
            self.resolve_dir()
                .and_then(|dir| PitchforkToml::namespace_for_dir(&dir).ok())
        })
    }
}

/// Raw group entry as read from TOML.
/// ```toml
/// [groups.backend]
/// daemons = ["api", "worker"]
///
/// [groups.all]
/// groups = ["backend"]
/// daemons = ["postgres"]
/// ```
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize, JsonSchema)]
pub struct GroupEntryRaw {
    /// Daemons in this group: short names or fully qualified IDs.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    #[schemars(with = "Vec<DaemonId>")]
    pub daemons: Vec<String>,
    /// Names of other groups whose daemons this group also contains.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub groups: Vec<String>,
}

/// Resolved group entry with qualified DaemonIds.
///
/// `groups` stays unexpanded: it names groups that may be defined in a
/// different config file, so it is resolved by [`expand_group`] once the
/// configs are merged.
#[derive(Debug, Clone, Default)]
pub struct GroupEntry {
    pub daemons: Vec<DaemonId>,
    pub groups: Vec<String>,
}

/// Expand a group into its deduplicated daemons, following `groups` includes.
///
/// Daemons of included groups come first, in the order the groups are listed,
/// followed by the group's own `daemons`. A daemon reachable more than once is
/// kept at its first position. Including an undefined group, or a group that
/// includes itself directly or through other groups, is an error.
pub fn expand_group(groups: &IndexMap<String, GroupEntry>, name: &str) -> Result<Vec<DaemonId>> {
    fn visit(
        groups: &IndexMap<String, GroupEntry>,
        name: &str,
        path: &mut Vec<String>,
        done: &mut HashSet<String>,
        seen: &mut HashSet<DaemonId>,
        out: &mut Vec<DaemonId>,
    ) -> Result<()> {
        // Everything a finished group contributes is already in `out`, so
        // revisiting it through another include only repeats work.
        if done.contains(name) {
            return Ok(());
        }
        let Some(group) = groups.get(name) else {
            let suggestion = find_similar_daemon(name, groups.keys().map(|s| s.as_str()));
            return Err(match path.last() {
                Some(parent) => miette::miette!(
                    "group '{parent}' includes undefined group '{name}'{}",
                    suggestion.map(|s| format!(", {s}")).unwrap_or_default()
                ),
                None => miette::miette!(
                    "group '{name}' not found in configuration{}",
                    suggestion.map(|s| format!(", {s}")).unwrap_or_default()
                ),
            });
        };
        if path.iter().any(|p| p == name) {
            return Err(miette::miette!(
                "group include cycle: {} -> {name}",
                path.join(" -> ")
            ));
        }
        path.push(name.to_string());
        for included in &group.groups {
            visit(groups, included, path, done, seen, out)?;
        }
        path.pop();
        for id in &group.daemons {
            if seen.insert(id.clone()) {
                out.push(id.clone());
            }
        }
        done.insert(name.to_string());
        Ok(())
    }

    let mut out = Vec::new();
    visit(
        groups,
        name,
        &mut Vec::new(),
        &mut HashSet::new(),
        &mut HashSet::new(),
        &mut out,
    )?;
    Ok(out)
}

/// Raw namespace entry as read from TOML.
/// ```toml
/// [namespaces.myproject]
/// dir = "/home/user/projects/myproject"
/// ```
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, JsonSchema)]
pub struct NamespaceEntryRaw {
    /// Project directory containing the pitchfork.toml
    pub dir: String,
    /// Additional configuration files, relative to dir or absolute.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub config: Vec<String>,
    /// Hostname label for the project, used instead of the namespace when the
    /// namespace is only an identifier (for example a generated
    /// `shop-528f92b13a6784f0`). Must already be a valid DNS label.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub label: Option<String>,
}

/// Resolved namespace entry with PathBuf.
#[derive(Debug, Clone)]
pub struct NamespaceEntry {
    /// Project directory containing the pitchfork.toml
    pub dir: PathBuf,
    pub config: Vec<PathBuf>,
    /// Hostname label for the project, when the registration names one.
    pub label: Option<String>,
}

/// Internal structure for reading config files (uses String keys for short daemon names)
#[derive(Debug, Default, serde::Serialize, serde::Deserialize)]
struct PitchforkTomlRaw {
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub namespace: Option<String>,
    /// Hostname label for this checkout when it is a linked git worktree.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub worktree_label: Option<String>,
    #[serde(default)]
    pub daemons: IndexMap<String, PitchforkTomlDaemonRaw>,
    /// Top-level environment variables applied to all daemons as defaults.
    /// Per-daemon `env` overrides these. Values support Tera templates.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub env: Option<IndexMap<String, String>>,
    #[serde(default)]
    pub settings: Option<SettingsPartial>,
    /// Slug registry (only meaningful in global config).
    /// Maps slug names to their configuration (dir + optional daemon name).
    #[serde(skip_serializing_if = "IndexMap::is_empty", default)]
    pub slugs: IndexMap<String, SlugEntryRaw>,
    /// Named groups of daemons for batch operations.
    #[serde(skip_serializing_if = "IndexMap::is_empty", default)]
    pub groups: IndexMap<String, GroupEntryRaw>,
    /// Namespace registry (only meaningful in global config).
    /// Maps namespace names to their project directory.
    #[serde(skip_serializing_if = "IndexMap::is_empty", default)]
    pub namespaces: IndexMap<String, NamespaceEntryRaw>,
}

/// Per-daemon log configuration sub-table `[daemons.<name>.logs]`.
///
/// Fields here override the top-level daemon fields (`time_retention`,
/// `line_retention`, `archive_hook`) and the global `[settings.logs]` defaults.
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
pub struct PitchforkTomlDaemonLogs {
    /// Log line format: `json`, `logfmt`, or `text`.
    /// Defaults to `text` (no parsing).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub log_format: Option<String>,
    /// Maximum age of log entries to keep (e.g. "7d", "30d").
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub time_retention: Option<String>,
    /// Maximum number of log entries to keep per daemon.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub line_retention: Option<i64>,
    /// Archive hook command invoked before retention prunes this daemon's logs.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub archive_hook: Option<String>,
}

/// Internal daemon config for reading (uses String for depends).
///
/// Note: This struct mirrors `PitchforkTomlDaemon` but uses `Vec<String>` for `depends`
/// (before namespace resolution) and has serde attributes for TOML serialization.
/// When adding new fields, remember to update both structs and the conversion code
/// in `read()` and `write()`.
#[derive(Debug, serde::Serialize, serde::Deserialize)]
struct PitchforkTomlDaemonRaw {
    pub run: RunCommand,
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub auto: Vec<PitchforkTomlAuto>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub oneshot: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub cron: Option<PitchforkTomlCron>,
    #[serde(default)]
    pub retry: Retry,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub ready_delay: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub ready_output: Option<ReadyOutput>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub ready_http: Option<ReadyHttp>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub ready_port: Option<ReadyPort>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub ready_cmd: Option<ReadyCmd>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub health_cmd: Option<HealthCmd>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub health_http: Option<HealthHttp>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub health_port: Option<HealthPort>,
    /// New port configuration (preferred)
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub port: Option<PortConfig>,
    /// Proxy routing: `false` opts out, a string overrides the daemon's hostname label.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub proxy: Option<ProxyConfig>,
    /// Deprecated: use `port` instead
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub expected_port: Vec<u16>,
    /// Deprecated: use `port.bump` instead
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub auto_bump_port: Option<bool>,
    /// Deprecated: use `port.bump` instead
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub port_bump_attempts: Option<u32>,
    /// TLS handling for this daemon's proxy hostname: `terminate` or `passthrough`.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub proxy_tls: Option<ProxyTlsMode>,
    /// Which of the daemon's ports the proxy hostname maps to.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub proxy_tls_port: Option<u16>,
    /// Shorter spelling of `proxy_tls_port`. Never written back out, so a
    /// config that used it keeps one spelling rather than gaining both.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub proxy_port: Option<u16>,
    /// Stop after this long without proxy activity when the proxy started it.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub proxy_idle_timeout: Option<ProxyIdleTimeout>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub boot_start: Option<bool>,
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub depends: Vec<String>,
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub watch: Vec<String>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub watch_mode: Option<WatchMode>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub dir: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub env: Option<IndexMap<String, String>>,
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub env_file: Vec<String>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub hooks: Option<PitchforkTomlHooks>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub mise: Option<bool>,
    /// Unix user to run this daemon as.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub user: Option<String>,
    /// Memory limit for the daemon process (e.g. "50MB", "1GiB")
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub memory_limit: Option<MemoryLimit>,
    /// CPU usage limit as a percentage (e.g. 80 for 80%, 200 for 2 cores)
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub cpu_limit: Option<CpuLimit>,
    /// Unix signal to send for graceful shutdown (default: SIGTERM)
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub stop_signal: Option<StopConfig>,
    /// Allocate a pseudo-terminal for the daemon process.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub pty: Option<bool>,
    /// Maximum age of log entries to keep (e.g. "7d", "30d").
    /// Overrides the global `settings.logs.time_retention` when set.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub time_retention: Option<String>,
    /// Maximum number of log entries to keep per daemon.
    /// Overrides the global `settings.logs.line_retention` when set.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub line_retention: Option<i64>,
    /// Archive hook command invoked before retention prunes this daemon's logs.
    /// Overrides the global `settings.logs.archive_hook.command` when set.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub archive_hook: Option<String>,
    /// Per-daemon log configuration sub-table.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub logs: Option<PitchforkTomlDaemonLogs>,
}

/// Configuration schema for pitchfork.toml daemon supervisor configuration files.
///
/// Note: When read from a file, daemon keys are short names (e.g., "api").
/// After merging, keys become qualified DaemonIds (e.g., "project/api").
#[derive(Debug, Clone, Default, JsonSchema)]
#[schemars(title = "Pitchfork Configuration")]
pub struct PitchforkToml {
    /// Map of daemon IDs to their configurations
    #[serde(default)]
    pub daemons: IndexMap<DaemonId, PitchforkTomlDaemon>,
    /// Top-level environment variables applied to all daemons as defaults.
    /// Per-daemon `env` overrides these on key conflicts. Values support Tera
    /// templates (e.g. `{{ daemons.api.port }}`, `{{ settings.proxy.tld }}`).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub env: Option<IndexMap<String, String>>,
    /// Optional explicit namespace declared in this file.
    ///
    /// This applies to per-file read/write flows. Merged configs may contain
    /// daemons from multiple namespaces and leave this as `None`.
    pub namespace: Option<String>,
    /// Hostname label for this checkout when it is a linked git worktree.
    ///
    /// Overrides the worktree directory's name in proxy hostnames.
    #[schemars(default, with = "Option<String>")]
    pub worktree_label: Option<String>,
    /// Settings configuration (merged from all config files).
    ///
    /// **Note:** This field exists for serialization round-trips and for
    /// `PitchforkToml::merge()` to collect per-file overrides.  It is **not**
    /// consumed by the global `settings()` singleton, which is populated
    /// independently by `Settings::load()` to avoid a circular dependency
    /// between `PitchforkToml` and `Settings`.  Do not rely on mutations to
    /// this field being reflected in `settings()`.
    #[serde(default)]
    pub(crate) settings: SettingsPartial,
    /// Slug registry (merged from global config files).
    /// Maps slug names to their project directory and optional daemon name.
    /// Only populated from global config files (`~/.config/pitchfork/config.toml`
    /// or `/etc/pitchfork/config.toml`).
    #[schemars(default, with = "IndexMap<String, SlugEntryRaw>")]
    pub slugs: IndexMap<String, SlugEntry>,
    /// Named groups of daemons for batch operations.
    #[schemars(default, with = "IndexMap<String, GroupEntryRaw>")]
    pub groups: IndexMap<String, GroupEntry>,
    /// Namespace registry (merged from global config files).
    /// Maps namespace names to their project directory.
    #[schemars(default, with = "IndexMap<String, NamespaceEntryRaw>")]
    pub namespaces: IndexMap<String, NamespaceEntry>,
    #[schemars(skip)]
    pub path: Option<PathBuf>,
    /// Top-level `[env]` of the registered project each daemon merged in from
    /// another namespace came from, keyed by that daemon.
    ///
    /// Such a daemon renders against its own project's defaults, not those of
    /// the checkout that requested it. Daemons from the requesting checkout's
    /// own config chain are absent and use [`Self::env`], which carries every
    /// override along that chain.
    #[schemars(skip)]
    pub(crate) foreign_env: IndexMap<DaemonId, Option<IndexMap<String, String>>>,
}

impl PitchforkToml {
    /// The top-level `[env]` defaults `id` renders against: its own project's
    /// when it came from another registered project, otherwise this config's.
    pub(crate) fn env_for(&self, id: &DaemonId) -> Option<&IndexMap<String, String>> {
        self.foreign_env
            .get(id)
            .map_or(self.env.as_ref(), |env| env.as_ref())
    }
}

pub fn is_global_config(path: &Path) -> bool {
    path == *env::PITCHFORK_GLOBAL_CONFIG_USER || path == *env::PITCHFORK_GLOBAL_CONFIG_SYSTEM
}

pub(crate) fn is_dot_config_pitchfork(path: &Path) -> bool {
    path.ends_with(".config/pitchfork.toml") || path.ends_with(".config/pitchfork.local.toml")
}

fn parse_namespace_override_from_content(path: &Path, content: &str) -> Result<Option<String>> {
    use toml::Value;

    let doc: Value = toml::from_str(content)
        .map_err(|e| ConfigParseError::from_toml_error(path, content.to_string(), e))?;
    let Some(value) = doc.get("namespace") else {
        return Ok(None);
    };

    match value {
        Value::String(s) => Ok(Some(s.clone())),
        _ => Err(ConfigParseError::InvalidNamespace {
            path: path.to_path_buf(),
            namespace: value.to_string(),
            reason: "top-level 'namespace' must be a string".to_string(),
        }
        .into()),
    }
}

fn read_namespace_override_from_file(path: &Path) -> Result<Option<String>> {
    if !path.exists() {
        return Ok(None);
    }
    let content = std::fs::read_to_string(path).map_err(|e| FileError::ReadError {
        path: path.to_path_buf(),
        source: e,
    })?;
    parse_namespace_override_from_content(path, &content)
}

pub fn project_dir_for_config(path: &Path) -> Option<PathBuf> {
    crate::extra_configs::project_dir(path).or_else(|| {
        if is_dot_config_pitchfork(path) {
            path.parent().and_then(Path::parent).map(Path::to_path_buf)
        } else {
            path.parent().map(Path::to_path_buf)
        }
    })
}

fn project_config_family(path: &Path) -> Vec<PathBuf> {
    let Some(dir) = project_dir_for_config(path) else {
        return vec![path.to_path_buf()];
    };
    vec![
        dir.join(".config/pitchfork.toml"),
        dir.join(".config/pitchfork.local.toml"),
        dir.join("pitchfork.toml"),
        dir.join("pitchfork.local.toml"),
    ]
}

/// Resolve one namespace override shared by all project config files in a
/// directory. `content_override` represents unsaved content for `path`.
fn directory_namespace_override(
    path: &Path,
    content_override: Option<&str>,
) -> Result<Option<String>> {
    if is_global_config(path) {
        return match content_override {
            Some(content) => parse_namespace_override_from_content(path, content),
            None => read_namespace_override_from_file(path),
        };
    }

    let mut selected: Option<(String, PathBuf)> = None;
    for candidate in project_config_family(path) {
        let explicit = if candidate == path {
            match content_override {
                Some(content) => parse_namespace_override_from_content(&candidate, content)?,
                None => read_namespace_override_from_file(&candidate)?,
            }
        } else {
            read_namespace_override_from_file(&candidate)?
        };
        let Some(namespace) = explicit else { continue };
        if let Some((selected_namespace, selected_path)) = &selected
            && selected_namespace != &namespace
        {
            return Err(ConfigParseError::InvalidNamespace {
                path: candidate,
                namespace,
                reason: format!(
                    "namespace does not match directory-level namespace '{}' declared in {}",
                    selected_namespace,
                    selected_path.display()
                ),
            }
            .into());
        }
        selected = Some((namespace, candidate));
    }
    Ok(selected.map(|(namespace, _)| namespace))
}

fn validate_namespace(path: &Path, namespace: &str) -> Result<String> {
    if let Err(e) = DaemonId::try_new(namespace, "probe") {
        return Err(ConfigParseError::InvalidNamespace {
            path: path.to_path_buf(),
            namespace: namespace.to_string(),
            reason: e.to_string(),
        }
        .into());
    }
    Ok(namespace.to_string())
}

fn derive_namespace_from_dir(path: &Path) -> Result<String> {
    let dir_for_namespace = project_dir_for_config(path);
    if let Some(namespace) = dir_for_namespace
        .as_deref()
        .and_then(crate::extra_configs::namespace_for_dir)
    {
        return validate_namespace(path, &namespace);
    }
    let raw_namespace = dir_for_namespace
        .as_deref()
        .and_then(|p| p.file_name())
        .and_then(|n| n.to_str())
        .ok_or_else(|| miette::miette!("cannot derive namespace from path '{}'", path.display()))?
        .to_string();

    validate_namespace(path, &raw_namespace).map_err(|e| {
        ConfigParseError::InvalidNamespace {
            path: path.to_path_buf(),
            namespace: raw_namespace,
            reason: format!(
                "{e}. Set a valid top-level namespace, e.g. namespace = \"my-project\""
            ),
        }
        .into()
    })
}

fn namespace_from_path_with_override(path: &Path, explicit: Option<&str>) -> Result<String> {
    if is_global_config(path) {
        if let Some(ns) = explicit
            && ns != "global"
        {
            return Err(ConfigParseError::InvalidNamespace {
                path: path.to_path_buf(),
                namespace: ns.to_string(),
                reason: "global config files must use namespace 'global'".to_string(),
            }
            .into());
        }
        return Ok("global".to_string());
    }

    if let Some(ns) = explicit {
        return validate_namespace(path, ns);
    }

    derive_namespace_from_dir(path)
}

fn namespace_from_file(path: &Path) -> Result<String> {
    let explicit = directory_namespace_override(path, None)?;
    namespace_from_path_with_override(path, explicit.as_deref())
}

/// Extracts a namespace from a config file path.
///
/// - For user global config (`~/.config/pitchfork/config.toml`): returns "global"
/// - For system global config (`/etc/pitchfork/config.toml`): returns "global"
/// - For project configs: uses top-level `namespace` if present, otherwise parent directory name
///
/// Examples:
/// - `~/.config/pitchfork/config.toml` → `"global"`
/// - `/etc/pitchfork/config.toml` → `"global"`
/// - `/home/user/project-a/pitchfork.toml` → `"project-a"`
/// - `/home/user/project-b/sub/pitchfork.toml` → `"sub"`
/// - `/home/user/中文目录/pitchfork.toml` → error unless `namespace = "..."` is set
pub fn namespace_from_path(path: &Path) -> Result<String> {
    namespace_from_file(path)
}

/// Find the nearest ancestor directory of `dir` that contains a `.git` or
/// `.jj` marker (the project root of a git worktree / jj workspace).
///
/// Returns `None` when `dir` is not inside any git/jj project, so callers can
/// fall back to non-worktree behavior. In a linked git worktree, `.git` is a
/// *file* (not a directory) pointing at the common gitdir, so we check
/// existence rather than `is_dir()`.
fn find_project_root(dir: &Path) -> Option<PathBuf> {
    // Canonicalize the start dir so a symlinked path resolves into the
    // repository hierarchy before traversing parents; otherwise `parent()`
    // walks outside the repo and misses `.git`/`.jj`.
    let canonical_dir = dir.canonicalize().unwrap_or_else(|_| dir.to_path_buf());
    let mut current = canonical_dir.as_path();
    loop {
        if current.join(".git").exists() || current.join(".jj").exists() {
            return Some(current.to_path_buf());
        }
        current = current.parent()?;
    }
}

/// Cached result of `all_merged_from`, keyed by the cwd used to discover config paths.
///
/// The cache key is the canonical cwd `PathBuf`. The entry stores the merged
/// [`PitchforkToml`] plus a snapshot of every source file's (mtime, size) at
/// cache time. A cache hit requires the same set of paths with identical
/// mtimes **and** sizes.
///
/// Tracking size in addition to mtime catches timestamp-preserving content
/// changes (e.g. `cp --preserve=timestamps`, same-second edits on filesystems
/// with coarse mtime granularity like NFS) that mtime alone would miss.
///
/// **Known limitation**: an equal-size content replacement that also preserves
/// mtime will not be detected. This is an accepted trade-off — fully closing
/// this gap would require hashing file contents on every cache hit, negating
/// the I/O savings the cache exists to provide. In practice, editors and `git
/// pull` always change mtime, and `cp --preserve=timestamps` almost always
/// changes size. The `ReloadConfig` IPC handler (`settings reload`) serves as
/// an explicit escape hatch to force a full re-read when needed.
struct ConfigCacheEntry {
    config: PitchforkToml,
    /// (path, (mtime, size)) snapshot — order matches `list_paths_from` at cache time.
    source_meta: Vec<(PathBuf, Option<(SystemTime, u64)>)>,
}

/// Global config parse cache, keyed by canonical cwd.
///
/// Uses a `std::sync::Mutex` (not tokio) because config parsing is CPU-bound
/// and callers like `spawn_blocking(PitchforkToml::all_merged)` run outside
/// the async runtime. Contention is minimal: the mutex is held only for the
/// metadata comparison and the occasional re-read, not across I/O.
static CONFIG_CACHE: Lazy<StdMutex<HashMap<PathBuf, ConfigCacheEntry>>> =
    Lazy::new(|| StdMutex::new(HashMap::new()));

/// Compare a list of paths' current (mtime, size) against a cached snapshot.
///
/// Returns `true` if every path exists (or not) and has the same mtime and
/// size as when the snapshot was taken. Any difference — a new file, a deleted
/// file, a changed mtime, or a changed size — invalidates the cache.
fn meta_matches(paths: &[PathBuf], snapshot: &[(PathBuf, Option<(SystemTime, u64)>)]) -> bool {
    if paths.len() != snapshot.len() {
        return false;
    }
    paths
        .iter()
        .zip(snapshot.iter())
        .all(|(p, (snap_p, snap_meta))| p == snap_p && current_meta(p) == *snap_meta)
}

/// Best-effort (mtime, size) — `None` if the path doesn't exist or metadata fails.
pub(crate) fn current_meta(path: &Path) -> Option<(SystemTime, u64)> {
    let md = std::fs::metadata(path).ok()?;
    Some((md.modified().ok()?, md.len()))
}

/// Snapshot all (path, (mtime, size)) pairs for a list of paths.
fn snapshot_meta(paths: &[PathBuf]) -> Vec<(PathBuf, Option<(SystemTime, u64)>)> {
    paths.iter().map(|p| (p.clone(), current_meta(p))).collect()
}

/// Invalidate the entire config parse cache.
///
/// Called after any config file write (`write()`, `write_unlocked()`,
/// `add_slug_with_namespace()`, `remove_slug()`, `register_namespace()`,
/// `remove_namespace()`) so that subsequent `all_merged_from` calls re-read
/// from disk.
///
/// Also called by `settings reload` (via IPC `ReloadConfig`) so that external
/// edits to config files are picked up.
///
/// **Cross-process note**: CLI and supervisor are separate processes with
/// independent caches. When the CLI calls this after `write_unlocked()`, it
/// only clears the CLI's own cache (which is about to exit anyway). The
/// supervisor relies on mtime change detection to pick up CLI-written changes.
/// The `ReloadConfig` IPC handler is the one that matters — it clears the
/// supervisor's cache.
pub fn invalidate_config_cache() {
    crate::extra_configs::invalidate();
    // The web project pages keep their own parsed-group cache, validated the
    // same way, so it must be dropped here too.
    crate::web::routes::api::projects::invalidate_group_cache();
    if let Ok(mut cache) = CONFIG_CACHE.lock() {
        cache.clear();
    }
}

impl PitchforkToml {
    /// Resolves a user-provided daemon ID to qualified DaemonIds.
    ///
    /// If the ID is already qualified (contains '/'), parses and returns it.
    /// Otherwise, looks up the short ID in the config and returns
    /// matching qualified IDs.
    ///
    /// # Arguments
    /// * `user_id` - The daemon ID provided by the user
    ///
    /// # Returns
    /// A Result containing a vector of matching DaemonIds (usually one, but could be multiple
    /// if the same short ID exists in multiple namespaces), or an error if the ID is invalid.
    pub fn resolve_daemon_id(&self, user_id: &str) -> Result<Vec<DaemonId>> {
        // If already qualified, parse and return
        if user_id.contains('/') {
            return match DaemonId::parse(user_id) {
                Ok(id) => Ok(vec![id]),
                Err(e) => Err(e), // Invalid format - propagate error
            };
        }

        // Check for slug match in global slugs registry
        let global_slugs = Self::read_global_slugs();
        if let Some(entry) = global_slugs.get(user_id) {
            // Load the project's config from the slug's dir to find the daemon ID
            let daemon_name = entry.daemon.as_deref().unwrap_or(user_id);
            if let Some(dir) = entry.resolve_dir()
                && let Ok(project_config) = Self::all_merged_from(&dir)
            {
                // Find daemon by short name in that project
                let matches: Vec<DaemonId> = project_config
                    .daemons
                    .keys()
                    .filter(|id| id.name() == daemon_name)
                    .cloned()
                    .collect();
                match matches.as_slice() {
                    [] => {}
                    [id] => return Ok(vec![id.clone()]),
                    _ => {
                        let mut candidates: Vec<String> =
                            matches.iter().map(|id| id.qualified()).collect();
                        candidates.sort();
                        return Err(miette::miette!(
                            "slug '{}' maps to daemon '{}' which matches multiple daemons: {}",
                            user_id,
                            daemon_name,
                            candidates.join(", ")
                        ));
                    }
                }
            }
        }

        // Look for matching qualified IDs in the config
        let matches: Vec<DaemonId> = self
            .daemons
            .keys()
            .filter(|id| id.name() == user_id)
            .cloned()
            .collect();

        if matches.is_empty() {
            // No config matches. Search state file for any daemon with matching short name.
            let state_matches = Self::find_in_state_file(user_id);
            match state_matches.as_slice() {
                [] => {}
                [id] => return Ok(vec![id.clone()]),
                _ => {
                    let mut candidates: Vec<String> =
                        state_matches.iter().map(|id| id.qualified()).collect();
                    candidates.sort();
                    return Err(miette::miette!(
                        "daemon '{}' is ambiguous; matches: {}. Use a qualified daemon ID (namespace/name)",
                        user_id,
                        candidates.join(", ")
                    ));
                }
            }
            // No config or state matches. Validate short ID format and return no matches.
            let _ = DaemonId::try_new("global", user_id)?;
        }
        Ok(matches)
    }

    /// Finds all daemons in the persisted state file whose short name matches `short_name`.
    ///
    /// Logs a warning if the state file exists but cannot be read or parsed.
    ///
    /// Returns the matching `DaemonId`s. The caller must handle zero / one / many cases.
    fn find_in_state_file(short_name: &str) -> Vec<DaemonId> {
        match StateFile::read(&*env::PITCHFORK_STATE_FILE) {
            Ok(state) => state
                .daemons
                .keys()
                .filter(|id| id.name() == short_name)
                .cloned()
                .collect(),
            Err(e) => {
                warn!("cannot read state file: {e}");
                Vec::new()
            }
        }
    }

    /// Resolves a user-provided daemon ID to a qualified DaemonId, preferring the current directory's namespace.
    ///
    /// If the ID is already qualified (contains '/'), parses and returns it.
    /// Otherwise, tries to find a daemon in the current directory's namespace first.
    /// Falls back to any matching daemon if not found in current namespace.
    ///
    /// # Arguments
    /// * `user_id` - The daemon ID provided by the user
    /// * `current_dir` - The current working directory (used to determine namespace preference)
    ///
    /// # Returns
    /// The resolved DaemonId, or an error if the ID format is invalid
    ///
    /// # Errors
    /// Returns an error if `user_id` contains '/' but is not a valid qualified ID
    /// (e.g., "foo/bar/baz" with multiple slashes), or if `user_id` contains invalid characters.
    ///
    /// # Warnings
    /// If multiple daemons match the short name and none is in the current namespace,
    /// a warning is logged to stderr indicating the ambiguity.
    #[allow(dead_code)]
    pub fn resolve_daemon_id_prefer_local(
        &self,
        user_id: &str,
        current_dir: &Path,
    ) -> Result<DaemonId> {
        // If already qualified, parse and return (or error if invalid)
        if user_id.contains('/') {
            return DaemonId::parse(user_id);
        }

        // Determine the current directory's namespace by finding the nearest
        // pitchfork.toml. Cache the namespace in the caller when resolving
        // multiple IDs to avoid repeated filesystem traversal.
        let current_namespace = Self::namespace_for_dir(current_dir)?;

        self.resolve_daemon_id_with_namespace(user_id, &current_namespace)
    }

    /// Like `resolve_daemon_id_prefer_local` but accepts a pre-computed namespace,
    /// avoiding redundant filesystem traversal when resolving multiple IDs.
    fn resolve_daemon_id_with_namespace(
        &self,
        user_id: &str,
        current_namespace: &str,
    ) -> Result<DaemonId> {
        // A daemon in the current namespace comes first, so another project's
        // slug of the same name does not take over a local daemon. A slug can
        // be a name no daemon can have (e.g. `my--alias`), so an invalid name
        // only skips this check and is rejected after the slug lookup.
        if let Ok(preferred_id) = DaemonId::try_new(current_namespace, user_id)
            && self.daemons.contains_key(&preferred_id)
        {
            return Ok(preferred_id);
        }

        // Check for slug match in global slugs registry
        let global_slugs = Self::read_global_slugs();
        if let Some(entry) = global_slugs.get(user_id) {
            let daemon_name = entry.daemon.as_deref().unwrap_or(user_id);
            if let Some(dir) = entry.resolve_dir()
                && let Ok(project_config) = Self::all_merged_from(&dir)
            {
                let matches: Vec<DaemonId> = project_config
                    .daemons
                    .keys()
                    .filter(|id| id.name() == daemon_name)
                    .cloned()
                    .collect();
                match matches.as_slice() {
                    [] => {}
                    [id] => return Ok(id.clone()),
                    _ => {
                        let mut candidates: Vec<String> =
                            matches.iter().map(|id| id.qualified()).collect();
                        candidates.sort();
                        return Err(miette::miette!(
                            "slug '{}' maps to daemon '{}' which matches multiple daemons: {}",
                            user_id,
                            daemon_name,
                            candidates.join(", ")
                        ));
                    }
                }
            }
        }

        // Use try_new to validate user input
        DaemonId::try_new(current_namespace, user_id)?;

        // Fall back to any matching daemon
        let matches = self.resolve_daemon_id(user_id)?;

        // Error on ambiguity instead of implicitly preferring global.
        if matches.len() > 1 {
            let mut candidates: Vec<String> = matches.iter().map(|id| id.qualified()).collect();
            candidates.sort();
            return Err(miette::miette!(
                "daemon '{}' is ambiguous; matches: {}. Use a qualified daemon ID (namespace/name)",
                user_id,
                candidates.join(", ")
            ));
        }

        if let Some(id) = matches.into_iter().next() {
            return Ok(id);
        }

        // If not found in current namespace or merged config matches, only fall back
        // to global when it is explicitly configured.
        let global_id = DaemonId::try_new("global", user_id)?;
        if self.daemons.contains_key(&global_id) {
            return Ok(global_id);
        }

        let suggestion = find_similar_daemon(user_id, self.daemons.keys().map(|id| id.name()));
        Err(DependencyError::DaemonNotFound {
            name: user_id.to_string(),
            suggestion,
        }
        .into())
    }

    /// Resolve a project's namespace even when it has no ordinary config file.
    pub fn namespace_for_project_dir(dir: &Path) -> Result<String> {
        namespace_from_path(&dir.join("pitchfork.toml"))
    }

    /// Return the `worktree_label` declared for this project, ignoring configs
    /// inherited from parent directories.
    ///
    /// This covers the project's own four config files and any external file
    /// registered to this directory with `pitchfork config add --dir`, which is
    /// where a generator such as mise writes its configuration. Later files win,
    /// matching the ordinary configuration precedence.
    pub fn project_worktree_label(dir: &Path) -> Option<String> {
        let mut label = None;
        let candidates = project_config_family(&dir.join("pitchfork.toml"))
            .into_iter()
            .chain(crate::extra_configs::configs_for_dir(dir));
        for candidate in candidates {
            if !candidate.exists() {
                continue;
            }
            if let Ok(pt) = Self::read(&candidate)
                && let Some(found) = pt.worktree_label
            {
                label = Some(found);
            }
        }
        label
    }

    /// Return the explicit namespace shared by this project's own configuration files.
    pub fn project_namespace_override(dir: &Path) -> Result<Option<String>> {
        directory_namespace_override(&dir.join("pitchfork.toml"), None)
    }

    /// Find the effective namespace from the nearest configuration file.
    pub fn namespace_for_dir(dir: &Path) -> Result<String> {
        Ok(Self::list_paths_from(dir)
            .iter()
            .filter(|p| p.exists())
            .max_by_key(|p| {
                if is_global_config(p) {
                    0
                } else {
                    project_dir_for_config(p).map_or(0, |dir| dir.components().count())
                }
            })
            .map(|p| namespace_from_path(p))
            .transpose()?
            .unwrap_or_else(|| "global".to_string()))
    }

    /// Convenience method: resolves a single user ID using the merged config and current directory.
    ///
    /// Equivalent to:
    /// ```ignore
    /// PitchforkToml::all_merged().resolve_daemon_id_prefer_local(user_id, &env::CWD)
    /// ```
    ///
    /// # Errors
    /// Returns an error if `user_id` contains '/' but is not a valid qualified ID
    pub fn resolve_id(user_id: &str) -> Result<DaemonId> {
        if user_id.contains('/') {
            return DaemonId::parse(user_id);
        }

        // Compute the namespace once and reuse it — avoids a second traversal
        // inside resolve_daemon_id_prefer_local.
        let config = Self::all_merged()?;
        let ns = Self::namespace_for_dir(&env::CWD)?;
        config.resolve_daemon_id_with_namespace(user_id, &ns)
    }

    /// Like `resolve_id`, but allows ad-hoc short IDs in the current directory's
    /// derived namespace.
    ///
    /// This is intended for commands such as `pitchfork run` that create
    /// managed daemons without requiring prior config entries.
    pub fn resolve_id_allow_adhoc(user_id: &str) -> Result<DaemonId> {
        Self::resolve_id_allow_adhoc_from(user_id, &env::CWD)
    }

    fn resolve_id_allow_adhoc_from(user_id: &str, dir: &Path) -> Result<DaemonId> {
        if user_id.contains('/') {
            return DaemonId::parse(user_id);
        }

        let ns = Self::namespace_for_dir(dir)?;
        DaemonId::try_new(ns, user_id)
    }

    /// Convenience method: resolves multiple user IDs using the merged config and current directory.
    ///
    /// Equivalent to:
    /// ```ignore
    /// let config = PitchforkToml::all_merged();
    /// ids.iter().map(|s| config.resolve_daemon_id_prefer_local(s, &env::CWD)).collect()
    /// ```
    ///
    /// # Errors
    /// Returns an error if any ID is malformed
    pub fn resolve_ids<S: AsRef<str>>(user_ids: &[S]) -> Result<Vec<DaemonId>> {
        // Fast path: all IDs are already qualified and can be parsed directly.
        if user_ids.iter().all(|s| s.as_ref().contains('/')) {
            return user_ids
                .iter()
                .map(|s| DaemonId::parse(s.as_ref()))
                .collect();
        }

        let config = Self::all_merged()?;
        // Compute namespace once for all IDs
        let ns = Self::namespace_for_dir(&env::CWD)?;
        user_ids
            .iter()
            .map(|s| {
                let id = s.as_ref();
                if id.contains('/') {
                    DaemonId::parse(id)
                } else {
                    config.resolve_daemon_id_with_namespace(id, &ns)
                }
            })
            .collect()
    }

    /// Resolve explicit daemon IDs and/or a group name into a deduplicated list of DaemonIds.
    ///
    /// This is more efficient than calling `resolve_ids` and `resolve_group` separately
    /// because it reads the merged config only once.
    pub fn resolve_ids_and_group<S: AsRef<str>>(
        user_ids: &[S],
        group_name: Option<&str>,
    ) -> Result<Vec<DaemonId>> {
        let config = Self::all_merged()?;
        let ns = Self::namespace_for_dir(&env::CWD)?;
        let mut ids = Vec::new();
        let mut seen = std::collections::HashSet::new();

        for id in user_ids {
            let id_str = id.as_ref();
            let daemon_id = if id_str.contains('/') {
                DaemonId::parse(id_str)?
            } else {
                config.resolve_daemon_id_with_namespace(id_str, &ns)?
            };
            if seen.insert(daemon_id.clone()) {
                ids.push(daemon_id);
            }
        }

        if let Some(name) = group_name {
            let members = expand_group(&config.groups, name)?;
            let missing: Vec<String> = members
                .iter()
                .filter(|id| !config.daemons.contains_key(*id))
                .map(|id| id.qualified())
                .collect();
            if !missing.is_empty() {
                return Err(miette::miette!(
                    "group '{}' references undefined daemon{}: {}",
                    name,
                    if missing.len() > 1 { "s" } else { "" },
                    missing.join(", ")
                ));
            }
            for daemon_id in members {
                if seen.insert(daemon_id.clone()) {
                    ids.push(daemon_id);
                }
            }
        }

        Ok(ids)
    }

    /// List all configuration file paths from the current working directory.
    /// See `list_paths_from` for details on the search order.
    pub fn list_paths() -> Vec<PathBuf> {
        Self::list_paths_from(&env::CWD)
    }

    /// List all configuration file paths starting from a given directory.
    ///
    /// Returns paths in order of precedence (lowest to highest):
    /// 1. System-level: /etc/pitchfork/config.toml
    /// 2. User-level: ~/.config/pitchfork/config.toml
    /// 3. Project-level: .config/pitchfork.toml, .config/pitchfork.local.toml, pitchfork.toml and pitchfork.local.toml files
    ///    from filesystem root to the given directory
    ///
    /// Within each directory, .config/ comes before pitchfork.toml,
    /// which comes before pitchfork.local.toml, so local.toml values override base config.
    pub fn list_paths_from(cwd: &Path) -> Vec<PathBuf> {
        let mut paths = Vec::new();
        paths.push(env::PITCHFORK_GLOBAL_CONFIG_SYSTEM.clone());
        paths.push(env::PITCHFORK_GLOBAL_CONFIG_USER.clone());

        // Find all project config files. Order is reversed so after .reverse():
        // - each directory has: .config/pitchfork.toml < .config/pitchfork.local.toml < pitchfork.toml < pitchfork.local.toml
        // - directories go from root to cwd (later configs override earlier)
        let mut project_paths = xx::file::find_up_all(
            cwd,
            &[
                "pitchfork.local.toml",
                "pitchfork.toml",
                ".config/pitchfork.local.toml",
                ".config/pitchfork.toml",
            ],
        );
        project_paths.reverse();
        paths.extend(project_paths);
        paths.extend(crate::extra_configs::paths_for(cwd));

        paths
    }

    /// Merge all configuration files from the current working directory.
    /// See `all_merged_from` for details.
    pub fn all_merged() -> Result<PitchforkToml> {
        Self::all_merged_from(&env::CWD)
    }
    /// Load all merged config including daemons from ALL registered namespaces.
    ///
    /// Unlike `all_merged_from` which only merges configs from the cwd chain,
    /// this also iterates all `[namespaces]` entries and loads their daemon configs.
    /// Use this when you need a complete view (e.g. `start` for a daemon from
    /// another namespace).
    ///
    /// The read walks the filesystem and can start `git` or `jj` to find
    /// worktrees, so it runs on a blocking worker: being `async` is what keeps
    /// an async caller from running it on the runtime by accident. Code already
    /// on a blocking thread uses [`Self::all_merged_all_namespaces_blocking`].
    pub async fn all_merged_all_namespaces() -> Result<Self> {
        Self::all_merged_all_namespaces_from(&env::CWD).await
    }

    /// [`Self::all_merged_all_namespaces`] starting from `start_dir`.
    pub(crate) async fn all_merged_all_namespaces_from(start_dir: &Path) -> Result<Self> {
        let start_dir = start_dir.to_path_buf();
        match tokio::task::spawn_blocking(move || {
            Self::all_merged_all_namespaces_from_blocking(&start_dir)
        })
        .await
        {
            Ok(result) => result,
            Err(e) => Err(miette::miette!("reading the merged config panicked: {e}")),
        }
    }

    /// [`Self::all_merged_all_namespaces`] on the calling thread, for code that
    /// is already on a blocking thread and must not wait on the runtime.
    pub fn all_merged_all_namespaces_blocking() -> Result<Self> {
        Self::all_merged_all_namespaces_from_blocking(&env::CWD)
    }

    /// Core of [`Self::all_merged_all_namespaces`], parameterized by the
    /// starting directory so it is testable without touching the global `CWD`.
    pub(crate) fn all_merged_all_namespaces_from_blocking(start_dir: &Path) -> Result<Self> {
        let mut pt = Self::all_merged_from(start_dir)?;

        let namespaces = Self::read_global_namespaces();
        for (ns_name, entry) in namespaces {
            match Self::all_merged_from(&entry.dir) {
                Ok(ns_config) => {
                    for (daemon_id, daemon_config) in ns_config.daemons {
                        if !pt.daemons.contains_key(&daemon_id) {
                            pt.foreign_env
                                .insert(daemon_id.clone(), ns_config.env.clone());
                            pt.daemons.insert(daemon_id, daemon_config);
                        }
                    }
                    // Merge namespace-level settings so daemon-local
                    // overrides (e.g. hooks, env defaults) are available.
                    pt.settings.merge_from(&ns_config.settings);
                }
                Err(e) => {
                    log::warn!(
                        "Failed to load namespace '{ns_name}' from {}: {e}",
                        entry.dir.display()
                    );
                }
            }
        }

        // Auto-discover git worktrees / jj workspaces under the current
        // project, so daemons defined in a worktree are visible to supervisor
        // background tasks (cron registration, boot_start, file watch) even
        // when that worktree's namespace was never registered in
        // `[namespaces]`. Discovery spawns a `git`/`jj` subprocess (<1ms) and
        // the per-worktree config reads are cached by `CONFIG_CACHE`, so no
        // extra caching layer is needed here.
        // Controlled by the global setting so disabling worktrees affects both config
        // discovery and proxy slug routing.
        if crate::settings::settings().general.worktree
            && let Some(project_root) = find_project_root(start_dir)
        {
            let worktrees = crate::proxy::worktree::discover_worktrees(&project_root);
            for wt in &worktrees {
                match Self::all_merged_from(&wt.path) {
                    Ok(wt_config) => {
                        for (daemon_id, daemon_config) in wt_config.daemons {
                            if !pt.daemons.contains_key(&daemon_id) {
                                pt.daemons.insert(daemon_id, daemon_config);
                            }
                        }
                        pt.settings.merge_from(&wt_config.settings);
                    }
                    Err(e) => {
                        log::warn!(
                            "Failed to load worktree '{}' config from {}: {e}",
                            wt.branch,
                            wt.path.display()
                        );
                    }
                }
            }
        }

        Ok(pt)
    }

    /// Merge all configuration files starting from a given directory.
    ///
    /// Reads and merges configuration files in precedence order.
    /// Each daemon ID is qualified with a namespace based on its config file location:
    /// - Global configs (`~/.config/pitchfork/config.toml`) use namespace "global"
    /// - Project configs use the parent directory name as namespace
    ///
    /// This prevents ID conflicts when multiple projects define daemons with the same name.
    ///
    /// Results are cached by cwd and invalidated when any source file's mtime
    /// changes or when [`invalidate_config_cache`] is called (e.g. after a
    /// config write via `write()` / `write_unlocked()`).
    ///
    /// # Errors
    /// Returns an error if any config file fails to parse. Aborts with an error
    /// if two *different* project config files produce the same namespace (e.g. two
    /// `pitchfork.toml` files in separate directories that share the same directory name).
    pub fn all_merged_from(cwd: &Path) -> Result<PitchforkToml> {
        let paths = Self::list_paths_from(cwd);

        // Fast path: check the cache under a short-lived lock.
        // We canonicalize cwd for a stable key. If canonicalization fails
        // (e.g. the directory was just deleted), fall back to the raw path.
        let cache_key = cwd.canonicalize().unwrap_or_else(|_| cwd.to_path_buf());

        {
            let cache = CONFIG_CACHE.lock().unwrap_or_else(|e| e.into_inner());
            if let Some(entry) = cache.get(&cache_key)
                && meta_matches(&paths, &entry.source_meta)
            {
                return Ok(entry.config.clone());
            }
        }

        // Cache miss: snapshot (mtime, size) BEFORE reading.
        // If a file changes during the read, the snapshot (old mtime/size) won't
        // match the current values on the next call, forcing a re-read.
        // Taking the snapshot after the read would store old content with new
        // metadata, serving stale data indefinitely.
        let snapshot = snapshot_meta(&paths);
        let pt = Self::all_merged_from_uncached(&paths)?;

        // Store in cache.
        let mut cache = CONFIG_CACHE.lock().unwrap_or_else(|e| e.into_inner());
        cache.insert(
            cache_key,
            ConfigCacheEntry {
                config: pt.clone(),
                source_meta: snapshot,
            },
        );

        Ok(pt)
    }

    /// Uncached merge of all configuration files from a list of paths.
    ///
    /// This is the original merge logic extracted from `all_merged_from` so that
    /// the cache layer can wrap it without duplicating the algorithm.
    fn all_merged_from_uncached(paths: &[PathBuf]) -> Result<PitchforkToml> {
        use std::collections::HashMap as StdHashMap;

        let mut ns_to_origin: StdHashMap<String, (PathBuf, PathBuf)> = StdHashMap::new();

        let mut pt = Self::default();
        for p in paths {
            match Self::read(p) {
                Ok(pt2) => {
                    // Detect collisions for all existing project configs, including
                    // pitchfork.local.toml. Allow sibling base/local files in the same
                    // directory to share a namespace, including siblings via .config subfolder
                    if p.exists() && !is_global_config(p) {
                        let ns = namespace_from_path(p)?;
                        let origin_dir = project_dir_for_config(p)
                            .map(|dir| dir.canonicalize().unwrap_or_else(|_| dir.to_path_buf()))
                            .unwrap_or_else(|| p.clone());

                        if let Some((other_path, other_dir)) = ns_to_origin.get(ns.as_str())
                            && *other_dir != origin_dir
                        {
                            return Err(crate::error::ConfigParseError::NamespaceCollision {
                                path_a: other_path.clone(),
                                path_b: p.clone(),
                                ns,
                            }
                            .into());
                        }
                        ns_to_origin.insert(ns, (p.clone(), origin_dir));
                    }

                    pt.merge(pt2)
                }
                Err(e) => return Err(e.wrap_err(format!("error reading {}", p.display()))),
            }
        }
        Ok(pt)
    }
}

impl PitchforkToml {
    pub fn new(path: PathBuf) -> Self {
        Self {
            daemons: Default::default(),
            env: None,
            namespace: None,
            worktree_label: None,
            settings: SettingsPartial::default(),
            slugs: IndexMap::new(),
            groups: IndexMap::new(),
            namespaces: IndexMap::new(),
            path: Some(path),
            foreign_env: IndexMap::new(),
        }
    }

    /// Parse TOML content as a [`PitchforkToml`] without touching the filesystem.
    ///
    /// Applies the same namespace derivation and daemon validation as [`read()`] but
    /// uses the provided `content` directly instead of reading from disk.  `path` is
    /// used only for namespace derivation and error messages.
    ///
    /// This is useful for validating user-edited content before saving it.
    pub fn parse_str(content: &str, path: &Path) -> Result<Self> {
        let mut raw_config: PitchforkTomlRaw = toml::from_str(content)
            .map_err(|e| ConfigParseError::from_toml_error(path, content.to_string(), e))?;
        if let Some(settings) = &mut raw_config.settings {
            settings.canonicalize_aliases();
        }

        let explicit = directory_namespace_override(path, Some(content))?;
        let namespace = namespace_from_path_with_override(path, explicit.as_deref())?;
        let mut pt = Self::new(path.to_path_buf());
        pt.namespace = raw_config.namespace.clone();
        pt.worktree_label = raw_config.worktree_label.clone();

        for (short_name, raw_daemon) in raw_config.daemons {
            let id = match DaemonId::try_new(&namespace, &short_name) {
                Ok(id) => id,
                Err(e) => {
                    return Err(ConfigParseError::InvalidDaemonName {
                        name: short_name,
                        path: path.to_path_buf(),
                        reason: e.to_string(),
                    }
                    .into());
                }
            };

            let mut depends = Vec::new();
            for dep in raw_daemon.depends {
                let dep_id = if dep.contains('/') {
                    match DaemonId::parse(&dep) {
                        Ok(id) => id,
                        Err(e) => {
                            return Err(ConfigParseError::InvalidDependency {
                                daemon: short_name.clone(),
                                dependency: dep,
                                path: path.to_path_buf(),
                                reason: e.to_string(),
                            }
                            .into());
                        }
                    }
                } else {
                    match DaemonId::try_new(&namespace, &dep) {
                        Ok(id) => id,
                        Err(e) => {
                            return Err(ConfigParseError::InvalidDependency {
                                daemon: short_name.clone(),
                                dependency: dep,
                                path: path.to_path_buf(),
                                reason: e.to_string(),
                            }
                            .into());
                        }
                    }
                };
                depends.push(dep_id);
            }

            // Resolve port config: prefer new `port` field, fall back to deprecated fields
            let has_deprecated = !raw_daemon.expected_port.is_empty()
                || raw_daemon.auto_bump_port.is_some()
                || raw_daemon.port_bump_attempts.is_some();
            let deprecated_port = has_deprecated.then(|| {
                let bump = if raw_daemon.auto_bump_port.unwrap_or(false) {
                    PortBump(
                        raw_daemon
                            .port_bump_attempts
                            .unwrap_or_else(|| settings().default_port_bump_attempts()),
                    )
                } else {
                    PortBump(0)
                };
                PortConfig {
                    expect: raw_daemon.expected_port,
                    bump,
                }
            });
            let port = match (raw_daemon.port, deprecated_port) {
                (Some(port), Some(deprecated)) => {
                    // Writing the config adds the deprecated fields beside
                    // `port` for older versions; only a disagreement is news.
                    if deprecated != port {
                        warn!(
                            "daemon {short_name}: both `port` and deprecated expected_port/auto_bump_port/port_bump_attempts are set; ignoring deprecated fields"
                        );
                    }
                    Some(port)
                }
                (Some(port), None) => Some(port),
                (None, Some(deprecated)) => {
                    deprecated_at!(
                        "2026-10-03",
                        "2027-10-03",
                        format!("port-fields:{id}"),
                        "daemon {short_name}: expected_port/auto_bump_port/port_bump_attempts are deprecated, use [daemons.{short_name}.port] instead."
                    );
                    Some(deprecated)
                }
                (None, None) => None,
            };

            // `proxy_port` is the shorter spelling of the same setting.
            if let (Some(explicit), Some(short)) =
                (raw_daemon.proxy_tls_port, raw_daemon.proxy_port)
                && explicit != short
            {
                warn!(
                    "daemon {short_name}: proxy_tls_port ({explicit}) and proxy_port ({short}) \
                     disagree; using proxy_tls_port"
                );
            }
            let proxy_tls_port = raw_daemon.proxy_tls_port.or(raw_daemon.proxy_port);

            // Port 0 asks the operating system to choose, so it names no port
            // a hostname can be sent to.
            for (key, value) in [
                ("proxy_tls_port", raw_daemon.proxy_tls_port),
                ("proxy_port", raw_daemon.proxy_port),
            ] {
                if value == Some(0) {
                    return Err(ConfigParseError::ProxyPortZero {
                        daemon: short_name.clone(),
                        key,
                        path: path.to_path_buf(),
                    }
                    .into());
                }
            }

            // The hostname maps to one of the daemon's own ports, so a port it
            // never declares cannot be routed to.
            if let Some(port_want) = proxy_tls_port {
                let declared = port.as_ref().map(|p| p.expect.clone()).unwrap_or_default();
                if !declared.contains(&port_want) {
                    return Err(ConfigParseError::ProxyPortNotDeclared {
                        daemon: short_name.clone(),
                        port: port_want,
                        declared,
                        path: path.to_path_buf(),
                    }
                    .into());
                }
            }

            // TLS passthrough splices the raw stream to 127.0.0.1:<port>, so a
            // daemon without a known port has nothing to splice to.
            if raw_daemon
                .proxy_tls
                .is_some_and(ProxyTlsMode::is_passthrough)
                && port
                    .as_ref()
                    .is_none_or(|p| p.expect.iter().all(|&port| port == 0))
            {
                return Err(ConfigParseError::PassthroughWithoutPort {
                    daemon: short_name.clone(),
                    path: path.to_path_buf(),
                }
                .into());
            }

            if let RunCommand::Argv(argv) = &raw_daemon.run {
                match argv.first().map(String::as_str) {
                    None => {
                        return Err(ConfigParseError::EmptyRunArgv {
                            daemon: short_name.clone(),
                            path: path.to_path_buf(),
                        }
                        .into());
                    }
                    // Almost certainly a shell command line carried over: in
                    // an array it would look for a program called `exec`.
                    Some("exec") => {
                        return Err(ConfigParseError::ExecInRunArgv {
                            daemon: short_name.clone(),
                            path: path.to_path_buf(),
                        }
                        .into());
                    }
                    Some(_) => {}
                }
            }

            if let Some(RunCommand::Argv(argv)) = raw_daemon.ready_cmd.as_ref().map(|c| &c.run) {
                match argv.first().map(String::as_str) {
                    // An empty program would fail every probe, and with no
                    // timeout the start would wait for readiness forever.
                    None | Some("") => {
                        return Err(ConfigParseError::EmptyReadyCmdArgv {
                            daemon: short_name.clone(),
                            path: path.to_path_buf(),
                        }
                        .into());
                    }
                    Some("exec") => {
                        return Err(ConfigParseError::ExecInReadyCmdArgv {
                            daemon: short_name.clone(),
                            path: path.to_path_buf(),
                        }
                        .into());
                    }
                    Some(_) => {}
                }
            }

            if let Some(RunCommand::Argv(argv)) = raw_daemon.health_cmd.as_ref().map(|c| &c.run) {
                match argv.first().map(String::as_str) {
                    // An empty program would fail every probe, and the daemon
                    // would be killed once its health check retries ran out.
                    None | Some("") => {
                        return Err(ConfigParseError::EmptyHealthCmdArgv {
                            daemon: short_name.clone(),
                            path: path.to_path_buf(),
                        }
                        .into());
                    }
                    Some("exec") => {
                        return Err(ConfigParseError::ExecInHealthCmdArgv {
                            daemon: short_name.clone(),
                            path: path.to_path_buf(),
                        }
                        .into());
                    }
                    Some(_) => {}
                }
            }

            let daemon = PitchforkTomlDaemon {
                run: raw_daemon.run,
                auto: raw_daemon.auto,
                oneshot: raw_daemon.oneshot,
                cron: raw_daemon.cron,
                retry: raw_daemon.retry,
                ready_delay: raw_daemon.ready_delay,
                ready_output: raw_daemon.ready_output,
                ready_http: raw_daemon.ready_http,
                ready_port: raw_daemon.ready_port,
                ready_cmd: raw_daemon.ready_cmd,
                health_cmd: raw_daemon.health_cmd,
                health_http: raw_daemon.health_http,
                health_port: raw_daemon.health_port,
                port,
                proxy: raw_daemon.proxy,
                proxy_tls: raw_daemon.proxy_tls,
                proxy_tls_port: raw_daemon.proxy_tls_port,
                proxy_port: raw_daemon.proxy_port,
                proxy_idle_timeout: raw_daemon.proxy_idle_timeout,
                boot_start: raw_daemon.boot_start,
                depends,
                watch: raw_daemon.watch,
                watch_mode: raw_daemon.watch_mode.unwrap_or_default(),
                dir: raw_daemon.dir,
                env: raw_daemon.env,
                env_file: raw_daemon.env_file,
                hooks: raw_daemon.hooks,
                mise: raw_daemon.mise,
                deferred_template_context: None,
                user: raw_daemon.user,
                memory_limit: raw_daemon.memory_limit,
                cpu_limit: raw_daemon.cpu_limit,
                stop_signal: raw_daemon.stop_signal,
                pty: raw_daemon.pty,
                time_retention: raw_daemon.time_retention,
                line_retention: raw_daemon.line_retention,
                archive_hook: raw_daemon.archive_hook,
                logs: raw_daemon.logs,
                path: Some(path.to_path_buf()),
            };
            if daemon.is_oneshot() {
                let conflicts = daemon.oneshot_conflicts();
                if !conflicts.is_empty() {
                    return Err(ConfigParseError::OneshotConflict {
                        daemon: short_name.clone(),
                        path: path.to_path_buf(),
                        conflicts: conflicts.into_iter().map(str::to_string).collect(),
                    }
                    .into());
                }
            }
            pt.daemons.insert(id, daemon);
        }

        // Copy settings if present
        if let Some(settings) = raw_config.settings {
            pt.settings = settings;
        }

        // Copy top-level env
        pt.env = raw_config.env;

        // Copy slugs registry (only meaningful in global config files)
        for (slug, entry) in raw_config.slugs {
            pt.slugs.insert(
                slug,
                SlugEntry {
                    dir: entry.dir.map(env::expand_tilde),
                    namespace: entry.namespace,
                    daemon: entry.daemon,
                },
            );
        }

        // Copy namespaces registry (only meaningful in global config files)
        for (name, entry) in raw_config.namespaces {
            pt.namespaces.insert(
                name,
                NamespaceEntry {
                    config: entry
                        .config
                        .iter()
                        .map(|p| {
                            crate::extra_configs::resolve_path(&env::expand_tilde(&entry.dir), p)
                        })
                        .collect(),
                    dir: env::expand_tilde(entry.dir),
                    label: entry.label,
                },
            );
        }

        // Resolve group entries: convert short daemon names to qualified DaemonIds
        for (group_name, raw_group) in raw_config.groups {
            let mut daemons = Vec::new();
            for daemon_name in &raw_group.daemons {
                let id = if daemon_name.contains('/') {
                    DaemonId::parse(daemon_name).map_err(|e| {
                        ConfigParseError::InvalidDependency {
                            daemon: group_name.clone(),
                            dependency: daemon_name.clone(),
                            path: path.to_path_buf(),
                            reason: e.to_string(),
                        }
                    })?
                } else {
                    DaemonId::try_new(&namespace, daemon_name).map_err(|e| {
                        ConfigParseError::InvalidDaemonName {
                            name: daemon_name.clone(),
                            path: path.to_path_buf(),
                            reason: e.to_string(),
                        }
                    })?
                };
                daemons.push(id);
            }
            pt.groups.insert(
                group_name,
                GroupEntry {
                    daemons,
                    groups: raw_group.groups,
                },
            );
        }

        Ok(pt)
    }

    pub fn read<P: AsRef<Path>>(path: P) -> Result<Self> {
        let path = path.as_ref();
        if !path.exists() {
            return Ok(Self::new(path.to_path_buf()));
        }
        let _lock = xx::fslock::get(path, false)
            .wrap_err_with(|| format!("failed to acquire lock on {}", path.display()))?;
        let raw = std::fs::read_to_string(path).map_err(|e| FileError::ReadError {
            path: path.to_path_buf(),
            source: e,
        })?;
        Self::parse_str(&raw, path)
    }

    pub fn write(&self) -> Result<()> {
        if let Some(path) = &self.path {
            let _lock = xx::fslock::get(path, false)
                .wrap_err_with(|| format!("failed to acquire lock on {}", path.display()))?;
            self.write_unlocked()
        } else {
            Err(FileError::NoPath.into())
        }
    }

    /// Write the config file without acquiring a file lock.
    ///
    /// The caller MUST hold the file lock (via `xx::fslock::get`) before
    /// calling this method. This is used by `register_slug` which needs to
    /// hold a single lock across a read-modify-write cycle.
    pub(crate) fn write_unlocked(&self) -> Result<()> {
        if let Some(path) = &self.path {
            // Determine the namespace for this config file
            // A new file without its own `namespace` shares the one its
            // directory's other config files declare, as it will once read.
            let config_namespace = if path.exists() || self.namespace.is_none() {
                namespace_from_path(path)?
            } else {
                namespace_from_path_with_override(path, self.namespace.as_deref())?
            };

            // Convert back to raw format for writing (use short names as keys)
            // Preserve settings so read-modify-write (e.g. `settings set`, `proxy add`)
            // doesn't drop `[settings.*]`. Gate on is_empty to avoid a bare `[settings]`.
            let mut raw = PitchforkTomlRaw {
                namespace: self.namespace.clone(),
                worktree_label: self.worktree_label.clone(),
                env: self.env.clone(),
                settings: (!self.settings.is_empty()).then(|| self.settings.clone()),
                ..PitchforkTomlRaw::default()
            };
            for (id, daemon) in &self.daemons {
                if id.namespace() != config_namespace {
                    return Err(miette::miette!(
                        "cannot write daemon '{}' to {}: daemon belongs to namespace '{}' but file namespace is '{}'",
                        id,
                        path.display(),
                        id.namespace(),
                        config_namespace
                    ));
                }
                let port = daemon.port.as_ref();
                let raw_daemon = PitchforkTomlDaemonRaw {
                    run: daemon.run.clone(),
                    auto: daemon.auto.clone(),
                    oneshot: daemon.oneshot,
                    cron: daemon.cron.clone(),
                    retry: daemon.retry,
                    ready_delay: daemon.ready_delay,
                    ready_output: daemon.ready_output.clone(),
                    ready_http: daemon.ready_http.clone(),
                    ready_port: daemon.ready_port.clone(),
                    ready_cmd: daemon.ready_cmd.clone(),
                    health_cmd: daemon.health_cmd.clone(),
                    health_http: daemon.health_http.clone(),
                    health_port: daemon.health_port.clone(),
                    port: port.cloned(),
                    proxy: daemon.proxy.clone(),
                    proxy_tls: daemon.proxy_tls,
                    proxy_tls_port: daemon.proxy_tls_port,
                    proxy_port: daemon.proxy_port,
                    proxy_idle_timeout: daemon.proxy_idle_timeout,
                    // Deprecated fields: written for backward compatibility with older pitchfork versions
                    expected_port: port.map(|p| p.expect.clone()).unwrap_or_default(),
                    auto_bump_port: port.filter(|p| p.auto_bump()).map(|_| true),
                    port_bump_attempts: port
                        .filter(|p| p.auto_bump())
                        .map(|p| p.max_bump_attempts()),
                    boot_start: daemon.boot_start,
                    // Preserve cross-namespace dependencies: use qualified ID if namespace differs,
                    // otherwise use short name
                    depends: daemon
                        .depends
                        .iter()
                        .map(|d| {
                            if d.namespace() == config_namespace {
                                d.name().to_string()
                            } else {
                                d.qualified()
                            }
                        })
                        .collect(),
                    watch: daemon.watch.clone(),
                    watch_mode: match daemon.watch_mode {
                        WatchMode::Native => None,
                        mode => Some(mode),
                    },
                    dir: daemon.dir.clone(),
                    env: daemon.env.clone(),
                    env_file: daemon.env_file.clone(),
                    hooks: daemon.hooks.clone(),
                    mise: daemon.mise,
                    user: daemon.user.clone(),
                    memory_limit: daemon.memory_limit,
                    cpu_limit: daemon.cpu_limit,
                    stop_signal: daemon.stop_signal,
                    pty: daemon.pty,
                    time_retention: daemon.time_retention.clone(),
                    line_retention: daemon.line_retention,
                    archive_hook: daemon.archive_hook.clone(),
                    logs: daemon.logs.clone(),
                };
                raw.daemons.insert(id.name().to_string(), raw_daemon);
            }

            // Copy slugs registry to raw format
            for (slug, entry) in &self.slugs {
                raw.slugs.insert(
                    slug.clone(),
                    SlugEntryRaw {
                        dir: entry.dir.as_ref().map(|d| d.to_string_lossy().to_string()),
                        namespace: entry.namespace.clone(),
                        daemon: entry.daemon.clone(),
                    },
                );
            }

            // Serialize groups back to raw format (preserve cross-namespace refs as qualified IDs)
            for (name, group) in &self.groups {
                let raw_daemons: Vec<String> = group
                    .daemons
                    .iter()
                    .map(|id| {
                        if id.namespace() == config_namespace {
                            id.name().to_string()
                        } else {
                            id.qualified()
                        }
                    })
                    .collect();
                raw.groups.insert(
                    name.clone(),
                    GroupEntryRaw {
                        daemons: raw_daemons,
                        groups: group.groups.clone(),
                    },
                );
            }

            // Copy namespaces registry to raw format
            for (name, entry) in &self.namespaces {
                raw.namespaces.insert(
                    name.clone(),
                    NamespaceEntryRaw {
                        dir: entry.dir.to_string_lossy().to_string(),
                        config: entry
                            .config
                            .iter()
                            .map(|p| p.to_string_lossy().into_owned())
                            .collect(),
                        label: entry.label.clone(),
                    },
                );
            }

            let raw_str = toml::to_string(&raw).map_err(|e| FileError::SerializeError {
                path: path.clone(),
                source: e,
            })?;
            xx::file::write(path, &raw_str).map_err(|e| FileError::WriteError {
                path: path.clone(),
                details: Some(e.to_string()),
            })?;
            invalidate_config_cache();
            Ok(())
        } else {
            Err(FileError::NoPath.into())
        }
    }

    /// Simple merge without namespace re-qualification.
    /// Used primarily for testing or when merging configs from the same namespace.
    /// Since read() already qualifies daemon IDs with namespace, this just inserts them.
    /// Settings are also merged - later values override earlier ones.
    pub fn merge(&mut self, pt: Self) {
        if pt.worktree_label.is_some() {
            self.worktree_label = pt.worktree_label.clone();
        }
        for (id, d) in pt.daemons {
            self.daemons.insert(id, d);
        }
        // Merge top-level env - pt's values override self's values
        if let Some(env) = pt.env {
            let merged = self.env.get_or_insert_with(IndexMap::new);
            for (k, v) in env {
                merged.insert(k, v);
            }
        }
        // Merge slugs - pt's values override self's values
        for (slug, entry) in pt.slugs {
            self.slugs.insert(slug, entry);
        }
        // Merge groups - pt's values override self's values
        for (name, group) in pt.groups {
            self.groups.insert(name, group);
        }
        // Merge namespaces - pt's values override self's values
        for (name, entry) in pt.namespaces {
            self.namespaces.insert(name, entry);
        }
        // Merge settings - pt's values override self's values
        self.settings.merge_from(&pt.settings);
    }

    /// Read the global slug registry from the user-level global config.
    ///
    /// Returns a map of slug → SlugEntry from `[slugs]` in
    /// `~/.config/pitchfork/config.toml`.
    pub fn read_global_slugs() -> IndexMap<String, SlugEntry> {
        match Self::read(&*env::PITCHFORK_GLOBAL_CONFIG_USER) {
            Ok(pt) => pt.slugs,
            Err(_) => IndexMap::new(),
        }
    }

    /// Whether more than one registry key folds to `slug`'s ASCII-lowercased form.
    ///
    /// Host names are case-insensitive (RFC 4343), so the proxy refuses to route
    /// such a slug at all rather than pick one of the spellings.  Callers that
    /// turn a slug into a URL must not advertise an address the proxy will
    /// reject, so they check this first.
    pub fn slug_is_ambiguous(slug: &str, global_slugs: &IndexMap<String, SlugEntry>) -> bool {
        global_slugs
            .keys()
            .filter(|k| k.eq_ignore_ascii_case(slug))
            .count()
            > 1
    }

    /// Find the registered slug for a daemon using a pre-loaded slug registry.
    ///
    /// Returns `None` for a slug the proxy will not route — see
    /// [`Self::slug_is_ambiguous`].
    pub fn find_slug_for_daemon_in_registry(
        daemon_id: &DaemonId,
        global_slugs: &IndexMap<String, SlugEntry>,
    ) -> Option<String> {
        global_slugs
            .iter()
            .find(|(slug, entry)| {
                let daemon_name = entry.daemon.as_deref().unwrap_or(slug);
                if daemon_id.name() != daemon_name {
                    return false;
                }

                // Skipped rather than returned and discarded: another alias for
                // the same daemon may still be routable.
                if Self::slug_is_ambiguous(slug, global_slugs) {
                    return false;
                }

                match entry.resolve_namespace() {
                    Some(namespace) => daemon_id.namespace() == namespace,
                    None => false,
                }
            })
            .map(|(slug, _)| slug.clone())
    }

    /// Check if a slug is registered in the global config's `[slugs]` section.
    #[allow(dead_code)]
    pub fn is_slug_registered(slug: &str) -> bool {
        Self::read_global_slugs().contains_key(slug)
    }

    /// Add a slug entry to the global config's `[slugs]` section using namespace instead of dir.
    ///
    /// Reads the global config, adds/updates the slug entry, and writes it back.
    /// If `namespace` is provided but not yet registered in `[namespaces]`,
    /// also registers it at `dir` (acquired via `resolve_dir()` on the slug entry).
    pub fn add_slug_with_namespace(
        slug: &str,
        namespace: Option<&str>,
        daemon: Option<&str>,
    ) -> Result<()> {
        let global_path = &*env::PITCHFORK_GLOBAL_CONFIG_USER;

        // Ensure the config directory exists
        if let Some(parent) = global_path.parent() {
            std::fs::create_dir_all(parent).map_err(|e| {
                miette::miette!(
                    "Failed to create config directory {}: {e}",
                    parent.display()
                )
            })?;
        }

        let _lock = xx::fslock::get(global_path, false)
            .wrap_err_with(|| format!("failed to acquire lock on {}", global_path.display()))?;

        let mut pt = if global_path.exists() {
            let raw = std::fs::read_to_string(global_path).map_err(|e| FileError::ReadError {
                path: global_path.to_path_buf(),
                source: e,
            })?;
            Self::parse_str(&raw, global_path)?
        } else {
            Self::new(global_path.to_path_buf())
        };

        // If caller provided a namespace that isn't yet registered,
        // auto-register it at the directory we can resolve.
        // Falls back to CWD if the slug dir cannot be resolved.
        if let Some(ns) = namespace
            && !pt.namespaces.contains_key(ns)
        {
            // Resolve against the already-parsed `pt` instead of
            // SlugEntry::resolve_dir(): that re-reads the global config via
            // read(), which would re-acquire the lock held above (flock is per
            // open file description, so the same process deadlocks on itself).
            let dir = pt
                .slugs
                .get(slug)
                .and_then(|e| {
                    e.dir.clone().or_else(|| {
                        e.namespace
                            .as_ref()
                            .and_then(|ns| pt.namespaces.get(ns).map(|entry| entry.dir.clone()))
                    })
                })
                .or_else(|| env::CWD.as_path().canonicalize().ok());
            if let Some(ref d) = dir {
                pt.namespaces.insert(
                    ns.to_string(),
                    NamespaceEntry {
                        dir: d.clone(),
                        config: Vec::new(),
                        label: None,
                    },
                );
            }
        }

        pt.slugs.insert(
            slug.to_string(),
            SlugEntry {
                dir: None,
                namespace: namespace.map(str::to_string),
                daemon: daemon.map(str::to_string),
            },
        );
        pt.write_unlocked()?;
        // Sync hosts from the in-memory slug set, not sync_hosts_from_settings():
        // that re-reads the global config via read(), which acquires the lock held
        // above — flock is per open file description, so re-acquiring in the same
        // process deadlocks against our own lock. Staying under the lock also keeps
        // hosts writes ordered with config mutations across concurrent commands.
        let slug_names: Vec<String> = pt.slugs.keys().cloned().collect();
        crate::proxy::hosts::sync_hosts_from_settings_with_slugs(&slug_names);
        Ok(())
    }

    /// Remove a slug from the global config's `[slugs]` section.
    pub fn remove_slug(slug: &str) -> Result<bool> {
        let global_path = &*env::PITCHFORK_GLOBAL_CONFIG_USER;
        if !global_path.exists() {
            return Ok(false);
        }

        let _lock = xx::fslock::get(global_path, false)
            .wrap_err_with(|| format!("failed to acquire lock on {}", global_path.display()))?;

        let raw = std::fs::read_to_string(global_path).map_err(|e| FileError::ReadError {
            path: global_path.to_path_buf(),
            source: e,
        })?;
        let mut pt = Self::parse_str(&raw, global_path)?;

        let removed = pt.slugs.shift_remove(slug).is_some();
        if removed {
            pt.write_unlocked()?;
            // Sync hosts from the in-memory slug set, not sync_hosts_from_settings():
            // that re-reads the global config via read(), which acquires the lock held
            // above — flock is per open file description, so re-acquiring in the same
            // process deadlocks against our own lock. Staying under the lock also keeps
            // hosts writes ordered with config mutations across concurrent commands.
            let slug_names: Vec<String> = pt.slugs.keys().cloned().collect();
            crate::proxy::hosts::sync_hosts_from_settings_with_slugs(&slug_names);
        }
        Ok(removed)
    }
    /// Returns a map of namespace → NamespaceEntry from `[namespaces]` in
    /// `~/.config/pitchfork/config.toml`.
    pub fn read_global_namespaces() -> IndexMap<String, NamespaceEntry> {
        match Self::read(&*env::PITCHFORK_GLOBAL_CONFIG_USER) {
            Ok(pt) => pt.namespaces,
            Err(_) => IndexMap::new(),
        }
    }

    /// Add a namespace entry to the global config's `[namespaces]` section.
    ///
    /// Reads the global config, adds/updates the namespace entry, and writes it back.
    pub fn register_namespace(name: &str, dir: &str) -> crate::Result<()> {
        let global_path = &*crate::env::PITCHFORK_GLOBAL_CONFIG_USER;

        // Ensure the config directory exists
        if let Some(parent) = global_path.parent() {
            std::fs::create_dir_all(parent).map_err(|e| {
                miette::miette!(
                    "Failed to create config directory {}: {e}",
                    parent.display()
                )
            })?;
        }

        let _lock = xx::fslock::get(global_path, false)
            .wrap_err_with(|| format!("failed to acquire lock on {}", global_path.display()))?;

        let mut pt = if global_path.exists() {
            let raw = std::fs::read_to_string(global_path).map_err(|e| {
                crate::error::FileError::ReadError {
                    path: global_path.to_path_buf(),
                    source: e,
                }
            })?;
            Self::parse_str(&raw, global_path)?
        } else {
            Self::new(global_path.to_path_buf())
        };

        let dir = env::expand_tilde(dir);
        if let Some(entry) = pt.namespaces.get_mut(name) {
            if crate::extra_configs::path_is_gone(&entry.dir)
                && crate::extra_configs::normalize(&entry.dir)
                    != crate::extra_configs::normalize(&dir)
            {
                if crate::extra_configs::namespace_has_running_daemon(name) {
                    // Retargeting would show the old project's running daemons
                    // to the new one.
                    miette::bail!(
                        "namespace '{name}' has running daemons from {}, which no longer exists; stop them first",
                        entry.dir.display()
                    );
                }
                // The old project is gone: its attachments and label go with it.
                entry.config.clear();
                entry.label = None;
            }
            if !entry.config.is_empty()
                && crate::extra_configs::normalize(&entry.dir)
                    != crate::extra_configs::normalize(&dir)
            {
                miette::bail!(
                    "namespace '{name}' has external configuration attached to another directory"
                );
            }
            entry.dir = dir;
        } else {
            pt.namespaces.insert(
                name.to_string(),
                NamespaceEntry {
                    dir,
                    config: Vec::new(),
                    label: None,
                },
            );
        }
        pt.write_unlocked()?;
        Ok(())
    }

    /// Remove a namespace from the global config's `[namespaces]` section.
    pub fn remove_namespace(name: &str) -> crate::Result<bool> {
        let global_path = &*crate::env::PITCHFORK_GLOBAL_CONFIG_USER;
        if !global_path.exists() {
            return Ok(false);
        }

        let _lock = xx::fslock::get(global_path, false)
            .wrap_err_with(|| format!("failed to acquire lock on {}", global_path.display()))?;

        let raw = std::fs::read_to_string(global_path).map_err(|e| {
            crate::error::FileError::ReadError {
                path: global_path.to_path_buf(),
                source: e,
            }
        })?;
        let mut pt = Self::parse_str(&raw, global_path)?;

        let removed = pt.namespaces.shift_remove(name).is_some();
        if removed {
            pt.write_unlocked()?;
        }
        Ok(removed)
    }
}

/// What [`PitchforkToml::prune_stale_registrations`] removed.
#[derive(Debug, Default, Clone, PartialEq, Eq)]
pub struct PruneReport {
    /// `[namespaces]` entries whose project directory no longer exists.
    pub namespaces: Vec<String>,
    /// `[slugs]` entries that pointed at a removed or missing directory.
    pub slugs: Vec<String>,
    /// Attached external configuration files that no longer exist.
    pub config_files: usize,
}

impl PruneReport {
    pub fn is_empty(&self) -> bool {
        self.namespaces.is_empty() && self.slugs.is_empty() && self.config_files == 0
    }
}

impl PitchforkToml {
    /// Drop `[namespaces]`, `[slugs]` and attached external config files in the
    /// user-level global config that point at paths that no longer exist.
    ///
    /// Tools and scratch projects register namespaces and slugs and are rarely
    /// able to unregister them when their directory is deleted, so the registry
    /// otherwise only ever grows.
    ///
    /// * `keep` names namespaces that must be left alone, typically those with
    ///   a running daemon.
    /// * `only` limits the pass to the listed namespaces; empty means all.
    ///
    /// A path is only treated as gone when the filesystem answers that it does
    /// not exist: an I/O error (permissions, a flaky mount) keeps the entry.
    pub fn prune_stale_registrations(
        keep: &std::collections::HashSet<String>,
        only: &[String],
    ) -> Result<PruneReport> {
        let global_path = &*env::PITCHFORK_GLOBAL_CONFIG_USER;
        let mut report = PruneReport::default();
        if !global_path.exists() {
            return Ok(report);
        }
        let _lock = xx::fslock::get(global_path, false)
            .wrap_err_with(|| format!("failed to acquire lock on {}", global_path.display()))?;
        let raw = std::fs::read_to_string(global_path).map_err(|e| FileError::ReadError {
            path: global_path.to_path_buf(),
            source: e,
        })?;
        let mut pt = Self::parse_str(&raw, global_path)?;
        let in_scope = |ns: &str| only.is_empty() || only.iter().any(|o| o == ns);

        for (name, entry) in pt.namespaces.iter_mut() {
            if keep.contains(name) || !in_scope(name) {
                continue;
            }
            if crate::extra_configs::path_is_gone(&entry.dir) {
                report.namespaces.push(name.clone());
                continue;
            }
            let before = entry.config.len();
            entry
                .config
                .retain(|file| !crate::extra_configs::path_is_gone(file));
            let dropped = before - entry.config.len();
            if dropped > 0 {
                report.config_files += dropped;
                if entry.config.is_empty() {
                    // Same as detaching the last file: the label goes with it.
                    entry.label = None;
                }
            }
        }
        for name in &report.namespaces {
            pt.namespaces.shift_remove(name);
        }

        if only.is_empty() || !report.namespaces.is_empty() {
            for (slug, entry) in &pt.slugs {
                // A slug of a namespace with a running daemon stays, even if
                // its own directory moved.
                if entry.namespace.as_ref().is_some_and(|ns| keep.contains(ns)) {
                    continue;
                }
                let ns_pruned = entry
                    .namespace
                    .as_ref()
                    .is_some_and(|ns| report.namespaces.contains(ns));
                let dir_gone = entry
                    .dir
                    .as_ref()
                    .is_some_and(|d| crate::extra_configs::path_is_gone(d));
                // A slug that names a directory directly is only in scope for
                // an unscoped pass, since it belongs to no namespace.
                let scoped_ok = only.is_empty() || ns_pruned;
                if scoped_ok && (ns_pruned || dir_gone) {
                    report.slugs.push(slug.clone());
                }
            }
            for slug in &report.slugs {
                pt.slugs.shift_remove(slug);
            }
        }

        if !report.is_empty() {
            pt.write_unlocked()?;
            if !report.slugs.is_empty() {
                let slug_names: Vec<String> = pt.slugs.keys().cloned().collect();
                crate::proxy::hosts::sync_hosts_from_settings_with_slugs(&slug_names);
            }
        }
        Ok(report)
    }
}

/// Configuration for a single daemon (internal representation with DaemonId)
#[derive(Debug, Clone, JsonSchema, Default)]
pub struct PitchforkTomlDaemon {
    /// The command to run: a command line for the shell, or an array of a
    /// program and its arguments to start without a shell. In the string
    /// form, prepend 'exec' to avoid shell process overhead.
    #[schemars(example = example_run_command())]
    pub run: RunCommand,
    /// Automatic start/stop behavior based on shell hooks
    #[schemars(default)]
    pub auto: Vec<PitchforkTomlAuto>,
    /// Run this daemon as a task that must finish rather than a long-running
    /// service. Readiness means the process exited with code 0, the daemon
    /// then reports the `completed` status, and daemons that `depends` on it
    /// wait for that completion. Cannot be combined with any `ready_*` or
    /// `health_*` field.
    pub oneshot: Option<bool>,
    /// Cron scheduling configuration for periodic execution
    pub cron: Option<PitchforkTomlCron>,
    /// Number of times to retry if the daemon fails.
    /// Can be a number (e.g., `3`) or `true` for infinite retries.
    #[schemars(default)]
    pub retry: Retry,
    /// Delay in seconds before considering the daemon ready
    pub ready_delay: Option<u64>,
    /// Regex pattern to match in ANSI-stripped stdout/stderr to determine readiness
    pub ready_output: Option<ReadyOutput>,
    /// HTTP URL to poll for readiness. Accepts any 2xx response by default, or configured statuses.
    pub ready_http: Option<ReadyHttp>,
    /// TCP port to check for readiness (connection success = ready).
    /// Accepts a port number, a Tera template string that renders to one, or an
    /// object with an optional overall polling timeout.
    pub ready_port: Option<ReadyPort>,
    /// Shell command to poll for readiness (exit code 0 = ready)
    pub ready_cmd: Option<ReadyCmd>,
    /// Shell command to poll for health (exit code 0 = healthy)
    pub health_cmd: Option<HealthCmd>,
    /// HTTP endpoint URL to poll for health
    pub health_http: Option<HealthHttp>,
    /// TCP port to probe for health (connection success = healthy).
    /// Accepts a port number, a Tera template string that renders to one, or an
    /// object with optional per-check `interval`, `retries`, and `timeout`.
    pub health_port: Option<HealthPort>,
    /// Port configuration: expected ports and auto-bump settings
    pub port: Option<PortConfig>,
    /// Proxy routing: `false` opts out of the automatic hostname, a string
    /// overrides the daemon label used in it.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub proxy: Option<ProxyConfig>,
    /// TLS handling for this daemon's proxy hostname.
    ///
    /// - `terminate` (default): the proxy terminates TLS with its own
    ///   certificate and forwards plain HTTP to the daemon.
    /// - `passthrough`: the proxy reads the SNI hostname from the TLS
    ///   ClientHello and splices the raw TCP stream to the daemon, which
    ///   presents its own certificate and can require client certificates.
    ///   Requires `port`.
    pub proxy_tls: Option<ProxyTlsMode>,
    /// Which of the daemon's ports the proxy hostname maps to.
    ///
    /// Must name one of the ports in `port`. Defaults to the daemon's first
    /// port. `proxy_port` is the shorter spelling of the same setting.
    #[schemars(range(min = 1))]
    pub proxy_tls_port: Option<u16>,
    /// Shorter spelling of `proxy_tls_port`. Set one or the other, not both.
    ///
    /// Kept separate rather than folded so that a config keeps the spelling
    /// its author chose when pitchfork rewrites it. Read
    /// [`Self::effective_proxy_tls_port`] rather than either field.
    #[schemars(range(min = 1))]
    pub proxy_port: Option<u16>,
    /// Idle timeout when the proxy auto-starts this daemon, for example `"15m"`.
    /// Accepts a duration string or `false`; `"0"` also disables idle shutdown.
    ///
    /// When omitted, a daemon started through its URL uses
    /// `settings.proxy.idle_timeout`; a dependency inherits the requested
    /// daemon's timeout. An explicit `false` exempts this daemon in either case.
    ///
    /// The timeout is recorded at startup. Explicitly started daemons are
    /// exempt; live dependents, active proxy connections, and tracked shell
    /// sessions prevent idle shutdown.
    pub proxy_idle_timeout: Option<ProxyIdleTimeout>,
    /// Whether to start this daemon automatically on system boot
    pub boot_start: Option<bool>,
    /// List of daemon IDs that must be started before this one
    #[schemars(default)]
    pub depends: Vec<DaemonId>,
    /// File patterns to watch for changes
    #[schemars(default)]
    pub watch: Vec<String>,
    /// File watching backend mode.
    ///
    /// - `native`: use platform-native notifications (default)
    /// - `poll`: use polling-based watcher
    /// - `auto`: prefer native, fall back to polling if native watch fails
    #[schemars(default)]
    pub watch_mode: WatchMode,
    /// Working directory for the daemon. Relative paths are resolved from the pitchfork.toml location.
    pub dir: Option<String>,
    /// Environment variables to set for the daemon process
    pub env: Option<IndexMap<String, String>>,
    /// Dotenv files (e.g. `.env.local`) whose variables are added to the daemon's
    /// environment. Relative paths resolve from the project directory (the same base as
    /// `dir`); missing files are skipped. Values from `env` win over the files, and later files win
    /// over earlier ones. Values support Tera templates.
    #[serde(default)]
    pub env_file: Vec<String>,
    /// Lifecycle hooks (on_ready, on_fail, on_retry)
    pub hooks: Option<PitchforkTomlHooks>,
    /// Wrap this daemon's command with `mise x --` for tool/env setup.
    /// Overrides the global `settings.general.mise` when set.
    pub mise: Option<bool>,
    /// Pitchfork's template context as JSON, set while rendering when `run` was left
    /// unrendered for `mise x` to finish. Never read from or written to a file.
    #[schemars(skip)]
    pub deferred_template_context: Option<String>,
    /// Unix user to run this daemon as. Overrides `settings.supervisor.user` when set.
    pub user: Option<String>,
    /// Memory limit for the daemon process (e.g. "50MB", "1GiB").
    /// The supervisor periodically monitors RSS and kills the process if it exceeds the limit.
    pub memory_limit: Option<MemoryLimit>,
    /// CPU usage limit as a percentage (e.g. 80 for 80%, 200 for 2 cores).
    /// The supervisor periodically monitors CPU usage and kills the process if it exceeds the limit.
    pub cpu_limit: Option<CpuLimit>,
    /// Stop signal and optional per-daemon timeout. Accepts a signal name string
    /// or `{ signal = "...", timeout = "..." }` object.
    pub stop_signal: Option<StopConfig>,
    /// Allocate a pseudo-terminal for the daemon process.
    pub pty: Option<bool>,
    /// Maximum age of log entries to keep (e.g. "7d", "30d").
    /// Overrides the global `settings.logs.time_retention` when set.
    pub time_retention: Option<String>,
    /// Maximum number of log entries to keep per daemon.
    /// Overrides the global `settings.logs.line_retention` when set.
    pub line_retention: Option<i64>,
    /// Archive hook command invoked before retention prunes this daemon's logs.
    /// Overrides the global `settings.logs.archive_hook.command` when set.
    pub archive_hook: Option<String>,
    /// Per-daemon log configuration sub-table.
    pub logs: Option<PitchforkTomlDaemonLogs>,
    #[schemars(skip)]
    pub path: Option<PathBuf>,
}

impl PitchforkTomlDaemon {
    /// Which of the daemon's ports its proxy hostname maps to, from either
    /// spelling of the setting.
    ///
    /// `proxy_tls_port` wins when both are set; parsing has already warned
    /// about that combination.
    pub fn effective_proxy_tls_port(&self) -> Option<u16> {
        self.proxy_tls_port.or(self.proxy_port)
    }

    /// Whether this daemon is a oneshot task (`oneshot = true`).
    pub fn is_oneshot(&self) -> bool {
        self.oneshot.unwrap_or(false)
    }

    /// Names of the readiness and health fields that are set on this daemon
    /// and cannot be combined with `oneshot`. Empty when there is no conflict.
    pub(crate) fn oneshot_conflicts(&self) -> Vec<&'static str> {
        [
            ("ready_delay", self.ready_delay.is_some()),
            ("ready_output", self.ready_output.is_some()),
            ("ready_http", self.ready_http.is_some()),
            ("ready_port", self.ready_port.is_some()),
            ("ready_cmd", self.ready_cmd.is_some()),
            ("health_cmd", self.health_cmd.is_some()),
            ("health_http", self.health_http.is_some()),
            ("health_port", self.health_port.is_some()),
        ]
        .into_iter()
        .filter(|(_, set)| *set)
        .map(|(name, _)| name)
        .collect()
    }

    /// Effective user for this daemon: per-daemon `user` overrides `settings.supervisor.user`.
    ///
    /// Returns `None` when neither is set (inherit the supervisor's user).
    pub fn effective_user(&self) -> Option<String> {
        let daemon_user = self
            .user
            .as_deref()
            .map(str::trim)
            .filter(|u| !u.is_empty());
        daemon_user.map(str::to_owned).or_else(|| {
            let s = crate::settings::settings();
            let su = s.supervisor.user.trim();
            (!su.is_empty()).then(|| su.to_owned())
        })
    }

    /// Build RunOptions from this daemon configuration.
    ///
    /// Carries over all config fields and resolves the working directory.
    /// Callers can override specific fields on the returned value.
    pub fn to_run_options(
        &self,
        id: &crate::daemon_id::DaemonId,
        cmd: Vec<String>,
    ) -> crate::daemon::RunOptions {
        use crate::daemon::RunOptions;

        let effective_user = self.effective_user();
        let dir = crate::ipc::batch::resolve_daemon_dir(
            self.dir.as_deref(),
            self.path.as_deref(),
            effective_user.as_deref(),
        );
        // The same lookup the proxy and the CLI use, so a slug the proxy
        // refuses to route as ambiguous is not handed to the daemon either.
        let slug = PitchforkToml::find_slug_for_daemon_in_registry(
            id,
            &PitchforkToml::read_global_slugs(),
        );

        RunOptions {
            id: id.clone(),
            cmd,
            run: self.run.shell_script().map(str::to_string),
            no_shell: self.run.is_argv(),
            replaces_ready_checks: false,
            // Set by the IPC handler for a client's own request.
            requested_by_client: false,
            force: false,
            shell_pid: None,
            dir: Dir(dir),
            autostop: self.auto.contains(&PitchforkTomlAuto::Stop),
            oneshot: self.is_oneshot(),
            // Set only by the cron watcher's own call; a start built from
            // config is not the schedule asking for a run.
            cron_started: false,
            // Filled in by `build_run_options`, which resolves it against the
            // daemon's own project rather than whatever directory this process
            // happens to be in.
            oneshot_wait: None,
            on_directory_enter: false,
            cron_schedule: self.cron.as_ref().map(|c| c.schedule.clone()),
            cron_retrigger: self.cron.as_ref().map(|c| c.retrigger),
            cron_immediate: self.cron.as_ref().map(|c| c.immediate),
            retry: self.retry,
            retry_count: 0,
            ready_delay: self.ready_delay,
            ready_output: self.ready_output.clone(),
            ready_http: self.ready_http.clone(),
            ready_port: self.ready_port.clone(),
            ready_cmd: self.ready_cmd.clone(),
            health_cmd: self.health_cmd.clone(),
            health_http: self.health_http.clone(),
            health_port: self.health_port.clone(),
            port: self.port.clone(),
            wait_ready: false,
            depends: self.depends.clone(),
            env: self.env.clone(),
            watch: self.watch.clone(),
            watch_mode: self.watch_mode,
            watch_base_dir: Some(crate::ipc::batch::resolve_config_base_dir(
                self.path.as_deref(),
            )),
            mise: self.mise,
            deferred_template_context: self.deferred_template_context.clone(),
            // Resolved from the project settings by `build_run_options`.
            mise_bin: None,
            slug,
            proxy: None,
            user: self.user.clone(),
            memory_limit: self.memory_limit,
            cpu_limit: self.cpu_limit,
            stop_signal: self.stop_signal,
            archive_hook: self
                .logs
                .as_ref()
                .and_then(|l| l.archive_hook.clone())
                .or_else(|| self.archive_hook.clone()),
            log_format: self.logs.as_ref().and_then(|l| l.log_format.clone()),
            on_output_hook: self.hooks.as_ref().and_then(|h| h.on_output.clone()),
            pty: self.pty,
            // Explicit unless the proxy's start marks it otherwise.
            proxy_idle_timeout_ms: None,
            replaces_saved_record: true,
        }
    }
}
fn example_run_command() -> &'static str {
    "exec node server.js"
}

/// A daemon's `run`: a command line for the shell, or a program and its
/// arguments to start without one.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, JsonSchema)]
#[serde(untagged)]
pub enum RunCommand {
    /// A command line, passed verbatim to the shell (`general.shell`, or
    /// `general.windows_shell` on Windows).
    Shell(String),
    /// A program and its arguments, started directly. No shell interprets
    /// them, so each argument reaches the program exactly as written, on
    /// every platform.
    Argv(#[schemars(length(min = 1))] Vec<String>),
}

impl Default for RunCommand {
    fn default() -> Self {
        Self::Shell(String::new())
    }
}

impl From<String> for RunCommand {
    fn from(run: String) -> Self {
        Self::Shell(run)
    }
}

impl From<&str> for RunCommand {
    fn from(run: &str) -> Self {
        Self::Shell(run.to_string())
    }
}

impl From<Vec<String>> for RunCommand {
    fn from(argv: Vec<String>) -> Self {
        Self::Argv(argv)
    }
}

impl PartialEq<str> for RunCommand {
    fn eq(&self, other: &str) -> bool {
        matches!(self, Self::Shell(run) if run == other)
    }
}

impl PartialEq<&str> for RunCommand {
    fn eq(&self, other: &&str) -> bool {
        self == *other
    }
}

/// The command as a user would read it: the shell form as written, the argv
/// form quoted for a POSIX shell.
impl std::fmt::Display for RunCommand {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Shell(run) => f.write_str(run),
            Self::Argv(argv) => f.write_str(&shell_words::join(argv)),
        }
    }
}

impl RunCommand {
    /// The command as separate words: the argv form as it is, the shell form
    /// split the way a POSIX shell would.
    pub fn argv(&self) -> std::result::Result<Vec<String>, shell_words::ParseError> {
        match self {
            Self::Shell(run) => shell_words::split(run),
            Self::Argv(argv) => Ok(argv.clone()),
        }
    }

    /// The command line for the shell, or `None` for the argv form.
    pub fn shell_script(&self) -> Option<&str> {
        match self {
            Self::Shell(run) => Some(run),
            Self::Argv(_) => None,
        }
    }

    pub fn is_argv(&self) -> bool {
        matches!(self, Self::Argv(_))
    }

    /// Apply `f` to the command line, or to each argument of the argv form.
    pub fn try_map<E>(
        &self,
        mut f: impl FnMut(&str) -> std::result::Result<String, E>,
    ) -> std::result::Result<Self, E> {
        Ok(match self {
            Self::Shell(run) => Self::Shell(f(run)?),
            Self::Argv(argv) => Self::Argv(
                argv.iter()
                    .map(|arg| f(arg))
                    .collect::<std::result::Result<_, _>>()?,
            ),
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::path::Path;

    fn parse_groups(toml: &str) -> IndexMap<String, GroupEntry> {
        PitchforkToml::parse_str(toml, Path::new("/tmp/my-project/pitchfork.toml"))
            .unwrap()
            .groups
    }

    fn names(ids: &[DaemonId]) -> Vec<&str> {
        ids.iter().map(|id| id.name()).collect()
    }

    #[test]
    fn test_group_includes_expand_before_own_daemons_and_dedupe() {
        let groups = parse_groups(
            r#"
[groups.core]
daemons = ["db", "cache"]

[groups.extras]
daemons = ["mailer", "cache"]

[groups.all]
groups = ["core", "extras"]
daemons = ["api", "db"]
"#,
        );
        let all = expand_group(&groups, "all").unwrap();
        assert_eq!(names(&all), ["db", "cache", "mailer", "api"]);
    }

    #[test]
    fn test_group_includes_nest_and_allow_diamonds() {
        let groups = parse_groups(
            r#"
[groups.base]
daemons = ["db"]

[groups.left]
groups = ["base"]
daemons = ["l"]

[groups.right]
groups = ["base"]
daemons = ["r"]

[groups.top]
groups = ["left", "right"]
"#,
        );
        let top = expand_group(&groups, "top").unwrap();
        assert_eq!(names(&top), ["db", "l", "r"]);
    }

    #[test]
    fn test_group_includes_shared_by_many_paths_are_expanded_once() {
        // Each level includes the next twice, so walking every path would
        // take 2^60 steps.
        let mut toml = String::from("[groups.g0]\ngroups = [\"g1\", \"g1\"]\n");
        for i in 1..60 {
            toml.push_str(&format!(
                "\n[groups.g{i}]\ngroups = [\"g{n}\", \"g{n}\"]\n",
                n = i + 1
            ));
        }
        toml.push_str("\n[groups.g60]\ndaemons = [\"db\"]\n");
        let groups = parse_groups(&toml);
        assert_eq!(names(&expand_group(&groups, "g0").unwrap()), ["db"]);
    }

    #[test]
    fn test_group_include_cycle_is_an_error() {
        let groups = parse_groups(
            r#"
[groups.a]
groups = ["b"]

[groups.b]
groups = ["c"]

[groups.c]
groups = ["a"]
"#,
        );
        let err = expand_group(&groups, "a").unwrap_err().to_string();
        assert!(err.contains("a -> b -> c -> a"), "{err}");
        let err = expand_group(&parse_groups("[groups.x]\ngroups = [\"x\"]\n"), "x")
            .unwrap_err()
            .to_string();
        assert!(err.contains("x -> x"), "{err}");
    }

    #[test]
    fn test_group_include_of_undefined_group_is_an_error() {
        let groups = parse_groups("[groups.all]\ngroups = [\"cor\"]\n\n[groups.core]\n");
        let err = expand_group(&groups, "all").unwrap_err().to_string();
        assert!(
            err.contains("group 'all' includes undefined group 'cor'"),
            "{err}"
        );
    }

    #[test]
    fn test_group_without_daemons_key_parses() {
        let groups = parse_groups("[groups.empty]\n");
        assert!(expand_group(&groups, "empty").unwrap().is_empty());
    }

    #[test]
    fn test_daemon_user_parses_and_flows_to_run_options() {
        let pt = PitchforkToml::parse_str(
            r#"
[daemons.api]
run = "node server.js"
user = "postgres"
"#,
            Path::new("/tmp/my-project/pitchfork.toml"),
        )
        .unwrap();

        let id = DaemonId::new("my-project", "api");
        let daemon = pt.daemons.get(&id).unwrap();
        assert_eq!(daemon.user.as_deref(), Some("postgres"));

        let opts = daemon.to_run_options(&id, vec!["node".to_string(), "server.js".to_string()]);
        assert_eq!(opts.user.as_deref(), Some("postgres"));
        // A start from config describes the daemon in full.
        assert!(opts.replaces_saved_record);
    }

    #[test]
    fn test_new_local_file_writes_daemons_of_the_directory_namespace() {
        let temp = tempfile::tempdir().unwrap();
        std::fs::write(
            temp.path().join("pitchfork.toml"),
            "namespace = \"myns\"\n\n[daemons.web]\nrun = \"sleep 60\"\n",
        )
        .unwrap();
        let path = temp.path().join("pitchfork.local.toml");
        let mut pt = PitchforkToml::new(path.clone());
        let id = DaemonId::new(namespace_from_path(&path).unwrap(), "api");
        assert_eq!(id.namespace(), "myns");
        pt.daemons.insert(
            id.clone(),
            PitchforkTomlDaemon {
                run: "sleep 60".into(),
                ..PitchforkTomlDaemon::default()
            },
        );

        pt.write().unwrap();

        let parsed = PitchforkToml::read(&path).unwrap();
        assert!(parsed.daemons.contains_key(&id));
    }

    #[test]
    fn test_daemon_user_write_roundtrip() {
        let temp = tempfile::tempdir().unwrap();
        let path = temp.path().join("pitchfork.toml");
        let mut pt = PitchforkToml::new(path.clone());
        pt.namespace = Some("test-project".to_string());
        pt.daemons.insert(
            DaemonId::new("test-project", "api"),
            PitchforkTomlDaemon {
                run: "node server.js".into(),
                user: Some("postgres".to_string()),
                ..PitchforkTomlDaemon::default()
            },
        );

        pt.write().unwrap();

        let raw = std::fs::read_to_string(&path).unwrap();
        assert!(raw.contains("user = \"postgres\""));

        let parsed = PitchforkToml::read(&path).unwrap();
        let daemon = parsed
            .daemons
            .get(&DaemonId::new("test-project", "api"))
            .unwrap();
        assert_eq!(daemon.user.as_deref(), Some("postgres"));
    }

    /// Arguments a shell would reinterpret, which the argv form must not.
    fn awkward_argv() -> Vec<String> {
        [
            "node",
            "my server.js",
            "--name=\"a b\"",
            "it's",
            "a&b",
            "%PATH%",
            "$HOME",
        ]
        .map(str::to_string)
        .to_vec()
    }

    #[test]
    fn test_run_array_parses_and_starts_without_a_shell() {
        let pt = PitchforkToml::parse_str(
            r#"
[daemons.api]
run = ["node", "my server.js", "--name=\"a b\"", "it's", "a&b", "%PATH%", "$HOME"]
"#,
            Path::new("/tmp/my-project/pitchfork.toml"),
        )
        .unwrap();

        let id = DaemonId::new("my-project", "api");
        let daemon = pt.daemons.get(&id).unwrap();
        assert_eq!(daemon.run, RunCommand::Argv(awkward_argv()));

        let opts = daemon.to_run_options(&id, daemon.run.argv().unwrap());
        assert_eq!(opts.cmd, awkward_argv());
        assert!(opts.no_shell);
        assert_eq!(opts.run, None);
    }

    #[test]
    fn test_run_string_still_goes_through_the_shell() {
        let pt = PitchforkToml::parse_str(
            "[daemons.api]\nrun = \"exec node server.js\"\n",
            Path::new("/tmp/my-project/pitchfork.toml"),
        )
        .unwrap();

        let id = DaemonId::new("my-project", "api");
        let daemon = pt.daemons.get(&id).unwrap();
        let opts = daemon.to_run_options(&id, daemon.run.argv().unwrap());
        assert!(!opts.no_shell);
        assert_eq!(opts.run.as_deref(), Some("exec node server.js"));
    }

    #[test]
    fn test_run_array_write_roundtrip() {
        let temp = tempfile::tempdir().unwrap();
        let path = temp.path().join("pitchfork.toml");
        let mut pt = PitchforkToml::new(path.clone());
        pt.namespace = Some("test-project".to_string());
        let id = DaemonId::new("test-project", "api");
        pt.daemons.insert(
            id.clone(),
            PitchforkTomlDaemon {
                run: RunCommand::Argv(awkward_argv()),
                ..PitchforkTomlDaemon::default()
            },
        );
        pt.daemons.insert(
            DaemonId::new("test-project", "worker"),
            PitchforkTomlDaemon {
                run: "exec ./worker --queue \"a b\"".into(),
                ..PitchforkTomlDaemon::default()
            },
        );

        pt.write().unwrap();

        let parsed = PitchforkToml::read(&path).unwrap();
        assert_eq!(parsed.daemons[&id].run, RunCommand::Argv(awkward_argv()));
        assert_eq!(
            parsed.daemons[&DaemonId::new("test-project", "worker")].run,
            "exec ./worker --queue \"a b\""
        );
    }

    #[test]
    fn test_run_array_must_name_a_program() {
        let err = PitchforkToml::parse_str(
            "[daemons.api]\nrun = []\n",
            Path::new("/tmp/my-project/pitchfork.toml"),
        )
        .unwrap_err();
        assert!(
            err.chain()
                .any(|cause| cause.to_string().contains("empty run array")),
            "unexpected error: {err:?}"
        );
    }

    #[test]
    fn test_run_array_rejects_exec() {
        let err = PitchforkToml::parse_str(
            "[daemons.api]\nrun = [\"exec\", \"node\", \"server.js\"]\n",
            Path::new("/tmp/my-project/pitchfork.toml"),
        )
        .unwrap_err();
        assert!(
            err.chain().any(|cause| cause
                .to_string()
                .contains("starts its run array with \"exec\"")),
            "unexpected error: {err:?}"
        );
    }

    #[test]
    fn test_ready_cmd_array_parses_in_both_forms() {
        let pt = PitchforkToml::parse_str(
            r#"
[daemons.api]
run = "node server.js"
ready_cmd = ["node", "my server.js", "--name=\"a b\"", "it's", "a&b", "%PATH%", "$HOME"]

[daemons.db]
run = "postgres"
ready_cmd = { run = ["pg_isready", "-h", "localhost"], timeout = "30s" }

[daemons.cache]
run = "redis-server"
ready_cmd = "redis-cli ping"
"#,
            Path::new("/tmp/my-project/pitchfork.toml"),
        )
        .unwrap();

        let ready = |name: &str| {
            pt.daemons[&DaemonId::new("my-project", name)]
                .ready_cmd
                .clone()
                .unwrap()
        };
        assert_eq!(ready("api").run, RunCommand::Argv(awkward_argv()));
        assert_eq!(ready("api").timeout, None);
        assert_eq!(
            ready("db").run,
            RunCommand::Argv(
                ["pg_isready", "-h", "localhost"]
                    .map(str::to_string)
                    .to_vec()
            )
        );
        assert_eq!(
            ready("db").timeout,
            Some(std::time::Duration::from_secs(30))
        );
        assert_eq!(ready("cache").run, "redis-cli ping");
    }

    #[test]
    fn test_ready_cmd_array_write_roundtrip() {
        let temp = tempfile::tempdir().unwrap();
        let path = temp.path().join("pitchfork.toml");
        let mut pt = PitchforkToml::new(path.clone());
        pt.namespace = Some("test-project".to_string());
        let short = ReadyCmd::new(awkward_argv());
        let full = ReadyCmd {
            run: RunCommand::Argv(
                ["pg_isready", "-h", "localhost"]
                    .map(str::to_string)
                    .to_vec(),
            ),
            timeout: Some(std::time::Duration::from_secs(30)),
        };
        for (name, ready_cmd) in [("api", &short), ("db", &full)] {
            pt.daemons.insert(
                DaemonId::new("test-project", name),
                PitchforkTomlDaemon {
                    run: "true".into(),
                    ready_cmd: Some(ready_cmd.clone()),
                    ..PitchforkTomlDaemon::default()
                },
            );
        }

        pt.write().unwrap();

        let parsed = PitchforkToml::read(&path).unwrap();
        let ready = |name: &str| {
            parsed.daemons[&DaemonId::new("test-project", name)]
                .ready_cmd
                .clone()
        };
        assert_eq!(ready("api"), Some(short));
        assert_eq!(ready("db"), Some(full));
    }

    #[test]
    fn test_ready_cmd_array_must_name_a_program() {
        for ready_cmd in ["[]", "[\"\"]", "{ run = [\"\", \"-h\"] }"] {
            let err = PitchforkToml::parse_str(
                &format!("[daemons.api]\nrun = \"true\"\nready_cmd = {ready_cmd}\n"),
                Path::new("/tmp/my-project/pitchfork.toml"),
            )
            .unwrap_err();
            assert!(
                err.chain().any(|cause| cause
                    .to_string()
                    .contains("has no program in its ready_cmd array")),
                "unexpected error for {ready_cmd}: {err:?}"
            );
        }
    }

    #[test]
    fn test_ready_cmd_array_rejects_exec() {
        let err = PitchforkToml::parse_str(
            "[daemons.api]\nrun = \"true\"\nready_cmd = { run = [\"exec\", \"pg_isready\"] }\n",
            Path::new("/tmp/my-project/pitchfork.toml"),
        )
        .unwrap_err();
        assert!(
            err.chain().any(|cause| cause
                .to_string()
                .contains("starts its ready_cmd array with \"exec\"")),
            "unexpected error: {err:?}"
        );
    }

    #[test]
    fn test_health_cmd_array_parses_and_round_trips() {
        let pt = PitchforkToml::parse_str(
            r#"
[daemons.api]
run = "node server.js"
health_cmd = ["node", "my server.js", "--name=\"a b\"", "it's", "a&b", "%PATH%", "$HOME"]

[daemons.db]
run = "postgres"
health_cmd = { run = ["pg_isready", "-h", "localhost"], interval = "5s", retries = 2 }

[daemons.cache]
run = "redis-server"
health_cmd = "redis-cli ping"
"#,
            Path::new("/tmp/my-project/pitchfork.toml"),
        )
        .unwrap();
        let health = |pt: &PitchforkToml, ns: &str, name: &str| {
            pt.daemons[&DaemonId::new(ns, name)]
                .health_cmd
                .clone()
                .unwrap()
        };
        assert_eq!(
            health(&pt, "my-project", "api").run,
            RunCommand::Argv(awkward_argv())
        );
        let db = health(&pt, "my-project", "db");
        assert_eq!(
            db.run,
            RunCommand::Argv(
                ["pg_isready", "-h", "localhost"]
                    .map(str::to_string)
                    .to_vec()
            )
        );
        assert_eq!(db.interval, Some(std::time::Duration::from_secs(5)));
        assert_eq!(db.retries, Some(2));
        assert_eq!(health(&pt, "my-project", "cache").run, "redis-cli ping");

        let temp = tempfile::tempdir().unwrap();
        let path = temp.path().join("pitchfork.toml");
        let mut written = PitchforkToml::new(path.clone());
        written.namespace = Some("test-project".to_string());
        for name in ["api", "db"] {
            written.daemons.insert(
                DaemonId::new("test-project", name),
                PitchforkTomlDaemon {
                    run: "true".into(),
                    health_cmd: Some(health(&pt, "my-project", name)),
                    ..PitchforkTomlDaemon::default()
                },
            );
        }
        written.write().unwrap();
        let parsed = PitchforkToml::read(&path).unwrap();
        for name in ["api", "db"] {
            assert_eq!(
                health(&parsed, "test-project", name),
                health(&pt, "my-project", name)
            );
        }
    }

    #[test]
    fn test_health_cmd_array_must_name_a_program_and_not_exec() {
        for (health_cmd, expected) in [
            ("[]", "has no program in its health_cmd array"),
            ("[\"\"]", "has no program in its health_cmd array"),
            (
                "{ run = [\"exec\", \"pg_isready\"] }",
                "starts its health_cmd array with \"exec\"",
            ),
        ] {
            let err = PitchforkToml::parse_str(
                &format!("[daemons.api]\nrun = \"true\"\nhealth_cmd = {health_cmd}\n"),
                Path::new("/tmp/my-project/pitchfork.toml"),
            )
            .unwrap_err();
            assert!(
                err.chain()
                    .any(|cause| cause.to_string().contains(expected)),
                "unexpected error for {health_cmd}: {err:?}"
            );
        }
    }

    #[test]
    fn test_registry_dirs_expand_tilde() {
        let pt = PitchforkToml::parse_str(
            r#"
[slugs.api]
dir = "~/projects/api"

[namespaces.web]
dir = "~/projects/web"
"#,
            Path::new("/tmp/config.toml"),
        )
        .unwrap();

        assert_eq!(
            pt.slugs["api"].dir,
            Some(crate::env::HOME_DIR.join("projects/api"))
        );
        assert_eq!(
            pt.namespaces["web"].dir,
            crate::env::HOME_DIR.join("projects/web")
        );
    }

    #[test]
    fn test_settings_write_roundtrip() {
        let temp = tempfile::tempdir().unwrap();
        let path = temp.path().join("pitchfork.toml");
        let mut pt = PitchforkToml::new(path.clone());
        pt.namespace = Some("test-project".to_string());
        pt.settings.web.auto_start = Some(true);
        pt.settings.general.log_level = Some("debug".to_string());

        pt.write().unwrap();

        let raw = std::fs::read_to_string(&path).unwrap();
        assert!(
            raw.contains("[settings.web]"),
            "settings.web section should be written, got:\n{raw}"
        );
        assert!(raw.contains("auto_start = true"));
        assert!(raw.contains("log_level = \"debug\""));

        let parsed = PitchforkToml::read(&path).unwrap();
        assert_eq!(parsed.settings.web.auto_start, Some(true));
        assert_eq!(parsed.settings.general.log_level.as_deref(), Some("debug"));
    }

    fn slug_entry(namespace: &str, daemon: Option<&str>) -> SlugEntry {
        SlugEntry {
            dir: None,
            namespace: Some(namespace.to_string()),
            daemon: daemon.map(str::to_string),
        }
    }

    #[test]
    fn test_slug_is_ambiguous() {
        let mut slugs = IndexMap::new();
        slugs.insert("api".to_string(), slug_entry("my-project", None));
        assert!(!PitchforkToml::slug_is_ambiguous("api", &slugs));

        slugs.insert("API".to_string(), slug_entry("other-project", None));
        // Host names are case-insensitive, so both spellings are ambiguous.
        assert!(PitchforkToml::slug_is_ambiguous("api", &slugs));
        assert!(PitchforkToml::slug_is_ambiguous("API", &slugs));
    }

    #[test]
    fn test_find_slug_for_daemon_skips_case_collisions() {
        let id = DaemonId::new("my-project", "api");
        let mut slugs = IndexMap::new();
        slugs.insert("api".to_string(), slug_entry("my-project", None));
        assert_eq!(
            PitchforkToml::find_slug_for_daemon_in_registry(&id, &slugs),
            Some("api".to_string())
        );

        // The proxy refuses to route either spelling, so no URL may be
        // advertised for this daemon.
        slugs.insert("API".to_string(), slug_entry("other-project", None));
        assert_eq!(
            PitchforkToml::find_slug_for_daemon_in_registry(&id, &slugs),
            None
        );
    }

    #[test]
    fn test_find_slug_for_daemon_prefers_a_routable_alias() {
        let id = DaemonId::new("my-project", "api");
        let mut slugs = IndexMap::new();
        // A colliding pair comes first in config order, then a routable alias
        // for the same daemon.
        slugs.insert("api".to_string(), slug_entry("my-project", None));
        slugs.insert("API".to_string(), slug_entry("my-project", None));
        slugs.insert("my-api".to_string(), slug_entry("my-project", Some("api")));

        assert_eq!(
            PitchforkToml::find_slug_for_daemon_in_registry(&id, &slugs),
            Some("my-api".to_string())
        );
    }

    #[test]
    fn test_settings_preserved_on_unrelated_write() {
        // Regression test for https://github.com/jdx/pitchfork/discussions/574
        // A read-modify-write of slugs/namespaces must not drop existing [settings].
        let temp = tempfile::tempdir().unwrap();
        let path = temp.path().join("pitchfork.toml");
        std::fs::write(&path, "[settings.web]\nauto_start = true\n").unwrap();

        let mut pt = PitchforkToml::read(&path).unwrap();
        pt.slugs.insert(
            "api".to_string(),
            SlugEntry {
                dir: None,
                namespace: Some("myproject".to_string()),
                daemon: None,
            },
        );
        pt.namespaces.insert(
            "myproject".to_string(),
            NamespaceEntry {
                dir: PathBuf::from("/tmp/myproject"),
                config: Vec::new(),
                label: None,
            },
        );
        pt.write().unwrap();

        let raw = std::fs::read_to_string(&path).unwrap();
        assert!(
            raw.contains("[settings.web]"),
            "existing settings must be preserved, got:\n{raw}"
        );
        assert!(raw.contains("auto_start = true"));
        assert!(raw.contains("[slugs.api]"));

        let parsed = PitchforkToml::read(&path).unwrap();
        assert_eq!(parsed.settings.web.auto_start, Some(true));
        assert!(parsed.slugs.contains_key("api"));
    }

    #[tokio::test]
    async fn test_proxy_worktree_alias_is_canonicalized_on_rewrite() {
        let temp = tempfile::tempdir().unwrap();
        let path = temp.path().join("pitchfork.toml");
        tokio::fs::write(&path, "[settings.proxy]\nworktree = false\n")
            .await
            .unwrap();

        let read_path = path.clone();
        let pt = tokio::task::spawn_blocking(move || PitchforkToml::read(&read_path))
            .await
            .unwrap()
            .unwrap();
        assert_eq!(pt.settings.general.worktree, Some(false));
        assert_eq!(pt.settings.proxy.worktree, None);
        tokio::task::spawn_blocking(move || pt.write())
            .await
            .unwrap()
            .unwrap();

        let raw = tokio::fs::read_to_string(&path).await.unwrap();
        assert!(raw.contains("[settings.general]"), "{raw}");
        assert!(raw.contains("worktree = false"), "{raw}");
        assert!(!raw.contains("[settings.proxy]"), "{raw}");

        let parsed = tokio::task::spawn_blocking(move || PitchforkToml::read(&path))
            .await
            .unwrap()
            .unwrap();
        assert_eq!(parsed.settings.general.worktree, Some(false));
    }

    #[test]
    fn test_config_cache_hit_and_invalidation() {
        let temp = tempfile::tempdir().unwrap();
        let dir = temp.path();
        let config_path = dir.join("pitchfork.toml");
        std::fs::write(&config_path, "[daemons.api]\nrun = \"echo v1\"\n").unwrap();

        // Clear any pre-existing cache entries for this directory.
        super::invalidate_config_cache();

        // First call: cache miss, reads from disk.
        let pt1 = PitchforkToml::all_merged_from(dir).unwrap();
        let daemon_id = DaemonId::new(namespace_from_path(&config_path).unwrap(), "api");
        assert_eq!(pt1.daemons[&daemon_id].run, "echo v1");

        // Second call: should be a cache hit (same mtime).
        let pt2 = PitchforkToml::all_merged_from(dir).unwrap();
        assert_eq!(pt2.daemons[&daemon_id].run, "echo v1");

        // Modify the config file — mtime changes, cache should miss.
        // Sleep briefly to ensure mtime resolution differs.
        std::thread::sleep(std::time::Duration::from_millis(50));
        std::fs::write(&config_path, "[daemons.api]\nrun = \"echo v2\"\n").unwrap();

        let pt3 = PitchforkToml::all_merged_from(dir).unwrap();
        assert_eq!(pt3.daemons[&daemon_id].run, "echo v2");

        // Explicit invalidation should also force a re-read.
        super::invalidate_config_cache();
        let pt4 = PitchforkToml::all_merged_from(dir).unwrap();
        assert_eq!(pt4.daemons[&daemon_id].run, "echo v2");

        // Clean up.
        super::invalidate_config_cache();
    }

    #[test]
    fn test_config_cache_invalidation_on_write() {
        let temp = tempfile::tempdir().unwrap();
        let dir = temp.path();
        let config_path = dir.join("pitchfork.toml");
        std::fs::write(&config_path, "[daemons.api]\nrun = \"echo v1\"\n").unwrap();

        super::invalidate_config_cache();

        // Populate cache.
        let pt1 = PitchforkToml::all_merged_from(dir).unwrap();
        let daemon_id = DaemonId::new(namespace_from_path(&config_path).unwrap(), "api");
        assert_eq!(pt1.daemons[&daemon_id].run, "echo v1");

        // Write via PitchforkToml::write() — should invalidate cache.
        let mut pt = PitchforkToml::read(&config_path).unwrap();
        pt.daemons.get_mut(&daemon_id).unwrap().run = "echo v3".into();
        // write() needs the path set and namespace match
        let _ = pt.write();

        // Next read should see the updated value, not the cached one.
        let pt2 = PitchforkToml::all_merged_from(dir).unwrap();
        assert_eq!(pt2.daemons[&daemon_id].run, "echo v3");

        super::invalidate_config_cache();
    }

    #[test]
    fn test_config_cache_size_invalidation() {
        let temp = tempfile::tempdir().unwrap();
        let dir = temp.path();
        let config_path = dir.join("pitchfork.toml");
        std::fs::write(&config_path, "[daemons.api]\nrun = \"echo v1\"\n").unwrap();

        super::invalidate_config_cache();

        // Populate cache.
        let pt1 = PitchforkToml::all_merged_from(dir).unwrap();
        let daemon_id = DaemonId::new(namespace_from_path(&config_path).unwrap(), "api");
        assert_eq!(pt1.daemons[&daemon_id].run, "echo v1");

        // Capture the original mtime, then write different-size content and
        // restore the *same* mtime — simulating `cp --preserve=timestamps`
        // or a same-second edit on a coarse-grained filesystem.
        let original_mtime = std::fs::metadata(&config_path).unwrap().modified().unwrap();
        std::fs::write(&config_path, "[daemons.api]\nrun = \"echo different\"\n").unwrap();
        // On Windows, set_times requires the file handle to be opened with
        // write access; File::open is read-only.
        let file = std::fs::OpenOptions::new()
            .write(true)
            .open(&config_path)
            .unwrap();
        let times = std::fs::FileTimes::new().set_modified(original_mtime);
        file.set_times(times).unwrap();

        // Size changed (shorter run string), so cache should miss even though
        // mtime is identical.
        let pt2 = PitchforkToml::all_merged_from(dir).unwrap();
        assert_eq!(
            pt2.daemons[&daemon_id].run, "echo different",
            "cache should invalidate on size change even with identical mtime"
        );

        super::invalidate_config_cache();
    }

    #[test]
    fn test_find_project_root_in_plain_dir_returns_none() {
        let temp = tempfile::tempdir().unwrap();
        assert_eq!(find_project_root(temp.path()), None);
    }

    #[test]
    fn test_find_project_root_finds_git_marker() {
        let temp = tempfile::tempdir().unwrap();
        let repo = temp.path().join("my-repo");
        std::fs::create_dir(&repo).unwrap();
        std::fs::create_dir(repo.join(".git")).unwrap();

        let sub = repo.join("sub/dir");
        std::fs::create_dir_all(&sub).unwrap();

        // `find_project_root` canonicalizes, so compare against the canonical
        // path (on Windows this differs by the `\\?\` verbatim prefix).
        assert_eq!(find_project_root(&sub), Some(repo.canonicalize().unwrap()));
    }

    #[test]
    fn test_find_project_root_accepts_git_file_marker() {
        // Linked git worktrees store `.git` as a *file* pointing at the
        // common gitdir, so `exists()` (not `is_dir()`) is the right check.
        let temp = tempfile::tempdir().unwrap();
        let wt = temp.path().join("my-worktree");
        std::fs::create_dir(&wt).unwrap();
        std::fs::write(wt.join(".git"), "gitdir: /tmp/some-common-gitdir\n").unwrap();

        assert_eq!(find_project_root(&wt), Some(wt.canonicalize().unwrap()));
    }

    /// A symlinked start dir must resolve into the repository hierarchy so
    /// `parent()` traversal does not walk out of the repo.
    #[cfg(unix)]
    #[test]
    fn test_find_project_root_resolves_symlinked_start_dir() {
        use std::os::unix::fs::symlink;

        let temp = tempfile::tempdir().unwrap();
        let repo = temp.path().join("real-repo");
        std::fs::create_dir(&repo).unwrap();
        std::fs::create_dir(repo.join(".git")).unwrap();

        let sub = repo.join("sub/dir");
        std::fs::create_dir_all(&sub).unwrap();
        let link = temp.path().join("link-to-sub");
        symlink(&sub, &link).unwrap();

        assert_eq!(find_project_root(&link), Some(repo.canonicalize().unwrap()));
    }

    /// Build a real git repository with a linked worktree and assert that
    /// `all_merged_all_namespaces_from` picks up daemons from both.
    #[test]
    fn test_all_merged_all_namespaces_discovers_worktrees() {
        let temp = tempfile::tempdir().unwrap();
        let repo = temp.path().join("my-repo");
        std::fs::create_dir(&repo).unwrap();

        // git worktree add requires at least one commit.
        let git_init = std::process::Command::new("git")
            .args(["init", "-b", "main"])
            .current_dir(&repo)
            .output()
            .expect("git init");
        assert!(git_init.status.success(), "git init failed: {:?}", git_init);

        std::fs::write(repo.join("main.toml"), "hello\n").unwrap();

        let git_commit = std::process::Command::new("git")
            .args([
                "-c",
                "user.name=pitchfork-test",
                "-c",
                "user.email=pitchfork-test@example.com",
                "add",
                "-A",
            ])
            .current_dir(&repo)
            .output()
            .expect("git add");
        assert!(git_commit.status.success());

        let git_commit = std::process::Command::new("git")
            .args([
                "-c",
                "user.name=pitchfork-test",
                "-c",
                "user.email=pitchfork-test@example.com",
                "commit",
                "-m",
                "init",
            ])
            .current_dir(&repo)
            .output()
            .expect("git commit");
        assert!(
            git_commit.status.success(),
            "git commit failed: {:?}",
            git_commit
        );

        let wt = temp.path().join("my-repo-feature");
        let git_wt = std::process::Command::new("git")
            .args(["worktree", "add", "-b", "feature-x", wt.to_str().unwrap()])
            .current_dir(&repo)
            .output()
            .expect("git worktree add");
        assert!(
            git_wt.status.success(),
            "git worktree add failed: {:?}",
            git_wt
        );

        // Config in the main checkout.
        std::fs::write(
            repo.join("pitchfork.toml"),
            "[daemons.api]\nrun = \"echo main\"\n",
        )
        .unwrap();
        // Config in the linked worktree (different namespace: dir name).
        std::fs::write(
            wt.join("pitchfork.toml"),
            "[daemons.worker]\nrun = \"echo wt\"\n",
        )
        .unwrap();

        super::invalidate_config_cache();

        // Resolve from inside the worktree: both namespaces must be visible.
        let pt = PitchforkToml::all_merged_all_namespaces_from_blocking(&wt).unwrap();

        let main_id = DaemonId::new("my-repo", "api");
        let wt_id = DaemonId::new("my-repo-feature", "worker");
        assert!(
            pt.daemons.contains_key(&main_id),
            "main checkout daemon missing"
        );
        assert!(pt.daemons.contains_key(&wt_id), "worktree daemon missing");

        // Resolving from the main checkout must also see the worktree daemon.
        let pt_from_main = PitchforkToml::all_merged_all_namespaces_from_blocking(&repo).unwrap();
        assert!(pt_from_main.daemons.contains_key(&wt_id));

        // Clean up.
        let _ = std::process::Command::new("git")
            .args(["worktree", "remove", "--force", wt.to_str().unwrap()])
            .current_dir(&repo)
            .output();
        super::invalidate_config_cache();
    }

    #[test]
    fn test_adhoc_id_uses_invocation_directory_namespace() {
        let temp = tempfile::tempdir().unwrap();
        let project = temp.path().join("feature-tree");
        std::fs::create_dir(&project).unwrap();
        std::fs::write(
            project.join("pitchfork.toml"),
            "[daemons.other]\nrun = \"true\"\n",
        )
        .unwrap();

        let id = PitchforkToml::resolve_id_allow_adhoc_from("api", &project).unwrap();
        assert_eq!(id, DaemonId::new("feature-tree", "api"));
        let qualified =
            PitchforkToml::resolve_id_allow_adhoc_from("explicit/api", &project).unwrap();
        assert_eq!(qualified, DaemonId::new("explicit", "api"));
    }

    #[test]
    fn test_adhoc_id_falls_back_to_global_without_project_config() {
        let temp = tempfile::tempdir().unwrap();
        let id = PitchforkToml::resolve_id_allow_adhoc_from("api", temp.path()).unwrap();
        assert_eq!(id, DaemonId::new("global", "api"));
    }
}