trustee-api 0.19.1

//! 16F: per-agent THQ dispatch lane — boot-time population of
//! `ServerState.thq_dispatch`.
//!
//! This module is the dispatch half of the old torpi-era registration
//! module (`thq_register.rs`), EXTRACTED UNCHANGED by the 0.15.0
//! enrollment rewrite. The two concepts are now hard-separated:
//!
//! - **Enrollment** (`thq_register.rs`, v0.3 lane): the trustee PROCESS
//!   registers itself as a runtime against THQ. Process-level, one loop,
//!   zero coupling to users.
//! - **Dispatch** (THIS module): agents-as-users. Per-user `[thq]` overlay
//!   sections declare which agent-user a THQ-dispatched session must run
//!   AS (`owner_id` = the agent's Kanidm `sub`, `service_token` = the env
//!   var holding her service credential). The `xagent` router consumes the
//!   table built here. Registration-era keys (`torpi_url`, `advertise_url`)
//!   in overlays are INERT here — dispatch only reads its own three keys.
//!
//! Boot-only lifecycle: overlays are read once at boot (restart to change),
//! exactly as before the rewrite.

use crate::state::{ServerState, ThqDispatchEntry};

/// Per-user `[thq]` overlay fields the DISPATCH lane reads.
///
/// Deliberately minimal: the dispatch lane keys on `agent_name`, runs AS
/// `owner_id`, and needs the declared `service_token` to be dispatchable.
/// Everything else in the overlay is another lane's business.
#[derive(Debug, Clone)]
pub struct DispatchConfig {
    /// The dispatch key — also the `xagent` path segment.
    pub agent_name: String,
    /// The agent's Kanidm `sub` (16E sub-pin): session bucket, per-user
    /// home, MCP loader cache, and Cedar principal all resolve through it.
    pub owner_id: Option<String>,
    /// Issue 8e0a1215: the env var holding her service credential
    /// (`service_token = "${PAYDAR_SERVICE_ACCOUNT}"` or bare `KEY`).
    pub service_token: Option<String>,
}

impl DispatchConfig {
    /// Parse the `[thq]` section of a per-user overlay. Returns `None` if
    /// the section is absent (user is not a dispatch target). Only the
    /// three dispatch keys are read; registration-era keys are ignored.
    pub fn from_toml(config_toml: &str) -> Option<Self> {
        let table: toml::Table = toml::from_str(config_toml).ok()?;
        let thq = table.get("thq")?.as_table()?;
        let agent_name = thq
            .get("agent_name")
            .and_then(|v| v.as_str())
            .map(String::from)
            .unwrap_or_else(|| {
                std::env::var("HOSTNAME")
                    .or_else(|_| std::env::var("COMPUTERNAME"))
                    .unwrap_or_else(|_| "trustee".to_string())
            });
        let owner_id = thq
            .get("owner_id")
            .and_then(|v| v.as_str())
            .map(|s| s.trim().to_string())
            .filter(|s| !s.is_empty());
        let service_token = thq
            .get("service_token")
            .and_then(|v| v.as_str())
            .map(|s| s.trim().to_string())
            .filter(|s| !s.is_empty());
        Some(Self {
            agent_name,
            owner_id,
            service_token,
        })
    }
}

/// One discovered agent-user: a `users/{hash}/` home whose overlay config
/// carries a `[thq]` section.
#[derive(Debug, Clone)]
pub struct DiscoveredAgent {
    /// Hash directory name under `~/.trustee/users/`.
    pub user_hash: String,
    /// The user's home directory (`~/.trustee/users/{hash}/`).
    pub user_home: std::path::PathBuf,
    /// Parsed `[thq]` section from the user's overlay config.
    pub config: DispatchConfig,
}

