agentmux_srv/server/app_api/

agent_open.rs

use super::*;

/// Per-agent-definition async lock serializing `agent.open`'s "check for a
/// live block / seed resume session / create block / register controller"
/// sequence.
///
/// Without this, two concurrent `agent.open` calls for the same agent (a
/// double-invocation, or two tabs opened for the same agent close together)
/// can both observe "not live yet" before either controller actually
/// registers — `CreateBlock` dispatch, the layout-action enqueue, and
/// `write_agent_config_files` all await in between — and both seed the same
/// `resume_session_id`, spawning two controllers that `--resume` the
/// identical provider session concurrently. That's the TOCTOU reagent
/// flagged on PR #2059's first concurrency-guard attempt (the earlier
/// single-point-in-time `agent_live_elsewhere` check closed the
/// already-live case but not the still-racing-to-become-live case).
///
/// Scope note: this only serializes calls handled by THIS process — like
/// the in-memory `CONTROLLER_REGISTRY` it guards, it can't see a genuinely
/// different AgentMux instance/channel racing the same registry entry.
/// Same boundary the live-elsewhere check already accepted.
static AGENT_OPEN_LOCKS: std::sync::LazyLock<
    std::sync::Mutex<std::collections::HashMap<String, Arc<tokio::sync::Mutex<()>>>>,
> = std::sync::LazyLock::new(|| std::sync::Mutex::new(std::collections::HashMap::new()));

fn agent_open_lock(agent_id: &str) -> Arc<tokio::sync::Mutex<()>> {
    let mut locks = AGENT_OPEN_LOCKS.lock().unwrap_or_else(|e| e.into_inner());
    locks
        .entry(agent_id.to_string())
        .or_insert_with(|| Arc::new(tokio::sync::Mutex::new(())))
        .clone()
}

/// How long `agent.open` waits for a missing pinned CLI to install before telling
/// the caller to retry. The install is not cancelled when this elapses.
const AGENT_OPEN_INSTALL_WAIT_SECS: u64 = 150;

/// Resolve the `(env_var, value)` pair to inject for this agent's model
/// vendor override, if any — redirects the harness at a non-default
/// backend (e.g. `ANTHROPIC_BASE_URL` for a `claude`-provider agent).
/// Pure — no I/O — so it's directly unit-testable without the full
/// async spawn-time harness this is called from.
///
/// `None` when there's nothing to override (empty `model_vendor_base_url`)
/// OR the provider doesn't declare `base_url_env_var` — the latter should
/// already be impossible by the time an agent reaches spawn (rejected at
/// `agent.define`), but this stays defensive rather than trusting that
/// write-time validation is the only thing that can ever set this field.
/// Resolve the CLI argv for spawning `provider`'s process under `controller_type`
/// (the string form: `"persistent"` / `"subprocess"` / `"acp"` / `"app-server"`).
/// Pure — no I/O — so it's directly unit-testable without the full async
/// spawn-time harness this is called from.
///
/// ReAgent P1 on PR #3215: this used to only branch on `"persistent"`, so an
/// `"app-server"` controller silently fell back to `provider.launch_args` —
/// Codex's one-shot `exec --json` args — instead of `provider.app_server`'s
/// `--listen stdio://` args. The spawned child would never complete the App
/// Server handshake once the provider registry flips a provider's controller
/// type to `AppServer`.
fn resolve_cli_args(provider: &providers::ProviderConfig, controller_type: &str) -> Vec<String> {
    let args: &[&str] = match controller_type {
        "persistent" => provider.persistent_launch_args.unwrap_or(provider.launch_args),
        "app-server" => provider
            .app_server
            .as_ref()
            .map(|app_server| app_server.launch_args)
            .unwrap_or(provider.launch_args),
        _ => provider.launch_args,
    };
    args.iter().map(|s| s.to_string()).collect()
}

fn resolve_vendor_env_override(
    provider: &providers::ProviderConfig,
    agent: &AgentDefinition,
) -> Option<(&'static str, String)> {
    if agent.model_vendor_base_url.is_empty() {
        return None;
    }
    provider
        .base_url_env_var
        .map(|var| (var, agent.model_vendor_base_url.clone()))
}

// resolve_effective_provider_id (and its store-lookup helper) moved to
// Store::resolve_effective_provider_id in backend/storage/agents/definition.rs
// (2026-08-15) — the identical resolution logic was independently
// duplicated in identity/resolver/inject.rs's layer-3 credential gate,
// found reading agent.provider directly (the same mstore-vs-id_store
// class of bug this file's own version was fixed for in round 3 of PR
// #2587's review). Consolidated so both call sites share one
// implementation and can't drift on it separately again — see that
// method's own doc comment for the full history and the tests that
// moved with it.

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

    fn base_agent(model_vendor_base_url: &str) -> AgentDefinition {
        AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: "a1".to_string(),
            slug: "a1".to_string(),
            name: "T".to_string(),
            icon: String::new(),
            provider: "claude".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: "host".to_string(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: model_vendor_base_url.to_string(),
            memory_id: String::new(),
        }
    }

    #[test]
    fn returns_none_when_override_is_unset() {
        let provider = providers::get_provider("claude").unwrap();
        let agent = base_agent("");
        assert!(resolve_vendor_env_override(provider, &agent).is_none());
    }

    #[test]
    fn returns_the_env_var_and_value_for_a_supporting_provider() {
        let provider = providers::get_provider("claude").unwrap();
        let agent = base_agent("https://my-proxy.example.com");
        assert_eq!(
            resolve_vendor_env_override(provider, &agent),
            Some(("ANTHROPIC_BASE_URL", "https://my-proxy.example.com".to_string()))
        );
    }

    #[test]
    fn returns_none_for_a_non_supporting_provider_even_if_the_field_is_set() {
        // Defensive: shouldn't be reachable in practice (agent.define
        // rejects this combination), but a non-supporting provider must
        // never get a spurious env var injected.
        let provider = providers::get_provider("codex").unwrap();
        let agent = base_agent("https://my-proxy.example.com");
        assert!(resolve_vendor_env_override(provider, &agent).is_none());
    }
}

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

    #[test]
    fn persistent_controller_uses_persistent_launch_args() {
        let provider = providers::get_provider("claude").unwrap();
        assert_eq!(
            resolve_cli_args(provider, "persistent"),
            provider.persistent_launch_args.unwrap().to_vec()
        );
    }

    #[test]
    fn subprocess_controller_uses_the_default_launch_args() {
        let provider = providers::get_provider("codex").unwrap();
        assert_eq!(resolve_cli_args(provider, "subprocess"), provider.launch_args.to_vec());
    }

    /// ReAgent P1 on PR #3215: this is the bug fix. Before it, an
    /// `"app-server"` controller_type fell into the `else` branch and got
    /// Codex's one-shot `exec --json` args — the App Server child would spawn
    /// but never see `--listen stdio://`, so it never speaks the App Server
    /// protocol and the handshake in `AppServerController::start` hangs until
    /// `INITIALIZE_TIMEOUT`.
    #[test]
    fn app_server_controller_uses_the_app_server_launch_args_not_the_one_shot_ones() {
        let provider = providers::get_provider("codex").unwrap();
        let app_server_args = provider.app_server.as_ref().unwrap().launch_args.to_vec();

        let resolved = resolve_cli_args(provider, "app-server");

        assert_eq!(resolved, app_server_args);
        assert_ne!(
            resolved,
            provider.launch_args.to_vec(),
            "must not silently fall back to the one-shot exec args"
        );
    }

    /// Defensive: a provider with no `app_server` config (everything except
    /// Codex today) must not panic if `controller_type` is somehow
    /// `"app-server"` for it — fall back to the ordinary launch args instead.
    #[test]
    fn app_server_controller_type_falls_back_gracefully_for_a_provider_without_one() {
        let provider = providers::get_provider("claude").unwrap();
        assert!(provider.app_server.is_none());
        assert_eq!(resolve_cli_args(provider, "app-server"), provider.launch_args.to_vec());
    }
}

/// The agent `agent.open` opens: a user agent (`is_seeded == 0`), named by
/// definition id or by display name (ASCII case-insensitive) — its id first,
/// then its name. Only when no user agent answers is a template consulted,
/// and then only to refuse it with `TEMPLATE_NOT_OPENABLE`: opening one would
/// launch a session that is no agent's (spec §6.5.8, template sessions); an
/// agent is created from a template in the picker. A template's id is its
/// lowercase name (`claude`), which a user agent created from it shares
/// case-insensitively, so templates must never be matched first.
fn select_openable_agent<'a>(
    agents: &'a [AgentDefinition],
    wanted: &str,
) -> Result<&'a AgentDefinition, String> {
    let names = |a: &&AgentDefinition| a.id == wanted || a.name.eq_ignore_ascii_case(wanted);
    let users = || agents.iter().filter(|a| a.is_seeded == 0);
    let found = users()
        .find(|a| a.id == wanted)
        .or_else(|| users().find(|a| a.name.eq_ignore_ascii_case(wanted)))
        .or_else(|| agents.iter().find(names))
        .ok_or_else(|| format!("AGENT_NOT_FOUND: no agent definition with id '{wanted}'"))?;
    if found.is_seeded != 0 {
        return Err(format!(
            "TEMPLATE_NOT_OPENABLE: '{}' is a template; agent.open opens an agent from My Agents — create an agent from this template in the agent picker first",
            found.name
        ));
    }
    Ok(found)
}

/// Identity M4b-4 (spec §6.5.8): a user agent's local row, backfilled from
/// the shared registry if it is another channel's — and **confirmed**, or the
/// open fails: without a local row the spawn would resolve to nothing, with
/// no UID/token and no credential gate, exactly the process M4b closes (Codex
/// P1 on #3584). `agent_def_list` listed the agent, so a missing row here is a
/// failed backfill, not a missing agent.
fn require_local_agent_row(mstore: &Store, agent_id: &str) -> Result<(), String> {
    match mstore.agent_row_ensure_local(agent_id) {
        Ok(true) => Ok(()),
        Ok(false) => Err(format!(
            "AGENT_ROW_UNAVAILABLE: could not create a local row for agent '{agent_id}' — not started"
        )),
        Err(e) => Err(format!(
            "AGENT_ROW_UNAVAILABLE: local row for agent '{agent_id}' could not be read or created ({e}) — not started"
        )),
    }
}

