agentmux_srv/backend/

agent_config.rs

// Copyright 2024-2026, AgentMux Corp.
// SPDX-License-Identifier: Apache-2.0

//! Pure config-building logic for agent definitions.
//!
//! Ports the `buildConfigFiles`, `buildMcpConfig`, and `expandTemplate`
//! functions from `frontend/app/view/agent/agent-model.ts`.
//! Most functions here are pure — no I/O, no async. The exception is the
//! `managed skill files manifest` section near the end: real filesystem
//! I/O shared by the two independent RPC handlers that materialize config
//! files to disk (`agent.open`'s `write_agent_config_files` in
//! `server/app_api/agent_open.rs`, and `writeagentconfig` in
//! `server/editor_handlers.rs` — the latter is the actual "click Launch"
//! path used on every normal agent launch). Lives here rather than in
//! either handler file so the two callers can't drift out of sync on the
//! manifest format or the path-traversal defense (reagent P1, PR #2322 —
//! `writeagentconfig` initially had no cleanup at all).

use std::collections::{HashMap, HashSet};

use chrono::Utc;
use serde_json::{json, Value};

use crate::backend::storage::store::{derive_slug, AgentSkill};

/// `skill_type` value that materializes a skill as an Agent Skills-format
/// `.claude/skills/<slug>/SKILL.md` instead of a `.claude/commands/<trigger>.md`
/// slash command. Any other value (in practice, always `"prompt"` today) keeps
/// the pre-existing slash-command behavior. See
/// `docs/specs/REPORT_ARMORY_BUNDLE_STANDARD_RESEARCH_2026_07_16.md` Phase 0 —
/// `skill_type` already existed end-to-end but was never branched on before
/// this, making it the lowest-friction place to hang the format discriminator
/// rather than adding a new column.
pub const SKILL_TYPE_AGENT_SKILL: &str = "agent-skill";

/// A single file to be written to the agent working directory.
#[derive(Debug, Clone)]
pub struct AgentConfigFile {
    /// Path relative to the agent working directory (e.g. `"CLAUDE.md"`, `".mcp.json"`).
    pub filename: String,
    /// UTF-8 file content.
    pub content: String,
}

/// Build the list of config files to write to the agent working directory.
///
/// Assembles the startup instructions file (`CLAUDE.md`, `AGENTS.md`,
/// `GEMINI.md`, ... — resolved per `provider_id` via
/// `providers::get_provider(provider_id).startup_instructions_filename`;
/// see docs/specs/SPEC_PROVIDER_AWARE_STARTUP_INSTRUCTIONS_2026_08_24.md)
/// from `soul` + `agentmd` + `memory` + skills index, writes each skill as
/// a slash command under `.claude/commands/<trigger>.md`, writes
/// `.claude/hooks.json` if a `hooks` content entry is present, auto-injects
/// the AgentMux MCP server entry, and applies `{{VARIABLE}}` template
/// substitution throughout. An unrecognized `provider_id`, or one with no
/// confirmed native file (currently only `kimi`), gets no instructions
/// file written at all — never a silent `CLAUDE.md` fallback.
///
/// Mirrors `buildConfigFiles()` in `frontend/app/view/agent/agent-model.ts`.
pub fn build_config_files(
    content_map: &HashMap<String, String>,
    skills: &[AgentSkill],
    agent_name: &str,
    agent_id: &str,
    agent_slug: &str,
    working_directory: &str,
    provider_id: &str,
) -> Vec<AgentConfigFile> {
    let mut files: Vec<AgentConfigFile> = Vec::new();

    // Template variables for {{}} substitution
    let mut template_vars: HashMap<String, String> = HashMap::new();
    template_vars.insert("AGENT".to_string(), agent_name.to_string());
    template_vars.insert("AGENT_DISPLAY".to_string(), agent_name.to_string());
    template_vars.insert("AGENT_SLUG".to_string(), agent_slug.to_string());
    template_vars.insert("AGENT_ID".to_string(), agent_id.to_string());
    template_vars.insert("WORKING_DIR".to_string(), working_directory.to_string());
    // DATE in YYYY-MM-DD format, UTC
    template_vars.insert("DATE".to_string(), Utc::now().format("%Y-%m-%d").to_string());

    // ----------------------------------------------------------------
    // Build the startup instructions file: Soul + AgentMD + Memory + Skills index
    // ----------------------------------------------------------------
    let mut instructions_parts: Vec<String> = Vec::new();

    if let Some(soul) = content_map.get("soul") {
        instructions_parts.push(expand_template(soul, &template_vars));
    }
    if let Some(agentmd) = content_map.get("agentmd") {
        if !instructions_parts.is_empty() {
            instructions_parts.push("\n---\n".to_string());
        }
        instructions_parts.push(expand_template(agentmd, &template_vars));
    }
    if let Some(memory) = content_map.get("memory") {
        instructions_parts.push(format!("\n{BUNDLE_SECTION_HEADING}\n"));
        instructions_parts.push(memory.clone());
    }

    // Append skill index with trigger references. Claude Code lists the
    // skills it has a file for (.claude/commands, .claude/skills) by itself,
    // so for it the index carries only those without one (LC3, §4.4).
    // By the resolved provider, so an alias (`claude-code`) counts as Claude.
    let is_claude = crate::backend::providers::get_provider(provider_id).is_some_and(|p| p.id == "claude");
    let own_file = skills_with_their_own_file(skills);
    let indexed: Vec<_> = skills.iter().enumerate().filter(|(i, _)| !is_claude || !own_file[*i]).map(|(_, s)| s).collect();
    if !indexed.is_empty() {
        instructions_parts.push("\n# Available Skills\n\n".to_string());
        instructions_parts.push("Use `/<trigger>` to invoke a skill.\n\n".to_string());
        for skill in indexed {
            let trigger_part = if skill.trigger.is_empty() {
                String::new()
            } else {
                format!(" (trigger: /{})", skill.trigger)
            };
            let desc_part = if skill.description.is_empty() {
                String::new()
            } else {
                format!(" \u{2014} {}", skill.description)
            };
            instructions_parts.push(format!("- **{}**{}{}\n", skill.name, trigger_part, desc_part));
        }
    }

    // Resolved per-provider — `None` for an unrecognized provider_id or one
    // with no confirmed native file (kimi) skips writing this file
    // entirely rather than guessing "CLAUDE.md".
    // Written even when empty: srv injects the Global Memory into it at write
    // time (`inject_global_bundles`), and with the skills index gone for
    // Claude (LC3) an agent with no soul, instructions or memory would
    // otherwise get no startup file, and no Global Memory in it, at all.
    let instructions_filename = crate::backend::providers::get_provider(provider_id)
        .and_then(|p| p.startup_instructions_filename);
    if let Some(filename) = instructions_filename {
        files.push(AgentConfigFile {
            filename: filename.to_string(),
            content: instructions_parts.join(""),
        });
    }

    // ----------------------------------------------------------------
    // Write each skill as either a slash command
    // (.claude/commands/{trigger}.md, default) or an Agent Skills-format
    // SKILL.md (.claude/skills/{slug}/SKILL.md, skill_type ==
    // SKILL_TYPE_AGENT_SKILL) for native Claude Code consumption.
    // ----------------------------------------------------------------
    let mut used_skill_slugs: HashSet<String> = HashSet::new();
    for skill in skills {
        if skill.content.is_empty() {
            continue;
        }
        if skill.skill_type == SKILL_TYPE_AGENT_SKILL {
            let slug = unique_skill_slug(&skill.name, &mut used_skill_slugs);
            let content = expand_template(&skill.content, &template_vars);
            files.push(AgentConfigFile {
                filename: format!(".claude/skills/{slug}/SKILL.md"),
                content: render_skill_md(&slug, &skill.description, &content),
            });
        } else if let Some(safe_trigger) = sanitize_trigger(&skill.trigger) {
            let content = expand_template(&skill.content, &template_vars);
            files.push(AgentConfigFile {
                filename: format!(".claude/commands/{safe_trigger}.md"),
                content,
            });
        }
    }

    // ----------------------------------------------------------------
    // Write .claude/hooks.json — always includes a PreToolUse:Bash
    // entry pointing at `agentmux-bashwrap hook` so the streaming
    // wrapper is invoked for every Bash tool call, plus two
    // PreCompact entries (matcher "manual" / "auto") pointing at
    // `agentmux-bashwrap precompact` so a live "compaction started"
    // signal reaches the sidecar. User-provided hooks (from
    // content_map["hooks"]) are merged on top, with the user's
    // entries winning on key collisions, EXCEPT that our PreToolUse
    // and PreCompact entries are always appended to any user array
    // for those keys so streaming / compaction visibility stay on
    // regardless. See docs/specs/SPEC_STREAMING_BASH_RUNNER_2026_05_11.md
    // §5 and docs/specs/SPEC_COMPACTION_DETECTION_AND_HANDLING_2026_07_31.md
    // §4.2.
    // ----------------------------------------------------------------
    let user_hooks = content_map.get("hooks").map(|s| s.as_str());
    let user_settings = content_map.get("settings").map(|s| s.as_str());
    if let Some(settings_json) = build_settings_with_hooks(user_settings, user_hooks) {
        files.push(AgentConfigFile {
            filename: ".claude/settings.json".to_string(),
            content: settings_json,
        });
    }

    // ----------------------------------------------------------------
    // Build .mcp.json with auto-injected AgentMux MCP server
    // ----------------------------------------------------------------
    // agent_bus_id is not in the function signature; callers that have it
    // should call build_mcp_config directly and push the result themselves,
    // or use the variant below.
    let mcp_content = content_map.get("mcp").map(|s| s.as_str());
    if let Some(mcp_json) = build_mcp_config(mcp_content, agent_slug, "") {
        files.push(AgentConfigFile {
            filename: ".mcp.json".to_string(),
            content: mcp_json,
        });
    }

    files
}

/// Build `.mcp.json` content with the auto-injected AgentMux MCP server entry.
///
/// The AgentMux server is always present as `mcpServers.agentmux`.
/// If `user_mcp_content` is `Some`, its `mcpServers` entries are merged on top
/// (user entries win over the auto-injected entry if the key collides).
/// If the user content is not valid JSON the auto-injected-only config is
/// returned and no error is propagated (mirrors TS behavior).
///
/// Returns `None` only if serialization unexpectedly fails (should never happen).
///
/// Mirrors `buildMcpConfig()` in `frontend/app/view/agent/agent-model.ts`.
pub fn build_mcp_config(
    user_mcp_content: Option<&str>,
    agent_slug: &str,
    agent_bus_id: &str,
) -> Option<String> {
    // Auto-injected AgentMux MCP server entry.
    // agent_slug must be the pre-computed stable role slug (e.g. "korp"),
    // NOT the display name — callers are responsible for passing the right
    // value so renamed agents always advertise the same routing ID.
    let mut env_map = serde_json::Map::new();
    if !agent_slug.is_empty() {
        env_map.insert("AGENTMUX_AGENT_ID".to_string(), json!(agent_slug));
    }
    if !agent_bus_id.is_empty() {
        env_map.insert("AGENTMUX_AGENT_BUS_ID".to_string(), json!(agent_bus_id));
    }

    let agentmux_server = json!({
        "type": "stdio",
        "command": "agentmux-mcp",
        "args": [],
        "env": Value::Object(env_map),
    });

    let mut mcp_servers = serde_json::Map::new();
    mcp_servers.insert("agentmux".to_string(), agentmux_server);

    // Merge user-provided MCP config if present
    if let Some(raw) = user_mcp_content {
        match serde_json::from_str::<Value>(raw) {
            Ok(Value::Object(user_obj)) => {
                if let Some(Value::Object(user_servers)) = user_obj.get("mcpServers") {
                    for (k, v) in user_servers {
                        mcp_servers.insert(k.clone(), v.clone());
                    }
                }
            }
            Ok(_) => {
                // User content parsed but isn't an object — skip merge silently
            }
            Err(_) => {
                // Invalid JSON in agent content — keep auto-injected only (mirrors TS behavior)
                tracing::error!("agent_config: invalid MCP JSON in agent content, using auto-injected only");
            }
        }
    }

    let result = json!({ "mcpServers": Value::Object(mcp_servers) });
    match serde_json::to_string_pretty(&result) {
        Ok(s) => Some(s),
        Err(e) => {
            tracing::error!("agent_config: failed to serialize MCP config: {e}");
            None
        }
    }
}

/// Build `.mcp.json` from standalone McpServer ref rows (v1 composable model).
///
/// Layering (later wins on key collision, except the reserved `agentmux` key):
///   1. synthetic `agentmux` entry (always injected)
///   2. `user_mcp_blob`'s `mcpServers` — the legacy per-agent blob, merged when
///      the caller passes it (used so a global-only ref set never wipes a
///      legacy agent's user servers)
///   3. `servers` ref rows (the agent's own bound servers + globals)
/// For each ref row the `config` field is a JSON object used as the server
/// value directly. Falls back to `build_mcp_config` when there are no ref rows
/// and no blob.
pub fn build_mcp_config_from_refs(
    servers: &[crate::backend::storage::McpServer],
    user_mcp_blob: Option<&str>,
    agent_slug: &str,
    agent_bus_id: &str,
) -> Option<String> {
    if servers.is_empty() {
        return build_mcp_config(user_mcp_blob, agent_slug, agent_bus_id);
    }

    let mut env_map = serde_json::Map::new();
    if !agent_slug.is_empty() {
        env_map.insert("AGENTMUX_AGENT_ID".to_string(), json!(agent_slug));
    }
    if !agent_bus_id.is_empty() {
        env_map.insert("AGENTMUX_AGENT_BUS_ID".to_string(), json!(agent_bus_id));
    }
    let agentmux_server = json!({
        "type": "stdio",
        "command": "agentmux-mcp",
        "args": [],
        "env": Value::Object(env_map),
    });

    let mut mcp_servers = serde_json::Map::new();
    mcp_servers.insert("agentmux".to_string(), agentmux_server);

    // Layer 2: merge the legacy user blob's servers (skip the reserved key).
    if let Some(raw) = user_mcp_blob {
        match serde_json::from_str::<Value>(raw) {
            Ok(Value::Object(user_obj)) => {
                if let Some(Value::Object(user_servers)) = user_obj.get("mcpServers") {
                    for (k, v) in user_servers {
                        if k == "agentmux" {
                            continue;
                        }
                        mcp_servers.insert(k.clone(), v.clone());
                    }
                }
            }
            Ok(_) => {}
            Err(_) => {
                tracing::error!("agent_config: invalid MCP JSON in legacy blob; skipping blob merge");
            }
        }
    }

    // Layer 3: ref rows (own + global) overlay the blob.
    crate::backend::mcp_launch::insert_server_rows(&mut mcp_servers, servers);

    let result = json!({ "mcpServers": Value::Object(mcp_servers) });
    match serde_json::to_string_pretty(&result) {
        Ok(s) => Some(s),
        Err(e) => {
            tracing::error!("agent_config: failed to serialize ref-based MCP config: {e}");
            None
        }
    }
}

/// Convert standalone Skill records into the AgentSkill shape expected by
/// `build_config_files`. Used when the v1 ref tables are non-empty.
pub fn skills_to_agent_skills(
    skills: &[crate::backend::storage::Skill],
    agent_id: &str,
) -> Vec<crate::backend::storage::AgentSkill> {
    skills
        .iter()
        .map(|s| crate::backend::storage::AgentSkill {
            id: s.id.clone(),
            agent_id: agent_id.to_string(),
            name: s.name.clone(),
            trigger: s.trigger.clone(),
            skill_type: s.skill_type.clone(),
            description: s.description.clone(),
            content: s.content.clone(),
            created_at: s.created_at,
        })
        .collect()
}

/// Merge a user-supplied `settings.json`-level hook-array (`PreToolUse`
/// or `PreCompact`) with whatever is already staged in `hooks_obj`
/// under `key` (our auto-injected entries, possibly already carrying
/// legacy `content_map["hooks"]`-merged user entries from the earlier
/// pass in [`build_settings_with_hooks`]). User entries are PREPENDED
/// so their matchers/gates get first refusal; AgentMux's own entries
/// always stay last. A non-array value is warned and dropped rather
/// than silently discarded — same discipline as every other branch in
/// this function (reagent P1 on PR #813).
fn prepend_user_hook_array(
    hooks_obj: &mut serde_json::Map<String, Value>,
    key: &str,
    user_value: Value,
) {
    match user_value {
        Value::Array(mut user_arr) => {
            if let Some(Value::Array(ours)) = hooks_obj.remove(key) {
                user_arr.extend(ours);
            }
            hooks_obj.insert(key.to_string(), Value::Array(user_arr));
        }
        _ => {
            tracing::warn!(
                "agent_config: user settings.hooks.{key} is not an array; dropped"
            );
        }
    }
}

/// The `SessionStart` hook entry: one `agentmux-bashwrap sessionstart --part N`
/// command per memory part, `N` = 1..=`HOOK_PARTS`
/// (`backend::memory_delivery`). The commands run in parallel, and each
/// prints its own part (or nothing).
fn agentmux_sessionstart_entry() -> serde_json::Value {
    let commands: Vec<serde_json::Value> = (1..=crate::backend::memory_delivery::HOOK_PARTS)
        .map(|n| json!({ "type": "command", "command": format!("agentmux-bashwrap sessionstart --part {n}") }))
        .collect();
    json!({ "hooks": commands })
}