/// Scan `~/.trustee/users/*/config/trustee.toml` for per-user `[thq]`
/// sections. Deterministic order (sorted by hash) so startup logs are
/// reproducible.
pub fn discover_user_agents() -> Vec<DiscoveredAgent> {
    let home = std::env::var("HOME")
        .or_else(|_| std::env::var("USERPROFILE"))
        .unwrap_or_else(|_| ".".to_string());
    discover_user_agents_in(
        &std::path::PathBuf::from(home)
            .join(".trustee")
            .join("users"),
    )
}

/// Testable core of [`discover_user_agents`].
pub fn discover_user_agents_in(users_dir: &std::path::Path) -> Vec<DiscoveredAgent> {
    let mut found = Vec::new();
    let Ok(entries) = std::fs::read_dir(users_dir) else {
        return found;
    };
    for entry in entries.flatten() {
        let user_home = entry.path();
        if !user_home.is_dir() {
            continue;
        }
        let overlay = user_home.join("config").join("trustee.toml");
        let Ok(content) = std::fs::read_to_string(&overlay) else {
            continue;
        };
        if let Some(config) = DispatchConfig::from_toml(&content) {
            found.push(DiscoveredAgent {
                user_hash: user_home
                    .file_name()
                    .map(|n| n.to_string_lossy().into_owned())
                    .unwrap_or_default(),
                user_home,
                config,
            });
        }
    }
    found.sort_by(|a, b| a.user_hash.cmp(&b.user_hash));
    found
}

/// The issuer declared by the overlay's first `service-account` credential —
/// the origin the agent's service token was minted for (16F: exchange is
/// origin-bound, so it must travel with the credential).
fn read_overlay_service_issuer(user_home: &std::path::Path) -> Option<String> {
    let overlay = std::fs::read_to_string(user_home.join("config").join("trustee.toml")).ok()?;
    let v: toml::Value = overlay.parse().ok()?;
    let creds = v.get("mcp")?.get("credentials")?.as_table()?;
    for (_name, cred) in creds {
        if cred.get("type").and_then(|t| t.as_str()) == Some("service-account") {
            if let Some(issuer) = cred.get("issuer_url").and_then(|i| i.as_str()) {
                return Some(issuer.to_string());
            }
        }
    }
    None
}

/// 16F: every service-account issuer declared by the discovered agent-user
/// overlays — the vhosts the deployed agents' tokens are actually minted on.
pub fn discover_service_issuers() -> Vec<String> {
    let mut out = Vec::new();
    for agent in discover_user_agents() {
        if let Some(issuer) = read_overlay_service_issuer(&agent.user_home) {
            if !out.contains(&issuer) {
                out.push(issuer);
            }
        }
    }
    out
}

/// Issue 8e0a1215: outcome of resolving an agent-user's dispatch credential.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ServiceTokenResolution {
    /// `[thq].service_token` declared and resolved from the agent's `.env`.
    /// The ONLY way an agent becomes dispatchable — the hardcoded key scan
    /// (THQ/FAME/FARZAN/KANIDM_SERVICE_TOKEN) was removed in api 0.13.0.
    Resolved(String),
    /// No `[thq].service_token` declared at all. The agent is NOT
    /// dispatchable; with an `owner_id` present (dispatch intent) boot
    /// FAILS LOUD — an undeclared credential is the same silent-skip shape
    /// this issue was filed to kill.
    Undeclared,
    /// `[thq].service_token` DECLARED but its variable did not resolve from
    /// the agent's `.env` (missing file, missing key, or an unresolved
    /// `${…}` placeholder value). Boot FAILS LOUD naming agent + variable;
    /// the agent is NOT dispatchable. Never a silent skip.
    DeclaredUnresolved { var: String },
}

/// Extract the env-var name from a `[thq].service_token` declaration.
/// Accepts the canonical `"${KEY}"` wrapper and a bare `"KEY"`. Malformed
/// input returns the raw trimmed string — the lookup then fails and the
/// boot error names exactly what the config said.
fn declared_service_var(decl: &str) -> String {
    let s = decl.trim();
    match s.strip_prefix("${").and_then(|r| r.strip_suffix('}')) {
        Some(inner) => inner.trim().to_string(),
        None => s.to_string(),
    }
}