/// Identity M4b-4 (spec §6.5.8): record `agent.open`'s launch of user agent
/// `agent_id` on `block_id` — a lifecycle-only update, never
/// `instance_create` with a fresh record (whose fold would blank the agent's
/// account, bundle and workspace) — and stamp the block with the row id.
/// A row that is gone (the agent deleted mid-open — the delete handlers do
/// not take `AGENT_OPEN_LOCKS`) or a failed write **fails the open**: the
/// spawn would otherwise resolve to nothing, tokenless and past the
/// credential gate (Codex P1 on #3584). A failed stamp is only logged — for a
/// user agent the block's `agentId` already names its row.
fn record_agent_open_launch(mstore: &Store, agent_id: &str, block_id: &str) -> Result<(), String> {
    let now = agentmux_common::time::now_ms();
    match mstore.instance_record_launch(agent_id, block_id, now) {
        Ok(true) => {
            let mut stamp = obj::MetaMapType::new();
            stamp.insert("agentInstanceId".to_string(), json!(agent_id));
            if let Err(e) = crate::server::service::update_object_meta(
                mstore,
                &format!("block:{block_id}"),
                &stamp,
            ) {
                tracing::warn!(agent_id, block_id, error = %e, "agent.open: stamping the block failed");
            }
        }
        Ok(false) => {
            return Err(format!(
                "AGENT_ROW_UNAVAILABLE: agent '{agent_id}' has no local row to record the launch on (deleted?) — not started"
            ));
        }
        Err(e) => {
            return Err(format!(
                "AGENT_ROW_UNAVAILABLE: recording the launch of agent '{agent_id}' failed ({e}) — not started"
            ));
        }
    }
    Ok(())
}

pub fn register(engine: &Arc<WshRpcEngine>, state: &AppState) {
    register_agent_open(engine, state);
}

fn register_agent_open(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let app_state = state.clone();

    engine.register_typed(COMMAND_AGENT_OPEN, move |cmd: CommandAgentOpenData, _ctx| {
        let app_state = app_state.clone();
        async move { open_agent_impl(&app_state, cmd).await }
    });
}

/// The `agent.open` implementation — load the definition, resolve the
/// provider/CLI, create the block, enqueue the layout insert, and register
/// the controller. Extracted from the RPC closure so the HTTP surface
/// (`POST /api/v1/agent/open`, backing the `OpenAgent` MCP tool) shares this
/// exact code path instead of re-deriving it: the TOCTOU serialization via
/// `AGENT_OPEN_LOCKS` (reagent P1 on PR #2059), the ABF provider shadowing,
/// the resume-session seeding guard, and the CLI path resolution all live
/// here once. Same extraction shape as `open_pane` / `handle_pane_open`.
/// See docs/reports/REPORT_AGENT_OPEN_API_GAP_2026_09_06.md.
pub(crate) async fn open_agent_impl(
    state: &AppState,
    cmd: CommandAgentOpenData,
) -> Result<AgentOpenResult, String> {
    open_agent_inner(state, cmd, None).await
}

/// `agent.open`, but launching into an existing, empty agent pane
/// (`{view:"agent"}`, the picker) instead of creating a new one and
/// inserting it into the layout. Used by Layouts → Open layout…
/// (`SPEC_LAYOUT_FILES_2026_09_25.md` §3.5), which rebuilds the saved split
/// tree first and then launches each agent into its placeholder — so every
/// check `agent.open` makes (admission, one live instance, provider, CLI,
/// resume, config files) applies unchanged. If the agent is already open in
/// this tab, that pane is returned and the placeholder is left as a picker.
pub(crate) async fn open_agent_into_block(
    state: &AppState,
    agent_id: &str,
    tab_id: &str,
    block_id: &str,
) -> Result<AgentOpenResult, String> {
    open_agent_inner(
        state,
        CommandAgentOpenData {
            agent_id: agent_id.to_string(),
            tab_id: Some(tab_id.to_string()),
            split_direction: None,
            split_reference_block_id: None,
            focus: Some(false),
        },
        Some(block_id),
    )
    .await
}