/// Build `.claude/settings.json` content with the auto-injected
/// PreToolUse Bash hook and PreCompact hooks (under the `"hooks"`
/// key). PreToolUse redirects Bash invocations into the streaming
/// wrapper (`agentmux-bashwrap exec`); PreCompact (two entries,
/// matcher `"manual"` / `"auto"`) pings the sidecar the instant
/// compaction starts (`agentmux-bashwrap precompact`) — see
/// `docs/specs/SPEC_COMPACTION_DETECTION_AND_HANDLING_2026_07_31.md`
/// §4.2. User-supplied settings.json (from the agent's
/// `content_map["settings"]`) is parsed and merged at the top level;
/// user-supplied legacy hooks content (from `content_map["hooks"]`)
/// is merged into `settings.hooks`.
///
/// **File location matters.** Claude Code reads project hooks from
/// `<project>/.claude/settings.json` under the `"hooks"` key.
/// A standalone `.claude/hooks.json` is NOT a Claude Code
/// discovery location — that was the v0.33.804 streaming-bug root
/// cause: the file was written but Claude never read it, so the
/// PreToolUse hook never fired and live streaming silently failed.
///
/// See `docs/specs/SPEC_STREAMING_BASH_RUNNER_2026_05_11.md` §5
/// and Claude Code docs: https://code.claude.com/docs/en/hooks.md
pub fn build_settings_with_hooks(
    user_settings_content: Option<&str>,
    user_hooks_content: Option<&str>,
) -> Option<String> {
    use serde_json::Value;
    let agentmux_pretooluse = json!({
        "matcher": "^(Bash|.*[Bb]ash.*)$",
        "hooks": [
            {
                "type": "command",
                "command": "agentmux-bashwrap hook"
            }
        ]
    });
    // `PreCompact` requires an explicit `matcher` (`"manual"` or
    // `"auto"`) — Claude Code has no confirmed wildcard-all value for
    // this hook — so two separate entries are registered, each with a
    // different static `--trigger=` argv baked in so the binary knows
    // which fired without needing it from stdin (PreCompact's stdin
    // payload carries no `trigger` field; see `precompact.rs`). See
    // `docs/specs/SPEC_COMPACTION_DETECTION_AND_HANDLING_2026_07_31.md`
    // §4.2.
    let agentmux_precompact_manual = json!({
        "matcher": "manual",
        "hooks": [
            {
                "type": "command",
                "command": "agentmux-bashwrap precompact --trigger=manual"
            }
        ]
    });
    let agentmux_precompact_auto = json!({
        "matcher": "auto",
        "hooks": [
            {
                "type": "command",
                "command": "agentmux-bashwrap precompact --trigger=auto"
            }
        ]
    });
    // `SessionStart`: one command per memory part, so the agent's memory
    // reaches the model at every new session, `/clear` and compaction
    // without a visible turn — see
    // docs/specs/SPEC_GLOBAL_MEMORY_DELIVERY_2026_09_27.md §7 P2. The CLI
    // delivers about 10,000 characters of `additionalContext` per hook
    // command, so the memory is split into parts and each command asks the
    // sidecar for its own. No matcher: the sidecar itself answers "nothing"
    // for `resume` and `fork` (the conversation is intact, D10).
    let agentmux_sessionstart = agentmux_sessionstart_entry();
    let mut hooks_obj = serde_json::Map::new();
    let mut pretooluse_entries: Vec<Value> = Vec::new();
    let mut precompact_entries: Vec<Value> = Vec::new();
    let mut sessionstart_entries: Vec<Value> = Vec::new();

    // Start with user hooks if present + parseable. Parse failures or
    // non-Object top-levels are logged at WARN so the diagnostic trail
    // surfaces — silent swallowing made user hooks disappear with no
    // signal (reagent P2 on PR #809).
    if let Some(raw) = user_hooks_content {
        match serde_json::from_str::<Value>(raw) {
            Ok(Value::Object(user_obj)) => {
                for (k, v) in user_obj {
                    if k == "PreToolUse" {
                        if let Value::Array(arr) = v {
                            pretooluse_entries.extend(arr);
                        } else {
                            tracing::warn!(
                                "agent_config: user hooks.PreToolUse is not an array; dropped"
                            );
                        }
                    } else if k == "PreCompact" {
                        if let Value::Array(arr) = v {
                            precompact_entries.extend(arr);
                        } else {
                            tracing::warn!(
                                "agent_config: user hooks.PreCompact is not an array; dropped"
                            );
                        }
                    } else if k == "SessionStart" {
                        if let Value::Array(arr) = v {
                            sessionstart_entries.extend(arr);
                        } else {
                            tracing::warn!(
                                "agent_config: user hooks.SessionStart is not an array; dropped"
                            );
                        }
                    } else {
                        hooks_obj.insert(k, v);
                    }
                }
            }
            Ok(other) => {
                tracing::warn!(
                    kind = ?other,
                    "agent_config: user hooks top-level value is not an object; dropped"
                );
            }
            Err(e) => {
                tracing::warn!(
                    error = %e,
                    "agent_config: failed to parse user hooks JSON; dropped"
                );
            }
        }
    }
    // Append our entries last so user matchers (deny rules etc.) get a chance
    // to short-circuit before our rewrite / observation hooks. PreCompact
    // gets both matcher entries, in matcher order (manual, then auto).
    pretooluse_entries.push(agentmux_pretooluse);
    hooks_obj.insert("PreToolUse".to_string(), Value::Array(pretooluse_entries));
    precompact_entries.push(agentmux_precompact_manual);
    precompact_entries.push(agentmux_precompact_auto);
    hooks_obj.insert("PreCompact".to_string(), Value::Array(precompact_entries));
    sessionstart_entries.push(agentmux_sessionstart);
    hooks_obj.insert("SessionStart".to_string(), Value::Array(sessionstart_entries));

    // Build the settings.json object: start from user-supplied settings.json
    // (if any), then overlay our hooks key. User keys other than `hooks`
    // pass through unchanged.
    let mut settings_obj = serde_json::Map::new();
    if let Some(raw) = user_settings_content {
        match serde_json::from_str::<Value>(raw) {
            Ok(Value::Object(user_obj)) => {
                for (k, v) in user_obj {
                    settings_obj.insert(k, v);
                }
            }
            Ok(_other) => {
                tracing::warn!(
                    "agent_config: user settings.json top-level is not an object; dropped"
                );
            }
            Err(e) => {
                tracing::warn!(
                    error = %e,
                    "agent_config: failed to parse user settings.json; dropped"
                );
            }
        }
    }
    // Merge: any existing hooks key from user settings is merged with our
    // additions. For PreToolUse and PreCompact specifically, user matchers
    // from settings.json are PREPENDED (not dropped) so they short-circuit
    // before our auto-injected entries — same ordering rule we apply to
    // legacy content_map["hooks"] entries for these two keys. For other
    // event types (PostToolUse, Stop, etc.) we keep user's entries
    // verbatim. Reagent P1 on PR #813 (the `continue` was a silent drop —
    // caught a real merge bug); PreCompact is deliberately folded into the
    // same array-merge discipline rather than the generic `or_insert`
    // below, or a user-supplied PreCompact entry would hit that path and
    // be silently and permanently dropped the moment PreCompact became
    // auto-injected too — the exact bug class this file already guards
    // PreToolUse against. See
    // `docs/specs/SPEC_COMPACTION_DETECTION_AND_HANDLING_2026_07_31.md`
    // §4.2. SessionStart joins them for the same reason now that it is
    // auto-injected too (SPEC_GLOBAL_MEMORY_DELIVERY_2026_09_27.md §7 P2).
    if let Some(Value::Object(existing_hooks)) = settings_obj.get("hooks").cloned() {
        for (k, v) in existing_hooks {
            if k == "PreToolUse" || k == "PreCompact" || k == "SessionStart" {
                prepend_user_hook_array(&mut hooks_obj, &k, v);
                continue;
            }
            hooks_obj.entry(k).or_insert(v);
        }
    }
    settings_obj.insert("hooks".to_string(), Value::Object(hooks_obj));

    // Claude Code requires the bashwrap exec command (produced by the hook rewrite)
    // to be in permissions.allow — otherwise it raises a permissions error and the
    // agent cannot run any bash commands. Merge with any user-supplied allow list
    // rather than overwriting it.
    {
        // Space before * enforces a command-name boundary: matches
        // "agentmux-bashwrap <args>" only, not other executables that
        // happen to share the prefix (e.g. agentmux-bashwrapXYZ).
        let bashwrap_allow = Value::String("Bash(agentmux-bashwrap *)".to_string());
        let mut allow_arr = match settings_obj.get("permissions") {
            Some(Value::Object(perms)) => match perms.get("allow") {
                Some(Value::Array(arr)) => arr.clone(),
                _ => Vec::new(),
            },
            _ => Vec::new(),
        };
        if !allow_arr.iter().any(|v| v == &bashwrap_allow) {
            allow_arr.push(bashwrap_allow);
        }
        let mut perms_obj = match settings_obj.remove("permissions") {
            Some(Value::Object(obj)) => obj,
            _ => serde_json::Map::new(),
        };
        perms_obj.insert("allow".to_string(), Value::Array(allow_arr));
        settings_obj.insert("permissions".to_string(), Value::Object(perms_obj));
    }

    // No AI attribution in commits or PR descriptions: the repos' checks
    // (`.github/workflows/no-coauthor-trailers.yml`) reject Co-Authored-By
    // trailers and "Generated with" lines, and Claude Code adds both by
    // default. An empty string hides each. An agent's own string `commit` or
    // `pr` wins; a field it leaves out or sets to a non-string is replaced
    // with "", and so is a non-object `attribution`, because Claude Code falls
    // back to its default attribution for any of those.
    let attribution = settings_obj.entry("attribution").or_insert_with(|| json!({}));
    if !attribution.is_object() {
        *attribution = json!({});
    }
    if let Value::Object(fields) = attribution {
        for field in ["commit", "pr"] {
            let value = fields.entry(field).or_insert_with(|| Value::String(String::new()));
            if !value.is_string() {
                *value = Value::String(String::new());
            }
        }
    }

    match serde_json::to_string_pretty(&Value::Object(settings_obj)) {
        Ok(s) => Some(s),
        Err(e) => {
            tracing::error!("agent_config: failed to serialize settings.json: {e}");
            None
        }
    }
}

/// Replace `{{VARIABLE}}` placeholders in `content` with values from `vars`.
///
/// Placeholders that have no corresponding key in `vars` are left unchanged
/// (the original `{{VARIABLE}}` text is preserved).
///
/// Mirrors `expandTemplate()` in `frontend/app/view/agent/agent-model.ts`.
pub fn expand_template(content: &str, vars: &HashMap<String, String>) -> String {
    // Hand-rolled replacement to avoid pulling in a regex dependency.
    // Scans for `{{`, extracts the key name up to `}}`, and substitutes.
    let mut result = String::with_capacity(content.len());
    let bytes = content.as_bytes();
    let len = bytes.len();
    let mut i = 0;

    while i < len {
        // Look for '{{'
        if i + 1 < len && bytes[i] == b'{' && bytes[i + 1] == b'{' {
            // Find closing '}}'
            if let Some(rel) = content[i + 2..].find("}}") {
                let key = &content[i + 2..i + 2 + rel];
                // Only substitute if key is a simple word (alphanumeric + underscore)
                if key.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_') {
                    if let Some(val) = vars.get(key) {
                        result.push_str(val);
                    } else {
                        // No match — preserve the original placeholder
                        result.push_str(&content[i..i + 2 + rel + 2]);
                    }
                    i += 2 + rel + 2; // skip past '}}'
                    continue;
                }
            }
        }
        // Not a placeholder start — copy character verbatim
        // Safety: i is always on a valid char boundary because we only advance
        // by 1 when not inside a placeholder, and UTF-8 single-byte characters
        // are the only ones we index directly.
        let ch = content[i..].chars().next().unwrap();
        result.push(ch);
        i += ch.len_utf8();
    }

    result
}

/// Agent Skills spec caps `description` at 1024 characters.
const SKILL_DESCRIPTION_MAX_LEN: usize = 1024;

/// Truncate `s` to at most `max_units` UTF-16 code units, on a UTF-8 char
/// boundary. Mirrors JS `.slice(0, n)` semantics (JS strings are indexed in
/// UTF-16 code units, so a Rust byte-length cap diverges from the TS mirror
/// for any non-ASCII text — reagent P2, PR #2322).
fn truncate_utf16_units(s: &str, max_units: usize) -> String {
    let mut units = 0usize;
    for (byte_idx, ch) in s.char_indices() {
        units += ch.len_utf16();
        if units > max_units {
            return s[..byte_idx].to_string();
        }
    }
    s.to_string()
}

/// Render an Agent Skills-format `SKILL.md`: YAML frontmatter with the two
/// required fields (`name`, `description` — per the spec's six-field
/// frontmatter; AgentMux doesn't populate the four optional ones today:
/// `license`, `compatibility`, `metadata`, `allowed-tools`), followed by the
/// skill's content as the Markdown body. See https://agentskills.io/specification.
///
/// `slug` (not the skill's raw display name) is REQUIRED here — the spec
/// requires `name` be lowercase/hyphenated and match its parent directory;
/// callers must pass the same value used to build the `.claude/skills/<slug>/`
/// path (reagent P1, PR #2322). `description` is validated: the spec requires
/// a non-empty value (falls back to a placeholder) capped at 1024 **UTF-16
/// code units** — matching the TS mirror's `.slice(0, 1024)` (JS string
/// indexing is UTF-16-code-unit based), since the UI permits arbitrary-length
/// free text with no spec-awareness and non-ASCII descriptions previously
/// truncated to different byte vs. UTF-16 lengths between the two paths
/// (reagent P2, PR #2322).
///
/// YAML double-quoted scalars use JSON-compatible escaping (YAML 1.2
/// §7.3.1), so `serde_json::to_string` on a plain string produces a valid,
/// correctly-escaped YAML value — this avoids hand-rolling YAML escaping or
/// adding a yaml crate dependency (this workspace has neither today) just
/// for two scalar fields.
pub(crate) fn render_skill_md(slug: &str, description: &str, body: &str) -> String {
    let owned_description;
    let description = if description.trim().is_empty() {
        "No description provided."
    } else {
        owned_description = truncate_utf16_units(description, SKILL_DESCRIPTION_MAX_LEN);
        owned_description.as_str()
    };
    let name_yaml =
        serde_json::to_string(slug).expect("string serialization is infallible");
    let description_yaml =
        serde_json::to_string(description).expect("string serialization is infallible");
    format!("---\nname: {name_yaml}\ndescription: {description_yaml}\n---\n\n{body}")
}

/// For each skill, whether `build_config_files` leaves it a file of its own
/// that Claude Code lists natively: an Agent Skill's `SKILL.md` (slugs are
/// made unique), or a command with a usable trigger that no later skill's
/// command overwrites. Triggers are compared case-insensitively, as a
/// case-insensitive filesystem would. Trigger uniqueness isn't enforced by
/// the skill store (Codex on #4131). A non-ASCII trigger never counts as
/// owning its file: a normalization-insensitive filesystem (macOS) folds
/// Unicode-equivalent names together, and keeping such a skill in the index
/// costs at most a repeated line, never a lost skill.
fn skills_with_their_own_file(skills: &[AgentSkill]) -> Vec<bool> {
    let command_key = |s: &AgentSkill| {
        (!s.content.is_empty() && s.skill_type != SKILL_TYPE_AGENT_SKILL)
            .then(|| sanitize_trigger(&s.trigger).filter(|t| t.is_ascii()).map(str::to_lowercase))
            .flatten()
    };
    let mut last_writer: HashMap<String, usize> = HashMap::new();
    for (i, s) in skills.iter().enumerate() {
        if let Some(key) = command_key(s) {
            last_writer.insert(key, i);
        }
    }
    skills
        .iter()
        .enumerate()
        .map(|(i, s)| {
            // A non-ASCII trigger maps to no key: it never owns a file here,
            // and doesn't count as overwriting anyone (it may, harmlessly).
            !s.content.is_empty()
                && (s.skill_type == SKILL_TYPE_AGENT_SKILL || command_key(s).is_some_and(|k| last_writer.get(&k) == Some(&i)))
        })
        .collect()
}

/// Validate a skill's `trigger` is safe to use as a single path segment in
/// `.claude/commands/<trigger>.md`. `trigger` is free-form user input with
/// no format validation anywhere upstream (the skill create/update RPCs and
/// the frontend form all accept it as-is), so a trigger containing a path
/// separator or a `..` segment previously let the resulting filename
/// resolve OUTSIDE the agent's working directory -- both for this write and,
/// once stale-file cleanup existed, for the corresponding delete (reagent
/// P1, PR #2322). Rejects (returns `None`) anything containing `/` or `\`,
/// or that is exactly `.`/`..`; callers skip writing that skill's command
/// file entirely rather than silently rewriting the trigger into something
/// the user didn't ask for.
fn sanitize_trigger(trigger: &str) -> Option<&str> {
    if trigger.is_empty() || trigger == "." || trigger == ".." {
        return None;
    }
    if trigger.contains('/') || trigger.contains('\\') {
        return None;
    }
    Some(trigger)
}

/// Derive a slug for an Agent Skill name that is valid per the Agent Skills
/// `name` grammar: lowercase letters, digits, and hyphens ONLY (no
/// underscores). `derive_slug` is shared with agent role-slugs, which
/// deliberately DO permit underscores, so it isn't spec-valid here as-is —
/// hyphenate underscores (and re-collapse any resulting run of hyphens)
/// rather than reusing it directly (Codex P1, PR #2322).
fn skill_name_slug(name: &str) -> String {
    let base = derive_slug(name).replace('_', "-");
    let collapsed: String = base
        .split('-')
        .filter(|s| !s.is_empty())
        .collect::<Vec<_>>()
        .join("-");
    if collapsed.is_empty() {
        "skill".to_string()
    } else {
        collapsed
    }
}

/// Derive a filesystem-safe, COLLISION-FREE, spec-valid slug for an Agent
/// Skill name within one caller-scoped `used` set. `skill_name_slug` alone
/// can produce identical output for distinct names that differ only in
/// punctuation/whitespace (e.g. "Deploy Checklist" and "Deploy!!!Checklist"
/// both -> "deploy-checklist"), which would otherwise silently overwrite one
/// skill's `SKILL.md` with another's on disk (reagent P1, PR #2322). Appends
/// `-2`, `-3`, ... until the slug is unique within `used`, truncating the
/// base first so the suffixed result never exceeds the spec's 64-character
/// max (Codex P2, PR #2322 — a 64-char base plus `-2` was previously 66
/// chars).
pub(crate) fn unique_skill_slug(name: &str, used: &mut HashSet<String>) -> String {
    const MAX_LEN: usize = 64;
    let base = skill_name_slug(name);
    if used.insert(base.clone()) {
        return base;
    }
    let mut n: u32 = 2;
    loop {
        let suffix = format!("-{n}");
        let max_base_len = MAX_LEN.saturating_sub(suffix.len());
        let mut truncated_base = base.clone();
        if truncated_base.len() > max_base_len {
            let mut end = max_base_len;
            while end > 0 && !truncated_base.is_char_boundary(end) {
                end -= 1;
            }
            truncated_base.truncate(end);
        }
        let candidate = format!("{truncated_base}{suffix}");
        if used.insert(candidate.clone()) {
            return candidate;
        }
        n += 1;
    }
}

// ============================================================
// Managed skill files manifest (I/O — see module doc comment)
// ============================================================

/// Hidden manifest (relative to the agent working directory) tracking which
/// skill-derived paths (`.claude/commands/*.md`, `.claude/skills/*/SKILL.md`)
/// AgentMux itself wrote on the last materialization, so a subsequent one
/// can delete ones that are no longer current without touching any
/// user-authored `.claude/commands`/`.claude/skills` content.
pub const MANAGED_SKILL_FILES_MANIFEST: &str = ".claude/.agentmux-managed-skill-files.json";

/// Compute the subset of `filenames` that are skill-derived managed paths
/// (the ones tracked in [`MANAGED_SKILL_FILES_MANIFEST`]) — everything else
/// (`CLAUDE.md`, `.mcp.json`, `.claude/settings.json`, ...) is always fully
/// regenerated at a fixed path every launch, so it has no staleness problem
/// to track.
pub fn managed_skill_file_paths<'a>(
    filenames: impl Iterator<Item = &'a str>,
) -> std::collections::BTreeSet<String> {
    filenames
        .filter(|f| f.starts_with(".claude/commands/") || f.starts_with(".claude/skills/"))
        .map(|f| f.to_string())
        .collect()
}