/// Look up `key` in a `.env` file (`KEY=value`, quotes unwrapped, `#`
/// comments skipped). A missing key, an empty value, or an unresolved
/// `${…}` placeholder value (the house "never provisioned" convention)
/// all yield None. The user's `.env` is the
/// ONLY source — no process-env fallback, so a declared credential must be
/// provisioned where the agent's identity lives.
fn lookup_env_value(env_path: &std::path::Path, key: &str) -> Option<String> {
    if key.is_empty() {
        return None;
    }
    let env = std::fs::read_to_string(env_path).ok()?;
    let prefix = format!("{key}=");
    for line in env.lines() {
        let line = line.trim();
        if line.starts_with('#') {
            continue;
        }
        if let Some(value) = line.strip_prefix(&prefix) {
            let value = value.trim().trim_matches('"').trim_matches('\'');
            if !value.is_empty() && !value.starts_with("${") {
                return Some(value.to_string());
            }
        }
    }
    None
}

/// Issue 8e0a1215: resolve an agent-user's dispatch credential.
///
/// The `[thq].service_token` declaration is the ONLY source — the config
/// declares, the code never guesses. Declared-but-unresolved and
/// undeclared are both distinct loud outcomes
/// ([`ServiceTokenResolution`]); neither silently degrades.
pub fn resolve_user_service_token(
    user_home: &std::path::Path,
    config: &DispatchConfig,
) -> ServiceTokenResolution {
    match config.service_token.as_deref() {
        Some(decl) => {
            let var = declared_service_var(decl);
            match lookup_env_value(&user_home.join(".env"), &var) {
                Some(value) => ServiceTokenResolution::Resolved(value),
                None => ServiceTokenResolution::DeclaredUnresolved { var },
            }
        }
        None => ServiceTokenResolution::Undeclared,
    }
}

/// 16F: build the dispatch table from per-user `[thq]` overlays.
///
/// The dispatch lane of the old `thq_register::spawn_all`, extracted
/// unchanged by the 0.15.0 enrollment rewrite: every discovered agent-user
/// with an `owner_id` (dispatch intent) lands in `ServerState.thq_dispatch`
/// keyed by `agent_name`, carrying her resolved service credential and
/// issuer. Loud errors on undeclared/unresolved credentials — the agent
/// stays out of the table, never a silent skip. Registration is NOT this
/// function's business anymore (see `thq_register`).
pub fn populate(state: ServerState) {
    let agents = discover_user_agents();
    if agents.is_empty() {
        tracing::debug!("THQ dispatch: no per-user [thq] entries under users/");
        return;
    }

    tracing::info!(
        "THQ dispatch table: {} agent-user(s) from users/",
        agents.len()
    );

    for agent in agents.iter() {
        let label = format!("{} ({})", agent.config.agent_name, agent.user_hash);
        // Issue 8e0a1215: credential resolution is config-DECLARED, not
        // code-guessed. An explicit [thq].service_token wins; absent →
        // loud error; declared-but-unresolved → LOUD error, non-dispatchable.
        let resolution = resolve_user_service_token(&agent.user_home, &agent.config);
        let bearer = match &resolution {
            ServiceTokenResolution::Resolved(token) => Some(token.clone()),
            ServiceTokenResolution::Undeclared => {
                tracing::error!(
                    "THQ: agent {} has NO [thq].service_token declaration — dispatch credentials are \
                     config-declared since api 0.13.0 (the hardcoded THQ/FAME/FARZAN/KANIDM key scan \
                     was removed). Add service_token = \"${{YOUR_KEY}}\" to the [thq] section of {} — \
                     agent NOT dispatchable until then.",
                    label,
                    agent.user_home.join("config").join("trustee.toml").display()
                );
                None
            }
            ServiceTokenResolution::DeclaredUnresolved { var } => {
                tracing::error!(
                    "THQ: agent {} declared [thq].service_token = \"${{{var}}}\" but {var} is NOT set in {} — \
                     agent NOT dispatchable. Set the variable in the agent's .env (a placeholder value \
                     like ${{...}} does not count) or fix the declaration.",
                    label,
                    agent.user_home.join(".env").display()
                );
                None
            }
        };

        // 16F: register the dispatch target so THQ-proxied sessions can be
        // impersonated AS this agent-user (see crate::xagent).
        if agent.config.owner_id.as_deref().map(str::len).unwrap_or(0) > 0 {
            if !matches!(resolution, ServiceTokenResolution::Resolved(_)) {
                // Already SCREAMED above — the agent stays out of the
                // dispatch table (non-dispatchable). Never a silent skip.
            } else {
                state.thq_dispatch.insert(
                    agent.config.agent_name.clone(),
                    ThqDispatchEntry {
                        user_key: agent.config.owner_id.clone().unwrap_or_default(),
                        service_token: bearer,
                        issuer_url: read_overlay_service_issuer(&agent.user_home),
                    },
                );
            }
        } else {
            tracing::warn!(
                "THQ: agent-user {} has no [thq].owner_id — NOT dispatchable (16F)",
                label
            );
        }

        tracing::info!(
            "THQ: agent-user {} (owner={})",
            label,
            agent.config.owner_id.as_deref().unwrap_or("<none>")
        );
    }
}