async fn open_agent_inner(
    state: &AppState,
    cmd: CommandAgentOpenData,
    into_block: Option<&str>,
) -> Result<AgentOpenResult, String> {
    let mstore = state.mstore.clone();
    let broker = state.broker.clone();
    let event_bus = state.event_bus.clone();
    let filestore = state.filestore.clone();
    // Owned handle so the reducer-dispatch sites below read exactly as they
    // did inside the RPC closure (which captured an owned clone).
    let app_state = state.clone();

    tracing::info!(agent_id = %cmd.agent_id, "agent.open");

                // 1. Load the agent definition (by id or name)
                let agents = mstore.agent_def_list()
                    .map_err(|e| format!("agent.open: {e}"))?;
                let mut agent = select_openable_agent(&agents, &cmd.agent_id)?.clone();

                // Settle `agent.provider` once through the shared resolver
                // (the agent's own, or its bundle's when it has none; see
                // Store::resolve_effective_provider_id) instead of at every
                // downstream read in this handler. MUST be
                // app_state.id_store, never mstore.
                agent.provider = app_state.id_store.resolve_effective_provider_id(&agent);

                // Serialize the rest of this handler per agent definition —
                // held until the function returns (guard drops at every exit
                // path, success or error). See AGENT_OPEN_LOCKS' doc comment.
                let open_lock = agent_open_lock(&agent.id);
                let _open_guard = open_lock.lock().await;

                // One live instance per agent across every AgentMux instance
                // on this host (SPEC_AGENT_SINGLE_LIVE_INSTANCE_2026_09_24
                // Phase 1, I9) — checked before this handler writes anything
                // on the agent's behalf. The in-process checks below only see
                // this srv; this sees the others.
                crate::backend::agent_admission::check_before_spawn(
                    crate::backend::agent_admission::lease_store_for(mstore.shared_agent_registry()),
                    &agent.id,
                    &agent.name,
                    &app_state.boot_id,
                )
                .await
                .map_err(|refusal| format!("AGENT_LIVE_ELSEWHERE: {refusal}"))?;

                // Identity M4b-4 (spec §6.5.8): a user agent known only from
                // the shared registry (another channel's) gets its local row
                // before any spawn, so its block resolves to it. Templates
                // were refused above.
                require_local_agent_row(&mstore, &agent.id)?;

                // 2. Resolve provider
                let provider = providers::get_provider(&agent.provider)
                    .ok_or_else(|| format!("INVALID_PROVIDER: unknown provider '{}'", agent.provider))?;

                // 3. Determine tab
                let tab_id = resolve_tab_id(&mstore, cmd.tab_id.as_deref())?;

                // 4. Check for existing agent pane in this tab (idempotent)
                // Use resolved agent.id (not raw user input which could be a name)
                if let Some(existing) = find_agent_block(&mstore, &tab_id, &agent.id)? {
                    // Ensure the controller is registered (may be missing if block
                    // was created by the frontend without backend initialization)
                    if blockcontroller::get_controller(&existing.oid).is_none() {
                        let controller_type = if agent.agent_type == "container" {
                            "subprocess"
                        } else {
                            provider.controller_type_str()
                        };
                        // Set essential metadata if missing
                        let mut meta_update = obj::MetaMapType::new();
                        meta_update.insert("controller".to_string(), json!(controller_type));
                        meta_update.insert("agentProvider".to_string(), json!(&agent.provider));
                        let _ = crate::server::service::update_object_meta(
                            &mstore, &format!("block:{}", existing.oid), &meta_update,
                        );
                        // Identity M4b-4: record the launch before the
                        // resync — a controller can report its session id
                        // during it, and that capture finds the row by
                        // block (Codex P2 on #3584). Only on this branch's
                        // resync, never for a pane that is already live.
                        record_agent_open_launch(&mstore, &agent.id, &existing.oid)?;
                        // Register controller
                        let block_for_resync = mstore.must_get::<Block>(&existing.oid)
                            .map_err(|e| format!("agent.open: reload block: {e}"))?;
                        let _ = blockcontroller::resync_controller(
                            &block_for_resync, &tab_id, None, true, true,
                            Some(broker.clone()), Some(event_bus.clone()), Some(mstore.clone()),
                            Some(filestore.clone()),
                            Some(app_state.id_store.clone()), Some(app_state.identity_store.clone()),
                            mstore.shared_agent_registry(),
                            app_state.boot_id.clone(), &app_state.auth_key,
                            Some(app_state.config_watcher.clone()),
                        );
                    }
                    let status = blockcontroller::get_block_controller_status(&existing.oid)
                        .map(|s| s.shellprocstatus)
                        .unwrap_or_else(|| "init".to_string());
                    return Ok(AgentOpenResult {
                        block_id: existing.oid,
                        tab_id,
                        agent_id: cmd.agent_id,
                        provider: agent.provider,
                        controller_type: provider.controller_type_str().to_string(),
                        status,
                        created: false,
                    });
                }

                // 5. Resolve CLI path.
                //
                // The SAME lookup as `resolvecli` / `install.start` /
                // `install.check`: the shared pinned-version dir, then the
                // legacy per-AgentMux-version one (`backend::cli_install`).
                //
                // History worth keeping: this once hand-rolled
                // `$HOME/.agentmux/<version>/cli/...` — a path that never
                // existed — so `agent.open` failed with `CLI_NOT_AVAILABLE`
                // for every agent even with the CLI installed (verified live
                // 2026-09-01). One shared resolver is what keeps the launch
                // paths from drifting apart again.
                let paths = agentmux_common::DataPaths::from_env()
                    .ok_or_else(|| "DataPaths::from_env() failed".to_string())?;
                let npm_bin = crate::backend::cli_install::npm_bin(
                    &crate::backend::cli_install::install_dir(&paths, &provider.id, provider.pinned_version),
                    provider.cli_command,
                )
                .to_string_lossy()
                .to_string();
                let mut resolved_cli_path = crate::backend::cli_install::find_installed(
                    &paths,
                    &provider.id,
                    provider.pinned_version,
                    provider.cli_command,
                )
                .map(|p| p.to_string_lossy().to_string())
                .unwrap_or_else(|| npm_bin.clone());
                if !std::path::Path::new(&resolved_cli_path).exists() {
                    // Fallback: provider not installed via npm — try system PATH.
                    // This is used for Python-based CLIs like Kimi that are not
                    // distributed on npm.
                    if provider.npm_package.is_empty() {
                        if let Some(path) = resolve_provider_cli_on_path(provider.id, provider.cli_command).await {
                            resolved_cli_path = path;
                        }
                    }
                    if !std::path::Path::new(&resolved_cli_path).exists() {
                        // An npm-backed provider whose pinned CLI isn't there yet
                        // (a fresh install, or the minute or two after an upgrade
                        // moved the pin): install it, as the UI's launch flow does,
                        // instead of making the caller go and do that first.
                        if provider.npm_package.is_empty() || provider.pinned_version.is_empty() {
                            return Err(format!(
                                "CLI_NOT_AVAILABLE: {} not found at {}. Install it, then try again.",
                                provider.cli_command, npm_bin
                            ));
                        }
                        let req = crate::backend::cli_install::NpmInstallRequest {
                            provider_id: provider.id.to_string(),
                            npm_package: provider.npm_package.to_string(),
                            pinned_version: provider.pinned_version.to_string(),
                            cli_command: provider.cli_command.to_string(),
                            background: false,
                        };
                        match crate::backend::cli_install::ensure_installed(
                            paths.clone(),
                            req,
                            std::time::Duration::from_secs(AGENT_OPEN_INSTALL_WAIT_SECS),
                        )
                        .await
                        {
                            Ok(bin) => resolved_cli_path = bin.to_string_lossy().to_string(),
                            Err(crate::backend::cli_install::EnsureError::StillInstalling) => {
                                return Err(format!(
                                    "CLI_INSTALLING: {} {} is still being installed. Try again in a minute; \
                                     the install carries on in the background.",
                                    provider.cli_command, provider.pinned_version
                                ));
                            }
                            Err(crate::backend::cli_install::EnsureError::Failed(why)) => {
                                return Err(format!(
                                    "CLI_NOT_AVAILABLE: {} {} could not be installed: {why}",
                                    provider.cli_command, provider.pinned_version
                                ));
                            }
                        }
                    }
                }

                // 6. Build metadata
                let controller_type = provider.controller_type_str();
                // Container agents use per-turn docker exec; the subprocess controller
                // is required regardless of what the provider defaults to (claude returns
                // "persistent", which causes AgentInput to skip the container exec path).
                let controller_type = if agent.agent_type == "container" {
                    "subprocess"
                } else {
                    controller_type
                };
                // Catalog args, the runtime the menu will show applied on top, then the
                // definition's own flags. Without the middle step a pane opened here
                // ran on the CLI's default model while its menu read Sonnet — see
                // backend/agent_runtime.rs.
                //
                // What the user last picked in the menu for this agent sits above the
                // definition's flags (and replaces them in this pane's copy), so
                // reopening an agent starts where it was left. A read failure only
                // means "nothing remembered".
                let remembered = crate::backend::agent_runtime::Remembered::parse(
                    provider.id,
                    &mstore.agent_last_runtime_get(&agent.id).unwrap_or_default(),
                );
                let (base_args, pane_flags, remembered_mode) = crate::backend::agent_runtime::apply_remembered(
                    provider.id,
                    resolve_cli_args(&provider, controller_type),
                    &agent.provider_flags,
                    &remembered,
                );
                let mut seeded =
                    crate::backend::agent_runtime::seed_launch(provider.id, base_args, &pane_flags);
                if let (Some(mode), Some(rt)) = (remembered_mode, seeded.runtime.as_mut()) {
                    rt["permissionMode"] = json!(mode);
                }

                let agent_slug = agentmux_common::slug::path_slug(&agent.name);
                // Shared with native-memory resolution so the two can never
                // disagree about where a blank-working_directory agent
                // actually runs — they did, and Personal Bundle broke for the
                // common case as a result (ReAgent/Codex P1, PR #2901; see
                // SPEC_FIX_PERSONAL_MEMORY_EMPTY_WORKDIR_2026_09_01.md).
                let work_dir = if agent.working_directory.is_empty() {
                    crate::backend::storage::agents::default_agent_working_dir(&agent.name)
                } else {
                    agent.working_directory.clone()
                };

                // Build env vars
                let mut env_vars = serde_json::Map::new();
                for key in provider.unset_env {
                    env_vars.insert(key.to_string(), json!(""));
                }
                // Auth dir — the DEFAULT provider auth lives in the shared,
                // instance/channel/version-independent providers area so a single
                // login is shared everywhere (the structural fix for the per-channel
                // validate-spin regression). The per-account auth dir
                // (identity_handlers) still wins for explicit multi-account.
                let auth_dir = providers::default_auth_dir(provider)?;
                // Create the dir AND apply its isolation guarantees in one
                // inseparable step. Claude Code CLI's own user-level CLAUDE.md
                // discovery falls through to the real $HOME/.claude/CLAUDE.md
                // when this isolated dir has none of its own — CLAUDE_CONFIG_DIR
                // relocates credential/session/project storage but NOT that
                // lookup (proven live, three-arm experiment:
                // docs/reports/REPORT_CLAUDE_CONFIG_DIR_ISOLATION_EVIDENCE_2026_09_01.md).
                //
                // Fail closed (block the spawn) rather than warn-and-continue:
                // continuing would launch the agent with exactly the
                // unprotected condition this exists to close (Codex P1 +
                // ReAgent P1, PR #2854). Non-claude providers get the dir
                // created and nothing else, so this never blocks their spawns.
                // See SPEC_ISOLATE_HOST_CLAUDE_MD_2026_08_31.md.
                providers::prepare_provider_auth_dir(provider, &auth_dir).map_err(|e| {
                    format!(
                        "failed to isolate this agent's Claude Code config ({auth_dir}): {e}. \
                         Refusing to launch with an unprotected config dir."
                    )
                })?;
                env_vars.insert(provider.auth_config_dir_env_var.to_string(), json!(auth_dir));
                for (k, v) in provider.auth_extra_env {
                    env_vars.insert(k.to_string(), json!(v));
                }
                // Model vendor override (harness vs. model-vendor decoupling)
                // — e.g. ANTHROPIC_BASE_URL for a claude-provider agent
                // pointed at a proxy/Bedrock/OpenRouter instead of
                // Anthropic's default endpoint. Inserted before the
                // free-form env blob below so it wins if a definition-level
                // KEY=VALUE line collides with it (structured field over
                // free-form blob, same precedence as the auth entries above).
                if let Some((var, value)) = resolve_vendor_env_override(provider, &agent) {
                    env_vars.insert(var.to_string(), json!(value));
                }
                // Merge env vars from the definition's persisted env content blob (KEY=VALUE lines).
                // Provider/auth entries inserted above take precedence; definition-level vars
                // are merged after so they can extend (but not override) the auth env.
                if let Ok(Some(env_blob)) = mstore.agent_content_get(&agent.id, "env") {
                    for line in env_blob.content.lines() {
                        if let Some((k, v)) = line.split_once('=') {
                            let k = k.trim();
                            if !k.is_empty() && !env_vars.contains_key(k) {
                                env_vars.insert(k.to_string(), json!(v));
                            }
                        }
                    }
                }
                // Agent identity. `GH_CONFIG_DIR` is not persisted here: it is
                // a reserved variable set on every spawn by `backend::gh_guard`,
                // which this env reaches through `build_persistent_spawn_env`.
                // Use stored slug (stable across renames) for muxbus routing;
                // fall back to the computed slug derived from the display name.
                let routing_id = if !agent.slug.is_empty() { &agent.slug } else { &agent_slug };
                env_vars.insert("AGENTMUX_AGENT_ID".to_string(), json!(routing_id));
                // Mirror under MUXBUS_AGENT_ID too, matching the same
                // additive fix in agent_handlers/input.rs (ARCH-002) --
                // this MuxAPI path (agent.open -> agent.send, via
                // agent_io.rs reading this back from persisted cmd:env)
                // builds its own env_vars independently of input.rs's spawn
                // path, so it needs the same mirror applied here rather than
                // inheriting it (codex P2 on PR #2345).
                env_vars.insert("MUXBUS_AGENT_ID".to_string(), json!(routing_id));
                // Exit delay only for subprocess
                if controller_type != "persistent" {
                    env_vars.insert("CLAUDE_CODE_EXIT_AFTER_STOP_DELAY".to_string(), json!("30000"));
                }

                // Cross-tab/cross-restart continuity: this agent may already have
                // a captured provider session sitting in the shared registry
                // (backfilled from its provider transcript, or captured live by a
                // prior block) even though no block for it exists in THIS tab —
                // e.g. after a full app restart lands on a different/rehydrated
                // tab. Seed the new block's agent:sessionid meta so its FIRST
                // turn resumes that conversation instead of silently starting
                // fresh and orphaning the original — the same thing the
                // picker's explicit "Continue" flow already does via
                // continueOfInstanceId (RecentSessionRow.session_id), extended
                // here to the default open path.
                // See docs/retro/retro-cross-channel-conversation-continuity-regression-2026-06-16.md
                // ("Mechanism 2 — continuity"), action item 4.
                //
                // Concurrency guard (reagent P1 on PR #2059): only seed
                // agent:sessionid when no OTHER block for this same agent
                // definition currently has a LIVE controller registered
                // anywhere in this process — not just this tab (find_agent_block
                // above only scoped the "reuse" check to the target tab).
                // Without this, opening the same named agent in a second tab
                // while the first is still live would seed the new block with
                // the SAME session_id, letting two controllers concurrently
                // `--resume` one provider session — risking transcript
                // corruption or exactly the orphaning bug this fix exists to
                // prevent. A block with no registered controller (e.g. right
                // after an app restart, before anything has resynced) is not
                // "live" and doesn't block seeding.
                // A block of this agent that is mid-close has already left
                // CONTROLLER_REGISTRY but its process may still be exiting
                // (up to the close's grace period). Wait for it, so the check
                // below sees it gone AND no second `--resume` starts on the
                // session while the old process still holds it
                // (SPEC_AGENT_PANE_CLOSE_GRACEFUL_SHUTDOWN_2026_09_18.md §9.6).
                let closing_blocks: Vec<String> = mstore
                    .get_all::<Block>()
                    .map(|blocks| {
                        blocks
                            .into_iter()
                            .filter(|b| {
                                obj::meta_get_string(&b.meta, "agentId", "") == agent.id
                                    && blockcontroller::is_closing(&b.oid)
                            })
                            .map(|b| b.oid)
                            .collect()
                    })
                    .unwrap_or_default();
                for closing in &closing_blocks {
                    blockcontroller::wait_closing_stopped(
                        closing,
                        blockcontroller::SHUTDOWN_GRACE + std::time::Duration::from_secs(2),
                    )
                    .await;
                }
                let agent_live_elsewhere = mstore.get_all::<Block>()
                    .map(|blocks| {
                        blocks.iter().any(|b| {
                            obj::meta_get_string(&b.meta, "agentId", "") == agent.id
                                && blockcontroller::get_controller(&b.oid).is_some()
                        })
                    })
                    .unwrap_or(false);
                let resume_session_id: Option<String> = if agent_live_elsewhere {
                    None
                } else {
                    mstore.shared_agent_registry()
                        .and_then(|reg| reg.list_active().ok())
                        .and_then(|records| {
                            records.into_iter()
                                .filter(|r| r.data.definition_id == agent.id)
                                .filter(|r| r.data.session_id.as_deref().map_or(false, |s| !s.is_empty()))
                                .max_by_key(|r| r.data.last_launched_at_ms)
                        })
                        .and_then(|r| r.data.session_id)
                };

                let mut meta = MetaMapType::new();
                meta.insert("view".to_string(), json!("agent"));
                meta.insert("agentId".to_string(), json!(&agent.id));
                // Per-agent zoom persistence (SPEC_AGENT_ZOOM_PERSISTENCE): seed
                // the new block's `term:zoom` from the agent's saved `ui:zoom`
                // (per-agent content store, global cross-channel) so reopening
                // the same agent restores its zoom instead of resetting to 1.0.
                // Stored only for non-default zooms; clamp to the frontend's
                // [0.5, 2.0] range so a corrupt value can't escape it.
                if let Ok(Some(c)) = mstore.agent_content_get(&agent.id, "ui:zoom") {
                    if let Some(z) = parse_seed_zoom(&c.content) {
                        meta.insert("term:zoom".to_string(), json!(z));
                    }
                }
                // Per-agent color (SPEC_AGENT_COLOR_2026_08_08.md): seed the
                // new block's frame border colors from the agent's stored
                // ui:color so the existing pane-frame rendering shows it —
                // full-strength on the focused border
                // (frame:activebordercolor), dimmed on the unfocused one
                // (frame:bordercolor) so the color is visible either way
                // while focus stays distinguishable by brightness.
                // Assign-if-missing write-through covers defs created by
                // paths the createagent handler doesn't own (forks,
                // imports) and any def that predates migration m0020 on
                // this channel. Strict #rrggbb validation so a corrupt row
                // can't inject arbitrary CSS.
                {
                    use crate::backend::agent_color::{dim_agent_color, is_valid_agent_color, pick_agent_color};
                    let stored = mstore
                        .agent_content_get(&agent.id, "ui:color")
                        .ok()
                        .flatten()
                        .map(|c| c.content.trim().to_string())
                        .filter(|c| is_valid_agent_color(c));
                    let color = match stored {
                        Some(c) => c,
                        None => {
                            let picked = pick_agent_color(&agent.id).to_string();
                            let now_ms = agentmux_common::time::now_ms();
                            // Best-effort: a store error here shouldn't block
                            // opening the agent — the pane just stays uncolored
                            // this session and we retry next open.
                            let _ = mstore.agent_content_set(&crate::backend::storage::store::AgentContent {
                                agent_id: agent.id.clone(),
                                content_type: "ui:color".to_string(),
                                content: picked.clone(),
                                updated_at: now_ms,
                            });
                            picked
                        }
                    };
                    meta.insert("frame:activebordercolor".to_string(), json!(&color));
                    meta.insert("frame:bordercolor".to_string(), json!(dim_agent_color(&color)));
                }
                meta.insert("agentProvider".to_string(), json!(&agent.provider));
                meta.insert("agentName".to_string(), json!(&agent.name));
                meta.insert("agentIcon".to_string(), json!(if agent.icon.is_empty() { "wand-magic-sparkles" } else { &agent.icon }));
                meta.insert("agentMode".to_string(), json!(if agent.agent_type.is_empty() { "host" } else { &agent.agent_type }));
                if !agent.container_image.is_empty() {
                    meta.insert("agent:container_image".to_string(), json!(&agent.container_image));
                }
                if agent.container_volumes != "[]" && !agent.container_volumes.is_empty() {
                    meta.insert("agent:container_volumes".to_string(), json!(&agent.container_volumes));
                }
                // Container-local CLI command: the provider's CLI as it resolves
                // INSIDE the image (on the image's PATH, e.g. `claude`). Distinct
                // from `cmd` below, which is the host-resolved absolute npm path
                // (`<config_home>/.../node_modules/.bin/claude`) and does NOT exist
                // in the container — passing it as docker-exec argv[0] would fail
                // with "no such file or directory". Container turns use this.
                meta.insert("agent:container_command".to_string(), json!(provider.cli_command));
                // The provider's own format, as the UI launch writes it
                // (`agent-model.ts`). A hard-coded map here stamped every
                // provider it didn't list (Antigravity, the ACP ones) as Claude.
                meta.insert("agentOutputFormat".to_string(), json!(provider.styled_output_format));
                meta.insert("controller".to_string(), json!(controller_type));
                meta.insert("cmd".to_string(), json!(&resolved_cli_path));
                // cmd:args + agent:runtime + agent:provider_flags, written together.
                crate::backend::agent_runtime::apply_to_meta(&mut meta, seeded, &pane_flags);
                meta.insert("cmd:cwd".to_string(), json!(&work_dir));
                meta.insert("cmd:env".to_string(), serde_json::Value::Object(env_vars));
                meta.insert("agent:resume_flag".to_string(), json!(provider.resume_flag.unwrap_or("")));
                meta.insert("agent:resume_strategy".to_string(), json!(provider.resume_strategy_str()));
                meta.insert("agent:session_id_field".to_string(), json!(provider.session_id_field));
                meta.insert("agent:prompt_arg_flag".to_string(), json!(provider.prompt_arg_flag().unwrap_or("")));
                if let Some(sid) = &resume_session_id {
                    meta.insert("agent:sessionid".to_string(), json!(sid));
                }

                // 7. Create block + insert into layout tree.
                // Through the reducer (#1681), not wcore-direct: a store-only
                // block is invisible to the reducer-canonical `state.blocks`
                // (only hydrated from SQLite at bootstrap), so tearing this agent
                // pane off later was rejected "block not found". BlockCreated
                // carries meta → apply_block_created writes the mstore Block,
                // which the controller resync below reloads by id.
                let meta_val = serde_json::to_value(&meta)
                    .map_err(|e| format!("agent.open: meta serialize: {e}"))?;
                let block_id = if let Some(target) = into_block {
                    // Layouts → Open layout…: the pane already exists and sits
                    // in the rebuilt tree — give it the agent's meta through
                    // the reducer (like `pane.open`'s editor reuse) and skip
                    // the layout insert below.
                    let target_block = mstore
                        .get::<Block>(target)
                        .map_err(|e| format!("agent.open: read target pane: {e}"))?
                        .ok_or_else(|| format!("agent.open: no such pane: {target}"))?;
                    if obj::meta_get_string(&target_block.meta, "view", "") != "agent"
                        || !obj::meta_get_string(&target_block.meta, "agentId", "").is_empty()
                    {
                        return Err("agent.open: the target pane is not an empty agent pane".to_string());
                    }
                    let mut patch = meta_val.clone();
                    if let Some(p) = patch.as_object_mut() {
                        // The layout's "which agent goes here" hint is spent.
                        p.insert(crate::backend::layout_file::META_LAYOUT_AGENT.to_string(), serde_json::Value::Null);
                    }
                    let meta_events = crate::server::service::dispatch_to_reducer(
                        &app_state,
                        agentmux_common::ipc::Command::UpdateBlockMeta { block_id: target.to_string(), meta_patch: patch },
                    )
                    .await;
                    if let Some(msg) = meta_events.iter().find_map(|e| match e {
                        agentmux_common::ipc::Event::Error { message, .. } => Some(message.clone()),
                        _ => None,
                    }) {
                        return Err(format!("agent.open: UpdateBlockMeta: {msg}"));
                    }
                    for ev in &meta_events {
                        if let Err(e) = crate::persist_subscriber::apply_event_to_mstore(ev, &mstore) {
                            tracing::warn!("agent.open: UpdateBlockMeta mstore apply failed: {e}");
                        }
                    }
                    crate::server::service::publish_events(&app_state, &meta_events);
                    target.to_string()
                } else {
                let create_events = crate::server::service::dispatch_to_reducer(
                    &app_state,
                    agentmux_common::ipc::Command::CreateBlock {
                        tab_id: tab_id.clone(),
                        meta: meta_val,
                    },
                )
                .await;
                if let Some(msg) = create_events.iter().find_map(|e| match e {
                    agentmux_common::ipc::Event::Error { message, .. } => Some(message.clone()),
                    _ => None,
                }) {
                    return Err(format!("agent.open: CreateBlock: {msg}"));
                }
                let block_id = create_events
                    .iter()
                    .find_map(|e| match e {
                        agentmux_common::ipc::Event::BlockCreated { block_id, .. } => {
                            Some(block_id.clone())
                        }
                        _ => None,
                    })
                    .ok_or_else(|| "agent.open: CreateBlock emitted no BlockCreated".to_string())?;
                for ev in &create_events {
                    if let Err(e) = crate::persist_subscriber::apply_event_to_mstore(ev, &mstore) {
                        tracing::warn!("agent.open: CreateBlock mstore apply failed: {e}");
                    }
                }
                crate::server::service::publish_events(&app_state, &create_events);

                // Enqueue a layout insert action for the frontend to process.
                // The frontend's LayoutModel watches pendingbackendactions on the
                // LayoutState and applies them via treeReducer — same mechanism
                // used by cross-window drag-and-drop (dnd.rs).
                // SPEC_864 Phase 4 — append through the reducer (single
                // writer of db_layout). Best-effort like the store-direct
                // write it replaces.
                {
                    let action = obj::LayoutActionData {
                        actiontype: "insert".to_string(),
                        actionid: uuid::Uuid::new_v4().to_string(),
                        blockid: block_id.clone(),
                        nodesize: None,
                        nodesizefraction: None,
                        indexarr: None,
                        // Honors the request's `focus` (default true — the UI
                        // flow's behavior). Was hardcoded `true` while the RPC
                        // surface was the only caller and nothing set the
                        // field; this PR documents `focus`/`--no-focus` on
                        // OpenAgent/muxopen, so ignoring it would silently
                        // contradict their own help text. reagent P1, PR #3032.
                        focused: cmd.focus.unwrap_or(true),
                        magnified: false,
                        ephemeral: false,
                        targetblockid: String::new(),
                        position: String::new(),
                    };
                    if let Err(e) = crate::server::service::queue_layout_actions_via_reducer(
                        &app_state,
                        &tab_id,
                        vec![action],
                    )
                    .await
                    {
                        tracing::warn!("agent.open: layout action enqueue failed: {e}");
                    }
                }
                block_id
                };

                tracing::info!(
                    block_id = %block_id,
                    agent_id = %cmd.agent_id,
                    provider = %agent.provider,
                    controller_type = %controller_type,
                    "agent.open: block created + layout updated"
                );

                // 8. Write agent config files. No collision resolution
                //    in this path — the function creates the dir if
                //    missing and overwrites whatever's there. Same-
                //    name same-hour launches will share a workdir;
                //    proper allocation is tracked as a follow-up.
                write_agent_config_files(&mstore, &app_state.id_store, &app_state.identity_store, &agent, routing_id, &work_dir)?;

                // Identity M4b-4: record the launch and stamp the block before
                // the resync — a controller can report its session id during
                // it, and that capture finds the row by block (Codex P2 on
                // #3584).
                record_agent_open_launch(&mstore, &agent.id, &block_id)?;

                // 9. Register controller (resync)
                let block_for_resync = mstore.must_get::<Block>(&block_id)
                    .map_err(|e| format!("agent.open: reload block: {e}"))?;
                blockcontroller::resync_controller(
                    &block_for_resync,
                    &tab_id,
                    None,
                    true,
                    true,
                    Some(broker.clone()),
                    Some(event_bus.clone()),
                    Some(mstore.clone()),
                    Some(filestore.clone()),
                    Some(app_state.id_store.clone()),
                    Some(app_state.identity_store.clone()),
                    mstore.shared_agent_registry(),
                    app_state.boot_id.clone(),
                    &app_state.auth_key,
                    Some(app_state.config_watcher.clone()),
                )?;

                // 10. Broadcast block + tab + layout updates to frontend
                {
                    let mut updates = Vec::new();
                    if let Ok(updated_block) = mstore.must_get::<Block>(&block_id) {
                        updates.push(obj::MuxObjUpdate {
                            updatetype: "update".into(),
                            otype: "block".into(),
                            oid: block_id.clone(),
                            obj: Some(obj::mux_obj_to_value(&updated_block)),
                        });
                    }
                    if let Ok(updated_tab) = mstore.must_get::<Tab>(&tab_id) {
                        updates.push(obj::MuxObjUpdate {
                            updatetype: "update".into(),
                            otype: "tab".into(),
                            oid: tab_id.clone(),
                            obj: Some(obj::mux_obj_to_value(&updated_tab)),
                        });
                        if let Ok(updated_layout) = mstore.must_get::<obj::LayoutState>(&updated_tab.layoutstate) {
                            updates.push(obj::MuxObjUpdate {
                                updatetype: "update".into(),
                                otype: "layout".into(),
                                oid: updated_tab.layoutstate.clone(),
                                obj: Some(obj::mux_obj_to_value(&updated_layout)),
                            });
                        }
                    }
                    // One batched frame so the renderer applies all of them in
                    // a single reactive flush — see
                    // EventBus::broadcast_mux_obj_updates.
                    event_bus.broadcast_mux_obj_updates(&updates);
                }

                // codex P2 on PR #3513: this used to be safe to hardcode --
                // before eager resume existed, a freshly created pane could
                // only ever be `STATUS_INIT` at this point. Now that
                // `resync_controller` above is handed real identity stores,
                // a pane seeded with a registry-derived `agent:sessionid`
                // (picker reattach, an agent definition with prior history)
                // can come back already `running`. Read the real status
                // the same way the existing-pane branch above does, rather
                // than tell the caller "init" for a pane that's actually
                // live.
                let status = blockcontroller::get_block_controller_status(&block_id)
                    .map(|s| s.shellprocstatus)
                    .unwrap_or_else(|| "init".to_string());
                Ok(AgentOpenResult {
                    block_id,
                    tab_id,
                    agent_id: cmd.agent_id,
                    provider: agent.provider,
                    controller_type: controller_type.to_string(),
                    status,
                    created: true,
                })
}