/// Delete skill-derived files a PREVIOUS materialization wrote (per the
/// on-disk manifest) but that are no longer part of `new_managed_paths` --
/// e.g. a skill's format switched between `"prompt"`/`"agent-skill"`, or it
/// was renamed/removed. Without this, the stale file stays on disk and
/// Claude keeps treating it as active alongside the newly selected format
/// (reagent P1 + Codex P1/P2, PR #2322).
///
/// MUST be called before writing the new files (so a deletion never races a
/// write to the same path); callers must call
/// [`write_managed_skill_file_manifest`] after writing to record the new
/// set for the next materialization. Best-effort: any individual read/parse
/// failure is treated as "no prior manifest" (nothing to clean up yet)
/// rather than propagated, since a missing/corrupt manifest must never
/// block the write that follows.
///
/// Every path is resolved through [`crate::backend::base::safe_join_within_base`]
/// before deletion — defense in depth against a manifest path that somehow
/// escapes the working directory (e.g. a future bypass of trigger
/// sanitization upstream, or manual tampering with the manifest file
/// itself); such a path is skipped with a warning, never followed.
pub fn cleanup_stale_managed_skill_files(
    base_path: &std::path::Path,
    new_managed_paths: &std::collections::BTreeSet<String>,
) {
    let manifest_path = base_path.join(MANAGED_SKILL_FILES_MANIFEST);
    let Ok(raw) = std::fs::read_to_string(&manifest_path) else {
        return;
    };
    let Ok(old_paths) = serde_json::from_str::<Vec<String>>(&raw) else {
        return;
    };
    let Ok(wd) = crate::backend::workdir_fs::Workdir::open(base_path) else {
        return;
    };
    for old in &old_paths {
        if new_managed_paths.contains(old) {
            continue;
        }
        // Through the workdir: a manifest path outside it, or under a
        // `.claude` that links out of it, is refused, never deleted.
        match wd.remove_file(old) {
            Err(e) if e.kind() == std::io::ErrorKind::PermissionDenied => {
                tracing::warn!(
                    work_dir = %base_path.display(),
                    path = %old,
                    error = %e,
                    "cleanup_stale_managed_skill_files: refusing to delete a manifest path outside the working directory"
                );
                continue;
            }
            _ => {}
        }
        // Agent Skills format nests under .claude/skills/<slug>/ -- clean up
        // the now-empty slug directory too (no-op/fails silently if
        // anything else still lives there, e.g. a future scripts/ dir).
        if let Some(parent) = std::path::Path::new(old).parent().and_then(|p| p.to_str()).filter(|p| !p.is_empty()) {
            let _ = wd.remove_dir(parent);
        }
    }
}

/// Record `new_managed_paths` as the manifest for the NEXT call to
/// [`cleanup_stale_managed_skill_files`]. Best-effort: a write failure is
/// logged, not propagated — losing this write only means the next
/// materialization's stale-file cleanup is skipped once, not a correctness
/// issue for the current one.
pub fn write_managed_skill_file_manifest(
    base_path: &std::path::Path,
    new_managed_paths: &std::collections::BTreeSet<String>,
) {
    if let Ok(manifest_json) = serde_json::to_string(new_managed_paths) {
        let written = crate::backend::workdir_fs::Workdir::open(base_path)
            .and_then(|wd| wd.write(MANAGED_SKILL_FILES_MANIFEST, manifest_json.as_bytes(), false));
        if let Err(e) = written {
            tracing::warn!(
                work_dir = %base_path.display(),
                error = %e,
                "write_managed_skill_file_manifest: failed to write manifest; \
                 stale file cleanup may be skipped on the next materialization"
            );
        }
    }
}

// ============================================================
// CLAUDE.md ownership protection (I/O — see module doc comment)
// ============================================================

/// First line AgentMux writes on any `CLAUDE.md` it fully owns (freshly
/// created, or regenerated on every launch since). Its ABSENCE on an
/// EXISTING file is what marks that file as foreign — predates AgentMux
/// touching this working directory, or a human replaced AgentMux's file
/// with their own — and is never overwritten again. See
/// `docs/specs/SPEC_CLAUDE_MD_OWNERSHIP_PROTECTION_2026_08_22.md`.
pub const CLAUDE_MD_MANAGED_MARKER: &str = "<!-- agentmux:managed-claude-md -->";

/// AgentMux-owned side file carrying the full Soul+AgentMD+Bundle+Skills
/// composition when the real `CLAUDE.md` is foreign — always safe to
/// regenerate in place every launch, unlike `CLAUDE.md` itself in that case.
pub const AGENTMUX_MEMORY_FILENAME: &str = ".claude/AGENTMUX_MEMORY.md";

/// Heading of the bundle-content section in a generated `CLAUDE.md`.
///
/// Persisted format marker, NOT an internal identifier: the frontend builder
/// (`frontend/app/view/agent/agent-config-builder.ts`) emits the same literal,
/// and `editor_handlers::inject_global_bundles` searches for it to prepend the
/// global block ahead of per-agent content. All three must agree, so the string
/// stays `# Memory` until the frontend heading changes in the same release
/// (SPEC_ARMORY_NAMING_CONSOLIDATION_2026_09_09.md §4 do-not-rename list).
pub const BUNDLE_SECTION_HEADING: &str = "# Memory";

/// One-time marker recording whether the `@import` line (below) has
/// already been offered for this working directory. Checked INSTEAD of
/// re-scanning `CLAUDE.md` content on every launch — without it, a user
/// who deliberately deletes the import line (opting out of AgentMux
/// content entirely) would see it silently reappear on their next launch.
const CLAUDE_MD_OWNERSHIP_MARKER_PATH: &str = ".claude/.agentmux-claude-md-ownership.json";

/// Where an adopted legacy `CLAUDE.md` is kept (`is_legacy_agentmux_claude_md`).
pub const CLAUDE_MD_PRE_ADOPT_BACKUP: &str = ".claude/CLAUDE.md.pre-adopt";

/// A skills-index row exactly as `build_config_files` renders it:
/// `- **<name>**`, then optionally ` (trigger: /<trigger>)`, then optionally
/// ` — <description>` (Codex on #4131: a bare `- **note` is a person's).
fn is_generated_skill_row(line: &str) -> bool {
    let Some(rest) = line.strip_prefix("- **") else { return false };
    let Some(close) = rest.find("**") else { return false };
    if close == 0 {
        return false;
    }
    let mut rest = &rest[close + 2..];
    if let Some(after) = rest.strip_prefix(" (trigger: /") {
        let Some(end) = after.find(')') else { return false };
        if end == 0 {
            return false;
        }
        rest = &after[end + 1..];
    }
    rest.is_empty() || rest.strip_prefix(" \u{2014} ").is_some_and(|d| !d.is_empty())
}


/// Whether `content` is exactly what an older AgentMux wrote as `CLAUDE.md`,
/// in its order, ignoring blank lines: the `# Available Skills` heading, its
/// usage line, at least one skill row (`- **…`; AgentMux wrote the section
/// only when there were skills), then optionally the managed import (its
/// comment and line, or the line alone). Anything else means a person wrote
/// there, and it stays theirs.
pub fn is_legacy_agentmux_claude_md(content: &str) -> bool {
    let import_line = format!("@{AGENTMUX_MEMORY_FILENAME}");
    let mut lines = content.lines().map(str::trim_end).filter(|l| !l.trim().is_empty()).peekable();
    if lines.next() != Some("# Available Skills") || lines.next() != Some("Use `/<trigger>` to invoke a skill.") {
        return false;
    }
    let mut skill_rows = 0;
    while lines.next_if(|l| is_generated_skill_row(l)).is_some() {
        skill_rows += 1;
    }
    let tail: Vec<&str> = lines.collect();
    skill_rows > 0
        && (tail.is_empty()
            || tail == [import_line.as_str()]
            || tail == [CLAUDE_MD_IMPORT_MARKER_COMMENT, import_line.as_str()])
}

/// Comment wrapping the `@import` line so its origin — and how to remove
/// it — is unambiguous to anyone reading a foreign `CLAUDE.md` by hand.
const CLAUDE_MD_IMPORT_MARKER_COMMENT: &str =
    "<!-- agentmux:managed-import (safe to delete this line to opt out) -->";

#[derive(serde::Serialize, serde::Deserialize, Default)]
struct ClaudeMdOwnershipMarker {
    import_line_offered: bool,
}

/// Materialize `generated_content` (the composed Soul+AgentMD+Bundle+Skills
/// `CLAUDE.md` body `build_config_files` already produced) against whatever
/// is already on disk at `base_path/CLAUDE.md`, WITHOUT ever overwriting a
/// foreign file's content:
///
/// - No file yet, or the existing file starts with
///   [`CLAUDE_MD_MANAGED_MARKER`]: AgentMux owns it — write `CLAUDE.md`
///   directly (marker + `generated_content`), exactly as every call site
///   did unconditionally before this function existed. **This is the one
///   path that still hard-fails on an I/O error** (propagated via `?`,
///   same as every call site's pre-existing behavior) — AgentMux's own
///   config file failing to write is a real launch-blocking problem.
/// - Existing file present WITHOUT the marker, **or present but
///   unreadable** (permission denied, non-UTF-8 content, transient I/O
///   error — a `read_to_string` error here must never collapse into "no
///   file yet," or an unreadable foreign file gets silently clobbered,
///   defeating this whole function's purpose; reagent P0 + codex P1 on
///   PR #2747): treated identically as foreign. `CLAUDE.md` itself is
///   never written to again. `generated_content` instead goes to
///   [`AGENTMUX_MEMORY_FILENAME`] (always safe to regenerate — it's 100%
///   AgentMux's own content), pulled in via a single `@import` line
///   appended to the real `CLAUDE.md` — offered at most once per working
///   directory (see [`CLAUDE_MD_OWNERSHIP_MARKER_PATH`]'s doc comment).
///   If the file is unreadable specifically, the `@import` offer is
///   skipped for this launch (nothing to safely append to/check
///   idempotency against) — retried on the next launch.
///
/// Everything in the foreign-file branch is best-effort, in the same
/// spirit as [`write_managed_skill_file_manifest`] and unlike the
/// AgentMux-owned branch above: an I/O failure writing the side file,
/// appending the import line, or writing the ownership marker is logged
/// and this function still returns `Ok(())` — losing one of these only
/// means the import line isn't offered (or the side file isn't
/// refreshed) on this one launch, not a correctness issue serious enough
/// to fail the whole agent launch (codex P1 on PR #2747: the original
/// version used `?` throughout this branch, contradicting this doc
/// comment and propagating a side-file write failure into a hard launch
/// failure).
///
/// The `@import` append is a true O_APPEND write
/// (`OpenOptions::append(true)`), never a read-modify-write of the whole
/// file — if the foreign file changes between this function's read and
/// the append (edited by the user or another process mid-launch), a
/// full-file rewrite would silently discard that intervening edit; a
/// true append can only ever add bytes at whatever the end happens to be
/// (codex P2 on PR #2747).
///
/// Every new path this function writes ([`AGENTMUX_MEMORY_FILENAME`],
/// [`CLAUDE_MD_OWNERSHIP_MARKER_PATH`]) is resolved through
/// [`crate::backend::base::safe_join_within_base`] and verified against
/// [`crate::backend::base::verify_no_symlink_escape`] before any write —
/// both constants are fixed, not user-controllable, but `.claude/` itself
/// could exist as a symlink escaping the working directory, and without
/// this check a write would silently follow it outside the selected
/// project (codex P1 on PR #2747, same defense-in-depth the other
/// config-file write loops already apply to their own paths).
///
/// First line AgentMux writes on any non-`CLAUDE.md` startup-instructions
/// file it fully owns (freshly created, or one it wrote on a prior
/// launch) — mirrors [`CLAUDE_MD_MANAGED_MARKER`]'s role for `CLAUDE.md`,
/// generic across filenames since `AGENTS.md`/`GEMINI.md`/`QWEN.md`/pi's
/// `APPEND_SYSTEM.md` don't each need distinct marker text. An HTML
/// comment renders invisibly in every markdown viewer and every one of
/// these providers reads its instructions file as plain text fed into a
/// prompt, so a leading comment line is universally harmless regardless
/// of provider — no per-provider syntax needed for the marker itself
/// (only the `@import`-equivalent side-file fallback CLAUDE.md also gets
/// would need that, and this function deliberately doesn't attempt it —
/// see the doc comment below).
const STARTUP_INSTRUCTIONS_MANAGED_MARKER: &str = "<!-- agentmux:managed-startup-instructions -->";

/// Does this file's content say AgentMux wrote it?
///
/// There are two markers, not one: `CLAUDE.md` carries
/// [`CLAUDE_MD_MANAGED_MARKER`] and every other startup-instructions file
/// carries [`STARTUP_INSTRUCTIONS_MANAGED_MARKER`], because the two writers
/// grew separately. Anything asking "is this ours" has to know both — a check
/// against only the first reports every AgentMux-generated `AGENTS.md`,
/// `GEMINI.md`, `QWEN.md` and `.pi/APPEND_SYSTEM.md` as foreign, inverting the
/// answer for most providers (Codex, PR #3144).
///
/// Deliberately content-based rather than path-based: the marker is what makes
/// the claim, and a file's name says nothing about who wrote it. Phase 3 of
/// `SPEC_INSTRUCTION_AND_MEMORY_PORTABILITY_2026_09_09.md` reuses this to
/// label tracked instruction files `agentmux` or `foreign`, which is the one
/// field that decides whether a file is ours to touch.
///
/// **The two writers below deliberately do NOT use this**, and that is not an
/// oversight. Each asks a narrower question — "did I write this file, in my
/// own format, such that I may rewrite it" — and each answer must stay pinned
/// to its own marker. A `CLAUDE.md`-marked file is ours, but it is not
/// `write_startup_instructions_respecting_existing`'s to rewrite. This helper
/// answers the broader question, which is the one a read-only tracker asks.
pub fn is_agentmux_managed_instructions(content: &str) -> bool {
    content.starts_with(CLAUDE_MD_MANAGED_MARKER)
        || content.starts_with(STARTUP_INSTRUCTIONS_MANAGED_MARKER)
}

/// Write a NON-`CLAUDE.md` startup-instructions file (`AGENTS.md`,
/// `GEMINI.md`, `QWEN.md`, `.pi/APPEND_SYSTEM.md`, ...) WITHOUT ever
/// overwriting a pre-existing, non-AgentMux-authored file at that path.
///
/// codex P1, PR #2788: before
/// `docs/specs/SPEC_PROVIDER_AWARE_STARTUP_INSTRUCTIONS_2026_08_24.md`,
/// every provider's agent got `CLAUDE.md` written regardless of provider —
/// wrong, but harmless to a real Codex/Gemini/etc. project, since AgentMux
/// was never writing to the filename that project's own real `AGENTS.md`/
/// `GEMINI.md` actually lived at. Once `build_config_files` started
/// resolving the CORRECT native filename per provider, an unconditional
/// write (the plain `std::fs::write` every other config file still uses)
/// would silently destroy a pre-existing, user-authored project file the
/// moment its name collided with the now-correctly-resolved target — a
/// real, novel data-loss regression introduced BY fixing the filename,
/// not present before.
///
/// Mirrors [`write_claude_md_respecting_ownership`]'s OWNED-vs-foreign
/// marker check (freely regenerate if AgentMux wrote it, either freshly or
/// on a prior launch; never touch it otherwise) — WITHOUT that function's
/// `@import`-line side-file fallback offer for the foreign case. That
/// fuller mechanism is deliberately Claude-Code-`@import`-syntax-specific;
/// whether `AGENTS.md`/`GEMINI.md`/`QWEN.md`/pi's `APPEND_SYSTEM.md`
/// support an equivalent include directive their own harness actually
/// honors is unverified per-provider research this spec didn't do (§5/§6
/// of the spec above). The tradeoff accepted here: if the target file is
/// foreign, this agent's Soul/AgentMD/Bundle content is simply not
/// delivered via a file for this launch (logged, not silently dropped) —
/// a real capability gap, but strictly safer than overwriting a stranger's
/// file. Revisit once each provider's own include syntax is confirmed.
pub fn write_startup_instructions_respecting_existing(
    base_path: &std::path::Path,
    filename: &str,
    content: &str,
) -> std::io::Result<()> {
    let path = base_path.join(filename);

    // `None` = genuinely no file yet. `Some(Ok(content))` = read fine.
    // `Some(Err(_))` = exists but unreadable — MUST be treated the same as
    // "foreign," never as "no file yet" (same reasoning as
    // write_claude_md_respecting_ownership's own doc comment).
    let existing = match std::fs::read_to_string(&path) {
        Ok(content) => Some(Ok(content)),
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => None,
        Err(e) => Some(Err(e)),
    };
    let agentmux_owns_it =
        matches!(&existing, Some(Ok(content)) if content.starts_with(STARTUP_INSTRUCTIONS_MANAGED_MARKER));

    if agentmux_owns_it || existing.is_none() {
        let marked_content = format!("{STARTUP_INSTRUCTIONS_MANAGED_MARKER}\n\n{content}");
        // Through the workdir: never written through a symlink (dangling or
        // not), nor under a folder that links out of it (`.pi/` for pi).
        // A refusal leaves the file alone, like a foreign one.
        let written = crate::backend::workdir_fs::Workdir::open(base_path)
            .and_then(|wd| wd.write(filename, marked_content.as_bytes(), false));
        return match written {
            Err(e) if e.kind() == std::io::ErrorKind::PermissionDenied => {
                tracing::warn!(path = %path.display(), error = %e, "write_startup_instructions_respecting_existing: not writing");
                Ok(())
            }
            other => other,
        };
    }

    tracing::warn!(
        path = %path.display(),
        "write_startup_instructions_respecting_existing: pre-existing, \
         non-AgentMux-authored file — leaving it untouched; this agent's \
         Global Bundle/Soul/AgentMD content is not delivered via this file \
         for this launch"
    );
    Ok(())
}

/// Names of the `mcpServers` entries AgentMux wrote into a working
/// directory's `.mcp.json` on the last materialization — see
/// [`write_mcp_json_respecting_user_servers`]. Lives beside
/// [`MANAGED_SKILL_FILES_MANIFEST`] for the same reason: it lets the next
/// launch tell entries it owns from entries the user put there.
pub const MANAGED_MCP_SERVERS_MANIFEST: &str = ".claude/.agentmux-managed-mcp-servers.json";

/// Held (exclusively) for the whole read-merge-write in
/// [`write_mcp_json_respecting_user_servers`]. See its doc comment.
pub const MCP_JSON_WRITE_LOCK: &str = ".claude/.agentmux-mcp-json.lock";