/// Testable core of [`populate`], writing into an explicit table.
#[cfg(test)]
pub fn populate_into(
    table: &dashmap::DashMap<String, ThqDispatchEntry>,
    agents: &[DiscoveredAgent],
) {
    for agent in agents {
        let resolution = resolve_user_service_token(&agent.user_home, &agent.config);
        if agent.config.owner_id.as_deref().map(str::len).unwrap_or(0) == 0 {
            continue;
        }
        if let ServiceTokenResolution::Resolved(token) = resolution {
            table.insert(
                agent.config.agent_name.clone(),
                ThqDispatchEntry {
                    user_key: agent.config.owner_id.clone().unwrap_or_default(),
                    service_token: Some(token),
                    issuer_url: read_overlay_service_issuer(&agent.user_home),
                },
            );
        }
    }
}

/// Shared test fixture: a fresh temp dir standing in for a user home.
#[cfg(test)]
fn temp_users_dir(tag: &str) -> std::path::PathBuf {
    let dir = std::env::temp_dir().join(format!("trustee-dispatch-{}-{}", tag, std::process::id()));
    let _ = std::fs::remove_dir_all(&dir);
    std::fs::create_dir_all(&dir).unwrap();
    dir
}

#[cfg(test)]
mod tests {
    use super::*;
    use dashmap::DashMap;

    #[test]
    fn parse_dispatch_keys_only() {
        // 0.15.0: registration-era keys in an overlay are INERT — dispatch
        // reads agent_name/owner_id/service_token and nothing else.
        let toml = r#"
[thq]
torpi_url = "https://torpi.example.com"
advertise_url = "https://10.0.0.5:3000"
agent_name = "ravand"
owner_id = "1a71c077-b3b3-4581-b605-925c3f276f30"
service_token = "${PAYDAR_SERVICE_ACCOUNT}"
"#;
        let cfg = DispatchConfig::from_toml(toml).expect("should parse");
        assert_eq!(cfg.agent_name, "ravand");
        assert_eq!(
            cfg.owner_id.as_deref(),
            Some("1a71c077-b3b3-4581-b605-925c3f276f30")
        );
        assert_eq!(
            cfg.service_token.as_deref(),
            Some("${PAYDAR_SERVICE_ACCOUNT}")
        );
    }

    #[test]
    fn parse_minimal_overlay_no_registration_keys() {
        // The new shape: no torpi_url/advertise_url at all.
        let toml = r#"
[thq]
agent_name = "nox"
owner_id = "d0f5c4ba-9c10-4ff7-85a4-f2c0e588a55a"
"#;
        let cfg = DispatchConfig::from_toml(toml).expect("should parse");
        assert_eq!(cfg.agent_name, "nox");
        assert!(cfg.service_token.is_none());
    }