/// Write agent config files (CLAUDE.md, .mcp.json, etc.) to the working directory.
pub(super) fn write_agent_config_files(
    mstore: &Store,
    id_store: &Store,
    identity_store: &Store,
    agent: &crate::backend::storage::AgentDefinition,
    agent_slug: &str,
    work_dir: &str,
) -> Result<(), String> {
    // Load agent content
    let contents = mstore.agent_content_get_all(&agent.id)
        .unwrap_or_default();

    let mut content_map = std::collections::HashMap::new();
    for fc in &contents {
        content_map.insert(fc.content_type.clone(), fc.content.clone());
    }

    // Disable autonomous memory writes only when using the bare slug-fallback workdir
    // (~/.agentmux/agents/<slug>) — that path is shared across same-name multi-tab
    // launches with no collision resolution, risking concurrent MEMORY.md corruption
    // (upstream issue #29051). An empty working_directory field means the caller
    // chose the fallback; any explicitly set workdir is isolated and keeps writes on.
    let workdir_is_shared = agent.working_directory.is_empty();
    if workdir_is_shared {
        let settings_str = content_map
            .entry("settings".to_string())
            .or_insert_with(|| "{}".to_string());
        match serde_json::from_str::<serde_json::Map<String, serde_json::Value>>(settings_str) {
            Ok(mut obj) => {
                obj.entry("autoMemoryEnabled".to_string())
                    .or_insert(json!(false));
                *settings_str =
                    serde_json::to_string(&obj).unwrap_or_else(|_| "{}".to_string());
            }
            Err(e) => {
                tracing::warn!(
                    work_dir = %work_dir,
                    error = %e,
                    "write_agent_config_files: settings JSON unparseable; \
                     autoMemoryEnabled guard skipped — memory writes may be active on shared workdir"
                );
            }
        }
    }

    // Global Memory (minus Operator Config for another agent kind), then the
    // agent's picked bundles in list order, go into CLAUDE.md; WriteAgentConfig
    // composes the same text (SPEC_RENAME_KNOWLEDGE_TO_MEMORY_2026_10_06.md §3.6).
    let global_bundles = crate::backend::operator_config_seed::global_bundles_for_agent(
        id_store.bundle_list_global().unwrap_or_default(),
        &agent.agent_type,
    );
    let startup_block = crate::backend::storage::join_startup_blocks(
        &crate::backend::storage::format_global_bundle_block(&global_bundles),
        &crate::backend::storage::format_agent_bundle_block(&crate::backend::storage::agent_picked_bundles(
            mstore, id_store, &agent.id,
        )),
    );
    if !startup_block.is_empty() {
        content_map
            .entry("memory".to_string())
            .and_modify(|existing| {
                *existing = format!("{startup_block}\n\n---\n\n{existing}");
            })
            .or_insert(startup_block);
    }

    // v1 skills: globals are always injected; the agent's OWN ref-bound skills
    // are authoritative when present, otherwise fall back to legacy
    // db_agent_skills. See Store::effective_skills for the merge algorithm —
    // shared with the `listagentskills` RPC handler so the frontend's
    // pre-launch skill fetch and this materialization path never diverge.
    let effective_skills = mstore.effective_skills(identity_store, &agent.id);

    let mut config_files = crate::backend::agent_config::build_config_files(
        &content_map,
        &effective_skills,
        &agent.name,
        &agent.id,
        agent_slug,
        work_dir,
        &agent.provider,
    );

    // v1 MCP: "agentmux" plus the agent's effective servers. The
    // legacy blob's user servers are merged in ONLY when the agent has no own
    // ref-bound servers (so a global server never wipes a legacy-only agent's
    // .mcp.json). When the agent has own refs, those are authoritative.
    // A bundle carries no MCP servers
    // (SPEC_BUNDLE_CONTENTS_MEMORY_NOT_MCP_2026_10_07.md §3.1), so bundles
    // add none.
    let visible_mcp: Vec<crate::backend::storage::McpServer> = mstore.effective_mcp_servers(identity_store, &agent.id, agent.agent_type == "container");
    let has_own_mcp_refs = visible_mcp.iter().any(|server| !server.is_global);
    if !visible_mcp.is_empty() {
        let blob_for_merge = if has_own_mcp_refs {
            None
        } else {
            content_map.get("mcp").map(|s| s.as_str())
        };
        if let Some(mcp_json) = crate::backend::agent_config::build_mcp_config_from_refs(
            &visible_mcp,
            blob_for_merge,
            agent_slug,
            &agent.agent_bus_id,
        ) {
            if let Some(pos) = config_files.iter().position(|f| f.filename == ".mcp.json") {
                config_files[pos].content = mcp_json;
            } else {
                config_files.push(crate::backend::agent_config::AgentConfigFile {
                    filename: ".mcp.json".to_string(),
                    content: mcp_json,
                });
            }
        }
    }

    // Host-tier + LAN-tier jekt sender signing keys
    // (SPEC_JEKT_TRUST_LAYER_COMPLETION_2026_08_13.md §2.2,
    // SPEC_JEKT_LAN_TIER_SIGNING_2026_08_15.md §2.1) — inject
    // AGENTMUX_JEKT_KEY / AGENTMUX_LAN_KEY into the agentmux MCP server's
    // own env, right alongside AGENTMUX_AGENT_ID, so `SendMessage`/`Loop`
    // can sign outgoing jekts as this agent. Best-effort: a failure here
    // must never block agent spawn — the agent still launches, just
    // without a key, and its jekts render TRUST=self-declared /
    // TRUST=network-claimed instead of verified until the next successful
    // materialization. Shared with `WriteAgentConfig`
    // (server/editor_handlers.rs, the "click Launch" path) via
    // `agent_config::inject_jekt_signing_keys_into_mcp_json` — see that
    // function's doc comment for why this must not be duplicated inline
    // again.
    if let Some(pos) = config_files.iter().position(|f| f.filename == ".mcp.json") {
        crate::server::agent_self_keys::record_config_id_drift("m4d.config_id_drift.agent_open", agent_slug, Some(&agent.slug));
        match crate::backend::agent_config::inject_jekt_signing_keys_into_mcp_json(
            &config_files[pos].content,
            &mstore,
            agent_slug,
        ) {
            Some(rewritten) => config_files[pos].content = rewritten,
            None => {
                tracing::warn!(
                    agent_id = %agent.id,
                    "agent_open: jekt/LAN signing keys not injected into .mcp.json — \
                     this agent's jekts will render TRUST=self-declared / TRUST=network-claimed \
                     instead of verified"
                );
            }
        }
    }

    // Expand ~ in work_dir
    let expanded_dir = if work_dir.starts_with("~/") || work_dir == "~" {
        if let Ok(home) = std::env::var("HOME").or_else(|_| std::env::var("USERPROFILE")) {
            format!("{}/{}", home, work_dir.trim_start_matches("~/"))
        } else {
            work_dir.to_string()
        }
    } else {
        work_dir.to_string()
    };

    let base_path = std::path::Path::new(&expanded_dir);
    if !base_path.exists() {
        std::fs::create_dir_all(base_path) // workdir-fs: creates the workdir itself
            .map_err(|e| format!("failed to create working dir: {e}"))?;
    }
    let wd = crate::backend::workdir_fs::Workdir::open(base_path)
        .map_err(|e| format!("failed to open working dir {}: {e}", base_path.display()))?;

    // Remove skill-derived files (.claude/commands/*.md, .claude/skills/*/SKILL.md)
    // that WE wrote on a previous launch but aren't part of this run's output --
    // e.g. a skill's format switched between "prompt" and "agent-skill", or a
    // skill was renamed/removed. Shared with `writeagentconfig` (editor_handlers.rs)
    // so the two RPC paths that materialize config files never drift out of sync
    // on this (reagent P1 + Codex P1/P2, PR #2322).
    let new_managed_skill_paths = crate::backend::agent_config::managed_skill_file_paths(
        config_files.iter().map(|f| f.filename.as_str()),
    );
    crate::backend::agent_config::cleanup_stale_managed_skill_files(base_path, &new_managed_skill_paths);

    for file in &config_files {
        // CLAUDE.md never gets the generic write below — it goes through
        // ownership-aware materialization instead, which never overwrites
        // a pre-existing, non-AgentMux-authored file's content. See
        // docs/specs/SPEC_CLAUDE_MD_OWNERSHIP_PROTECTION_2026_08_22.md.
        if file.filename == "CLAUDE.md" {
            if let Err(e) =
                crate::backend::agent_config::write_claude_md_respecting_ownership(base_path, &file.content)
            {
                return Err(format!("failed to write CLAUDE.md: {e}"));
            }
            continue;
        }
        // Every OTHER provider's startup-instructions filename (AGENTS.md,
        // GEMINI.md, QWEN.md, .pi/APPEND_SYSTEM.md) never overwrites a
        // pre-existing file — codex P1, PR #2788: unlike CLAUDE.md's full
        // ownership-aware materialization above, this is a plain
        // exists-guard (see write_startup_instructions_respecting_existing's
        // own doc comment for why a fuller mechanism isn't attempted here).
        if crate::backend::providers::is_known_startup_instructions_filename(&file.filename) {
            crate::backend::agent_config::write_startup_instructions_respecting_existing(
                base_path,
                &file.filename,
                &file.content,
            )
            .map_err(|e| format!("failed to write {}: {e}", file.filename))?;
            continue;
        }
        // `.mcp.json` merges into a user's own file instead of replacing it,
        // and is written owner-only (#3680) — see the function's doc comment.
        if file.filename == ".mcp.json" {
            crate::backend::agent_config::write_mcp_json_respecting_user_servers(base_path, &file.content)
                .map_err(|e| format!("failed to write .mcp.json: {e}"))?;
            continue;
        }
        // Through the workdir (SPEC_WORKDIR_SAFE_WRITES_2026_10_01): a path
        // outside it, under a folder linking out of it, or onto a symlink is
        // refused and skipped, like an escaping path always was here.
        match wd.write(&file.filename, file.content.as_bytes(), false) {
            Err(e) if e.kind() == std::io::ErrorKind::PermissionDenied => {
                tracing::warn!(
                    work_dir = %expanded_dir,
                    path = %file.filename,
                    error = %e,
                    "write_agent_config_files: refusing to write a config path outside the working directory"
                );
            }
            other => other.map_err(|e| format!("failed to write {}: {e}", file.filename))?,
        }
    }

    crate::backend::agent_config::write_managed_skill_file_manifest(base_path, &new_managed_skill_paths);

    // Record what this agent will read as project instructions, now that
    // AgentMux's own files are in their final state for this launch — observed
    // before the write, this would record the previous launch's content.
    //
    // Phase 3 of SPEC_INSTRUCTION_AND_MEMORY_PORTABILITY_2026_09_09.md.
    // Observing at open is the spec's §8 decision 2: it costs nothing, catches
    // the case that matters (the repository changed since last launch), and
    // avoids a watcher. Drift *during* a session is deliberately not covered
    // yet — revisit only if it shows up in practice.
    //
    // Best-effort: an agent must never fail to launch because a tracking row
    // could not be written.
    observe_project_instructions(mstore, agent, &expanded_dir);

    tracing::info!(
        agent_id = %agent.id,
        work_dir = %expanded_dir,
        file_count = config_files.len(),
        "agent.open: wrote config files"
    );

    Ok(())
}