/// Write `.mcp.json` into `base_path` without destroying a user's own MCP
/// server entries (issue #3680). Shared by `agent.open` and the
/// `WriteAgentConfig` "click Launch" path — the two config-materializing call
/// sites this module keeps in sync.
///
/// An agent's `working_directory` may be the user's own project, where a
/// `.mcp.json` often already exists (and is often committed). A plain
/// `fs::write` replaced it, dropping every server entry the agent definition
/// didn't duplicate. Instead:
///
/// - **Merge.** Every existing `mcpServers` entry is kept, except the ones a
///   previous materialization wrote (per [`MANAGED_MCP_SERVERS_MANIFEST`]),
///   which are replaced by this launch's set — so a server unbound in
///   Connectors still disappears. Other top-level keys in the existing file are
///   kept too. On a name clash this launch's entry wins (the `agentmux` entry
///   must always be ours).
/// - **No manifest yet** (first launch after this change, or a user's file):
///   a file that already has an `agentmux` entry was written by AgentMux, so
///   all its entries are treated as managed — the old regenerate-every-launch
///   behavior, once. A file without one is the user's; all of it is kept.
/// - **Unreadable or not a JSON object** → left untouched and logged, never
///   overwritten — the same "never overwrite a stranger's file" rule
///   [`write_claude_md_respecting_ownership`] follows. Claude Code couldn't
///   parse such a file either.
/// - **Owner-only.** The file carries the agent's jekt signing material
///   (`inject_jekt_signing_keys_into_mcp_json`), so it is written `0600` on
///   Unix, via a temp file renamed into place so it is never briefly visible
///   with the default mode.
/// - **One launch at a time per directory.** `.mcp.json` and its manifest
///   must describe the same launch, or a server AgentMux wrote gets mistaken
///   for the user's and is never removed. Neither call site serializes by
///   directory (`agent_open`'s lock is per agent; `WriteAgentConfig` has
///   none), so the whole read-merge-write holds an exclusive lock on
///   [`MCP_JSON_WRITE_LOCK`]. A file lock rather than an in-process mutex, so
///   two AgentMux instances pointed at one project are serialized too; it is
///   released when the handle drops, including on error or panic.
///
/// Not addressed here: the signing material being in this file at all
/// (the identity plan's M4d/M5 move it out — see
/// `SPEC_AGENT_IDENTITY_CARRIED_NOT_DERIVED_2026_09_23.md` §6.5), and a
/// user's project not git-ignoring `.mcp.json`.
pub fn write_mcp_json_respecting_user_servers(
    base_path: &std::path::Path,
    generated_content: &str,
) -> std::io::Result<()> {
    use serde_json::{Map, Value};

    let wd = crate::backend::workdir_fs::Workdir::open(base_path)?;
    // Refused (a symlink, or outside the workdir) before anything is read
    // or locked: this file carries the agent's signing keys. A refusal
    // leaves the link alone and the launch goes on, as for `CLAUDE.md`
    // (ReAgent on #4141). So does a refused ownership manifest (a `.claude`
    // linking out): without it the next merge would take the user's own
    // servers for AgentMux's and drop them (Codex on #4141).
    let path = match wd.resolve(MANAGED_MCP_SERVERS_MANIFEST).and_then(|_| wd.resolve(".mcp.json")) {
        Ok(path) => path,
        Err(e) if e.kind() == std::io::ErrorKind::PermissionDenied => {
            tracing::warn!(error = %e, "write_mcp_json_respecting_user_servers: not writing .mcp.json");
            return Ok(());
        }
        Err(e) => return Err(e),
    };
    let generated: Value = serde_json::from_str(generated_content).map_err(|e| {
        std::io::Error::new(std::io::ErrorKind::InvalidData, format!("generated .mcp.json is not JSON: {e}"))
    })?;
    let Some(generated_obj) = generated.as_object() else {
        return Err(std::io::Error::new(
            std::io::ErrorKind::InvalidData,
            "generated .mcp.json is not a JSON object",
        ));
    };
    // Serialize concurrent launches into this directory — see the doc comment.
    // The exclusive per-directory write lock; released on drop. A `.claude`
    // linking out of the workdir refuses the lock file: the write then goes
    // ahead unlocked (it is still atomic) rather than failing the launch.
    let _dir_lock = match wd.open_lock_file(MCP_JSON_WRITE_LOCK) {
        Ok(file) => {
            file.lock()?;
            Some(file)
        }
        Err(e) if e.kind() == std::io::ErrorKind::PermissionDenied => {
            tracing::warn!(error = %e, "write_mcp_json_respecting_user_servers: writing .mcp.json without the directory lock");
            None
        }
        Err(e) => return Err(e),
    };

    let ours: Map<String, Value> = generated_obj
        .get("mcpServers")
        .and_then(Value::as_object)
        .cloned()
        .unwrap_or_default();

    let existing: Option<Map<String, Value>> = match std::fs::read_to_string(&path) {
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => None,
        Err(e) => {
            tracing::warn!(
                path = %path.display(),
                error = %e,
                "write_mcp_json_respecting_user_servers: existing .mcp.json is unreadable — \
                 leaving it untouched; this agent's MCP servers are not written for this launch"
            );
            return Ok(());
        }
        Ok(raw) => match serde_json::from_str::<Value>(&raw) {
            Ok(Value::Object(obj))
                if obj.get("mcpServers").map_or(true, Value::is_object) =>
            {
                Some(obj)
            }
            _ => {
                tracing::warn!(
                    path = %path.display(),
                    "write_mcp_json_respecting_user_servers: existing .mcp.json is not a JSON \
                     object with an object `mcpServers` — leaving it untouched; this agent's MCP \
                     servers are not written for this launch"
                );
                return Ok(());
            }
        },
    };

    let merged = match existing {
        None => generated_obj.clone(),
        Some(mut obj) => {
            let existing_servers = obj
                .get("mcpServers")
                .and_then(Value::as_object)
                .cloned()
                .unwrap_or_default();
            let previously_managed: std::collections::BTreeSet<String> =
                match read_managed_mcp_server_names(base_path) {
                    Some(names) => names,
                    None if existing_servers.contains_key("agentmux") => {
                        existing_servers.keys().cloned().collect()
                    }
                    None => Default::default(),
                };
            let mut servers: Map<String, Value> = existing_servers
                .into_iter()
                .filter(|(name, _)| !previously_managed.contains(name) && !ours.contains_key(name))
                .collect();
            servers.extend(ours.clone());
            for (k, v) in generated_obj {
                if k != "mcpServers" {
                    obj.insert(k.clone(), v.clone());
                }
            }
            obj.insert("mcpServers".to_string(), Value::Object(servers));
            obj
        }
    };

    let body = serde_json::to_string_pretty(&Value::Object(merged))
        .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;
    wd.write(".mcp.json", body.as_bytes(), true)?;
    write_managed_mcp_server_names(&wd, ours.keys());
    Ok(())
}

fn read_managed_mcp_server_names(base_path: &std::path::Path) -> Option<std::collections::BTreeSet<String>> {
    let raw = std::fs::read_to_string(base_path.join(MANAGED_MCP_SERVERS_MANIFEST)).ok()?;
    serde_json::from_str(&raw).ok()
}

/// Best-effort, like [`write_managed_skill_file_manifest`]: losing this write
/// only means the next launch falls back to the no-manifest rule once.
fn write_managed_mcp_server_names<'a>(
    wd: &crate::backend::workdir_fs::Workdir,
    names: impl Iterator<Item = &'a String>,
) {
    let names: std::collections::BTreeSet<&String> = names.collect();
    // Atomic (the workdir's write is) for the same reason as the .mcp.json
    // write itself: concurrent launches into one directory must not
    // interleave into one manifest.
    let result = serde_json::to_string(&names)
        .map_err(std::io::Error::other)
        .and_then(|json| wd.write(MANAGED_MCP_SERVERS_MANIFEST, json.as_bytes(), true));
    if let Err(e) = result {
        tracing::warn!(
            work_dir = %wd.base().display(),
            error = %e,
            "write_managed_mcp_server_names: failed to write manifest; the next launch \
             falls back to treating an agentmux-bearing .mcp.json as fully managed"
        );
    }
}

/// Shared by `agent.open` (`server/app_api/agent_open.rs`) and the
/// `WriteAgentConfig` "click Launch" path (`server/editor_handlers.rs`) —
/// per this module's own doc comment, the two config-materializing call
/// sites that must not drift out of sync. See
/// `docs/specs/SPEC_CLAUDE_MD_OWNERSHIP_PROTECTION_2026_08_22.md`.
pub fn write_claude_md_respecting_ownership(
    base_path: &std::path::Path,
    generated_content: &str,
) -> std::io::Result<()> {
    let claude_md_path = base_path.join("CLAUDE.md");

    // `None` = genuinely no file yet. `Some(Ok(content))` = read fine.
    // `Some(Err(_))` = exists but unreadable — MUST be treated the same
    // as "foreign," never as "no file yet" (see doc comment above).
    let existing = match std::fs::read_to_string(&claude_md_path) {
        Ok(content) => Some(Ok(content)),
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => None,
        Err(e) => Some(Err(e)),
    };

    let mut agentmux_owns_it =
        matches!(&existing, Some(Ok(content)) if content.starts_with(CLAUDE_MD_MANAGED_MARKER));

    // Every write below goes through the workdir
    // (SPEC_WORKDIR_SAFE_WRITES_2026_10_01): a `CLAUDE.md` that is a symlink
    // (dangling or not), or a `.claude` linking out of the workspace, is
    // refused rather than written through (Codex P1s on #4131).
    let wd = crate::backend::workdir_fs::Workdir::open(base_path)?;
    let claude_md_writable = wd.resolve("CLAUDE.md").is_ok();

    // A CLAUDE.md an older AgentMux wrote, before the managed marker existed:
    // nothing in it but the skills index and the managed import line. It was
    // taken for the user's and frozen, so its agent kept a stale skills list
    // forever. Adopt it, keeping a copy (LC3,
    // SPEC_LAUNCH_CONTEXT_WORKSPACE_RULE_AND_STARTUP_FILES_2026_09_30.md §4.4).
    if let Some(Ok(content)) = &existing {
        if !agentmux_owns_it && claude_md_writable && is_legacy_agentmux_claude_md(content) {
            match back_up_legacy_claude_md(&wd, content) {
                Ok(()) => {
                    tracing::info!(path = %claude_md_path.display(), "CLAUDE.md written by an older AgentMux: adopting it as managed");
                    agentmux_owns_it = true;
                }
                Err(e) => tracing::warn!(
                    path = %claude_md_path.display(),
                    error = %e,
                    "write_claude_md_respecting_ownership: couldn't back up a legacy CLAUDE.md; leaving it as is"
                ),
            }
        }
    }

    // Nothing is written to a CLAUDE.md the workdir refuses, not even the
    // @import append below: every write would land on a link's target.
    if !claude_md_writable {
        tracing::warn!(path = %claude_md_path.display(), "write_claude_md_respecting_ownership: CLAUDE.md is a symlink or outside the workspace; not writing through it");
        return Ok(());
    }
    // Known, accepted TOCTOU window (codex P2, third review round on
    // PR #2747): a foreign CLAUDE.md created between the read above and this
    // write would be replaced once. Closing it needs file locking across the
    // read-decide-write, which no sibling write here has either.
    if agentmux_owns_it || existing.is_none() {
        let content = format!("{CLAUDE_MD_MANAGED_MARKER}\n\n{generated_content}");
        return wd.write("CLAUDE.md", content.as_bytes(), false);
    }

    // Foreign (or unreadable) file — CLAUDE.md's own content is never
    // written to from here on. Everything from here down is best-effort
    // (see doc comment): a failure must not fail the whole agent launch.
    if let Err(e) = wd.write(AGENTMUX_MEMORY_FILENAME, generated_content.as_bytes(), false) {
        tracing::warn!(work_dir = %base_path.display(), error = %e, "write_claude_md_respecting_ownership: failed to write AGENTMUX_MEMORY.md this launch");
        return Ok(());
    }

    // Unreadable (not just "no marker") — nothing safe to check
    // idempotency against or append to. Skip the @import offer this
    // launch; the side file above is still fresh and ready whenever the
    // file becomes readable again.
    let Some(Ok(existing_content)) = existing else {
        tracing::warn!(path = %claude_md_path.display(), "write_claude_md_respecting_ownership: existing CLAUDE.md unreadable; treating as foreign, skipping @import offer this launch");
        return Ok(());
    };

    // Atomic "am I the first to offer this" gate, not a read-then-write
    // check: `create_new` reports an existing marker if another concurrent
    // call already won this race. Two agents sharing a working directory
    // (agent_open.rs's shared-workdir fallback, `~/.agentmux/agents/<slug>`,
    // launching concurrently) previously could both read "not yet offered"
    // and both append the import line, duplicating it (reagent P2, second
    // review round on PR #2747). Only the caller that creates the marker
    // proceeds to append; every other caller skips straight past.
    let marker_json = serde_json::to_string(&ClaudeMdOwnershipMarker { import_line_offered: true })
        .unwrap_or_default();
    match wd.create_new(CLAUDE_MD_OWNERSHIP_MARKER_PATH, marker_json.as_bytes()) {
        Ok(true) => {
            let import_needle = format!("@{AGENTMUX_MEMORY_FILENAME}");
            // Idempotent even having won the race: don't duplicate if
            // the import somehow already appears (e.g. a user copied it
            // in by hand before AgentMux ever ran here).
            if !existing_content.contains(&import_needle) {
                let import_block = format!("\n\n{CLAUDE_MD_IMPORT_MARKER_COMMENT}\n{import_needle}\n");
                // True append (never a read-modify-write of the whole
                // file) — an edit racing this function's earlier read is
                // preserved (codex P2 on PR #2747).
                if let Err(e) = wd.append("CLAUDE.md", import_block.as_bytes()) {
                    tracing::warn!(path = %claude_md_path.display(), error = %e, "write_claude_md_respecting_ownership: failed to append the @import line this launch");
                    // Roll back the marker we just created — winning the
                    // race doesn't mean the offer completed; a marker left
                    // behind would record "offered" forever with no retry
                    // (reagent P1 + codex, third review round on PR #2747).
                    let _ = wd.remove_file(CLAUDE_MD_OWNERSHIP_MARKER_PATH);
                }
            }
        }
        Ok(false) => {
            // Already offered — by us on a prior launch, or a concurrent
            // racer that won just now. Nothing to do.
        }
        Err(e) => {
            tracing::warn!(work_dir = %base_path.display(), error = %e, "write_claude_md_respecting_ownership: failed to create ownership marker");
        }
    }

    Ok(())
}

/// Copy a legacy `CLAUDE.md` to [`CLAUDE_MD_PRE_ADOPT_BACKUP`] before it is
/// adopted. Whole or not at all (a failed write removes its partial copy);
/// a copy left by an earlier attempt counts only if it is this file, whole
/// (Codex on #4131).
fn back_up_legacy_claude_md(wd: &crate::backend::workdir_fs::Workdir, content: &str) -> std::io::Result<()> {
    if wd.create_new(CLAUDE_MD_PRE_ADOPT_BACKUP, content.as_bytes())? {
        return Ok(());
    }
    let existing = std::fs::read_to_string(wd.resolve(CLAUDE_MD_PRE_ADOPT_BACKUP)?)?;
    if existing == content {
        Ok(())
    } else {
        Err(std::io::Error::new(std::io::ErrorKind::AlreadyExists, "a different .pre-adopt copy already exists"))
    }
}

/// Best-effort: mint-or-reuse `agent_slug`'s jekt/LAN signing keys
/// (`SPEC_JEKT_TRUST_LAYER_COMPLETION_2026_08_13.md` §2.2,
/// `SPEC_JEKT_LAN_TIER_SIGNING_2026_08_15.md` §2.1) and patch them into a
/// `.mcp.json` file's `mcpServers.agentmux.env` block. Returns `None` on
/// any parse failure, missing `mcpServers.agentmux.env` object, or if
/// neither key could be ensured — callers must keep the original content
/// in that case; this must never block writing the agent's config.
///
/// Shared by `agent.open` (`server/app_api/agent_open.rs`) and the
/// `WriteAgentConfig` "click Launch" path (`server/editor_handlers.rs`) —
/// per this module's own doc comment, the two `.mcp.json`-materializing
/// call sites that must not drift out of sync. Before this function
/// existed, only `agent.open` injected these keys — `WriteAgentConfig`
/// (the path a normal Launch-button click actually goes through) silently
/// never did, so ordinarily-launched agents' jekts rendered
/// `TRUST=self-declared` even on builds well past both features shipping.
/// See `docs/specs/REPORT_JEKT_SIGNING_KEY_INJECTION_GAP_2026_08_16.md`.
pub fn inject_jekt_signing_keys_into_mcp_json(
    content: &str,
    mstore: &crate::backend::storage::store::Store,
    agent_slug: &str,
) -> Option<String> {
    let mut mcp_json: Value = serde_json::from_str(content).ok()?;
    let env = mcp_json
        .pointer_mut("/mcpServers/agentmux/env")
        .and_then(|v| v.as_object_mut())?;

    let mut patched = false;
    if let Ok(key) = mstore.agent_jekt_key_ensure(agent_slug) {
        use base64::Engine as _;
        let key_b64 = base64::engine::general_purpose::STANDARD.encode(&key);
        env.insert("AGENTMUX_JEKT_KEY".to_string(), json!(key_b64));
        patched = true;
    }
    if let Ok(keypair) = mstore.agent_lan_key_ensure(agent_slug) {
        env.insert("AGENTMUX_LAN_KEY".to_string(), json!(keypair.private_key));
        // SPEC_JEKT_CROSS_CHANNEL_TRUST_2026_09_02.md §D5 (Phase B): the
        // cross-channel signature binds the sending channel into the signed
        // material, so the MCP process must know its channel by the SAME
        // string a receiver reads off this instance's shared registry entry.
        // Written explicitly rather than relying on the ambient
        // `AGENTMUX_CHANNEL` leaking into the agent's shell: a nested
        // portable, or an agent launched with a scrubbed env, would
        // otherwise sign as "stable" while registered under its real
        // channel, and every cross-channel jekt it sent would fail to verify.
        env.insert(
            "AGENTMUX_CHANNEL".to_string(),
            json!(crate::backend::reactive::registry::local_channel_id()),
        );
        patched = true;
    }
    // WAN-tier signing (issue #2586's WAN
    // half): a SEPARATE keypair from the LAN one above — see
    // storage/agent_wan_keys.rs for why the two tiers' key lifecycles cannot
    // be shared. Injected on the same terms and with the same guarantee:
    // this agent's env only, never over RPC.
    //
    // Minted and injected ahead of any verifier existing, deliberately. An
    // agent only receives a key at spawn, so an agent that is never respawned
    // never gets one — starting the propagation now is what makes WAN
    // verification meaningful when it lands, rather than applying to almost
    // no live agent on day one. Exactly the same reasoning that made
    // un-respawned agents render TRUST=self-declared for months after
    // host-tier signing shipped (REPORT_JEKT_SIGNING_KEY_INJECTION_GAP_2026_08_16.md).
    //
    // W3-S (SPEC_WAN_JEKT_VERIFICATION_2026_09_24.md §2.2): the key and the
    // instance both come from the channel-wide `wan.db`, so they survive an
    // upgrade. The agent's key from this version's `db_agent_wan_keys` is
    // read first (outside any `wan.db` lock) and carried over only the first
    // time. With no `wan.db` attached, the agent gets no WAN key at all —
    // never one minted somewhere else.
    if let Some(wan) = mstore.wan_identity() {
        let legacy = mstore.agent_wan_key_load(agent_slug).ok().flatten();
        let import = legacy.as_ref().map(|k| (k.public_key.as_str(), k.private_key.as_str()));
        match (
            wan.instance_ensure(&crate::backend::reactive::registry::local_host_label()),
            wan.agent_key_ensure(agent_slug, import),
        ) {
            (Ok(instance), Ok(key)) => {
                env.insert("AGENTMUX_WAN_KEY".to_string(), json!(key.private_key));
                // §2.1.2: the WAN signature binds the sending INSTANCE, not
                // just the agent. Since W3-S the instance is its
                // self-certifying id rather than the live hostname, which
                // collides and changes. Written explicitly for the same
                // reason `AGENTMUX_CHANNEL` above is: a scrubbed or nested env
                // must not sign as a different instance than the one that
                // certifies this agent's key.
                env.insert("AGENTMUX_HOST_LABEL".to_string(), json!(instance.instance_id));
                patched = true;
                // D1b: get this key into the cloud directory before the agent
                // needs it — until then its WAN jekts go unsigned. Always: only
                // the publisher knows the current directory (relay + account),
                // and a pass with nothing pending sends nothing.
                crate::muxbus::wan_publish::nudge();
            }
            (instance, key) => tracing::warn!(
                agent = agent_slug,
                instance_error = ?instance.err(),
                key_error = ?key.err(),
                "wan identity: could not provision this agent's WAN key — its WAN jekts go unsigned"
            ),
        }
    }
    if !patched {
        return None;
    }
    serde_json::to_string_pretty(&mcp_json).ok()
}