    #[test]
    fn parse_no_section_returns_none() {
        let toml = "[oidc]\nissuer_url = \"https://example.com\"\n";
        assert!(DispatchConfig::from_toml(toml).is_none());
    }

    #[test]
    fn empty_owner_id_is_none() {
        let toml = "[thq]\nagent_name = \"x\"\nowner_id = \"\"\n";
        let cfg = DispatchConfig::from_toml(toml).unwrap();
        assert!(cfg.owner_id.is_none());
    }

    #[test]
    fn discover_finds_only_users_with_thq() {
        let base = temp_users_dir("discover");
        let thq_overlay = "[mcp]\nenabled = true\n\n[thq]\nagent_name = \"ravand\"\n";
        for (hash, content) in [
            ("aaaa1111", thq_overlay),
            ("bbbb2222", "[mcp]\nenabled = true\n"), // no thq
            ("cccc3333", "not toml at all {{{"),     // unparsable
        ] {
            let dir = base.join(hash).join("config");
            std::fs::create_dir_all(&dir).unwrap();
            std::fs::write(dir.join("trustee.toml"), content).unwrap();
        }

        let found = discover_user_agents_in(&base);
        assert_eq!(found.len(), 1, "only the [thq]-bearing user is discovered");
        assert_eq!(found[0].user_hash, "aaaa1111");
        assert_eq!(found[0].config.agent_name, "ravand");
        let _ = std::fs::remove_dir_all(&base);
    }

    #[test]
    fn discover_is_deterministic_and_sorted() {
        let base = temp_users_dir("sorted");
        for hash in ["dddd4444", "bbbb2222", "cccc3333"] {
            let dir = base.join(hash).join("config");
            std::fs::create_dir_all(&dir).unwrap();
            std::fs::write(dir.join("trustee.toml"), "[thq]\nagent_name = \"a\"\n").unwrap();
        }
        let found = discover_user_agents_in(&base);
        let hashes: Vec<&str> = found.iter().map(|a| a.user_hash.as_str()).collect();
        assert_eq!(hashes, vec!["bbbb2222", "cccc3333", "dddd4444"]);
        let _ = std::fs::remove_dir_all(&base);
    }