/// Resolve and record this agent's project instructions.
///
/// Split out so the launch path reads as one line and this can be tested on
/// its own. Never returns an error: see the call site.
pub(super) fn observe_project_instructions(
    mstore: &crate::backend::storage::store::Store,
    agent: &crate::backend::storage::AgentDefinition,
    working_dir: &str,
) {
    use crate::backend::storage::project_instructions::ProjectInstructionObservation;

    let files = crate::backend::project_instructions::resolve_project_instructions(
        &agent.provider,
        working_dir,
    );
    if files.is_empty() {
        return;
    }
    let now = agentmux_common::time::now_ms();
    let observations: Vec<ProjectInstructionObservation> = files
        .iter()
        .map(|f| ProjectInstructionObservation {
            path: f.path.clone(),
            content_hash: f.content_hash.clone(),
            size_bytes: f.size_bytes as i64,
            owner: match f.owner {
                crate::backend::project_instructions::InstructionOwner::Agentmux => "agentmux",
                crate::backend::project_instructions::InstructionOwner::Foreign => "foreign",
            }
            .to_string(),
            existed: f.exists,
            observed_at: now,
        })
        .collect();

    if let Err(e) = mstore.project_instructions_record(&agent.id, &observations) {
        tracing::warn!(
            agent_id = %agent.id, error = %e,
            "agent.open: could not record project-instruction observations"
        );
    }
}