// ============================================================
// Tests
// ============================================================

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

    fn make_skill(name: &str, trigger: &str, description: &str, content: &str) -> AgentSkill {
        AgentSkill {
            id: format!("skill-{}", trigger),
            agent_id: "agent-1".to_string(),
            name: name.to_string(),
            trigger: trigger.to_string(),
            skill_type: "prompt".to_string(),
            description: description.to_string(),
            content: content.to_string(),
            created_at: 0,
        }
    }

    fn make_agent_skill(name: &str, description: &str, content: &str) -> AgentSkill {
        AgentSkill {
            id: format!("skill-{}", derive_slug(name)),
            agent_id: "agent-1".to_string(),
            name: name.to_string(),
            trigger: String::new(),
            skill_type: SKILL_TYPE_AGENT_SKILL.to_string(),
            description: description.to_string(),
            content: content.to_string(),
            created_at: 0,
        }
    }

    #[test]
    fn test_sanitize_trigger_rejects_path_traversal() {
        // reagent P1, PR #2322: a trigger with a path separator or ".."
        // must never be allowed to steer .claude/commands/<trigger>.md
        // outside the working directory.
        assert_eq!(sanitize_trigger("../../../../.ssh/authorized_keys"), None);
        assert_eq!(sanitize_trigger("../evil"), None);
        assert_eq!(sanitize_trigger("sub/evil"), None);
        assert_eq!(sanitize_trigger("sub\\evil"), None);
        assert_eq!(sanitize_trigger(".."), None);
        assert_eq!(sanitize_trigger("."), None);
        assert_eq!(sanitize_trigger(""), None);
        assert_eq!(sanitize_trigger("deploy"), Some("deploy"));
    }

    #[test]
    fn test_build_config_files_skips_prompt_skill_with_traversal_trigger() {
        // reagent P1, PR #2322: build_config_files must not materialize a
        // command file for a malicious trigger, not even under a sanitized
        // name -- skip it outright.
        let content_map = HashMap::new();
        let skills = vec![make_skill(
            "Evil",
            "../../../../.ssh/authorized_keys",
            "desc",
            "malicious content",
        )];
        let files = build_config_files(&content_map, &skills, "Aria", "agent-1", "aria", "/tmp/aria", "claude");
        assert!(
            files.iter().all(|f| !f.filename.contains("..")),
            "no config file path may contain '..': {:?}",
            files.iter().map(|f| &f.filename).collect::<Vec<_>>()
        );
        assert!(!files.iter().any(|f| f.filename.starts_with(".claude/commands/")));
    }

    #[test]
    fn test_expand_template_basic() {
        let mut vars = HashMap::new();
        vars.insert("AGENT".to_string(), "Aria".to_string());
        vars.insert("DATE".to_string(), "2026-04-10".to_string());

        let out = expand_template("Hello {{AGENT}}, today is {{DATE}}.", &vars);
        assert_eq!(out, "Hello Aria, today is 2026-04-10.");
    }

    #[test]
    fn test_expand_template_unknown_placeholder_preserved() {
        let vars = HashMap::new();
        let out = expand_template("Value: {{UNKNOWN}}", &vars);
        assert_eq!(out, "Value: {{UNKNOWN}}");
    }

    #[test]
    fn test_expand_template_empty_vars() {
        let vars = HashMap::new();
        let out = expand_template("No placeholders here.", &vars);
        assert_eq!(out, "No placeholders here.");
    }

    #[test]
    fn test_build_mcp_config_no_user_content() {
        let result = build_mcp_config(None, "aria", "bus-42").unwrap();
        let parsed: Value = serde_json::from_str(&result).unwrap();
        let servers = &parsed["mcpServers"];
        assert!(servers["agentmux"].is_object());
        assert_eq!(servers["agentmux"]["command"], "agentmux-mcp");
        assert_eq!(servers["agentmux"]["env"]["AGENTMUX_AGENT_ID"], "aria");
        assert_eq!(servers["agentmux"]["env"]["AGENTMUX_AGENT_BUS_ID"], "bus-42");
    }

    #[test]
    fn test_build_mcp_config_merges_user_servers() {
        let user_mcp = r#"{"mcpServers": {"mytool": {"type": "stdio", "command": "mytool"}}}"#;
        let result = build_mcp_config(Some(user_mcp), "aria", "").unwrap();
        let parsed: Value = serde_json::from_str(&result).unwrap();
        let servers = &parsed["mcpServers"];
        assert!(servers["agentmux"].is_object());
        assert!(servers["mytool"].is_object());
    }

    #[test]
    fn test_build_mcp_config_invalid_user_json_uses_auto_injected() {
        let result = build_mcp_config(Some("not json {{"), "aria", "").unwrap();
        let parsed: Value = serde_json::from_str(&result).unwrap();
        assert!(parsed["mcpServers"]["agentmux"].is_object());
    }

    #[test]
    fn test_build_config_files_claude_md_assembled() {
        let mut content_map = HashMap::new();
        content_map.insert("soul".to_string(), "You are {{AGENT}}.".to_string());
        content_map.insert("agentmd".to_string(), "## Instructions\nDo stuff.".to_string());

        let files = build_config_files(&content_map, &[], "Aria", "agent-1", "aria", "/tmp/aria", "claude");
        let claude_md = files.iter().find(|f| f.filename == "CLAUDE.md").unwrap();
        assert!(claude_md.content.contains("You are Aria."));
        assert!(claude_md.content.contains("---"));
        assert!(claude_md.content.contains("## Instructions"));
    }

    // docs/specs/SPEC_PROVIDER_AWARE_STARTUP_INSTRUCTIONS_2026_08_24.md §7:
    // per-provider filename resolution, pinned against §2's researched
    // table so it can't silently drift.
    #[test]
    fn test_build_config_files_resolves_provider_specific_filename() {
        let cases: &[(&str, &str)] = &[
            ("claude", "CLAUDE.md"),
            ("codex", "AGENTS.md"),
            ("gemini", "GEMINI.md"),
            ("qwen", "QWEN.md"),
            ("copilot", "AGENTS.md"),
            ("openclaw", "AGENTS.md"),
            ("pi", "AGENTS.md"),
            ("antigravity", "GEMINI.md"),
            ("muxcode", "CLAUDE.md"),
        ];
        for (provider_id, expected_filename) in cases {
            let mut content_map = HashMap::new();
            content_map.insert("soul".to_string(), "You are Aria.".to_string());
            let files = build_config_files(&content_map, &[], "Aria", "agent-1", "aria", "/tmp/aria", provider_id);
            let instructions_files: Vec<&str> = files
                .iter()
                .filter(|f| f.filename == *expected_filename)
                .map(|f| f.content.as_str())
                .collect();
            assert_eq!(
                instructions_files.len(),
                1,
                "provider '{provider_id}' should produce exactly one file named '{expected_filename}': {:?}",
                files.iter().map(|f| &f.filename).collect::<Vec<_>>()
            );
            assert!(instructions_files[0].contains("You are Aria."));
        }
    }

    #[test]
    fn test_build_config_files_kimi_gets_no_instructions_file() {
        // Confirmed absence (SPEC_PROVIDER_AWARE_STARTUP_INSTRUCTIONS_2026_08_24.md
        // §2): Kimi has no native file-based startup-instructions
        // discovery — writing one would be inert output nobody reads.
        let mut content_map = HashMap::new();
        content_map.insert("soul".to_string(), "You are Aria.".to_string());
        content_map.insert("agentmd".to_string(), "## Instructions".to_string());
        content_map.insert("memory".to_string(), "Some memory content".to_string());
        let files = build_config_files(&content_map, &[], "Aria", "agent-1", "aria", "/tmp/aria", "kimi");
        assert!(
            files.iter().all(|f| !f.filename.ends_with(".md") || f.filename.starts_with(".claude/")),
            "kimi must get no top-level instructions file, even with soul/agentmd/memory content present: {:?}",
            files.iter().map(|f| &f.filename).collect::<Vec<_>>()
        );
    }

    #[test]
    fn test_build_config_files_unrecognized_provider_gets_no_instructions_file() {
        // An unrecognized provider_id (typo, not-yet-registered) must not
        // silently fall back to "CLAUDE.md" — same no-op path as kimi.
        // .claude/settings.json and .mcp.json are still written (they're
        // provider-unconditional today, unaffected by this spec — §5's
        // ".claude/-namespaced files... out of scope"), so this checks
        // specifically for the absence of any known instructions filename,
        // not an empty result.
        let mut content_map = HashMap::new();
        content_map.insert("soul".to_string(), "You are Aria.".to_string());
        let files = build_config_files(&content_map, &[], "Aria", "agent-1", "aria", "/tmp/aria", "not-a-real-provider");
        let known_instructions_filenames = [
            "CLAUDE.md", "AGENTS.md", "GEMINI.md", "QWEN.md", ".pi/APPEND_SYSTEM.md",
        ];
        assert!(
            !files.iter().any(|f| known_instructions_filenames.contains(&f.filename.as_str())),
            "no instructions file should be written for an unrecognized provider: {:?}",
            files.iter().map(|f| &f.filename).collect::<Vec<_>>()
        );
    }

    #[test]
    fn test_build_config_files_skills_index_and_commands() {
        let content_map = HashMap::new();
        let skills = vec![
            make_skill("Deploy", "deploy", "Deploy the app", "Run: deploy all"),
            make_skill("Test", "test", "Run tests", "Run: test suite"),
        ];

        let files = build_config_files(&content_map, &skills, "Aria", "agent-1", "aria", "/tmp/aria", "claude");

        // Claude Code lists skills with a file by itself: no index (LC3).
        let claude_md = files.iter().find(|f| f.filename == "CLAUDE.md");
        assert!(claude_md.is_none_or(|f| !f.content.contains("Available Skills")), "{claude_md:?}");

        // Individual skill command files
        assert!(files.iter().any(|f| f.filename == ".claude/commands/deploy.md"));
        assert!(files.iter().any(|f| f.filename == ".claude/commands/test.md"));

        // Another provider reads only its instructions file: it keeps the index.
        let codex = build_config_files(&content_map, &skills, "Aria", "agent-1", "aria", "/tmp/aria", "codex");
        let agents_md = codex.iter().find(|f| f.filename == "AGENTS.md").unwrap();
        assert!(agents_md.content.contains("Available Skills"));
        assert!(agents_md.content.contains("/deploy"));
        assert!(agents_md.content.contains("/test"));
    }

    /// An alias of Claude (`claude-code`) is Claude: no index for skills with
    /// files (ReAgent on #4131).
    #[test]
    fn a_claude_alias_gets_no_index_for_file_backed_skills() {
        let skills = vec![make_skill("Deploy", "deploy", "Deploy the app", "Run: deploy all")];
        for alias in ["claude-code", "claude_code"] {
            if crate::backend::providers::get_provider(alias).is_none() {
                continue;
            }
            let files = build_config_files(&HashMap::new(), &skills, "Aria", "agent-1", "aria", "/tmp/aria", alias);
            let md = files.iter().find(|f| f.filename == "CLAUDE.md").unwrap();
            assert!(!md.content.contains("Available Skills"), "{alias}");
        }
    }

    /// A skill with no file of its own (no usable trigger) is still indexed
    /// for Claude: dropping it from the index would hide it entirely.
    #[test]
    fn claude_still_indexes_a_skill_that_has_no_file() {
        let skills = vec![
            make_skill("Deploy", "deploy", "Deploy the app", "Run: deploy all"),
            make_skill("Notes", "", "Read the notes", "Look in NOTES.md"),
        ];
        let files = build_config_files(&HashMap::new(), &skills, "Aria", "agent-1", "aria", "/tmp/aria", "claude");
        let claude_md = files.iter().find(|f| f.filename == "CLAUDE.md").unwrap();
        assert!(claude_md.content.contains("Available Skills"));
        assert!(claude_md.content.contains("**Notes**"));
        assert!(!claude_md.content.contains("/deploy"), "Deploy has a command file");
    }

    /// An agent whose skills all have files, and nothing else, still gets its
    /// instructions file: srv puts the Global Memory in it (LC3 live check —
    /// without this the launch wrote no CLAUDE.md at all).
    #[test]
    fn the_instructions_file_is_written_even_when_empty() {
        let skills = vec![make_skill("Deploy", "deploy", "Deploy the app", "Run: deploy all")];
        let files = build_config_files(&HashMap::new(), &skills, "Aria", "agent-1", "aria", "/tmp/aria", "claude");
        assert!(files.iter().any(|f| f.filename == "CLAUDE.md"), "{:?}", files.iter().map(|f| &f.filename).collect::<Vec<_>>());
        let kimi = build_config_files(&HashMap::new(), &skills, "Aria", "agent-1", "aria", "/tmp/aria", "kimi");
        assert!(!kimi.iter().any(|f| f.filename == "CLAUDE.md" || f.filename == "AGENTS.md"), "kimi has no file");
    }

    const LEGACY_CLAUDE_MD: &str = "\n# Available Skills\n\nUse `/<trigger>` to invoke a skill.\n\n\
        - **Test-Driven Development** (trigger: /tdd) \u{2014} write the test first.\n\
        - **Code Review** (trigger: /code-review) \u{2014} review.\n\n\n\
        <!-- agentmux:managed-import (safe to delete this line to opt out) -->\n\
        @.claude/AGENTMUX_MEMORY.md\n";

    /// Two skills on one trigger write one command file, the later winning:
    /// the earlier one has no file and stays in the index (Codex on #4131).
    #[test]
    fn a_skill_whose_command_file_a_later_one_overwrites_stays_indexed() {
        let skills = vec![
            make_skill("Deploy", "deploy", "Deploy the app", "Run: deploy all"),
            make_skill("Deploy Staging", "Deploy", "Deploy staging", "Run: deploy staging"),
        ];
        let files = build_config_files(&HashMap::new(), &skills, "Aria", "agent-1", "aria", "/tmp/aria", "claude");
        let md = files.iter().find(|f| f.filename == "CLAUDE.md").unwrap();
        assert!(md.content.contains("**Deploy**"), "the overwritten one is indexed");
        assert!(!md.content.contains("**Deploy Staging**"), "the one that owns the file isn't");
    }

    /// A non-ASCII trigger stays indexed: Unicode-equivalent names can share
    /// one file on macOS (Codex on #4131).
    #[test]
    fn a_skill_with_a_non_ascii_trigger_stays_indexed() {
        let skills = vec![make_skill("Caf\u{e9}", "caf\u{e9}", "coffee", "brew")];
        let files = build_config_files(&HashMap::new(), &skills, "Aria", "agent-1", "aria", "/tmp/aria", "claude");
        let md = files.iter().find(|f| f.filename == "CLAUDE.md").unwrap();
        assert!(md.content.contains("Caf\u{e9}"), "{}", md.content);
    }

    #[test]
    fn only_rows_as_agentmux_rendered_them_count() {
        assert!(is_generated_skill_row("- **TDD** (trigger: /tdd) \u{2014} write the test first."));
        assert!(is_generated_skill_row("- **TDD** (trigger: /tdd)"));
        assert!(is_generated_skill_row("- **TDD** \u{2014} write it first"));
        assert!(is_generated_skill_row("- **TDD**"));
        assert!(!is_generated_skill_row("- **this is my hand-written note"));
        assert!(!is_generated_skill_row("- **TDD** and also a note"));
        assert!(!is_generated_skill_row("- **TDD** (trigger: /tdd"));
        assert!(!is_legacy_agentmux_claude_md(
            "# Available Skills\nUse `/<trigger>` to invoke a skill.\n- **this is my hand-written note\n"
        ));
    }

    #[test]
    fn recognises_only_exactly_what_an_older_agentmux_wrote() {
        assert!(is_legacy_agentmux_claude_md(LEGACY_CLAUDE_MD));
        // AgentMux wrote the section only with skills: no rows, not ours (Codex on #4131).
        assert!(!is_legacy_agentmux_claude_md("# Available Skills\n\nUse `/<trigger>` to invoke a skill.\n"));
        // Its order: skill rows after the import mean someone rearranged it.
        assert!(!is_legacy_agentmux_claude_md(
            "# Available Skills\nUse `/<trigger>` to invoke a skill.\n@.claude/AGENTMUX_MEMORY.md\n- **A** x\n"
        ));
        assert!(is_legacy_agentmux_claude_md(
            "# Available Skills\nUse `/<trigger>` to invoke a skill.\n- **A** \u{2014} x\n@.claude/AGENTMUX_MEMORY.md\n"
        ));
        assert!(is_legacy_agentmux_claude_md("# Available Skills\n\nUse `/<trigger>` to invoke a skill.\n\n- **A** \u{2014} x\n"));
        assert!(!is_legacy_agentmux_claude_md(&format!("{LEGACY_CLAUDE_MD}\nAlways run the tests.\n")), "a person's line");
        assert!(!is_legacy_agentmux_claude_md(&format!("{CLAUDE_MD_MANAGED_MARKER}\n\n# Memory\n")));
        assert!(!is_legacy_agentmux_claude_md("# Project\n\n# Available Skills\n"));
        assert!(!is_legacy_agentmux_claude_md(""));
    }

    #[test]
    fn a_legacy_claude_md_is_adopted_with_a_backup() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("CLAUDE.md"), LEGACY_CLAUDE_MD).unwrap();
        write_claude_md_respecting_ownership(dir.path(), "# Memory\nfresh\n").unwrap();

        let now = std::fs::read_to_string(dir.path().join("CLAUDE.md")).unwrap();
        assert!(now.starts_with(CLAUDE_MD_MANAGED_MARKER), "{now}");
        assert!(now.contains("fresh"));
        let backup = std::fs::read_to_string(dir.path().join(CLAUDE_MD_PRE_ADOPT_BACKUP)).unwrap();
        assert_eq!(backup, LEGACY_CLAUDE_MD);

        // Managed from now on; the original copy is never overwritten.
        write_claude_md_respecting_ownership(dir.path(), "# Memory\nnewer\n").unwrap();
        assert!(std::fs::read_to_string(dir.path().join("CLAUDE.md")).unwrap().contains("newer"));
        assert_eq!(std::fs::read_to_string(dir.path().join(CLAUDE_MD_PRE_ADOPT_BACKUP)).unwrap(), LEGACY_CLAUDE_MD);
    }

    /// A `.claude` linked outside the workspace gets no backup written
    /// through it, and the file isn't adopted (Codex on #4131).
    #[test]
    fn a_legacy_claude_md_is_not_adopted_through_a_symlinked_claude_dir() {
        let dir = tempfile::tempdir().unwrap();
        let outside = tempfile::tempdir().unwrap();
        #[cfg(unix)]
        let made = std::os::unix::fs::symlink(outside.path(), dir.path().join(".claude")).is_ok();
        #[cfg(windows)]
        let made = std::os::windows::fs::symlink_dir(outside.path(), dir.path().join(".claude")).is_ok();
        if !made {
            // Windows needs privilege for symlinks; the guard is exercised
            // wherever one can be made.
            return;
        }
        std::fs::write(dir.path().join("CLAUDE.md"), LEGACY_CLAUDE_MD).unwrap();
        write_claude_md_respecting_ownership(dir.path(), "# Memory\nfresh\n").unwrap();
        assert!(!outside.path().join("CLAUDE.md.pre-adopt").exists(), "no backup outside the workspace");
        let now = std::fs::read_to_string(dir.path().join("CLAUDE.md")).unwrap();
        assert!(!now.starts_with(CLAUDE_MD_MANAGED_MARKER), "not adopted: {now}");
    }

    /// A copy left by an earlier attempt that isn't this file whole (a
    /// partial write) blocks adoption; the original stays.
    #[test]
    fn a_mismatched_backup_blocks_adoption() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("CLAUDE.md"), LEGACY_CLAUDE_MD).unwrap();
        std::fs::create_dir_all(dir.path().join(".claude")).unwrap();
        std::fs::write(dir.path().join(CLAUDE_MD_PRE_ADOPT_BACKUP), &LEGACY_CLAUDE_MD[..20]).unwrap();
        write_claude_md_respecting_ownership(dir.path(), "# Memory\nfresh\n").unwrap();
        assert_eq!(std::fs::read_to_string(dir.path().join("CLAUDE.md")).unwrap(), LEGACY_CLAUDE_MD);

        // The same copy, whole: adopted.
        std::fs::write(dir.path().join(CLAUDE_MD_PRE_ADOPT_BACKUP), LEGACY_CLAUDE_MD).unwrap();
        write_claude_md_respecting_ownership(dir.path(), "# Memory\nfresh\n").unwrap();
        assert!(std::fs::read_to_string(dir.path().join("CLAUDE.md")).unwrap().starts_with(CLAUDE_MD_MANAGED_MARKER));
    }

    /// A `CLAUDE.md` that is a symlink is never adopted: the managed write
    /// would follow it (Codex P1 on #4131).
    #[test]
    fn a_symlinked_legacy_claude_md_is_not_adopted() {
        let dir = tempfile::tempdir().unwrap();
        let outside = tempfile::tempdir().unwrap();
        let target = outside.path().join("CLAUDE.md");
        std::fs::write(&target, LEGACY_CLAUDE_MD).unwrap();
        #[cfg(unix)]
        let made = std::os::unix::fs::symlink(&target, dir.path().join("CLAUDE.md")).is_ok();
        #[cfg(windows)]
        let made = std::os::windows::fs::symlink_file(&target, dir.path().join("CLAUDE.md")).is_ok();
        if !made {
            return; // Windows needs privilege for symlinks.
        }
        write_claude_md_respecting_ownership(dir.path(), "# Memory\nfresh\n").unwrap();
        assert_eq!(std::fs::read_to_string(&target).unwrap(), LEGACY_CLAUDE_MD, "the outside file is untouched");
    }

    /// A symlinked `CLAUDE.md` whose target already looks managed is not
    /// written through either (Codex on #4131).
    #[test]
    fn a_symlinked_managed_claude_md_is_not_written_through() {
        let dir = tempfile::tempdir().unwrap();
        let outside = tempfile::tempdir().unwrap();
        let target = outside.path().join("CLAUDE.md");
        let managed = format!("{CLAUDE_MD_MANAGED_MARKER}\n\n# Memory\nold\n");
        std::fs::write(&target, &managed).unwrap();
        #[cfg(unix)]
        let made = std::os::unix::fs::symlink(&target, dir.path().join("CLAUDE.md")).is_ok();
        #[cfg(windows)]
        let made = std::os::windows::fs::symlink_file(&target, dir.path().join("CLAUDE.md")).is_ok();
        if !made {
            return; // Windows needs privilege for symlinks.
        }
        write_claude_md_respecting_ownership(dir.path(), "# Memory\nfresh\n").unwrap();
        assert_eq!(std::fs::read_to_string(&target).unwrap(), managed, "the outside file is untouched");
    }

    /// A symlinked non-Claude instructions file is never written through,
    /// dangling or pointing at an already-managed file (Codex on #4131).
    #[test]
    fn a_symlinked_startup_instructions_file_is_not_written_through() {
        let dir = tempfile::tempdir().unwrap();
        let outside = tempfile::tempdir().unwrap();
        let target = outside.path().join("AGENTS.md");
        let managed = format!("{STARTUP_INSTRUCTIONS_MANAGED_MARKER}\n\nold\n");
        std::fs::write(&target, &managed).unwrap();
        #[cfg(unix)]
        let made = std::os::unix::fs::symlink(&target, dir.path().join("AGENTS.md")).is_ok();
        #[cfg(windows)]
        let made = std::os::windows::fs::symlink_file(&target, dir.path().join("AGENTS.md")).is_ok();
        if !made {
            return; // Windows needs privilege for symlinks.
        }
        write_startup_instructions_respecting_existing(dir.path(), "AGENTS.md", "fresh").unwrap();
        assert_eq!(std::fs::read_to_string(&target).unwrap(), managed, "the outside file is untouched");

        // Dangling: nothing is created at the link's target either.
        let gone = outside.path().join("GEMINI.md");
        #[cfg(unix)]
        let made = std::os::unix::fs::symlink(&gone, dir.path().join("GEMINI.md")).is_ok();
        #[cfg(windows)]
        let made = std::os::windows::fs::symlink_file(&gone, dir.path().join("GEMINI.md")).is_ok();
        if made {
            write_startup_instructions_respecting_existing(dir.path(), "GEMINI.md", "fresh").unwrap();
            assert!(!gone.exists(), "no file created through a dangling link");
        }
    }

    #[test]
    fn a_plain_startup_instructions_file_is_still_written() {
        let dir = tempfile::tempdir().unwrap();
        write_startup_instructions_respecting_existing(dir.path(), "AGENTS.md", "fresh").unwrap();
        assert!(std::fs::read_to_string(dir.path().join("AGENTS.md")).unwrap().contains("fresh"));
        write_startup_instructions_respecting_existing(dir.path(), ".pi/APPEND_SYSTEM.md", "pi").unwrap();
        assert!(std::fs::read_to_string(dir.path().join(".pi/APPEND_SYSTEM.md")).unwrap().contains("pi"));
    }

    #[test]
    fn a_users_claude_md_is_still_left_alone() {
        let dir = tempfile::tempdir().unwrap();
        let mine = format!("{LEGACY_CLAUDE_MD}\nAlways run the tests.\n");
        std::fs::write(dir.path().join("CLAUDE.md"), &mine).unwrap();
        write_claude_md_respecting_ownership(dir.path(), "# Memory\nfresh\n").unwrap();
        assert_eq!(std::fs::read_to_string(dir.path().join("CLAUDE.md")).unwrap(), mine);
        assert!(!dir.path().join(CLAUDE_MD_PRE_ADOPT_BACKUP).exists());
    }

    #[test]
    fn test_build_config_files_agent_skill_format_writes_skill_md() {
        let content_map = HashMap::new();
        let skills = vec![make_agent_skill(
            "Deploy Checklist",
            "Runs the pre-deploy checklist",
            "1. Run tests\n2. Check migrations\n3. Deploy",
        )];

        let files = build_config_files(&content_map, &skills, "Aria", "agent-1", "aria", "/tmp/aria", "claude");

        // Materializes to .claude/skills/<slug>/SKILL.md, not .claude/commands/
        let skill_file = files
            .iter()
            .find(|f| f.filename == ".claude/skills/deploy-checklist/SKILL.md")
            .expect("expected .claude/skills/deploy-checklist/SKILL.md");
        assert!(!files.iter().any(|f| f.filename.starts_with(".claude/commands/")));

        // YAML frontmatter with the two required Agent Skills fields.
        // `name` is the slug (matching its parent directory per the Agent
        // Skills spec), NOT the raw display name -- reagent P1 on #2322.
        assert!(skill_file.content.starts_with("---\n"));
        assert!(skill_file.content.contains("name: \"deploy-checklist\""));
        assert!(skill_file
            .content
            .contains("description: \"Runs the pre-deploy checklist\""));
        assert!(skill_file.content.contains("---\n\n1. Run tests"));

        // Claude Code lists a SKILL.md itself, so CLAUDE.md doesn't index it (LC3).
        let claude_md = files.iter().find(|f| f.filename == "CLAUDE.md");
        assert!(claude_md.is_none_or(|f| !f.content.contains("Deploy Checklist")), "{claude_md:?}");
    }

    #[test]
    fn test_build_config_files_agent_skill_format_escapes_yaml_special_chars() {
        // Names/descriptions with colons, quotes, or newlines must not
        // corrupt the YAML frontmatter -- serde_json's escaping (valid YAML
        // double-quoted-scalar syntax per YAML 1.2 §7.3.1) is what protects
        // this; regression-test it explicitly rather than trusting the
        // dependency silently.
        let content_map = HashMap::new();
        let skills = vec![make_agent_skill(
            "Weird: \"Name\"",
            "Has a colon: and \"quotes\"",
            "body",
        )];

        let files = build_config_files(&content_map, &skills, "Aria", "agent-1", "aria", "/tmp/aria", "claude");
        let skill_file = files
            .iter()
            .find(|f| f.filename.starts_with(".claude/skills/") && f.filename.ends_with("SKILL.md"))
            .expect("expected a SKILL.md file");

        // Frontmatter must parse as exactly 3 lines before the closing ---
        // (name, description, and nothing else leaking onto a new line).
        let end = skill_file.content.find("\n---\n\n").expect("closing frontmatter delimiter");
        let frontmatter = &skill_file.content[4..end]; // skip leading "---\n"
        let lines: Vec<&str> = frontmatter.lines().collect();
        assert_eq!(lines.len(), 2, "frontmatter should be exactly name + description lines, got: {lines:?}");
    }

    #[test]
    fn test_build_config_files_agent_skill_format_name_is_the_slug_not_display_name() {
        // reagent P1 (PR #2322): the Agent Skills spec requires `name` be
        // lowercase/hyphenated and match its parent directory -- the raw
        // display name (e.g. "Deploy Checklist") is spec-invalid.
        let content_map = HashMap::new();
        let skills = vec![make_agent_skill("Deploy Checklist", "desc", "body")];
        let files = build_config_files(&content_map, &skills, "Aria", "agent-1", "aria", "/tmp/aria", "claude");
        let skill_file = files.iter().find(|f| f.filename.ends_with("SKILL.md")).unwrap();
        assert!(skill_file.content.contains("name: \"deploy-checklist\""));
        assert!(!skill_file.content.contains("name: \"Deploy Checklist\""));
    }

    #[test]
    fn test_build_config_files_agent_skill_format_empty_description_gets_fallback() {
        // reagent P1 (PR #2322): the Agent Skills spec requires a non-empty
        // description; the UI permits creating a skill with none.
        let content_map = HashMap::new();
        let skills = vec![make_agent_skill("Deploy Checklist", "", "body")];
        let files = build_config_files(&content_map, &skills, "Aria", "agent-1", "aria", "/tmp/aria", "claude");
        let skill_file = files.iter().find(|f| f.filename.ends_with("SKILL.md")).unwrap();
        assert!(!skill_file.content.contains("description: \"\""), "empty description must not reach the spec-invalid empty string: {}", skill_file.content);
        assert!(skill_file.content.contains("description: \"No description provided.\""));
    }

    #[test]
    fn test_build_config_files_agent_skill_format_truncates_long_description() {
        // reagent P1 (PR #2322): the Agent Skills spec caps description at
        // 1024 characters.
        let content_map = HashMap::new();
        let long_description = "x".repeat(2000);
        let skills = vec![make_agent_skill("Deploy Checklist", &long_description, "body")];
        let files = build_config_files(&content_map, &skills, "Aria", "agent-1", "aria", "/tmp/aria", "claude");
        let skill_file = files.iter().find(|f| f.filename.ends_with("SKILL.md")).unwrap();
        // Extract the description value between the quotes on its line.
        let desc_line = skill_file.content.lines().find(|l| l.starts_with("description: ")).unwrap();
        let quoted = desc_line.trim_start_matches("description: ");
        let inner_len = quoted.len() - 2; // strip surrounding quotes
        assert!(inner_len <= 1024, "description exceeds spec max of 1024 chars: {inner_len}");
    }

    #[test]
    fn test_build_config_files_agent_skill_format_dedupes_colliding_slugs() {
        // reagent P1 (PR #2322): two distinct skill names that derive_slug
        // collapses to the same slug must NOT silently overwrite each
        // other's SKILL.md file.
        let content_map = HashMap::new();
        let skills = vec![
            make_agent_skill("Deploy Checklist", "First skill", "body one"),
            make_agent_skill("Deploy!!!Checklist", "Second skill", "body two"),
            make_agent_skill("Deploy   Checklist", "Third skill", "body three"),
        ];

        let files = build_config_files(&content_map, &skills, "Aria", "agent-1", "aria", "/tmp/aria", "claude");

        let skill_files: Vec<&AgentConfigFile> = files
            .iter()
            .filter(|f| f.filename.starts_with(".claude/skills/") && f.filename.ends_with("SKILL.md"))
            .collect();
        assert_eq!(skill_files.len(), 3, "all three skills must materialize to distinct files");

        let filenames: HashSet<&str> = skill_files.iter().map(|f| f.filename.as_str()).collect();
        assert_eq!(filenames.len(), 3, "filenames must be unique: {filenames:?}");
        assert!(filenames.contains(".claude/skills/deploy-checklist/SKILL.md"));
        assert!(filenames.contains(".claude/skills/deploy-checklist-2/SKILL.md"));
        assert!(filenames.contains(".claude/skills/deploy-checklist-3/SKILL.md"));

        // Each file's content must correspond to the correct skill (not just
        // present -- verify no cross-contamination from the dedup logic).
        let first = skill_files.iter().find(|f| f.filename.ends_with("deploy-checklist/SKILL.md")).unwrap();
        assert!(first.content.contains("body one"));
        let second = skill_files.iter().find(|f| f.filename.ends_with("deploy-checklist-2/SKILL.md")).unwrap();
        assert!(second.content.contains("body two"));
        let third = skill_files.iter().find(|f| f.filename.ends_with("deploy-checklist-3/SKILL.md")).unwrap();
        assert!(third.content.contains("body three"));
    }

    #[test]
    fn test_unique_skill_slug_replaces_underscores_with_hyphens() {
        // Codex P1, PR #2322: derive_slug (shared with agent role-slugs) keeps
        // underscores, which is spec-invalid for an Agent Skills `name`.
        let mut used = HashSet::new();
        assert_eq!(unique_skill_slug("code_review", &mut used), "code-review");
    }

    #[test]
    fn test_unique_skill_slug_suffixed_slug_stays_within_64_chars() {
        // Codex P2, PR #2322: a 64-char base plus "-2" was previously 66 chars.
        let mut used = HashSet::new();
        let long = "a".repeat(100);
        let first = unique_skill_slug(&long, &mut used);
        assert_eq!(first.len(), 64);
        let second = unique_skill_slug(&long, &mut used);
        assert!(second.len() <= 64, "suffixed slug exceeds 64 chars: {second} ({})", second.len());
        assert!(second.ends_with("-2"));
    }

    #[test]
    fn test_render_skill_md_truncates_by_utf16_units_matching_ts_slice() {
        // reagent P2, PR #2322: Rust previously capped by byte length while
        // the TS mirror caps by UTF-16 code units (`.slice(0, 1024)`), so
        // non-ASCII descriptions truncated to different lengths between the
        // two paths. A 3-byte-per-char UTF-8 string (each char = 1 UTF-16
        // unit) makes the byte-vs-unit divergence obvious: byte-based
        // truncation would cut this off around char 341, not 1024.
        let description: String = "\u{4e2d}".repeat(2000); // "中" x2000 (3 bytes each, 1 UTF-16 unit each)
        let md = render_skill_md("slug", &description, "body");
        let desc_line = md.lines().find(|l| l.starts_with("description: ")).unwrap();
        let quoted = desc_line.trim_start_matches("description: ");
        let inner = &quoted[1..quoted.len() - 1]; // strip surrounding quotes
        let utf16_len: usize = inner.chars().map(|c| c.len_utf16()).sum();
        assert_eq!(utf16_len, 1024, "expected exactly 1024 UTF-16 units, got {utf16_len}");
    }

    #[test]
    fn test_build_config_files_settings_merges_user_hooks() {
        // PR #813 moved hooks from `.claude/hooks.json` (a Claude Code
        // dead-letter path) to `.claude/settings.json` under the
        // `"hooks"` key. This test exercises the merge path: user
        // PreToolUse entries must be PREPENDED (not silently
        // dropped) to the auto-injected bashwrap entry so streaming
        // stays on while user-supplied gates fire first.
        let mut content_map = HashMap::new();
        content_map.insert(
            "hooks".to_string(),
            r#"{"PreToolUse":[{"matcher":"Read","hooks":[{"type":"command","command":"my-audit"}]}]}"#
                .to_string(),
        );
        let files = build_config_files(&content_map, &[], "Aria", "agent-1", "aria", "/tmp/aria", "claude");
        let settings = files
            .iter()
            .find(|f| f.filename == ".claude/settings.json")
            .expect("settings.json emitted");
        let parsed: Value = serde_json::from_str(&settings.content).unwrap();
        let pre_tool_use = parsed["hooks"]["PreToolUse"]
            .as_array()
            .expect("PreToolUse is an array");
        // User's "Read" matcher prepended first, then our Bash matcher.
        assert!(
            pre_tool_use
                .iter()
                .any(|e| e["matcher"].as_str() == Some("Read")),
            "user-supplied PreToolUse:Read must survive the merge"
        );
        assert!(
            pre_tool_use
                .iter()
                .any(|e| e["matcher"].as_str().unwrap_or("").contains("Bash")),
            "auto-injected PreToolUse:Bash must still be present"
        );
    }

    #[test]
    fn test_build_config_files_settings_merges_user_precompact_hooks() {
        // SPEC_COMPACTION_DETECTION_AND_HANDLING_2026_07_31.md §4.2:
        // PreCompact becomes auto-injected (two entries, matcher
        // "manual"/"auto") the same way PreToolUse already is. This is
        // the exact regression class PR #813's PreToolUse fix guards
        // against — a user-supplied PreCompact entry (from the legacy
        // content_map["hooks"] path) must survive the merge, not get
        // silently and permanently dropped by the generic
        // `hooks_obj.entry(k).or_insert(v)` path once PreCompact stops
        // being "just another key".
        let mut content_map = HashMap::new();
        content_map.insert(
            "hooks".to_string(),
            r#"{"PreCompact":[{"matcher":"manual","hooks":[{"type":"command","command":"my-precompact-audit"}]}]}"#
                .to_string(),
        );
        let files = build_config_files(&content_map, &[], "Aria", "agent-1", "aria", "/tmp/aria", "claude");
        let settings = files
            .iter()
            .find(|f| f.filename == ".claude/settings.json")
            .expect("settings.json emitted");
        let parsed: Value = serde_json::from_str(&settings.content).unwrap();
        let pre_compact = parsed["hooks"]["PreCompact"]
            .as_array()
            .expect("PreCompact is an array");
        assert_eq!(
            pre_compact.len(),
            3,
            "expected user entry + 2 auto-injected (manual, auto) entries, got {pre_compact:?}"
        );
        assert!(
            pre_compact
                .iter()
                .any(|e| e["hooks"][0]["command"].as_str() == Some("my-precompact-audit")),
            "user-supplied PreCompact entry must survive the merge"
        );
        assert!(
            pre_compact.iter().any(|e| e["hooks"][0]["command"].as_str()
                == Some("agentmux-bashwrap precompact --trigger=manual")),
            "auto-injected PreCompact manual entry must still be present"
        );
        assert!(
            pre_compact.iter().any(|e| e["hooks"][0]["command"].as_str()
                == Some("agentmux-bashwrap precompact --trigger=auto")),
            "auto-injected PreCompact auto entry must still be present"
        );
    }

    #[test]
    fn test_build_config_files_settings_json_merges_user_precompact_hooks() {
        // Same regression as above, but exercising the OTHER merge
        // branch: a user-supplied PreCompact entry living in
        // settings.json's own `"hooks"` key (content_map["settings"])
        // rather than the legacy content_map["hooks"] path. Both
        // branches in `build_settings_with_hooks` needed the fix.
        let mut content_map = HashMap::new();
        content_map.insert(
            "settings".to_string(),
            r#"{"hooks":{"PreCompact":[{"matcher":"auto","hooks":[{"type":"command","command":"my-settings-precompact"}]}]}}"#
                .to_string(),
        );
        let files = build_config_files(&content_map, &[], "Aria", "agent-1", "aria", "/tmp/aria", "claude");
        let settings = files
            .iter()
            .find(|f| f.filename == ".claude/settings.json")
            .expect("settings.json emitted");
        let parsed: Value = serde_json::from_str(&settings.content).unwrap();
        let pre_compact = parsed["hooks"]["PreCompact"]
            .as_array()
            .expect("PreCompact is an array");
        assert!(
            pre_compact
                .iter()
                .any(|e| e["hooks"][0]["command"].as_str() == Some("my-settings-precompact")),
            "user-supplied settings.json PreCompact entry must survive the merge"
        );
        assert!(
            pre_compact.iter().any(|e| e["hooks"][0]["command"].as_str()
                == Some("agentmux-bashwrap precompact --trigger=manual")),
            "auto-injected PreCompact manual entry must still be present"
        );
        assert!(
            pre_compact.iter().any(|e| e["hooks"][0]["command"].as_str()
                == Some("agentmux-bashwrap precompact --trigger=auto")),
            "auto-injected PreCompact auto entry must still be present"
        );
        // Settings-level user entries PREPEND before AgentMux's own, per
        // this merge path's ordering rule (mirrors PreToolUse).
        assert_eq!(
            pre_compact[0]["hooks"][0]["command"].as_str(),
            Some("my-settings-precompact"),
            "user PreCompact entries must prepend before AgentMux's own"
        );
    }

    /// SPEC_GLOBAL_MEMORY_DELIVERY_2026_09_27.md §7 P2: one SessionStart
    /// entry, a command per memory part, no matcher; a user's own
    /// SessionStart hooks survive both merge paths, before ours.
    #[test]
    fn test_build_settings_injects_sessionstart_memory_parts_and_keeps_user_hooks() {
        let ours: Vec<String> = (1..=crate::backend::memory_delivery::HOOK_PARTS)
            .map(|n| format!("agentmux-bashwrap sessionstart --part {n}"))
            .collect();
        let commands = |entry: &Value| -> Vec<String> {
            entry["hooks"].as_array().unwrap().iter().map(|h| h["command"].as_str().unwrap().to_string()).collect()
        };
        let session_start = |settings: Option<&str>, hooks: Option<&str>| -> Vec<Value> {
            let parsed: Value = serde_json::from_str(&build_settings_with_hooks(settings, hooks).unwrap()).unwrap();
            parsed["hooks"]["SessionStart"].as_array().unwrap().clone()
        };

        let plain = session_start(None, None);
        assert_eq!(plain.len(), 1);
        assert!(plain[0].get("matcher").is_none(), "the sidecar answers per source; no matcher");
        assert_eq!(commands(&plain[0]), ours);

        let legacy = session_start(None, Some(r#"{"SessionStart":[{"hooks":[{"type":"command","command":"my-start"}]}]}"#));
        assert_eq!(legacy.len(), 2);
        assert_eq!(commands(&legacy[0]), vec!["my-start"]);
        assert_eq!(commands(&legacy[1]), ours);

        let settings = session_start(
            Some(r#"{"hooks":{"SessionStart":[{"hooks":[{"type":"command","command":"my-settings-start"}]}]}}"#),
            None,
        );
        assert_eq!(settings.len(), 2, "a settings.json SessionStart hook is kept, not dropped");
        assert_eq!(commands(&settings[0]), vec!["my-settings-start"]);
        assert_eq!(commands(&settings[1]), ours);
    }

    /// Claude Code adds a Co-Authored-By trailer and a "Generated with" line
    /// unless `attribution` is empty; the repos' checks reject both.
    #[test]
    fn test_build_settings_hides_attribution_unless_the_agent_sets_it() {
        let attribution = |settings: Option<&str>| -> Value {
            let parsed: Value = serde_json::from_str(&build_settings_with_hooks(settings, None).unwrap()).unwrap();
            parsed["attribution"].clone()
        };
        assert_eq!(attribution(None), json!({ "commit": "", "pr": "" }));
        assert_eq!(attribution(Some(r#"{"model":"opus"}"#)), json!({ "commit": "", "pr": "" }));
        assert_eq!(
            attribution(Some(r#"{"attribution":{"commit":"Agent: Aria","pr":"Agent: Aria"}}"#)),
            json!({ "commit": "Agent: Aria", "pr": "Agent: Aria" }),
            "an agent's own attribution wins"
        );
        assert_eq!(
            attribution(Some(r#"{"attribution":{"commit":"Agent: Aria"}}"#)),
            json!({ "commit": "Agent: Aria", "pr": "" }),
            "a field the agent leaves out is still hidden, not Claude Code's default"
        );
        for malformed in [r#"null"#, r#"[]"#, r#""text""#, r#"{"commit":null,"pr":7}"#] {
            assert_eq!(
                attribution(Some(&format!(r#"{{"attribution":{malformed}}}"#))),
                json!({ "commit": "", "pr": "" }),
                "a malformed attribution ({malformed}) is replaced, not passed through"
            );
        }
        assert_eq!(
            attribution(Some(r#"{"attribution":{"commit":"Agent: Aria","pr":false}}"#)),
            json!({ "commit": "Agent: Aria", "pr": "" }),
        );
    }

    #[test]
    fn test_build_config_files_mcp_written() {
        let content_map = HashMap::new();
        let files = build_config_files(&content_map, &[], "Aria", "agent-1", "aria", "/tmp/aria", "claude");
        let mcp = files.iter().find(|f| f.filename == ".mcp.json").unwrap();
        let parsed: Value = serde_json::from_str(&mcp.content).unwrap();
        assert!(parsed["mcpServers"]["agentmux"].is_object());
    }

    #[test]
    fn test_build_config_files_expands_agent_slug_and_working_dir() {
        // REPORT_REPO_HEALTH_AUDIT_2026_07_20.md §1.3: AGENT_SLUG/WORKING_DIR
        // were missing from build_config_files's template vars (present in
        // the TS mirror, `buildConfigFiles` in agent-config-builder.ts), so
        // any soul/agentmd content
        // using {{AGENT_SLUG}} or {{WORKING_DIR}} was left unexpanded.
        let mut content_map = HashMap::new();
        content_map.insert(
            "soul".to_string(),
            "I am {{AGENT_SLUG}}, working in {{WORKING_DIR}}.".to_string(),
        );
        let files = build_config_files(
            &content_map,
            &[],
            "Aria",
            "agent-1",
            "aria",
            "/home/user/my-project",
            "claude",
        );
        let claude_md = files.iter().find(|f| f.filename == "CLAUDE.md").unwrap();
        assert!(claude_md.content.contains("I am aria, working in /home/user/my-project."));
    }

    // docs/specs/REPORT_JEKT_SIGNING_KEY_INJECTION_GAP_2026_08_16.md: this
    // function exists specifically so `agent.open` and `WriteAgentConfig`
    // (the actual "click Launch" path) can't drift out of sync on jekt/LAN
    // key injection the way they did before this fix.
    #[test]
    fn inject_jekt_signing_keys_into_mcp_json_patches_both_keys_into_the_env_block() {
        let store = crate::backend::storage::store::Store::open_in_memory().unwrap();
        let (_wan_dir, wan) = crate::backend::storage::wan_identity::attach_temp_wan_identity(&store);
        let content = serde_json::to_string(&json!({
            "mcpServers": { "agentmux": { "type": "stdio", "command": "agentmux-mcp", "env": { "AGENTMUX_AGENT_ID": "aria" } } }
        }))
        .unwrap();

        let rewritten = inject_jekt_signing_keys_into_mcp_json(&content, &store, "aria")
            .expect("both keys should ensure successfully against a fresh in-memory store");
        let parsed: Value = serde_json::from_str(&rewritten).unwrap();
        let env = &parsed["mcpServers"]["agentmux"]["env"];
        assert_eq!(env["AGENTMUX_AGENT_ID"], "aria", "existing fields must survive the patch");
        assert!(env["AGENTMUX_JEKT_KEY"].is_string() && !env["AGENTMUX_JEKT_KEY"].as_str().unwrap().is_empty());
        assert!(env["AGENTMUX_LAN_KEY"].is_string() && !env["AGENTMUX_LAN_KEY"].as_str().unwrap().is_empty());
        // WAN-tier signing: a separate keypair
        // from the LAN one, injected on the same terms.
        assert!(env["AGENTMUX_WAN_KEY"].is_string() && !env["AGENTMUX_WAN_KEY"].as_str().unwrap().is_empty());
        assert_ne!(
            env["AGENTMUX_WAN_KEY"], env["AGENTMUX_LAN_KEY"],
            "WAN and LAN keys must be independently minted — see storage/agent_wan_keys.rs for why \
             sharing one keypair across the two tiers is not an option"
        );
        // §2.1.2: the WAN signature binds the sending instance, so the host
        // label must travel with the key. A missing one would make the sender
        // sign under a different instance identity than srv publishes.
        // W3-S §2.2: that instance identity is now the id of the instance
        // that certifies the key, and the key is the one held in wan.db.
        assert_eq!(
            env["AGENTMUX_HOST_LABEL"],
            json!(wan.instance_ensure("unused").unwrap().instance_id),
            "the MCP env must carry the instance id that certifies this agent's WAN key"
        );
        assert_eq!(
            env["AGENTMUX_WAN_KEY"],
            json!(wan.agent_key_load("aria").unwrap().unwrap().private_key),
            "the WAN key must be the one held in the channel-wide wan.db"
        );
        // SPEC_JEKT_CROSS_CHANNEL_TRUST_2026_09_02.md Phase B: the channel the
        // sender signs under must be the one the shared registry publishes.
        assert_eq!(
            env["AGENTMUX_CHANNEL"],
            json!(crate::backend::reactive::registry::local_channel_id()),
            "the MCP env must carry the same channel id the shared registry entry is written under"
        );
    }

    #[test]
    fn inject_jekt_signing_keys_into_mcp_json_reuses_the_same_key_on_a_second_call() {
        let store = crate::backend::storage::store::Store::open_in_memory().unwrap();
        let content = serde_json::to_string(&json!({
            "mcpServers": { "agentmux": { "env": { "AGENTMUX_AGENT_ID": "aria" } } }
        }))
        .unwrap();

        let first = inject_jekt_signing_keys_into_mcp_json(&content, &store, "aria").unwrap();
        let second = inject_jekt_signing_keys_into_mcp_json(&content, &store, "aria").unwrap();
        let first_key = serde_json::from_str::<Value>(&first).unwrap()["mcpServers"]["agentmux"]["env"]["AGENTMUX_JEKT_KEY"].clone();
        let second_key = serde_json::from_str::<Value>(&second).unwrap()["mcpServers"]["agentmux"]["env"]["AGENTMUX_JEKT_KEY"].clone();
        assert_eq!(first_key, second_key, "minted-on-first-use key must be reused, not re-minted, on every materialization");
    }

    /// W3-S §2.2: without a `wan.db` the agent gets no WAN key and no
    /// instance label — never a key minted in `objects.db` instead. Host and
    /// LAN keys are unaffected.
    #[test]
    fn inject_jekt_signing_keys_gives_no_wan_key_without_a_wan_identity_store() {
        let store = crate::backend::storage::store::Store::open_in_memory().unwrap();
        let content = serde_json::to_string(&json!({
            "mcpServers": { "agentmux": { "env": { "AGENTMUX_AGENT_ID": "aria" } } }
        }))
        .unwrap();
        let rewritten = inject_jekt_signing_keys_into_mcp_json(&content, &store, "aria").unwrap();
        let env = serde_json::from_str::<Value>(&rewritten).unwrap()["mcpServers"]["agentmux"]["env"].clone();
        assert!(env["AGENTMUX_JEKT_KEY"].is_string());
        assert!(env["AGENTMUX_LAN_KEY"].is_string());
        assert!(env.get("AGENTMUX_WAN_KEY").is_none());
        assert!(env.get("AGENTMUX_HOST_LABEL").is_none());
        assert!(store.agent_wan_key_load("aria").unwrap().is_none(), "nothing minted in objects.db");
    }

    /// W3-S §2.2: an agent's existing `objects.db` WAN key is carried into
    /// `wan.db` on first use, so an agent upgraded onto D1 keeps its key.
    #[test]
    fn inject_jekt_signing_keys_imports_the_legacy_wan_key_once() {
        let store = crate::backend::storage::store::Store::open_in_memory().unwrap();
        let legacy = store.agent_wan_key_ensure("aria").unwrap();
        let (_wan_dir, wan) = crate::backend::storage::wan_identity::attach_temp_wan_identity(&store);
        let content = serde_json::to_string(&json!({
            "mcpServers": { "agentmux": { "env": { "AGENTMUX_AGENT_ID": "aria" } } }
        }))
        .unwrap();
        let rewritten = inject_jekt_signing_keys_into_mcp_json(&content, &store, "aria").unwrap();
        let env = serde_json::from_str::<Value>(&rewritten).unwrap()["mcpServers"]["agentmux"]["env"].clone();
        assert_eq!(env["AGENTMUX_WAN_KEY"], json!(legacy.private_key));
        assert!(wan.agent_key_load("aria").unwrap().unwrap().imported);
    }

    #[test]
    fn inject_jekt_signing_keys_into_mcp_json_returns_none_when_theres_no_env_object_to_patch() {
        let store = crate::backend::storage::store::Store::open_in_memory().unwrap();
        // No mcpServers.agentmux.env at all -- nothing to patch into.
        let content = serde_json::to_string(&json!({"hello": "world"})).unwrap();
        assert!(inject_jekt_signing_keys_into_mcp_json(&content, &store, "aria").is_none());
    }

    #[test]
    fn inject_jekt_signing_keys_into_mcp_json_returns_none_on_malformed_json() {
        let store = crate::backend::storage::store::Store::open_in_memory().unwrap();
        assert!(inject_jekt_signing_keys_into_mcp_json("not json", &store, "aria").is_none());
    }

    // ============================================================
    // write_startup_instructions_respecting_existing
    // (SPEC_PROVIDER_AWARE_STARTUP_INSTRUCTIONS_2026_08_24.md — codex P1, PR #2788)
    // ============================================================

    #[test]
    fn startup_instructions_fresh_working_dir_writes_directly_with_the_marker() {
        let dir = tempfile::tempdir().unwrap();
        write_startup_instructions_respecting_existing(dir.path(), "AGENTS.md", "Soul + AgentMD content")
            .unwrap();

        let content = std::fs::read_to_string(dir.path().join("AGENTS.md")).unwrap();
        assert!(content.starts_with(STARTUP_INSTRUCTIONS_MANAGED_MARKER));
        assert!(content.contains("Soul + AgentMD content"));
    }

    #[test]
    fn startup_instructions_agentmux_owned_file_is_freely_regenerated() {
        let dir = tempfile::tempdir().unwrap();
        write_startup_instructions_respecting_existing(dir.path(), "QWEN.md", "first version").unwrap();
        write_startup_instructions_respecting_existing(dir.path(), "QWEN.md", "second version").unwrap();

        let content = std::fs::read_to_string(dir.path().join("QWEN.md")).unwrap();
        assert!(content.contains("second version"));
        assert!(!content.contains("first version"), "regeneration must replace, not accumulate");
    }

    #[test]
    fn startup_instructions_foreign_file_content_is_never_touched() {
        // The exact regression codex P1 (PR #2788) flagged: a real project's
        // own AGENTS.md must survive an agent launch untouched, byte for
        // byte — no AgentMux marker, no partial merge, nothing.
        let dir = tempfile::tempdir().unwrap();
        let human_content = "# My real project\n\nHand-written AGENTS.md, no AgentMux involvement.";
        std::fs::write(dir.path().join("AGENTS.md"), human_content).unwrap();

        write_startup_instructions_respecting_existing(dir.path(), "AGENTS.md", "AgentMux's generated content")
            .unwrap();

        let content = std::fs::read_to_string(dir.path().join("AGENTS.md")).unwrap();
        assert_eq!(content, human_content, "every byte of the original file must survive");
        assert!(!content.contains("AgentMux's generated content"));
    }

    #[test]
    fn startup_instructions_foreign_empty_file_is_never_touched() {
        // An empty pre-existing file (no marker) is still foreign — the
        // decision hinges on the marker prefix, not on non-emptiness.
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("GEMINI.md"), "").unwrap();

        write_startup_instructions_respecting_existing(dir.path(), "GEMINI.md", "AgentMux's generated content")
            .unwrap();

        let content = std::fs::read_to_string(dir.path().join("GEMINI.md")).unwrap();
        assert_eq!(content, "");
    }

    #[test]
    fn startup_instructions_non_utf8_file_is_treated_as_foreign_not_missing() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("AGENTS.md");
        std::fs::write(&path, [0x23, 0x20, 0xFF, 0xFE, 0x0A]).unwrap();
        let raw_before = std::fs::read(&path).unwrap();

        write_startup_instructions_respecting_existing(dir.path(), "AGENTS.md", "generated content").unwrap();

        let raw_after = std::fs::read(&path).unwrap();
        assert_eq!(raw_before, raw_after, "an unreadable file must be treated as foreign, never as absent");
    }

    #[test]
    fn startup_instructions_creates_parent_directories_for_nested_paths() {
        // pi's target is .pi/APPEND_SYSTEM.md — a nested path with no
        // existing parent directory on a fresh working dir.
        let dir = tempfile::tempdir().unwrap();
        write_startup_instructions_respecting_existing(dir.path(), ".pi/APPEND_SYSTEM.md", "content").unwrap();

        let content = std::fs::read_to_string(dir.path().join(".pi/APPEND_SYSTEM.md")).unwrap();
        assert!(content.contains("content"));
    }

    // ============================================================
    // write_claude_md_respecting_ownership
    // (SPEC_CLAUDE_MD_OWNERSHIP_PROTECTION_2026_08_22.md)
    // ============================================================

    #[test]
    fn claude_md_fresh_working_dir_writes_directly_with_the_marker() {
        let dir = tempfile::tempdir().unwrap();
        write_claude_md_respecting_ownership(dir.path(), "Soul + AgentMD + Memory + Skills").unwrap();

        let content = std::fs::read_to_string(dir.path().join("CLAUDE.md")).unwrap();
        assert!(content.starts_with(CLAUDE_MD_MANAGED_MARKER));
        assert!(content.contains("Soul + AgentMD + Memory + Skills"));
        // No foreign-file side effects on the common (fresh dir) path.
        assert!(!dir.path().join(AGENTMUX_MEMORY_FILENAME).exists());
    }

    #[test]
    fn claude_md_agentmux_owned_file_is_freely_regenerated() {
        let dir = tempfile::tempdir().unwrap();
        write_claude_md_respecting_ownership(dir.path(), "first version").unwrap();
        write_claude_md_respecting_ownership(dir.path(), "second version").unwrap();

        let content = std::fs::read_to_string(dir.path().join("CLAUDE.md")).unwrap();
        assert!(content.contains("second version"));
        assert!(!content.contains("first version"), "regeneration must replace, not accumulate");
    }

    #[test]
    fn claude_md_foreign_file_content_is_never_touched() {
        let dir = tempfile::tempdir().unwrap();
        let human_content = "# My real project\n\nHand-written rules, no AgentMux marker.";
        std::fs::write(dir.path().join("CLAUDE.md"), human_content).unwrap();

        write_claude_md_respecting_ownership(dir.path(), "AgentMux's generated content").unwrap();

        let content = std::fs::read_to_string(dir.path().join("CLAUDE.md")).unwrap();
        assert!(content.starts_with(human_content), "every byte of the original file must survive, at the start");
        assert!(!content.contains("AgentMux's generated content"), "generated content must never land in the real file");
    }

    #[test]
    fn claude_md_non_utf8_file_is_treated_as_foreign_not_missing() {
        // reagent P0 + codex P1 on PR #2747: read_to_string(...).ok()
        // collapsed ANY read error (not just NotFound) into "no file
        // yet," so a non-UTF-8 (or otherwise unreadable) foreign file
        // got silently clobbered — the exact data-loss bug this whole
        // function exists to prevent.
        let dir = tempfile::tempdir().unwrap();
        let claude_md_path = dir.path().join("CLAUDE.md");
        // Invalid UTF-8: a lone continuation byte. read_to_string must
        // fail on this (not silently lossy-convert it).
        std::fs::write(&claude_md_path, [0x23, 0x20, 0xFF, 0xFE, 0x0A]).unwrap();
        let raw_before = std::fs::read(&claude_md_path).unwrap();

        write_claude_md_respecting_ownership(dir.path(), "AgentMux's generated content").unwrap();

        let raw_after = std::fs::read(&claude_md_path).unwrap();
        assert_eq!(raw_before, raw_after, "an unreadable foreign file's bytes must be completely untouched, not overwritten");
        // Best-effort side file is still written even though the
        // @import offer itself is skipped (nothing safe to append to).
        let side_file = std::fs::read_to_string(dir.path().join(AGENTMUX_MEMORY_FILENAME)).unwrap();
        assert_eq!(side_file, "AgentMux's generated content");
    }

    #[test]
    fn claude_md_foreign_file_gets_a_side_file_and_one_import_line() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("CLAUDE.md"), "# Real project\n").unwrap();

        write_claude_md_respecting_ownership(dir.path(), "the generated body").unwrap();

        let side_file = std::fs::read_to_string(dir.path().join(AGENTMUX_MEMORY_FILENAME)).unwrap();
        assert_eq!(side_file, "the generated body");

        let claude_md = std::fs::read_to_string(dir.path().join("CLAUDE.md")).unwrap();
        assert!(claude_md.contains(&format!("@{AGENTMUX_MEMORY_FILENAME}")));
        assert!(claude_md.contains(CLAUDE_MD_IMPORT_MARKER_COMMENT));
    }

    #[test]
    fn claude_md_import_line_is_never_duplicated_across_launches() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("CLAUDE.md"), "# Real project\n").unwrap();

        write_claude_md_respecting_ownership(dir.path(), "v1").unwrap();
        write_claude_md_respecting_ownership(dir.path(), "v2").unwrap();
        write_claude_md_respecting_ownership(dir.path(), "v3").unwrap();

        let claude_md = std::fs::read_to_string(dir.path().join("CLAUDE.md")).unwrap();
        let import_needle = format!("@{AGENTMUX_MEMORY_FILENAME}");
        assert_eq!(claude_md.matches(&import_needle).count(), 1, "the import line must appear exactly once, no matter how many launches");
        // The side file, unlike CLAUDE.md, keeps regenerating freely.
        let side_file = std::fs::read_to_string(dir.path().join(AGENTMUX_MEMORY_FILENAME)).unwrap();
        assert_eq!(side_file, "v3");
    }

    #[test]
    fn claude_md_concurrent_launches_against_a_shared_workdir_never_duplicate_the_import() {
        // reagent P2 (second review round) on PR #2747: two agents
        // sharing a working directory (agent_open.rs's shared-workdir
        // fallback) launching concurrently previously could both read
        // "not yet offered" and both append the import line — the only
        // existing serialization (agent_open_lock) is keyed by
        // agent_id, not by working directory. Real threads, not a
        // sequential simulation, to actually exercise the race.
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("CLAUDE.md"), "# Real project\n").unwrap();
        let dir_path = dir.path().to_path_buf();

        let barrier = std::sync::Arc::new(std::sync::Barrier::new(8));
        let handles: Vec<_> = (0..8)
            .map(|i| {
                let dir_path = dir_path.clone();
                let barrier = barrier.clone();
                std::thread::spawn(move || {
                    barrier.wait(); // maximize actual overlap
                    write_claude_md_respecting_ownership(&dir_path, &format!("content-{i}")).unwrap();
                })
            })
            .collect();
        for h in handles {
            h.join().unwrap();
        }

        let claude_md = std::fs::read_to_string(dir.path().join("CLAUDE.md")).unwrap();
        let import_needle = format!("@{AGENTMUX_MEMORY_FILENAME}");
        assert_eq!(
            claude_md.matches(&import_needle).count(),
            1,
            "8 concurrent launches against the same foreign CLAUDE.md must still produce exactly one import line, not one per racer"
        );
    }

    #[test]
    fn claude_md_marker_is_rolled_back_when_the_append_fails() {
        // reagent P1 + codex, third review round on PR #2747: winning the
        // create_new race must not permanently record "offered" if the
        // append itself then fails -- otherwise every later launch's
        // create_new hits AlreadyExists and the import is never offered
        // again, with no retry path.
        let dir = tempfile::tempdir().unwrap();
        let claude_md_path = dir.path().join("CLAUDE.md");
        std::fs::write(&claude_md_path, "# Real project\n").unwrap();

        // Read-only so the append's .open(...) fails, even though the
        // read earlier in the function (which only needs read access)
        // succeeds fine.
        let mut perms = std::fs::metadata(&claude_md_path).unwrap().permissions();
        perms.set_readonly(true);
        std::fs::set_permissions(&claude_md_path, perms).unwrap();

        write_claude_md_respecting_ownership(dir.path(), "v1").unwrap();

        let marker_path = dir.path().join(CLAUDE_MD_OWNERSHIP_MARKER_PATH);
        assert!(!marker_path.exists(), "a failed append must roll back the ownership marker so a future launch can retry");

        // Restore write access and confirm a later launch actually succeeds.
        let mut perms = std::fs::metadata(&claude_md_path).unwrap().permissions();
        #[allow(clippy::permissions_set_readonly_false)]
        perms.set_readonly(false);
        std::fs::set_permissions(&claude_md_path, perms).unwrap();

        write_claude_md_respecting_ownership(dir.path(), "v2").unwrap();
        let claude_md = std::fs::read_to_string(&claude_md_path).unwrap();
        let import_needle = format!("@{AGENTMUX_MEMORY_FILENAME}");
        assert_eq!(claude_md.matches(&import_needle).count(), 1, "retry after the file becomes writable again must succeed");
    }

    #[test]
    fn claude_md_user_deleted_import_line_is_never_reinserted() {
        // The whole point of the ownership marker file: once offered, a
        // user's deliberate removal of the import line must stick.
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("CLAUDE.md"), "# Real project\n").unwrap();
        write_claude_md_respecting_ownership(dir.path(), "v1").unwrap();

        // User opts out: deletes the import line by hand.
        std::fs::write(dir.path().join("CLAUDE.md"), "# Real project\n").unwrap();

        write_claude_md_respecting_ownership(dir.path(), "v2").unwrap();

        let claude_md = std::fs::read_to_string(dir.path().join("CLAUDE.md")).unwrap();
        assert_eq!(claude_md, "# Real project\n", "import line must not silently reappear after the user removed it");
        // The side file still refreshes even though nothing links to it
        // from CLAUDE.md anymore — harmless, and keeps it ready if the
        // user re-adds the import line themselves later.
        let side_file = std::fs::read_to_string(dir.path().join(AGENTMUX_MEMORY_FILENAME)).unwrap();
        assert_eq!(side_file, "v2");
    }
}

#[cfg(test)]
mod bundle_section_heading_tests {
    use super::BUNDLE_SECTION_HEADING;

    /// Pins the persisted heading. `frontend/app/view/agent/agent-config-builder.ts`
    /// pushes the identical literal; if this test fails, change both sides in
    /// the same release or the global-bundle injector falls back to appending
    /// a second heading after the per-agent content.
    #[test]
    fn heading_matches_frontend_builder_literal() {
        assert_eq!(BUNDLE_SECTION_HEADING, "# Memory");
    }
}

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

    #[test]
    fn recognizes_both_marker_classes() {
        // The bug this exists to prevent: a check against CLAUDE.md's marker
        // alone reports every generated AGENTS.md / GEMINI.md / QWEN.md /
        // .pi/APPEND_SYSTEM.md as foreign (Codex, PR #3144).
        assert!(is_agentmux_managed_instructions(&format!(
            "{CLAUDE_MD_MANAGED_MARKER}\n\n# Memory\n"
        )));
        assert!(is_agentmux_managed_instructions(&format!(
            "{STARTUP_INSTRUCTIONS_MANAGED_MARKER}\n\nBe helpful.\n"
        )));
    }

    #[test]
    fn a_foreign_file_is_not_ours_however_it_starts() {
        assert!(!is_agentmux_managed_instructions("# My project\n\nRules.\n"));
        assert!(!is_agentmux_managed_instructions(""));
        // The marker has to be at the START — a file that merely mentions it
        // further down was not written by us.
        assert!(!is_agentmux_managed_instructions(&format!(
            "Someone pasted this below:\n{CLAUDE_MD_MANAGED_MARKER}\n"
        )));
    }
}

#[cfg(test)]
mod mcp_json_tests {
    //! #3680: `.mcp.json` keeps a user's own servers and is owner-only.
    use super::*;

    fn mcp_servers_of(dir: &std::path::Path) -> serde_json::Map<String, serde_json::Value> {
        let raw = std::fs::read_to_string(dir.join(".mcp.json")).unwrap();
        let v: serde_json::Value = serde_json::from_str(&raw).unwrap();
        v["mcpServers"].as_object().unwrap().clone()
    }

    const GENERATED_MCP: &str = r#"{"mcpServers":{"agentmux":{"command":"agentmux-mcp","env":{"AGENTMUX_AGENT_ID":"a1"}},"github":{"command":"gh-mcp"}}}"#;

    #[test]
    fn mcp_json_fresh_dir_is_written_as_generated() {
        let dir = tempfile::tempdir().unwrap();
        write_mcp_json_respecting_user_servers(dir.path(), GENERATED_MCP).unwrap();
        let servers = mcp_servers_of(dir.path());
        assert_eq!(servers.keys().collect::<Vec<_>>(), vec!["agentmux", "github"]);
    }

    /// ReAgent on #4141: a symlinked `.mcp.json`, even one pointing inside
    /// the workdir, is left alone and the launch goes on.
    #[test]
    fn mcp_json_a_symlinked_file_is_left_alone_without_failing_the_launch() {
        let dir = tempfile::tempdir().unwrap();
        let target = dir.path().join("my-mcp.json");
        std::fs::write(&target, r#"{"mcpServers":{}}"#).unwrap();
        #[cfg(unix)]
        let made = std::os::unix::fs::symlink(&target, dir.path().join(".mcp.json")).is_ok();
        #[cfg(windows)]
        let made = std::os::windows::fs::symlink_file(&target, dir.path().join(".mcp.json")).is_ok();
        if !made {
            return;
        }
        write_mcp_json_respecting_user_servers(dir.path(), GENERATED_MCP).unwrap();
        assert!(std::fs::symlink_metadata(dir.path().join(".mcp.json")).unwrap().file_type().is_symlink());
        assert_eq!(std::fs::read_to_string(&target).unwrap(), r#"{"mcpServers":{}}"#);
    }

    /// Codex on #4141: with `.claude` linking outside, the ownership manifest
    /// can't be written, so `.mcp.json` isn't either; otherwise the second
    /// launch would take the user's own server for AgentMux's and drop it.
    #[test]
    fn mcp_json_a_users_server_survives_two_launches_with_claude_linking_outside() {
        let dir = tempfile::tempdir().unwrap();
        let outside = tempfile::tempdir().unwrap();
        #[cfg(unix)]
        let made = std::os::unix::fs::symlink(outside.path(), dir.path().join(".claude")).is_ok();
        #[cfg(windows)]
        let made = std::os::windows::fs::symlink_dir(outside.path(), dir.path().join(".claude")).is_ok();
        if !made {
            return;
        }
        let users = r#"{"mcpServers":{"mine":{"command":"my-mcp"}}}"#;
        std::fs::write(dir.path().join(".mcp.json"), users).unwrap();
        write_mcp_json_respecting_user_servers(dir.path(), GENERATED_MCP).unwrap();
        write_mcp_json_respecting_user_servers(dir.path(), GENERATED_MCP).unwrap();
        assert!(mcp_servers_of(dir.path()).contains_key("mine"));
        assert!(std::fs::read_dir(outside.path()).unwrap().next().is_none(), "nothing written outside");
    }

    #[test]
    fn mcp_json_a_users_own_servers_and_keys_survive_the_launch() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(
            dir.path().join(".mcp.json"),
            r#"{"mcpServers":{"postgres":{"command":"pg-mcp"}},"someOtherKey":true}"#,
        )
        .unwrap();
        write_mcp_json_respecting_user_servers(dir.path(), GENERATED_MCP).unwrap();
        let servers = mcp_servers_of(dir.path());
        assert!(servers.contains_key("postgres"), "the user's server must survive");
        assert!(servers.contains_key("agentmux"));
        assert!(servers.contains_key("github"));
        let raw = std::fs::read_to_string(dir.path().join(".mcp.json")).unwrap();
        assert!(raw.contains("someOtherKey"), "other top-level keys must survive");
    }

    #[test]
    fn mcp_json_a_server_unbound_since_the_last_launch_is_removed_but_the_users_is_not() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join(".mcp.json"), r#"{"mcpServers":{"postgres":{"command":"pg-mcp"}}}"#).unwrap();
        write_mcp_json_respecting_user_servers(dir.path(), GENERATED_MCP).unwrap();
        // Next launch: `github` was unbound in Connectors.
        write_mcp_json_respecting_user_servers(dir.path(), r#"{"mcpServers":{"agentmux":{"command":"agentmux-mcp"}}}"#)
            .unwrap();
        let servers = mcp_servers_of(dir.path());
        assert!(!servers.contains_key("github"), "a server AgentMux wrote and no longer wants must go");
        assert!(servers.contains_key("postgres"), "the user's server must still be there");
        assert!(servers.contains_key("agentmux"));
    }

    #[test]
    fn mcp_json_without_a_manifest_an_agentmux_written_file_is_regenerated_as_before() {
        // A file an older AgentMux wrote: has our `agentmux` entry, no manifest.
        // All of it is ours, so a stale server from an old definition goes.
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(
            dir.path().join(".mcp.json"),
            r#"{"mcpServers":{"agentmux":{"command":"old"},"stale":{"command":"x"}}}"#,
        )
        .unwrap();
        write_mcp_json_respecting_user_servers(dir.path(), GENERATED_MCP).unwrap();
        let servers = mcp_servers_of(dir.path());
        assert!(!servers.contains_key("stale"));
        assert_eq!(servers["agentmux"]["command"], "agentmux-mcp");
    }

    #[test]
    fn mcp_json_our_entry_wins_a_name_clash() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join(".mcp.json"), r#"{"mcpServers":{"github":{"command":"users-own"}}}"#).unwrap();
        write_mcp_json_respecting_user_servers(dir.path(), GENERATED_MCP).unwrap();
        assert_eq!(mcp_servers_of(dir.path())["github"]["command"], "gh-mcp");
    }

    #[test]
    fn mcp_json_a_file_that_is_not_a_json_object_is_left_untouched() {
        for body in ["{ not json", "[1,2]", r#"{"mcpServers":[]}"#] {
            let dir = tempfile::tempdir().unwrap();
            std::fs::write(dir.path().join(".mcp.json"), body).unwrap();
            write_mcp_json_respecting_user_servers(dir.path(), GENERATED_MCP).unwrap();
            assert_eq!(std::fs::read_to_string(dir.path().join(".mcp.json")).unwrap(), body);
        }
    }

    #[test]
    fn mcp_json_rejects_generated_content_that_is_not_json() {
        let dir = tempfile::tempdir().unwrap();
        assert!(write_mcp_json_respecting_user_servers(dir.path(), "nope").is_err());
        assert!(!dir.path().join(".mcp.json").exists());
    }

    #[test]
    fn mcp_json_leaves_no_temp_file_behind() {
        let dir = tempfile::tempdir().unwrap();
        write_mcp_json_respecting_user_servers(dir.path(), GENERATED_MCP).unwrap();
        let leftovers: Vec<_> = std::fs::read_dir(dir.path())
            .unwrap()
            .filter_map(|e| e.ok())
            .filter(|e| e.file_name().to_string_lossy().contains("agentmux-tmp"))
            .collect();
        assert!(leftovers.is_empty());
    }

    #[test]
    fn mcp_json_concurrent_launches_into_one_dir_never_publish_corrupt_json() {
        // ReAgent P1 on #3803: a per-process temp name let two same-srv writes
        // interleave into one temp file before either rename. Many writers of
        // differently sized content maximise the chance of interleaving.
        let dir = tempfile::tempdir().unwrap();
        let base = dir.path().to_path_buf();
        let handles: Vec<_> = (0..16)
            .map(|i| {
                let base = base.clone();
                std::thread::spawn(move || {
                    // Each "agent" brings its own extra server, so a manifest from
                    // one launch paired with the file from another is detectable.
                    let padding = "x".repeat(i * 4096);
                    let content = format!(
                        r#"{{"mcpServers":{{"agentmux":{{"command":"agentmux-mcp","env":{{"AGENTMUX_AGENT_ID":"a{i}","PAD":"{padding}"}}}},"srv{i}":{{"command":"s{i}"}}}}}}"#
                    );
                    for _ in 0..10 {
                        write_mcp_json_respecting_user_servers(&base, &content).unwrap();
                    }
                })
            })
            .collect();
        for h in handles {
            h.join().unwrap();
        }
        let raw = std::fs::read_to_string(base.join(".mcp.json")).unwrap();
        let v: serde_json::Value = serde_json::from_str(&raw).expect("published .mcp.json must be valid JSON");
        assert!(v["mcpServers"]["agentmux"].is_object());
        let manifest = std::fs::read_to_string(base.join(MANAGED_MCP_SERVERS_MANIFEST)).unwrap();
        let managed: std::collections::BTreeSet<String> =
            serde_json::from_str(&manifest).expect("the manifest must not be interleaved either");
        // ReAgent P1 (round 2) on #3803: the manifest must describe the SAME
        // launch as the file. With no user servers here, that means exactly
        // the file's server names — and exactly one agent's set.
        let on_disk: std::collections::BTreeSet<String> =
            v["mcpServers"].as_object().unwrap().keys().cloned().collect();
        assert_eq!(managed, on_disk, "manifest and .mcp.json describe different launches");
        assert_eq!(on_disk.len(), 2, "exactly one launch's servers (agentmux + its own), got {on_disk:?}");
        for d in [base.clone(), base.join(".claude")] {
            let leftovers = std::fs::read_dir(&d)
                .unwrap()
                .filter_map(|e| e.ok())
                .filter(|e| e.file_name().to_string_lossy().contains("agentmux-tmp"))
                .count();
            assert_eq!(leftovers, 0, "temp files left in {}", d.display());
        }
    }

    #[cfg(unix)]
    #[test]
    fn mcp_json_is_owner_only_on_unix_even_when_replacing_a_0644_file() {
        use std::os::unix::fs::PermissionsExt;
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join(".mcp.json");
        std::fs::write(&path, r#"{"mcpServers":{}}"#).unwrap();
        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).unwrap();
        write_mcp_json_respecting_user_servers(dir.path(), GENERATED_MCP).unwrap();
        assert_eq!(std::fs::metadata(&path).unwrap().permissions().mode() & 0o777, 0o600);
    }
}