    #[test]
    fn read_overlay_service_issuer_picks_service_account_credential() {
        let base = std::env::temp_dir().join(format!("trustee-dispatch-issuer-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&base);
        let dir = base.join("config");
        std::fs::create_dir_all(&dir).unwrap();
        std::fs::write(
            dir.join("trustee.toml"),
            "[thq]\nagent_name = \"a\"\n\n[mcp.credentials.fame_service]\ntype = \"service-account\"\nservice_token = \"${FAME_SERVICE_TOKEN}\"\nissuer_url = \"https://idp.tanbal.ir/oauth2/openid/pdt-api\"\n\n[mcp.credentials.interactive]\ntype = \"interactive\"\nissuer_url = \"https://ignored.example/\"\n",
        )
        .unwrap();
        assert_eq!(
            read_overlay_service_issuer(&base).as_deref(),
            Some("https://idp.tanbal.ir/oauth2/openid/pdt-api"),
            "issuer must come from the service-account credential, not another type"
        );
        assert!(read_overlay_service_issuer(&base.join("nope")).is_none());
        let _ = std::fs::remove_dir_all(&base);
    }

    #[test]
    fn populate_into_builds_table_for_declared_and_resolved() {
        let base = temp_users_dir("populate");
        let home = base.join("aaaa1111");
        std::fs::create_dir_all(home.join("config")).unwrap();
        std::fs::write(
            home.join("config").join("trustee.toml"),
            "[thq]\nagent_name = \"ravand\"\nowner_id = \"sub-uuid\"\nservice_token = \"${KEY}\"\n\n[mcp.credentials.svc]\ntype = \"service-account\"\nissuer_url = \"https://idp.example\"\n",
        )
        .unwrap();
        std::fs::write(home.join(".env"), "KEY=token-1\n").unwrap();

        let agents = discover_user_agents_in(&base);
        let table: DashMap<String, ThqDispatchEntry> = DashMap::new();
        populate_into(&table, &agents);
        let e = table.get("ravand").expect("dispatch entry").clone();
        assert_eq!(e.user_key, "sub-uuid");
        assert_eq!(e.service_token.as_deref(), Some("token-1"));
        assert_eq!(e.issuer_url.as_deref(), Some("https://idp.example"));
        let _ = std::fs::remove_dir_all(&base);
    }

    #[test]
    fn populate_into_skips_unresolved_credential() {
        // Declared but unresolved → loud at populate(), and the entry is
        // NOT inserted (non-dispatchable, never a silent skip).
        let base = temp_users_dir("populate-unresolved");
        let home = base.join("aaaa1111");
        std::fs::create_dir_all(home.join("config")).unwrap();
        std::fs::write(
            home.join("config").join("trustee.toml"),
            "[thq]\nagent_name = \"ghost\"\nowner_id = \"sub-uuid\"\nservice_token = \"${NEVER_SET}\"\n",
        )
        .unwrap();

        let agents = discover_user_agents_in(&base);
        let table: DashMap<String, ThqDispatchEntry> = DashMap::new();
        populate_into(&table, &agents);
        assert!(table.get("ghost").is_none(), "unresolved credential must not dispatch");
        let _ = std::fs::remove_dir_all(&base);
    }
}

// ---------------------------------------------------------------------------
// Issue 8e0a1215: [thq].service_token declared credential key
// ---------------------------------------------------------------------------

#[cfg(test)]
mod service_token_declaration_tests {
    use super::*;

    /// Minimal overlay TOML with an optional service_token declaration.
    fn thq_toml(service_token: Option<&str>) -> String {
        let mut s = String::from("[thq]\nagent_name = \"ravand\"\n");
        if let Some(st) = service_token {
            s.push_str(&format!("service_token = \"{st}\"\n"));
        }
        s
    }

    #[test]
    fn parse_declared_service_token_field() {
        let cfg = DispatchConfig::from_toml(&thq_toml(Some("${PAYDAR_SERVICE_ACCOUNT}")))
            .expect("should parse");
        assert_eq!(
            cfg.service_token.as_deref(),
            Some("${PAYDAR_SERVICE_ACCOUNT}"),
            "declaration is stored verbatim; resolution happens at boot"
        );
        assert!(
            DispatchConfig::from_toml(&thq_toml(None))
                .unwrap()
                .service_token
                .is_none(),
            "absent field = None (non-dispatchable, loud when owner_id set)"
        );
    }

    #[test]
    fn declared_var_accepts_wrapped_and_bare_forms() {
        assert_eq!(
            declared_service_var("${PAYDAR_SERVICE_ACCOUNT}"),
            "PAYDAR_SERVICE_ACCOUNT"
        );
        assert_eq!(
            declared_service_var("  ${ PAYDAR_SERVICE_ACCOUNT }  "),
            "PAYDAR_SERVICE_ACCOUNT"
        );
        assert_eq!(
            declared_service_var("PAYDAR_SERVICE_ACCOUNT"),
            "PAYDAR_SERVICE_ACCOUNT"
        );
        // Malformed input surfaces verbatim in the loud error, never swallowed.
        assert_eq!(declared_service_var(""), "");
        assert_eq!(declared_service_var("${"), "${");
    }

    /// THE PAYDAR CASE (live incident, issue 8e0a1215): an agent whose
    /// credential lives under a key OUTSIDE the legacy four dispatches with
    /// zero source changes — config-declared, not code-guessed.
    #[test]
    fn declared_field_wins_over_legacy_scan_with_custom_key_name() {
        let base = temp_users_dir("declared-wins");
        std::fs::write(
            base.join(".env"),
            "THQ_SERVICE_TOKEN=legacy-token\nPAYDAR_SERVICE_ACCOUNT=paydar-token\n",
        )
        .unwrap();
        let cfg = DispatchConfig::from_toml(&thq_toml(Some("${PAYDAR_SERVICE_ACCOUNT}"))).unwrap();
        assert_eq!(
            resolve_user_service_token(&base, &cfg),
            ServiceTokenResolution::Resolved("paydar-token".to_string()),
            "explicit declaration must win over the legacy priority list"
        );
        let _ = std::fs::remove_dir_all(&base);
    }

    #[test]
    fn declared_but_env_file_missing_is_loud_unresolved() {
        let base = temp_users_dir("declared-no-env");
        let cfg = DispatchConfig::from_toml(&thq_toml(Some("${PAYDAR_SERVICE_ACCOUNT}"))).unwrap();
        assert_eq!(
            resolve_user_service_token(&base, &cfg),
            ServiceTokenResolution::DeclaredUnresolved {
                var: "PAYDAR_SERVICE_ACCOUNT".to_string()
            },
            ".env missing entirely → same loud path, never a silent skip"
        );
        let _ = std::fs::remove_dir_all(&base);
    }

    #[test]
    fn declared_but_key_missing_from_env_is_loud_unresolved() {
        let base = temp_users_dir("declared-no-key");
        std::fs::write(base.join(".env"), "THQ_SERVICE_TOKEN=legacy-token\n").unwrap();
        let cfg = DispatchConfig::from_toml(&thq_toml(Some("${PAYDAR_SERVICE_ACCOUNT}"))).unwrap();
        assert_eq!(
            resolve_user_service_token(&base, &cfg),
            ServiceTokenResolution::DeclaredUnresolved {
                var: "PAYDAR_SERVICE_ACCOUNT".to_string()
            },
            "legacy key presence must NOT satisfy a different declared key"
        );
        let _ = std::fs::remove_dir_all(&base);
    }

    #[test]
    fn declared_but_placeholder_value_is_unresolved() {
        let base = temp_users_dir("declared-placeholder");
        // House convention: a ${...} VALUE means the secret was never
        // provisioned.
        std::fs::write(
            base.join(".env"),
            "PAYDAR_SERVICE_ACCOUNT=${PAYDAR_SERVICE_ACCOUNT}\n",
        )
        .unwrap();
        let cfg = DispatchConfig::from_toml(&thq_toml(Some("${PAYDAR_SERVICE_ACCOUNT}"))).unwrap();
        assert_eq!(
            resolve_user_service_token(&base, &cfg),
            ServiceTokenResolution::DeclaredUnresolved {
                var: "PAYDAR_SERVICE_ACCOUNT".to_string()
            }
        );
        let _ = std::fs::remove_dir_all(&base);
    }

    /// The hardcoded key scan is REMOVED (api 0.13.0): an agent declaring
    /// nothing is `Undeclared` — non-dispatchable, loud at boot when
    /// `owner_id` (dispatch intent) is set. Legacy keys in .env are INERT.
    #[test]
    fn undeclared_declaration_is_undeclared_even_with_legacy_keys_present() {
        let base = temp_users_dir("undeclared");
        // The blessed-four keys sit right there in .env — they no longer
        // conjure a credential. Config declares or the agent is out.
        std::fs::write(base.join(".env"), "THQ_SERVICE_TOKEN=thq-token\n").unwrap();
        let cfg = DispatchConfig::from_toml(&thq_toml(None)).unwrap();
        assert_eq!(
            resolve_user_service_token(&base, &cfg),
            ServiceTokenResolution::Undeclared,
            "no declaration → Undeclared; the legacy scan must NOT rescue it"
        );
        // Same answer with no .env at all — the outcome is config-shaped,
        // not env-shaped.
        assert_eq!(
            resolve_user_service_token(&base.join("no-env"), &cfg),
            ServiceTokenResolution::Undeclared
        );
        let _ = std::fs::remove_dir_all(&base);
    }
}