#[cfg(test)]
mod write_agent_config_files_tests {
    use super::*;
    use crate::backend::storage::Skill;

    fn make_store() -> Store {
        Store::open_in_memory().unwrap()
    }

    fn make_agent(id: &str, working_directory: &str) -> AgentDefinition {
        AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: id.to_string(),
            slug: String::new(),
            name: "Test Agent".to_string(),
            icon: String::new(),
            provider: "claude".to_string(),
            description: String::new(),
            working_directory: working_directory.to_string(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 1_700_000_000_000,
            agent_type: "host".to_string(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 0,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 1_700_000_000_000,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: String::new(),
        }
    }

    fn make_skill(skill_type: &str) -> Skill {
        Skill {
            id: "skill-1".to_string(),
            name: "Deploy".to_string(),
            trigger: "deploy".to_string(),
            skill_type: skill_type.to_string(),
            description: "Deploy the app".to_string(),
            content: "1. Test\n2. Deploy".to_string(),
            is_global: false,
            created_at: 1_700_000_000_000,
            updated_at: 1_700_000_000_000,
        }
    }

    /// reagent P1 + Codex P1/P2, PR #2322: switching a skill's `skill_type`
    /// between "prompt" and "agent-skill" must remove the artifact from the
    /// PREVIOUS format, not just write the new one -- otherwise the stale
    /// file stays active alongside the newly selected format.
    #[test]
    fn switching_skill_format_removes_the_stale_artifact() {
        let mstore = make_store();
        let id_store = make_store();
        let work_dir = tempfile::tempdir().unwrap();
        let work_dir_str = work_dir.path().to_str().unwrap();

        let mut agent = make_agent("agent-1", work_dir_str);
        mstore.agent_def_insert(&mut agent).unwrap();
        mstore.skill_upsert_unique(&mstore, "agent-1", &make_skill("agent-skill"), true).unwrap();

        write_agent_config_files(&mstore, &id_store, &mstore, &agent, "test-agent", work_dir_str).unwrap();
        let skill_md = work_dir.path().join(".claude/skills/deploy/SKILL.md");
        assert!(skill_md.exists(), "expected .claude/skills/deploy/SKILL.md to be written");

        // Flip the same skill to "prompt" format and relaunch.
        let mut prompt_skill = make_skill("prompt");
        prompt_skill.updated_at = 1_700_000_000_001;
        mstore.skill_upsert_unique(&mstore, "agent-1", &prompt_skill, true).unwrap();
        write_agent_config_files(&mstore, &id_store, &mstore, &agent, "test-agent", work_dir_str).unwrap();

        let command_md = work_dir.path().join(".claude/commands/deploy.md");
        assert!(command_md.exists(), "expected .claude/commands/deploy.md to be written");
        assert!(
            !skill_md.exists(),
            "stale .claude/skills/deploy/SKILL.md must be removed when the skill switches to prompt format"
        );
        assert!(
            !skill_md.parent().unwrap().exists(),
            "the now-empty .claude/skills/deploy/ directory should be cleaned up too"
        );
    }

    /// A file the user hand-authored under .claude/commands or .claude/skills
    /// (never part of any AgentMux-written manifest) must never be deleted by
    /// the stale-cleanup pass.
    #[test]
    fn user_authored_files_outside_the_manifest_are_never_touched() {
        let mstore = make_store();
        let id_store = make_store();
        let work_dir = tempfile::tempdir().unwrap();
        let work_dir_str = work_dir.path().to_str().unwrap();

        let mut agent = make_agent("agent-1", work_dir_str);
        mstore.agent_def_insert(&mut agent).unwrap();

        let user_file = work_dir.path().join(".claude/commands/my-own-command.md");
        std::fs::create_dir_all(user_file.parent().unwrap()).unwrap();
        std::fs::write(&user_file, "# hand-authored, not from AgentMux").unwrap();

        mstore.skill_upsert_unique(&mstore, "agent-1", &make_skill("agent-skill"), true).unwrap();
        write_agent_config_files(&mstore, &id_store, &mstore, &agent, "test-agent", work_dir_str).unwrap();
        write_agent_config_files(&mstore, &id_store, &mstore, &agent, "test-agent", work_dir_str).unwrap();

        assert!(user_file.exists(), "hand-authored file outside AgentMux's manifest must survive");
    }

    /// Defense-in-depth: even if a manifest somehow contains a path-traversal
    /// entry (e.g. from a bypass of the trigger sanitization added upstream
    /// in agent_config.rs, or manual tampering with the manifest file
    /// itself), the cleanup pass must never delete anything outside the
    /// agent's working directory (reagent P1, PR #2322).
    #[test]
    fn cleanup_refuses_to_delete_a_manifest_path_that_escapes_the_working_dir() {
        let mstore = make_store();
        let id_store = make_store();
        let work_dir = tempfile::tempdir().unwrap();
        let work_dir_str = work_dir.path().to_str().unwrap();

        let mut agent = make_agent("agent-1", work_dir_str);
        mstore.agent_def_insert(&mut agent).unwrap();

        // A sentinel file OUTSIDE the working directory that a traversal
        // attempt would target.
        let sentinel_dir = tempfile::tempdir().unwrap();
        let sentinel = sentinel_dir.path().join("outside-file.txt");
        std::fs::write(&sentinel, "must survive").unwrap();

        // Simulate a manifest that (however it got there) records an escape.
        std::fs::create_dir_all(work_dir.path().join(".claude")).unwrap();
        let traversal_rel = format!(
            "../{}/outside-file.txt",
            sentinel_dir.path().file_name().unwrap().to_str().unwrap()
        );
        let malicious_manifest = serde_json::to_string(&vec![traversal_rel]).unwrap();
        std::fs::write(
            work_dir.path().join(crate::backend::agent_config::MANAGED_SKILL_FILES_MANIFEST),
            malicious_manifest,
        )
        .unwrap();

        // No skills at all this run, so the manifest's one entry is "stale"
        // and would normally be deleted.
        write_agent_config_files(&mstore, &id_store, &mstore, &agent, "test-agent", work_dir_str).unwrap();

        assert!(sentinel.exists(), "file outside the working directory must never be deleted");
    }

    /// A `.claude` that links outside the workdir: the generic file loop
    /// (skill files, settings) used to write straight through it, with only
    /// a lexical check (SPEC_WORKDIR_SAFE_WRITES_2026_10_01 §1). Now refused
    /// and skipped, and the launch still succeeds.
    #[test]
    fn config_files_are_never_written_through_a_claude_folder_linking_outside() {
        let mstore = make_store();
        let id_store = make_store();
        let work_dir = tempfile::tempdir().unwrap();
        let work_dir_str = work_dir.path().to_str().unwrap();
        let outside = tempfile::tempdir().unwrap();
        #[cfg(unix)]
        let linked = std::os::unix::fs::symlink(outside.path(), work_dir.path().join(".claude")).is_ok();
        #[cfg(windows)]
        let linked = std::os::windows::fs::symlink_dir(outside.path(), work_dir.path().join(".claude")).is_ok();
        if !linked {
            return; // this OS user can't create links
        }

        let mut agent = make_agent("agent-1", work_dir_str);
        mstore.agent_def_insert(&mut agent).unwrap();
        mstore.skill_upsert_unique(&mstore, "agent-1", &make_skill("agent-skill"), true).unwrap();
        write_agent_config_files(&mstore, &id_store, &mstore, &agent, "test-agent", work_dir_str).unwrap();

        let leaked: Vec<_> = walkdir_files(outside.path());
        assert!(leaked.is_empty(), "nothing may be written outside the workdir, found {leaked:?}");
    }

    fn walkdir_files(dir: &std::path::Path) -> Vec<std::path::PathBuf> {
        let mut out = Vec::new();
        for entry in std::fs::read_dir(dir).unwrap().flatten() {
            let p = entry.path();
            if p.is_dir() {
                out.extend(walkdir_files(&p));
            } else {
                out.push(p);
            }
        }
        out
    }

    /// A bundle carries no MCP servers
    /// (SPEC_BUNDLE_CONTENTS_MEMORY_NOT_MCP_2026_10_07.md §3.1): a bundle ref
    /// an older build left behind neither reaches `.mcp.json` nor counts as
    /// the agent's own, so the agent's legacy blob is still merged.
    #[test]
    fn a_leftover_bundle_mcp_ref_neither_launches_nor_drops_the_agents_legacy_mcp_blob() {
        let mstore = make_store();
        let id_store = make_store();
        let work_dir = tempfile::tempdir().unwrap();
        let work_dir_str = work_dir.path().to_str().unwrap();

        let mut agent = make_agent("agent-1", work_dir_str);
        agent.memory_id = "bundle-1".to_string();
        mstore.agent_def_insert(&mut agent).unwrap();

        mstore
            .bundle_upsert(&crate::backend::storage::bundles::Bundle {
                id: "bundle-1".to_string(),
                name: "Bundle 1".to_string(),
                description: String::new(),
                is_blank: false,
                is_global: false,
                provider: "claude".to_string(),
                model: "anthropic".to_string(),
                instructions: String::new(),
                instructions_by_provider: "{}".to_string(),
                context_files: "[]".to_string(),
                mcp_servers: "[]".to_string(),
                skills: "[]".to_string(),
                sort_order: 0,
                created_at: 1_700_000_000_000,
                updated_at: 1_700_000_000_000,
                is_system: false,
            })
            .unwrap();
        leftover_bundle_mcp_ref(&mstore, "bundle-1", "bundle-private-server", "bundle-server", "bundle-tool");
        // agent-1 itself has NO own db_mcp_servers ref — only its bundle does.

        mstore
            .agent_content_set(&crate::backend::storage::content::AgentContent {
                agent_id: "agent-1".to_string(),
                content_type: "mcp".to_string(),
                content: r#"{"mcpServers":{"legacy-server":{"command":"legacy-tool"}}}"#.to_string(),
                updated_at: 1_700_000_000_000,
            })
            .unwrap();

        write_agent_config_files(&mstore, &id_store, &mstore, &agent, "test-agent", work_dir_str).unwrap();

        let mcp_json_path = work_dir.path().join(".mcp.json");
        let mcp_json = std::fs::read_to_string(&mcp_json_path).unwrap();
        let parsed: serde_json::Value = serde_json::from_str(&mcp_json).unwrap();
        assert!(
            parsed["mcpServers"].get("legacy-server").is_some(),
            "a leftover bundle ref must not drop the agent's legacy .mcp.json blob: {mcp_json}"
        );
        assert!(
            parsed["mcpServers"].get("bundle-server").is_none(),
            "a bundle's server must not launch: {mcp_json}"
        );
    }

    /// A bundle MCP ref of the kind an older build wrote; nothing writes one now.
    fn leftover_bundle_mcp_ref(store: &Store, bundle_id: &str, id: &str, name: &str, command: &str) {
        store
            .mcp_server_insert_raw(&crate::backend::storage::McpServer {
                id: id.to_string(),
                name: name.to_string(),
                transport: "stdio".to_string(),
                config: format!(r#"{{"command":"{command}"}}"#),
                is_global: false,
                created_at: 1_700_000_000_000,
                updated_at: 1_700_000_000_000,
            })
            .unwrap();
        store
            .conn()
            .lock()
            .unwrap()
            .execute(
                "INSERT INTO db_bundle_mcp_ref (bundle_id, mcp_id) VALUES (?1, ?2)",
                rusqlite::params![bundle_id, id],
            )
            .unwrap();
    }

    fn make_bundle(id: &str, name: &str, instructions: &str, is_global: bool) -> crate::backend::storage::bundles::Bundle {
        crate::backend::storage::bundles::Bundle {
            id: id.to_string(),
            name: name.to_string(),
            description: String::new(),
            is_blank: false,
            is_global,
            provider: String::new(),
            model: String::new(),
            instructions: instructions.to_string(),
            instructions_by_provider: "{}".to_string(),
            context_files: "[]".to_string(),
            mcp_servers: "[]".to_string(),
            skills: "[]".to_string(),
            sort_order: 0,
            created_at: 1_700_000_000_000,
            updated_at: 1_700_000_000_000,
            is_system: false,
        }
    }

    /// The bundles picked for an agent reach its launch
    /// (SPEC_RENAME_KNOWLEDGE_TO_MEMORY_2026_10_06.md §3.6): their
    /// instructions as `# [Bundle]` sections after Global Memory, in list
    /// order; a listed bundle that no longer exists is skipped. Not MCP
    /// servers: a bundle carries none.
    #[test]
    fn picked_bundles_reach_the_startup_file_but_not_the_mcp_config() {
        let mstore = make_store();
        let id_store = make_store();
        let work_dir = tempfile::tempdir().unwrap();
        let work_dir_str = work_dir.path().to_str().unwrap();

        let mut agent = make_agent("agent-1", work_dir_str);
        mstore.agent_def_insert(&mut agent).unwrap();
        id_store.bundle_upsert(&make_bundle("global-1", "Rules", "global rule", true)).unwrap();
        id_store.bundle_upsert(&make_bundle("b1", "Reviewer", "review carefully", false)).unwrap();
        id_store.bundle_upsert(&make_bundle("b2", "Writer", "write plainly", false)).unwrap();
        leftover_bundle_mcp_ref(&mstore, "b2", "b2-server", "writer-tools", "writer-tool");
        mstore
            .agent_bundles_set("agent-1", &["b2".to_string(), "gone".to_string(), "b1".to_string()])
            .unwrap();

        write_agent_config_files(&mstore, &id_store, &mstore, &agent, "test-agent", work_dir_str).unwrap();

        let claude_md = std::fs::read_to_string(work_dir.path().join("CLAUDE.md")).unwrap();
        let global = claude_md.find("# [Workspace] Rules").expect("Global Memory section");
        let writer = claude_md.find("# [Bundle] Writer\n\nwrite plainly").expect("first pick's section");
        let reviewer = claude_md.find("# [Bundle] Reviewer\n\nreview carefully").expect("second pick's section");
        assert!(global < writer && writer < reviewer, "Global Memory, then the picks in order: {claude_md}");

        let mcp_json = std::fs::read_to_string(work_dir.path().join(".mcp.json")).unwrap_or_default();
        assert!(!mcp_json.contains("writer-tools"), "a picked bundle's server must not launch: {mcp_json}");
    }
}

#[cfg(test)]
mod record_agent_open_launch_tests {
    use super::*;
    use crate::backend::storage::agents::test_agent_def;

    /// Identity M4b-4 (spec §6.5.8): an `agent.open` of a user agent records
    /// the launch on its row (lifecycle only) and stamps the block, so the
    /// block resolves to that row — the row's UID and token at its spawn.
    /// Codex P1 on #3584: an open whose local row cannot be confirmed
    /// (here: an agent that exists neither locally nor in a registry) fails
    /// instead of spawning row-less; a local agent passes.
    #[test]
    fn an_open_without_a_confirmed_local_row_is_refused() {
        let store = Store::open_in_memory().unwrap();
        let err = require_local_agent_row(&store, "agent-nowhere").unwrap_err();
        assert!(err.starts_with("AGENT_ROW_UNAVAILABLE"), "{err}");
        let mut def = test_agent_def("agent-here", "Here", "claude", "agent", 1, "");
        store.agent_def_insert(&mut def).unwrap();
        assert!(require_local_agent_row(&store, "agent-here").is_ok());
    }

    /// Codex P1 on #3584: an agent deleted between the row check and the
    /// record (the delete handlers do not take the open lock) fails the open
    /// rather than spawning a block that names a missing row.
    #[test]
    fn an_open_whose_agent_was_deleted_mid_open_is_refused() {
        let store = Store::open_in_memory().unwrap();
        let mut def = test_agent_def("agent-gone-mid", "GoneMid", "claude", "agent", 1, "");
        store.agent_def_insert(&mut def).unwrap();
        assert!(require_local_agent_row(&store, "agent-gone-mid").is_ok());
        assert!(store.agent_def_delete("agent-gone-mid").unwrap());
        let err =
            record_agent_open_launch(&store, "agent-gone-mid", &uuid::Uuid::new_v4().to_string())
                .unwrap_err();
        assert!(err.starts_with("AGENT_ROW_UNAVAILABLE"), "{err}");
    }

    #[test]
    fn an_agent_open_launch_is_recorded_stamped_and_resolves() {
        let store = Store::open_in_memory().unwrap();
        let mut def = test_agent_def("agent-open-x", "OpenX", "claude", "agent", 1, "");
        store.agent_def_insert(&mut def).unwrap();
        // ORef::parse, behind update_object_meta, needs a UUID-shaped oid.
        let block_id = uuid::Uuid::new_v4().to_string();
        let mut block = Block {
            oid: block_id.clone(),
            parentoref: String::new(),
            version: 0,
            runtimeopts: None,
            stickers: None,
            meta: {
                let mut m = obj::MetaMapType::new();
                m.insert("agentId".to_string(), json!("agent-open-x"));
                m
            },
            subblockids: None,
        };
        store.insert(&mut block).unwrap();

        record_agent_open_launch(&store, "agent-open-x", &block_id).unwrap();

        let stamped: Block = store.must_get(&block_id).unwrap();
        assert_eq!(
            stamped.meta.get("agentInstanceId"),
            Some(&json!("agent-open-x"))
        );
        let row = store.instance_get("agent-open-x").unwrap().unwrap();
        assert_eq!(row.block_id, block_id);
        assert_eq!(row.status, "running");
        let resolved = store
            .instance_get_active_for_block(&block_id)
            .unwrap()
            .map(|r| r.id);
        assert_eq!(resolved.as_deref(), Some("agent-open-x"));
    }

    fn def(id: &str, name: &str, is_seeded: i64) -> AgentDefinition {
        let mut d = test_agent_def(id, name, "claude", "agent", 1, "");
        d.is_seeded = is_seeded;
        d
    }

    /// `agent.open` opens user agents only: a template is refused by id or by
    /// name, and a user agent is preferred over a template it shares a name
    /// with — including the template's id, which is its lowercase name
    /// (adversarial review of #3600) — whatever the list order.
    #[test]
    fn agent_open_selects_my_agents_and_refuses_templates() {
        let agents = vec![
            def("claude", "Claude", 1),
            def("agent-mine", "Claude", 0),
            def("codex", "Codex", 1),
            def("agent-other", "agent-mine", 0),
        ];
        let pick = |wanted| select_openable_agent(&agents, wanted).map(|a| a.id.as_str());

        assert_eq!(pick("agent-mine"), Ok("agent-mine"), "an id wins over a name");
        assert_eq!(pick("claude"), Ok("agent-mine"), "not the template's id");
        assert_eq!(pick("CLAUDE"), Ok("agent-mine"));
        for wanted in ["codex", "Codex"] {
            let err = pick(wanted).unwrap_err();
            assert!(err.starts_with("TEMPLATE_NOT_OPENABLE"), "{wanted}: {err}");
        }
        let err = pick("nobody").unwrap_err();
        assert!(err.starts_with("AGENT_NOT_FOUND"), "{err}");
    }
}

#[cfg(test)]
mod single_live_instance_tests {
    use super::*;
    use crate::backend::storage::agents::test_agent_def;

    /// Every file under the shared registry root except the lease tree, with
    /// its bytes — what "nothing shared was written" is measured against.
    fn snapshot(root: &std::path::Path) -> Vec<(std::path::PathBuf, Vec<u8>)> {
        let mut out = Vec::new();
        let mut stack = vec![root.to_path_buf()];
        while let Some(dir) = stack.pop() {
            for entry in std::fs::read_dir(&dir).into_iter().flatten().flatten() {
                let path = entry.path();
                if path.file_name().is_some_and(|n| n == "leases") {
                    continue;
                }
                if path.is_dir() {
                    stack.push(path);
                } else {
                    out.push((path.clone(), std::fs::read(&path).unwrap_or_default()));
                }
            }
        }
        out.sort();
        out
    }

    /// SPEC_AGENT_SINGLE_LIVE_INSTANCE_2026_09_24 §7 test 9 (I9): opening an
    /// agent another AgentMux instance on this host is running is refused
    /// before the handler writes anything — no block, no registry record.
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn opening_an_agent_live_in_another_instance_writes_nothing() {
        let state = crate::server::tests::test_state();
        let tmp = tempfile::tempdir().unwrap();
        let registry = Arc::new(crate::registry::Registry::open(tmp.path().join("registry")).unwrap());
        state.mstore.set_registry(Arc::clone(&registry));
        let uid = uuid::Uuid::new_v4().to_string();
        let mut def = test_agent_def(&uid, "Agent3", "claude", "host", 1, "");
        state.mstore.agent_def_insert(&mut def).unwrap();

        let lease_store =
            crate::backend::agent_admission::lease_store_for(Some(Arc::clone(&registry))).unwrap();
        let _other = crate::backend::agent_admission::acquire(
            &lease_store,
            &uid,
            "Agent3",
            &Arc::from("another-srv-boot"),
            "other-block",
            None,
            |_| {},
        )
        .unwrap();

        let blocks_before = state.mstore.get_all::<Block>().unwrap().len();
        let registry_before = snapshot(registry.root());

        let err = open_agent_impl(
            &state,
            CommandAgentOpenData {
                agent_id: uid.clone(),
                tab_id: None,
                split_direction: None,
                split_reference_block_id: None,
                focus: None,
            },
        )
        .await
        .err()
        .expect("the open must be refused");

        assert!(err.starts_with("AGENT_LIVE_ELSEWHERE: Agent3 is already running"), "{err}");
        assert_eq!(state.mstore.get_all::<Block>().unwrap().len(), blocks_before, "no block created");
        assert_eq!(snapshot(registry.root()), registry_before, "shared registry untouched");
    }
}