agentmux_srv\server/

app_api.rs

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

//! App API — high-level commands for programmatic control of AgentMux.
//!
//! These commands orchestrate multiple low-level operations (CreateBlock, SetMeta,
//! ControllerResync) behind stable, intent-based interfaces. Callers express what
//! they want ("open an agent pane with AgentX"), not how to do it.

use std::sync::Arc;

use base64::Engine;
use serde_json::json;

use crate::backend::blockcontroller;
use crate::backend::obj::{self, Block, Tab, Workspace, MetaMapType};
use crate::backend::providers;
use crate::backend::rpc::engine::WshRpcEngine;
use crate::backend::rpc_types::*;
use crate::backend::session_archive;
use crate::backend::storage::store::{Store, AgentContent, AgentDefinition, AgentInstance};

use super::AppState;
use crate::server::cli_handlers::resolve_cli_on_path;

/// Register all App API handlers on the RPC engine.
pub fn register_app_api_handlers(engine: &Arc<WshRpcEngine>, state: &AppState) {
    register_agent_open(engine, state);
    register_agent_send(engine, state);
    register_agent_stop(engine, state);
    register_agent_status(engine, state);
    register_agent_list(engine, state);
    register_agent_output(engine, state);
    register_agent_process_list(engine, state);
    register_agent_tracked_blocks(engine, state);
    register_agent_kill_process(engine, state);
    register_agent_kill_tree(engine, state);
    register_agent_define(engine, state);
    register_pane_open(engine, state);
    register_blockfile_line_count(engine, state);
    register_blockfile_read_range(engine, state);
    register_blockfile_read_state(engine, state);
    register_blockfile_write_state(engine, state);
    register_session_digest(engine, state);
    register_session_activity_summary(engine, state);
    register_session_archive_handler(engine, state);
    register_session_restore_handler(engine, state);
    register_session_export_handler(engine, state);
}

// ---------------------------------------------------------------------------
// agent.process-list + agent.tracked-blocks
// ---------------------------------------------------------------------------

fn register_agent_process_list(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let process_tracker = state.process_tracker.clone();
    engine.register_handler(
        COMMAND_AGENT_PROCESS_LIST,
        Box::new(move |data, _ctx| {
            let process_tracker = process_tracker.clone();
            Box::pin(async move {
                let cmd: AgentProcessListCommand = serde_json::from_value(data)
                    .map_err(|e| format!("agent.process-list: {e}"))?;
                let members = process_tracker.list_block(&cmd.block_id);
                let confidence = match process_tracker.confidence_of(&cmd.block_id) {
                    crate::backend::process_tracker::TrackingConfidence::High => "high",
                    crate::backend::process_tracker::TrackingConfidence::BestEffort => "best_effort",
                    crate::backend::process_tracker::TrackingConfidence::None => "none",
                };
                let processes: Vec<AgentProcessInfo> = members
                    .into_iter()
                    .map(|m| AgentProcessInfo {
                        pid: m.pid,
                        command: m.command,
                        rss_bytes: m.rss_bytes,
                        started_at_ms: m.started_at_ms,
                    })
                    .collect();
                Ok(Some(serde_json::to_value(&AgentProcessListResult {
                    block_id: cmd.block_id,
                    confidence: confidence.to_string(),
                    processes,
                }).unwrap()))
            })
        }),
    );
}

fn register_agent_tracked_blocks(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let process_tracker = state.process_tracker.clone();
    engine.register_handler(
        COMMAND_AGENT_TRACKED_BLOCKS,
        Box::new(move |_data, _ctx| {
            let process_tracker = process_tracker.clone();
            Box::pin(async move {
                let process_ids = process_tracker.list_all_blocks();
                let reactive_ids = crate::backend::reactive::get_global_handler().list_active_blocks();
                let mut seen = std::collections::HashSet::new();
                let block_ids: Vec<String> = process_ids.into_iter().chain(reactive_ids)
                    .filter(|id| seen.insert(id.clone()))
                    .collect();
                Ok(Some(serde_json::to_value(&AgentTrackedBlocksResult {
                    block_ids,
                }).unwrap()))
            })
        }),
    );
}

fn register_agent_kill_process(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let process_tracker = state.process_tracker.clone();
    engine.register_handler(
        COMMAND_AGENT_KILL_PROCESS,
        Box::new(move |data, _ctx| {
            let process_tracker = process_tracker.clone();
            Box::pin(async move {
                let cmd: AgentKillProcessCommand = serde_json::from_value(data)
                    .map_err(|e| format!("agent.kill-process: {e}"))?;
                tracing::info!(
                    block_id = %cmd.block_id,
                    pid = cmd.pid,
                    "agent.kill-process"
                );
                let ok = process_tracker.kill_pid(&cmd.block_id, cmd.pid);
                Ok(Some(serde_json::to_value(&AgentKillResult { ok }).unwrap()))
            })
        }),
    );
}

fn register_agent_kill_tree(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let process_tracker = state.process_tracker.clone();
    engine.register_handler(
        COMMAND_AGENT_KILL_TREE,
        Box::new(move |data, _ctx| {
            let process_tracker = process_tracker.clone();
            Box::pin(async move {
                let cmd: AgentKillTreeCommand = serde_json::from_value(data)
                    .map_err(|e| format!("agent.kill-tree: {e}"))?;
                tracing::info!(block_id = %cmd.block_id, "agent.kill-tree");
                let ok = process_tracker.kill_tree(&cmd.block_id);
                Ok(Some(serde_json::to_value(&AgentKillResult { ok }).unwrap()))
            })
        }),
    );
}

// ---------------------------------------------------------------------------
// agent.open
// ---------------------------------------------------------------------------

fn register_agent_open(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let wstore = state.wstore.clone();
    let broker = state.broker.clone();
    let event_bus = state.event_bus.clone();
    let filestore = state.filestore.clone();
    // Capture the whole (Arc-backed, Clone) AppState so the block can be created
    // through the reducer (#1681) — see the create-block site below.
    let app_state = state.clone();

    engine.register_handler(
        COMMAND_AGENT_OPEN,
        Box::new(move |data, _ctx| {
            let wstore = wstore.clone();
            let broker = broker.clone();
            let event_bus = event_bus.clone();
            let filestore = filestore.clone();
            let app_state = app_state.clone();
            Box::pin(async move {
                let cmd: CommandAgentOpenData = serde_json::from_value(data)
                    .map_err(|e| format!("agent.open: {e}"))?;

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

                // 1. Load the agent definition (by id or name)
                let agents = wstore.agent_def_list()
                    .map_err(|e| format!("agent.open: {e}"))?;
                let agent = agents.iter()
                    .find(|a| a.id == cmd.agent_id || a.name.eq_ignore_ascii_case(&cmd.agent_id))
                    .ok_or_else(|| format!("AGENT_NOT_FOUND: no agent definition with id '{}'", cmd.agent_id))?
                    .clone();

                // 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(&wstore, 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(&wstore, &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 = 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(
                            &wstore, &format!("block:{}", existing.oid), &meta_update,
                        );
                        // Register controller
                        let block_for_resync = wstore.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,
                            Some(broker.clone()), Some(event_bus.clone()), Some(wstore.clone()),
                            Some(filestore.clone()),
                        );
                    }
                    let status = blockcontroller::get_block_controller_status(&existing.oid)
                        .map(|s| s.shellprocstatus)
                        .unwrap_or_else(|| "init".to_string());
                    return Ok(Some(serde_json::to_value(&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,
                    }).unwrap()));
                }

                // 5. Resolve CLI path
                let version = env!("CARGO_PKG_VERSION");
                let home = std::env::var("HOME")
                    .or_else(|_| std::env::var("USERPROFILE"))
                    .map_err(|_| "cannot determine home directory".to_string())?;
                let provider_dir = format!("{}/.agentmux/{}/cli/{}", home, version, provider.id);
                let npm_bin = if cfg!(windows) {
                    format!("{}/node_modules/.bin/{}.cmd", provider_dir, provider.cli_command)
                } else {
                    format!("{}/node_modules/.bin/{}", provider_dir, provider.cli_command)
                };
                let mut resolved_cli_path = 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_cli_on_path(provider.cli_command).await {
                            resolved_cli_path = path;
                        }
                    }
                    if !std::path::Path::new(&resolved_cli_path).exists() {
                        return Err(format!(
                            "CLI_NOT_AVAILABLE: {} not installed at {}. Open an agent pane in the UI to trigger installation.",
                            provider.cli_command, npm_bin
                        ));
                    }
                }

                // 6. Build metadata
                let controller_type = provider.controller_type_str();
                let is_persistent = controller_type == "persistent";
                let mut cli_args: Vec<String> = if is_persistent {
                    provider.persistent_launch_args
                        .unwrap_or(provider.launch_args)
                        .iter().map(|s| s.to_string()).collect()
                } else {
                    provider.launch_args.iter().map(|s| s.to_string()).collect()
                };
                // Append definition-level flags (e.g. --model <value>) stored in provider_flags.
                if !agent.provider_flags.is_empty() {
                    cli_args.extend(agent.provider_flags.split_whitespace().map(str::to_string));
                }

                let agent_slug = agent.name.to_lowercase()
                    .chars().map(|c| if c.is_alphanumeric() || c == '-' || c == '_' { c } else { '-' })
                    .collect::<String>();
                let work_dir = if agent.working_directory.is_empty() {
                    format!("~/.agentmux/agents/{}", agent_slug)
                } 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!(""));
                }
                // Use AGENTMUX_CONFIG_HOME so portable installs stay self-contained.
                // Falls back to ~/.agentmux/config for non-portable installs.
                let config_home = std::env::var("AGENTMUX_CONFIG_HOME")
                    .unwrap_or_else(|_| format!("{}/.agentmux/config", home));
                // 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-identity bundle override
                // (identity_handlers) still wins for explicit multi-account.
                let auth_dir = agentmux_common::DataPaths::from_env()
                    .map(|p| p.provider_auth_dir(provider.auth_dir_name).to_string_lossy().into_owned())
                    .unwrap_or_else(|| format!("{}/.agentmux/shared/providers/{}", home, provider.auth_dir_name));
                let _ = std::fs::create_dir_all(&auth_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));
                }
                // 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)) = wstore.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
                env_vars.insert("GH_CONFIG_DIR".to_string(), json!(format!("{}/gh-{}", config_home, agent_slug)));
                // 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));
                // Exit delay only for subprocess
                if !is_persistent {
                    env_vars.insert("CLAUDE_CODE_EXIT_AFTER_STOP_DELAY".to_string(), json!("30000"));
                }

                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)) = wstore.agent_content_get(&agent.id, "ui:zoom") {
                    if let Some(z) = parse_seed_zoom(&c.content) {
                        meta.insert("term:zoom".to_string(), json!(z));
                    }
                }
                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() { "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));
                // Derive output format from provider ID (matches frontend providers/index.ts)
                let output_format = match provider.id {
                    "claude" => "claude-stream-json",
                    "codex" => "codex-json",
                    "gemini" => "gemini-json",
                    // Qwen Code is a Gemini-CLI fork → same stream-json schema.
                    "qwen" => "gemini-json",
                    "kimi" => "kimi-stream-json",
                    _ => "claude-stream-json",
                };
                meta.insert("agentOutputFormat".to_string(), json!(output_format));
                meta.insert("controller".to_string(), json!(controller_type));
                meta.insert("cmd".to_string(), json!(&resolved_cli_path));
                meta.insert("cmd:args".to_string(), json!(cli_args));
                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:session_id_field".to_string(), json!(provider.session_id_field));

                // 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 wstore 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 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_wstore(ev, &wstore) {
                        tracing::warn!("agent.open: CreateBlock wstore 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).
                {
                    let tab: Tab = wstore.must_get(&tab_id)
                        .map_err(|e| format!("agent.open: reload tab: {e}"))?;
                    if let Ok(mut layout) = wstore.must_get::<obj::LayoutState>(&tab.layoutstate) {
                        let mut actions = layout.pendingbackendactions.take().unwrap_or_default();
                        actions.push(obj::LayoutActionData {
                            actiontype: "insert".to_string(),
                            actionid: uuid::Uuid::new_v4().to_string(),
                            blockid: block_id.clone(),
                            nodesize: None,
                            indexarr: None,
                            focused: true,
                            magnified: false,
                            ephemeral: false,
                            targetblockid: String::new(),
                            position: String::new(),
                        });
                        layout.pendingbackendactions = Some(actions);
                        let _ = wstore.update(&mut layout);
                    }
                }

                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(&wstore, &agent, routing_id, &work_dir)?;

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

                // 10. Broadcast block + tab + layout updates to frontend
                {
                    let mut updates = Vec::new();
                    if let Ok(updated_block) = wstore.must_get::<Block>(&block_id) {
                        updates.push(obj::WaveObjUpdate {
                            updatetype: "update".into(),
                            otype: "block".into(),
                            oid: block_id.clone(),
                            obj: Some(obj::wave_obj_to_value(&updated_block)),
                        });
                    }
                    if let Ok(updated_tab) = wstore.must_get::<Tab>(&tab_id) {
                        updates.push(obj::WaveObjUpdate {
                            updatetype: "update".into(),
                            otype: "tab".into(),
                            oid: tab_id.clone(),
                            obj: Some(obj::wave_obj_to_value(&updated_tab)),
                        });
                        if let Ok(updated_layout) = wstore.must_get::<obj::LayoutState>(&updated_tab.layoutstate) {
                            updates.push(obj::WaveObjUpdate {
                                updatetype: "update".into(),
                                otype: "layout".into(),
                                oid: updated_tab.layoutstate.clone(),
                                obj: Some(obj::wave_obj_to_value(&updated_layout)),
                            });
                        }
                    }
                    for update in &updates {
                        let oref = format!("{}:{}", update.otype, update.oid);
                        if let Ok(data) = serde_json::to_value(update) {
                            event_bus.broadcast_event(
                                &crate::backend::eventbus::WSEventType {
                                    eventtype: "waveobj:update".to_string(),
                                    oref,
                                    data: Some(data),
                                },
                            );
                        }
                    }
                }

                Ok(Some(serde_json::to_value(&AgentOpenResult {
                    block_id,
                    tab_id,
                    agent_id: cmd.agent_id,
                    provider: agent.provider,
                    controller_type: controller_type.to_string(),
                    status: "init".to_string(),
                    created: true,
                }).unwrap()))
            })
        }),
    );
}

// ---------------------------------------------------------------------------
// agent.send
// ---------------------------------------------------------------------------

fn register_agent_send(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let wstore = state.wstore.clone();
    let broker = state.broker.clone();
    let container_manager = state.container_manager.clone();

    engine.register_handler(
        COMMAND_AGENT_SEND,
        Box::new(move |data, _ctx| {
            let wstore = wstore.clone();
            let broker = broker.clone();
            let container_manager = container_manager.clone();
            Box::pin(async move {
                let cmd: CommandAgentSendData = serde_json::from_value(data)
                    .map_err(|e| format!("agent.send: {e}"))?;

                tracing::info!(block_id = %cmd.block_id, "agent.send");

                let ctrl = blockcontroller::get_controller(&cmd.block_id)
                    .ok_or_else(|| format!("NOT_RUNNING: no controller for block {}", cmd.block_id))?;

                // Re-read spawn config from block metadata (same pattern as agentinput)
                let block: Block = wstore
                    .get(&cmd.block_id)
                    .map_err(|e| format!("agent.send: {e}"))?
                    .ok_or_else(|| format!("BLOCK_NOT_FOUND: {}", cmd.block_id))?;

                let cli_command = obj::meta_get_string(&block.meta, "cmd", "claude");
                let cli_args: Vec<String> = match block.meta.get("cmd:args") {
                    Some(serde_json::Value::Array(arr)) => arr
                        .iter()
                        .filter_map(|v| v.as_str().map(|s| s.to_string()))
                        .collect(),
                    _ => vec![],
                };
                let working_dir = obj::meta_get_string(&block.meta, "cmd:cwd", "");
                let mut env_vars: std::collections::HashMap<String, String> = match block.meta.get("cmd:env") {
                    Some(serde_json::Value::Object(obj)) => obj
                        .iter()
                        .filter_map(|(k, v)| v.as_str().map(|s| (k.clone(), s.to_string())))
                        .collect(),
                    _ => std::collections::HashMap::new(),
                };
                // Identity injection — same path as websocket.rs's
                // AgentInputCommand. See identity/resolver.rs. Passes
                // the broker so the OAuth-class branch can publish a
                // `identitybundlebindings:changed:<bundle_id>` event
                // when the expiry probe updates an account's status
                // (PR D — spec §4.4).
                env_vars = crate::identity::resolver::inject_identity_env_async(
                    wstore.clone(),
                    Some(broker.clone()),
                    cmd.block_id.clone(),
                    env_vars,
                )
                .await;
                let session_id_field = obj::meta_get_string(
                    &block.meta, "agent:session_id_field", "session_id",
                );

                // Dispatch to persistent or subprocess controller
                let mut session_id = None;
                if let Some(persistent_ctrl) = ctrl
                    .as_any()
                    .downcast_ref::<blockcontroller::persistent::PersistentSubprocessController>()
                {
                    // Container agents use per-turn docker exec — incompatible with a
                    // long-lived persistent subprocess. Fail loudly instead of silently
                    // spawning the CLI on the host.
                    let agent_mode = obj::meta_get_string(&block.meta, "agentMode", "host");
                    if agent_mode == "container" {
                        return Err("container agents require a subprocess controller; this provider uses a persistent controller".to_string());
                    }
                    // Resume parity with the subprocess path: pass the resume
                    // flag + captured session id so a respawn (e.g. after a
                    // /model change) continues the same conversation.
                    let resume_flag = obj::meta_get_string(
                        &block.meta, "agent:resume_flag", "--resume",
                    );
                    let persisted_session_id = obj::meta_get_string(
                        &block.meta, "agent:sessionid", "",
                    );
                    let config = blockcontroller::persistent::PersistentSpawnConfig {
                        cli_command,
                        cli_args,
                        working_dir,
                        env_vars,
                        session_id_field,
                        resume_flag,
                        session_id: persisted_session_id,
                        message_id: None,
                    };
                    persistent_ctrl.send_message(cmd.message, config)?;
                    session_id = persistent_ctrl.session_id();
                } else if let Some(subprocess_ctrl) = ctrl
                    .as_any()
                    .downcast_ref::<blockcontroller::subprocess::SubprocessController>()
                {
                    let resume_flag = obj::meta_get_string(
                        &block.meta, "agent:resume_flag", "--resume",
                    );
                    // Picker reattach (parallel of the websocket-path
                    // logic): hydrate the persisted session id from
                    // block meta so spawn_turn appends --resume <sid>
                    // on the FIRST turn after reattach.
                    let persisted_session_id = obj::meta_get_string(
                        &block.meta, "agent:sessionid", "",
                    );

                    // Container agent branch: use Docker socket API exec (P1a: no
                    // secrets in argv). Host agent branch: regular CLI subprocess.
                    let agent_mode = obj::meta_get_string(&block.meta, "agentMode", "host");
                    if agent_mode == "container" {
                        let cm = container_manager.as_deref()
                            .ok_or_else(|| "Docker not available on this host; cannot start container agent".to_string())?;
                        let container_image = obj::meta_get_string(
                            &block.meta, "agent:container_image", "ghcr.io/agentmuxai/agent-claude:latest",
                        );
                        // Use agentId (UUID) — always valid as a Docker name; display names can have spaces.
                        let agent_id = obj::meta_get_string(&block.meta, "agentId", "");
                        let container_name = crate::backend::container::container_name_for_slug(&agent_id);
                        let volumes_json = obj::meta_get_string(&block.meta, "agent:container_volumes", "[]");
                        let volumes: Vec<String> = serde_json::from_str(&volumes_json).unwrap_or_default();

                        // Ensure container is alive (pull image if needed — P1b).
                        cm.ensure_running(&container_name, &container_image, &volumes, &[]).await
                            .map_err(|e| format!("container ensure_running failed: {e}"))?;


                        tracing::info!(
                            container = %container_name,
                            image = %container_image,
                            "container agent turn: bollard exec (env via Docker socket, not argv)",
                        );

                        // Env is passed via CreateExecOptions.env (Docker socket API),
                        // NOT as -e KEY=VALUE argv args — this prevents CWE-214 exposure.
                        // spawn_container_turn filters config.env_vars (denylist) per
                        // turn, so cmd:cwd (host path) and host-path vars never reach
                        // the container, and each queued turn uses its own env.

                        // Base cmd: [container_command, ...cli_args]. The command
                        // is the provider CLI resolved INSIDE the image (on PATH,
                        // e.g. `claude`) — NOT `cli_command`/`cmd`, which is the
                        // host-resolved absolute npm path and does not exist in the
                        // container (docker exec would fail "no such file or
                        // directory"). cli_args are format flags + provider flags —
                        // no host paths, safe as-is. spawn_container_turn appends
                        // --resume <sid> internally.
                        let container_command = obj::meta_get_string(
                            &block.meta, "agent:container_command", "claude",
                        );
                        let mut base_cmd = vec![container_command];
                        base_cmd.extend(cli_args);

                        let config = blockcontroller::subprocess::SubprocessSpawnConfig {
                            cli_command: String::new(), // unused by spawn_container_turn
                            cli_args: vec![],           // unused by spawn_container_turn
                            working_dir: String::new(), // unused — container has own cwd
                            env_vars,
                            message: cmd.message,
                            resume_flag,
                            session_id_field,
                            message_id: None,
                            session_id: if persisted_session_id.is_empty() {
                                None
                            } else {
                                Some(persisted_session_id)
                            },
                        };
                        subprocess_ctrl.spawn_container_turn(cm.clone(), container_name, base_cmd, config)?;
                    } else {
                        // Host agent: regular CLI subprocess (env set on child process, not in argv).
                        let config = blockcontroller::subprocess::SubprocessSpawnConfig {
                            cli_command,
                            cli_args,
                            working_dir,
                            env_vars,
                            message: cmd.message,
                            resume_flag,
                            session_id_field,
                            message_id: None,
                            session_id: if persisted_session_id.is_empty() {
                                None
                            } else {
                                Some(persisted_session_id)
                            },
                        };
                        subprocess_ctrl.spawn_turn(config)?;
                    }
                } else {
                    return Err("NOT_RUNNING: controller type not supported".to_string());
                }

                Ok(Some(serde_json::to_value(&AgentSendResult {
                    block_id: cmd.block_id,
                    status: "running".to_string(),
                    session_id,
                }).unwrap()))
            })
        }),
    );
}

// ---------------------------------------------------------------------------
// agent.stop
// ---------------------------------------------------------------------------

fn register_agent_stop(engine: &Arc<WshRpcEngine>, _state: &AppState) {
    engine.register_handler(
        COMMAND_AGENT_STOP_API,
        Box::new(|data, _ctx| {
            Box::pin(async move {
                let cmd: CommandAgentStopApiData = serde_json::from_value(data)
                    .map_err(|e| format!("agent.stop: {e}"))?;

                tracing::info!(block_id = %cmd.block_id, signal = ?cmd.signal, "agent.stop");

                let ctrl = blockcontroller::get_controller(&cmd.block_id)
                    .ok_or_else(|| format!("NOT_RUNNING: no controller for block {}", cmd.block_id))?;

                let force = matches!(cmd.signal.as_deref(), Some("SIGKILL") | Some("SIGTERM"));
                ctrl.stop(!force, blockcontroller::STATUS_DONE)?;

                let exit_code = blockcontroller::get_block_controller_status(&cmd.block_id)
                    .map(|s| s.shellprocexitcode);

                Ok(Some(serde_json::to_value(&AgentStopResult {
                    block_id: cmd.block_id,
                    status: "done".to_string(),
                    exit_code,
                }).unwrap()))
            })
        }),
    );
}

// ---------------------------------------------------------------------------
// agent.status
// ---------------------------------------------------------------------------

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

    engine.register_handler(
        COMMAND_AGENT_STATUS,
        Box::new(move |data, _ctx| {
            let wstore = wstore.clone();
            Box::pin(async move {
                let cmd: CommandAgentStatusData = serde_json::from_value(data)
                    .map_err(|e| format!("agent.status: {e}"))?;

                let block: Block = wstore
                    .get(&cmd.block_id)
                    .map_err(|e| format!("agent.status: {e}"))?
                    .ok_or_else(|| format!("BLOCK_NOT_FOUND: {}", cmd.block_id))?;

                let agent_id = obj::meta_get_string(&block.meta, "agentId", "");
                let provider = obj::meta_get_string(&block.meta, "agentProvider", "");
                let controller_type = obj::meta_get_string(&block.meta, "controller", "");

                let runtime = blockcontroller::get_block_controller_status(&cmd.block_id);
                let status = runtime.as_ref()
                    .map(|s| s.shellprocstatus.clone())
                    .unwrap_or_else(|| "init".to_string());
                let exit_code = runtime.as_ref()
                    .and_then(|s| if s.shellprocstatus == "done" { Some(s.shellprocexitcode) } else { None });
                let pid = None; // PID not currently exposed in status struct

                // Get session ID from block meta
                let session_id = block.meta.get("agent:sessionid")
                    .and_then(|v| v.as_str())
                    .map(|s| s.to_string());

                Ok(Some(serde_json::to_value(&AgentStatusResult {
                    block_id: cmd.block_id,
                    agent_id,
                    provider,
                    controller_type,
                    status,
                    session_id,
                    pid,
                    exit_code,
                }).unwrap()))
            })
        }),
    );
}

// ---------------------------------------------------------------------------
// agent.list
// ---------------------------------------------------------------------------

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

    engine.register_handler(
        COMMAND_AGENT_LIST,
        Box::new(move |_data, _ctx| {
            let wstore = wstore.clone();
            Box::pin(async move {
                let tabs: Vec<Tab> = wstore.get_all::<Tab>()
                    .map_err(|e| format!("agent.list: {e}"))?;

                let mut agents = Vec::new();
                for tab in &tabs {
                    for block_id in &tab.blockids {
                        if let Ok(Some(block)) = wstore.get::<Block>(block_id) {
                            let agent_id = obj::meta_get_string(&block.meta, "agentId", "");
                            if agent_id.is_empty() {
                                continue;
                            }
                            let provider = obj::meta_get_string(&block.meta, "agentProvider", "");
                            let status = blockcontroller::get_block_controller_status(block_id)
                                .map(|s| s.shellprocstatus)
                                .unwrap_or_else(|| "init".to_string());
                            let session_id = block.meta.get("agent:sessionid")
                                .and_then(|v| v.as_str())
                                .map(|s| s.to_string());

                            agents.push(AgentListEntry {
                                block_id: block_id.clone(),
                                tab_id: tab.oid.clone(),
                                agent_id,
                                provider,
                                status,
                                session_id,
                            });
                        }
                    }
                }

                Ok(Some(serde_json::to_value(&AgentListResult { agents }).unwrap()))
            })
        }),
    );
}

// ---------------------------------------------------------------------------
// agent.output
// ---------------------------------------------------------------------------

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

    engine.register_handler(
        COMMAND_AGENT_OUTPUT,
        Box::new(move |data, _ctx| {
            let broker = broker.clone();
            Box::pin(async move {
                let cmd: CommandAgentOutputData = serde_json::from_value(data)
                    .map_err(|e| format!("agent.output: {e}"))?;

                let scope = format!("block:{}", cmd.block_id);
                let max = cmd.max_lines.unwrap_or(1000);
                let after = cmd.after_line.unwrap_or(0);

                // Read persisted blockfile events from broker history
                let mut all_lines: Vec<String> = Vec::new();
                {
                    let events = broker.read_event_history(
                        crate::backend::wps::EVENT_BLOCK_FILE,
                        &scope,
                        max + after, // read enough to cover offset
                    );
                    for event in events {
                        if let Some(ref data) = event.data {
                            if let Some(data64) = data.get("data64").and_then(|v| v.as_str()) {
                                if let Ok(bytes) = base64::engine::general_purpose::STANDARD
                                    .decode(data64)
                                {
                                    let text = String::from_utf8_lossy(&bytes);
                                    for line in text.lines() {
                                        if !line.trim().is_empty() {
                                            all_lines.push(line.to_string());
                                        }
                                    }
                                }
                            }
                        }
                    }
                }

                let total = all_lines.len();
                let lines: Vec<String> = all_lines.into_iter()
                    .skip(after)
                    .take(max)
                    .collect();
                let has_more = after + lines.len() < total;

                Ok(Some(serde_json::to_value(&AgentOutputResult {
                    block_id: cmd.block_id,
                    lines,
                    total_lines: total,
                    has_more,
                }).unwrap()))
            })
        }),
    );
}

// ---------------------------------------------------------------------------
// pane.open
// ---------------------------------------------------------------------------

fn register_pane_open(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let state = state.clone();
    engine.register_handler(
        COMMAND_PANE_OPEN,
        Box::new(move |data, _ctx| {
            let state = state.clone();
            Box::pin(async move {
                let cmd: CommandPaneOpenData = serde_json::from_value(data)
                    .map_err(|e| format!("pane.open: {e}"))?;
                let result = open_pane(&state, cmd).await?;
                Ok(Some(serde_json::to_value(&result).unwrap()))
            })
        }),
    );
}

/// Core `pane.open` logic, shared by the WebSocket RPC handler
/// (`register_pane_open`) and the HTTP route `POST /api/v1/pane/open`
/// (`agentmux-mcp`'s `OpenEditor` tool). Creates a block for the requested
/// view, enqueues a layout action (split or insert), and broadcasts the
/// block/tab/layout updates so the frontend renders the new pane.
pub async fn open_pane(state: &AppState, cmd: CommandPaneOpenData) -> Result<PaneOpenResult, String> {
    let wstore = state.wstore.clone();
    let event_bus = state.event_bus.clone();

    tracing::info!(view = %cmd.view, "pane.open");

    // Build meta for the requested view, validating required args
    let meta = build_pane_meta(&cmd)?;

    // Resolve tab
    let tab_id = resolve_tab_id(&wstore, cmd.tab_id.as_deref())?;

    // Floating path (SPEC_OPENEDITOR_FLOATING_AND_COLLAPSED_TREE_2026_06_16):
    // create the block in a fresh floating workspace (via reducer CreateBlock +
    // the existing tear_off_block saga) and signal the source window's frontend
    // to materialize the chromeless OS window — srv can't open windows itself.
    if cmd.floating == Some(true) {
        return open_pane_floating(state, &wstore, &event_bus, cmd.view, tab_id, meta).await;
    }

    // Create block (docked path) THROUGH THE REDUCER (#1681), not wcore-direct.
    // A store-only `create_block` lands the block in SQLite but never in the
    // reducer-canonical `state.blocks` map — and this RPC runs after bootstrap,
    // which is the only time `srv_state` is hydrated from SQLite. The pane then
    // renders fine (frontend reads SQLite) but a later TearOffBlock /
    // RedockFloatingPane is rejected "block not found" because the saga
    // pre-conditions check the reducer. The BlockCreated event carries meta,
    // which apply_block_created writes to the wstore Block. Mirrors the
    // already-correct open_pane_floating path.
    let meta_val = serde_json::to_value(&meta)
        .map_err(|e| format!("pane.open: meta serialize: {e}"))?;
    let create_events = crate::server::service::dispatch_to_reducer(
        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!("pane.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(|| "pane.open: CreateBlock emitted no BlockCreated".to_string())?;
    for ev in &create_events {
        if let Err(e) = crate::persist_subscriber::apply_event_to_wstore(ev, &wstore) {
            tracing::warn!("pane.open: CreateBlock wstore apply failed: {e}");
        }
    }
    crate::server::service::publish_events(state, &create_events);

    // Enqueue layout action — split if requested, else append
    let (actiontype, targetblockid, position) = resolve_placement(
        cmd.split_direction.as_deref(),
        cmd.split_reference_block_id.as_deref(),
    );
    let focused = cmd.focus.unwrap_or(true);

    {
        let tab: Tab = wstore.must_get(&tab_id)
            .map_err(|e| format!("pane.open: reload tab: {e}"))?;
        if let Ok(mut layout) = wstore.must_get::<obj::LayoutState>(&tab.layoutstate) {
            let mut actions = layout.pendingbackendactions.take().unwrap_or_default();
            actions.push(obj::LayoutActionData {
                actiontype,
                actionid: uuid::Uuid::new_v4().to_string(),
                blockid: block_id.clone(),
                nodesize: None,
                indexarr: None,
                focused,
                magnified: false,
                ephemeral: false,
                targetblockid,
                position,
            });
            layout.pendingbackendactions = Some(actions);
            let _ = wstore.update(&mut layout);
        }
    }

    tracing::info!(
        block_id = %block_id,
        view = %cmd.view,
        "pane.open: block created + layout updated"
    );

    // Broadcast block + tab + layout updates
    {
        let mut updates = Vec::new();
        if let Ok(updated_block) = wstore.must_get::<Block>(&block_id) {
            updates.push(obj::WaveObjUpdate {
                updatetype: "update".into(),
                otype: "block".into(),
                oid: block_id.clone(),
                obj: Some(obj::wave_obj_to_value(&updated_block)),
            });
        }
        if let Ok(updated_tab) = wstore.must_get::<Tab>(&tab_id) {
            updates.push(obj::WaveObjUpdate {
                updatetype: "update".into(),
                otype: "tab".into(),
                oid: tab_id.clone(),
                obj: Some(obj::wave_obj_to_value(&updated_tab)),
            });
            if let Ok(updated_layout) = wstore.must_get::<obj::LayoutState>(&updated_tab.layoutstate) {
                updates.push(obj::WaveObjUpdate {
                    updatetype: "update".into(),
                    otype: "layout".into(),
                    oid: updated_tab.layoutstate.clone(),
                    obj: Some(obj::wave_obj_to_value(&updated_layout)),
                });
            }
        }
        for update in &updates {
            let oref = format!("{}:{}", update.otype, update.oid);
            if let Ok(data) = serde_json::to_value(update) {
                event_bus.broadcast_event(
                    &crate::backend::eventbus::WSEventType {
                        eventtype: "waveobj:update".to_string(),
                        oref,
                        data: Some(data),
                    },
                );
            }
        }
    }

    Ok(PaneOpenResult {
        block_id,
        tab_id,
        view: cmd.view,
        created: true,
    })
}

/// Floating-pane branch of `open_pane`. The block already exists in
/// `source_tab_id`'s blockids (created by the caller, with no layout node).
/// This moves it into a fresh floating workspace via the `tear_off_block`
/// saga, sets up the new tab's layout, broadcasts the new WaveObjs, and asks
/// the source window's frontend to materialize the chromeless floating OS
/// window via the host `open_floating_pane_window` command (srv cannot open
/// windows itself). See docs/specs/SPEC_OPENEDITOR_FLOATING_AND_COLLAPSED_TREE_2026_06_16.md.
async fn open_pane_floating(
    state: &AppState,
    wstore: &Store,
    event_bus: &crate::backend::eventbus::EventBus,
    view: String,
    source_tab_id: String,
    meta: MetaMapType,
) -> Result<PaneOpenResult, String> {
    use agentmux_common::ipc::{Command, Event};

    // Source workspace from the reducer's canonical tab→workspace map.
    let source_ws_id = {
        let s = state.srv_state.lock().await;
        s.tabs
            .get(&source_tab_id)
            .map(|t| t.workspace_id.clone())
            .ok_or_else(|| format!("pane.open: floating: tab {source_tab_id} not in reducer state"))?
    };

    // Create the block through the reducer (NOT wcore-direct) so it lands in
    // `state.blocks` — the `tear_off_block` saga's pre-condition checks the
    // reducer-canonical block map. The `BlockCreated` event also carries the
    // meta, which `persist_subscriber::apply_block_created` writes into the
    // wstore Block so the editor renders with its file + tree state. We skip
    // layout placement, so the block never renders docked before the saga
    // moves it into the floating workspace (no flash).
    let meta_val = serde_json::to_value(&meta)
        .map_err(|e| format!("pane.open: floating: meta serialize: {e}"))?;
    let create_events = crate::server::service::dispatch_to_reducer(
        state,
        Command::CreateBlock {
            tab_id: source_tab_id.clone(),
            meta: meta_val,
        },
    )
    .await;
    if let Some(msg) = create_events.iter().find_map(|e| match e {
        Event::Error { message, .. } => Some(message.clone()),
        _ => None,
    }) {
        return Err(format!("pane.open: floating: CreateBlock: {msg}"));
    }
    let block_id = create_events
        .iter()
        .find_map(|e| match e {
            Event::BlockCreated { block_id, .. } => Some(block_id.clone()),
            _ => None,
        })
        .ok_or_else(|| "pane.open: floating: CreateBlock emitted no BlockCreated".to_string())?;
    for ev in &create_events {
        if let Err(e) = crate::persist_subscriber::apply_event_to_wstore(ev, wstore) {
            tracing::warn!("pane.open: floating: CreateBlock wstore apply failed: {e}");
        }
    }
    crate::server::service::publish_events(state, &create_events);

    // Tear the block off into a fresh floating workspace + tab (reuses the
    // exact saga the drag tear-off uses: CreateWorkspace → CreateTab → MoveBlock).
    let saga_val = crate::sagas::tear_off_block::run(
        state,
        block_id.clone(),
        source_tab_id.clone(),
        source_ws_id.clone(),
    )
    .await?;
    let new_ws_id = saga_val
        .get("new_workspace_id")
        .and_then(|v| v.as_str())
        .unwrap_or_default()
        .to_string();
    let new_tab_id = saga_val
        .get("new_tab_id")
        .and_then(|v| v.as_str())
        .unwrap_or_default()
        .to_string();
    if new_ws_id.is_empty() || new_tab_id.is_empty() {
        return Err("pane.open: floating: tear_off_block returned empty ids".to_string());
    }

    // Make the moved block the new tab's single root node so it renders.
    if let Err(e) =
        crate::server::service::setup_torn_off_block_layout(wstore, &new_tab_id, &block_id)
    {
        tracing::warn!(
            new_tab = %new_tab_id,
            "pane.open: floating: layout setup failed: {e} (block moved but layout malformed)"
        );
    }

    // Broadcast the new workspace + layout + tab + block so any frontend syncs
    // its WaveObj cache (mirrors the docked path + the tear-off DnD handler).
    {
        let mut updates: Vec<obj::WaveObjUpdate> = Vec::new();
        if let Ok(ws) = wstore.must_get::<Workspace>(&new_ws_id) {
            updates.push(obj::WaveObjUpdate {
                updatetype: "update".into(),
                otype: "workspace".into(),
                oid: new_ws_id.clone(),
                obj: Some(obj::wave_obj_to_value(&ws)),
            });
        }
        if let Ok(t) = wstore.must_get::<Tab>(&new_tab_id) {
            if let Ok(layout) = wstore.must_get::<obj::LayoutState>(&t.layoutstate) {
                updates.push(obj::WaveObjUpdate {
                    updatetype: "update".into(),
                    otype: "layout".into(),
                    oid: t.layoutstate.clone(),
                    obj: Some(obj::wave_obj_to_value(&layout)),
                });
            }
            updates.push(obj::WaveObjUpdate {
                updatetype: "update".into(),
                otype: "tab".into(),
                oid: new_tab_id.clone(),
                obj: Some(obj::wave_obj_to_value(&t)),
            });
        }
        if let Ok(b) = wstore.must_get::<Block>(&block_id) {
            updates.push(obj::WaveObjUpdate {
                updatetype: "update".into(),
                otype: "block".into(),
                oid: block_id.clone(),
                obj: Some(obj::wave_obj_to_value(&b)),
            });
        }
        for update in &updates {
            let oref = format!("{}:{}", update.otype, update.oid);
            if let Ok(data) = serde_json::to_value(update) {
                event_bus.broadcast_event(&crate::backend::eventbus::WSEventType {
                    eventtype: "waveobj:update".to_string(),
                    oref,
                    data: Some(data),
                });
            }
        }
    }

    // Ask the source window's frontend to open the floating OS window — scoped
    // to that window (mirrors the window-scoped `userinput` event) so exactly
    // one window acts. The frontend handler calls the host
    // `open_floating_pane_window` command.
    let window_id = {
        let s = state.srv_state.lock().await;
        s.windows
            .iter()
            .find(|(_, w)| w.workspace_id == source_ws_id)
            .map(|(id, _)| id.clone())
    };
    match window_id {
        Some(win) => {
            state.broker.publish(crate::backend::wps::WaveEvent {
                event: "openfloatingpane".to_string(),
                scopes: vec![win],
                sender: String::new(),
                persist: 0,
                data: Some(json!({
                    "block_id": block_id,
                    "workspace_id": new_ws_id,
                })),
            });
        }
        None => {
            tracing::warn!(
                source_ws = %source_ws_id,
                "pane.open: floating: no window mapped to source workspace — floater not opened"
            );
        }
    }

    Ok(PaneOpenResult {
        block_id,
        tab_id: new_tab_id,
        view,
        created: true,
    })
}

/// Build the metadata map for a pane.open request, validating required args.
fn build_pane_meta(cmd: &CommandPaneOpenData) -> Result<MetaMapType, String> {
    let mut meta = MetaMapType::new();

    match cmd.view.as_str() {
        "editor" => {
            let file = cmd.file.as_deref().filter(|s| !s.is_empty())
                .ok_or_else(|| "MISSING_ARG: view=editor requires 'file'".to_string())?;
            meta.insert("view".to_string(), json!("editor"));
            meta.insert("file".to_string(), json!(file));
            // Optional initial file-tree state. Only write when explicitly
            // requested; absent leaves the frontend default (expanded). The
            // frontend collapses iff this is literally `false`
            // (EditorViewModel restore: `meta["editor:tree_expanded"] === false`).
            if let Some(expanded) = cmd.tree_expanded {
                meta.insert("editor:tree_expanded".to_string(), json!(expanded));
            }
        }
        "term" => {
            meta.insert("view".to_string(), json!("term"));
            meta.insert("controller".to_string(), json!("shell"));
            if let Some(cwd) = cmd.cwd.as_deref().filter(|s| !s.is_empty()) {
                meta.insert("cmd:cwd".to_string(), json!(cwd));
            }
        }
        "browser" => {
            let url = cmd.url.as_deref().filter(|s| !s.is_empty())
                .ok_or_else(|| "MISSING_ARG: view=browser requires 'url'".to_string())?;
            meta.insert("view".to_string(), json!("browser"));
            meta.insert("url".to_string(), json!(url));
        }
        "sysinfo" => {
            meta.insert("view".to_string(), json!("sysinfo"));
        }
        "help" => {
            meta.insert("view".to_string(), json!("help"));
        }
        other => {
            return Err(format!(
                "INVALID_VIEW: unsupported view '{other}' (expected editor/term/browser/sysinfo/help)"
            ));
        }
    }

    if let Some(title) = cmd.title.as_deref().filter(|s| !s.is_empty()) {
        meta.insert("frame:title".to_string(), json!(title));
    }

    Ok(meta)
}

/// Translate `split_direction` + `split_reference_block_id` into the backend
/// layout action triple. Returns `(actiontype, targetblockid, position)`.
/// Falls back to a plain `insert` if direction/reference are missing.
fn resolve_placement(
    direction: Option<&str>,
    reference: Option<&str>,
) -> (String, String, String) {
    let reference = match reference.filter(|s| !s.is_empty()) {
        Some(r) => r,
        None => return ("insert".to_string(), String::new(), String::new()),
    };

    let (actiontype, position) = match direction {
        Some("right") => (crate::backend::wcore::LAYOUT_ACTION_SPLIT_HORIZONTAL, "after"),
        Some("left") => (crate::backend::wcore::LAYOUT_ACTION_SPLIT_HORIZONTAL, "before"),
        Some("down") | Some("below") => (crate::backend::wcore::LAYOUT_ACTION_SPLIT_VERTICAL, "after"),
        Some("up") | Some("above") => (crate::backend::wcore::LAYOUT_ACTION_SPLIT_VERTICAL, "before"),
        _ => return ("insert".to_string(), String::new(), String::new()),
    };

    (actiontype.to_string(), reference.to_string(), position.to_string())
}

// ---------------------------------------------------------------------------
// Cross-channel transcript fallback (shared by line_count + read_range)
// ---------------------------------------------------------------------------

/// If this channel has no local `output` for `block_id` but the agent's GLOBAL
/// transcript zone (`agent:<defId>:current`) does, return `(global_store,
/// agent_zone)`. Returns `None` when the local output is present and non-empty,
/// the block isn't agent-anchored, there's no global store, or the global zone
/// is empty — callers then read the per-channel store keyed by `block_id`.
///
/// Only the agent `output` stream is globalized; every other file stays local.
/// This is what makes opening a cross-channel agent show its conversation: the
/// freshly-opened local block has no `output`, so the read is transparently
/// served from the global zone the agent wrote elsewhere (mirrored live by the
/// block-controller hot path, or backfilled).
fn global_output_source(
    _per_channel: &Arc<crate::backend::storage::filestore::FileStore>,
    global: &Option<Arc<crate::backend::storage::filestore::FileStore>>,
    wstore: &Arc<crate::backend::storage::store::Store>,
    block_id: &str,
    filename: &str,
) -> Option<(Arc<crate::backend::storage::filestore::FileStore>, String)> {
    if filename != crate::backend::agent_session::OUTPUT_FILE {
        return None;
    }
    // Always prefer the global zone when available — it holds the complete
    // cross-channel history. Cross-channel opens (per-build portable channels,
    // agent reopens in a new session) start with an empty local `output`, so
    // the local file only ever holds the current session's lines. Bailing when
    // local is non-empty was silently truncating history: after the first
    // AgentInput the local had a few lines, and subsequent history loads showed
    // only those lines instead of the full global record.
    let gfs = global.as_ref()?;
    let block = wstore.get::<Block>(block_id).ok().flatten()?;
    // Suppress the fallback for an explicitly ARCHIVED block. The UI archive
    // button + the periodic `SessionArchiver` sweep delete the local block
    // `output` and stamp `session:archived_at` (`archive_session_output`). That
    // empty local output is intentional — the block must reopen archived (banner
    // + Restore), exactly as pre-PR — so we must NOT resurrect it from the global
    // mirror here. (reagent P1 #1399.)
    let archived = block
        .meta
        .get(crate::backend::session_archive::META_SESSION_ARCHIVED_AT)
        .and_then(|v| v.as_i64())
        .map(|v| v > 0)
        .unwrap_or(false);
    if archived {
        return None;
    }
    let zone = crate::backend::agent_session::agent_zone_for_block_meta(&block.meta)?;
    match gfs.stat(&zone, filename) {
        Ok(Some(ref wf)) if wf.size > 0 => Some((gfs.clone(), zone)),
        _ => None,
    }
}

/// Exact non-blank line count of the `output` file in `zone`, computed via the
/// same streaming index builder `read_range` uses (so the two endpoints always
/// agree). Returns `Some(0)` for an empty file, `None` on read failure.
fn global_zone_line_count(
    gfs: &Arc<crate::backend::storage::filestore::FileStore>,
    zone: &str,
) -> Option<u64> {
    let stat = gfs
        .stat(zone, crate::backend::agent_session::OUTPUT_FILE)
        .ok()??;
    if stat.size == 0 {
        return Some(0);
    }
    crate::backend::blockcontroller::shell::rebuild_output_idx(gfs, zone, stat.size as u64)
}

// ---------------------------------------------------------------------------
// blockfile:line_count
// ---------------------------------------------------------------------------

fn register_blockfile_line_count(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let broker = state.broker.clone();
    let wstore = state.wstore.clone();
    let filestore = state.filestore.clone();
    let global_store = state.global_transcript_store.clone();

    engine.register_handler(
        COMMAND_BLOCKFILE_LINE_COUNT,
        Box::new(move |data, _ctx| {
            let broker = broker.clone();
            let wstore = wstore.clone();
            let filestore = filestore.clone();
            let global_store = global_store.clone();
            Box::pin(async move {
                let cmd: CommandBlockfileLineCountData = serde_json::from_value(data)
                    .map_err(|e| format!("blockfile:line_count: {e}"))?;

                tracing::info!(block_id = %cmd.block_id, filename = %cmd.filename, "blockfile:line_count");

                // Cross-channel fallback (checked first): when this channel has
                // no local `output` for the block, the local `session:line_count`
                // meta is absent/stale, so a fresh cross-channel open would
                // report 0 lines and the pane would render empty. Count from the
                // agent's GLOBAL transcript zone instead. See
                // `docs/analysis/ANALYSIS_CROSS_CHANNEL_CONVERSATION_HISTORY_2026_06_14.md`.
                if let Some((gfs, zone)) =
                    global_output_source(&filestore, &global_store, &wstore, &cmd.block_id, &cmd.filename)
                {
                    if let Some(count) = global_zone_line_count(&gfs, &zone) {
                        return Ok(Some(
                            serde_json::to_value(&BlockfileLineCountResult { count }).unwrap(),
                        ));
                    }
                }

                // Fast path: read session:line_count meta (O(1), maintained
                // by SessionStatsAccumulator). For "output" filename this is
                // the authoritative total — matches the unbounded counter
                // that SessionStats increments on every line. FileStore's
                // persisted line count will trail meta by up to the debounce
                // interval (1s), and reading the full file just to count
                // lines is O(file size) which defeats the point of a fast
                // line_count endpoint.
                if cmd.filename == "output" {
                    if let Ok(Some(block)) = wstore.get::<Block>(&cmd.block_id) {
                        if let Some(count) = block.meta.get("session:line_count").and_then(|v| v.as_u64()) {
                            return Ok(Some(serde_json::to_value(
                                &BlockfileLineCountResult { count },
                            ).unwrap()));
                        }
                    }
                }

                // Fallback: count from WPS event ring buffer (capped at MAX_PERSIST = 4096).
                let scope = format!("block:{}", cmd.block_id);
                let events = broker.read_event_history(
                    crate::backend::wps::EVENT_BLOCK_FILE,
                    &scope,
                    usize::MAX, // broker clamps to MAX_PERSIST internally
                );

                let mut count: u64 = 0;
                for event in events {
                    if let Some(ref event_data) = event.data {
                        let ev_filename = event_data.get("filename")
                            .and_then(|v| v.as_str()).unwrap_or("");
                        if ev_filename != cmd.filename {
                            continue;
                        }
                        if let Some(data64) = event_data.get("data64").and_then(|v| v.as_str()) {
                            if let Ok(bytes) = base64::engine::general_purpose::STANDARD.decode(data64) {
                                let text = String::from_utf8_lossy(&bytes);
                                for line in text.lines() {
                                    if !line.trim().is_empty() {
                                        count += 1;
                                    }
                                }
                            }
                        }
                    }
                }

                Ok(Some(serde_json::to_value(&BlockfileLineCountResult { count }).unwrap()))
            })
        }),
    );
}

// ---------------------------------------------------------------------------
// blockfile:read_range
// ---------------------------------------------------------------------------

fn register_blockfile_read_range(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let broker = state.broker.clone();
    let filestore = state.filestore.clone();
    let global_store = state.global_transcript_store.clone();
    let wstore = state.wstore.clone();

    engine.register_handler(
        COMMAND_BLOCKFILE_READ_RANGE,
        Box::new(move |data, _ctx| {
            let broker = broker.clone();
            let filestore = filestore.clone();
            let global_store = global_store.clone();
            let wstore = wstore.clone();
            Box::pin(async move {
                let cmd: CommandBlockfileReadRangeData = serde_json::from_value(data)
                    .map_err(|e| format!("blockfile:read_range: {e}"))?;

                tracing::info!(block_id = %cmd.block_id, filename = %cmd.filename, offset = cmd.offset, limit = cmd.limit, "blockfile:read_range");

                let limit = cmd.limit.min(10_000) as usize;
                let offset = cmd.offset as usize;
                let end = offset.saturating_add(limit);

                // Cross-channel fallback: when this channel has no local `output`
                // for the block, read the agent's GLOBAL transcript zone
                // (`agent:<defId>:current`) instead. `read_block` is the zone for
                // every FileStore call below — the local block_id normally, the
                // agent zone when the agent ran in another build/channel.
                let (filestore, read_block) =
                    global_output_source(&filestore, &global_store, &wstore, &cmd.block_id, &cmd.filename)
                        .unwrap_or_else(|| (filestore.clone(), cmd.block_id.clone()));

                // Fast path: output.idx — a lazily-built, self-validating byte-offset
                // index of every non-blank line in `output`. It lets us seek directly
                // to the requested line range instead of loading the whole file.
                //
                // The index is a pure cache of `output` with NO incremental mutation:
                // its 8-byte header records the `output` size it was built for. If that
                // equals `output`'s current size the index is fresh; otherwise we rebuild
                // it from a single streaming scan (rebuild_output_idx). Because the index
                // is always derived from the current `output` in one shot, it can never
                // desync, mis-handle chunk-split lines, or miscount blank lines — the
                // failure modes an incremental index would have.
                //
                // Gated to non-circular files: circular `output` (terminal ring buffers)
                // drops early bytes, so absolute byte offsets wouldn't map cleanly.
                use crate::backend::blockcontroller::shell::{rebuild_output_idx, OUTPUT_IDX_HEADER_LEN};
                if cmd.filename == "output" {
                    let idx_result: Option<BlockfileReadRangeResult> = (|| {
                        let out_stat = filestore.stat(&read_block, "output").ok()??;
                        if out_stat.opts.circular {
                            return None; // circular files: fall back to slow path
                        }
                        let output_size = out_stat.size as u64;

                        // Determine total_lines, rebuilding the index iff it is missing or
                        // its covered-size header doesn't match the current output size.
                        let idx_stat = filestore.stat(&read_block, "output.idx").ok().flatten();
                        let fresh = match &idx_stat {
                            Some(s) if s.size >= OUTPUT_IDX_HEADER_LEN => {
                                let (_, h) = filestore
                                    .read_at(&read_block, "output.idx", 0, OUTPUT_IDX_HEADER_LEN)
                                    .ok()?;
                                u64::from_le_bytes(h.try_into().ok()?) == output_size
                            }
                            _ => false,
                        };
                        let total_lines: u64 = if fresh {
                            let s = idx_stat.unwrap();
                            ((s.size - OUTPUT_IDX_HEADER_LEN) / 8) as u64
                        } else {
                            rebuild_output_idx(&filestore, &read_block, output_size)?
                        };

                        // Empty result cases — answered from the index, no output read.
                        if limit == 0 || total_lines == 0 || (offset as u64) >= total_lines {
                            return Some(BlockfileReadRangeResult { lines: vec![], total: total_lines });
                        }

                        // entry(k) = byte offset of non-blank line k (past the 8-byte header).
                        let entry = |k: u64| -> Option<i64> {
                            let (_, b) = filestore
                                .read_at(
                                    &read_block,
                                    "output.idx",
                                    OUTPUT_IDX_HEADER_LEN + (k * 8) as i64,
                                    8,
                                )
                                .ok()?;
                            Some(u64::from_le_bytes(b.try_into().ok()?) as i64)
                        };

                        let byte_start = entry(offset as u64)?;
                        let byte_end: i64 = if (offset + limit) as u64 >= total_lines {
                            output_size as i64
                        } else {
                            entry((offset + limit) as u64)?
                        };
                        let read_len = (byte_end - byte_start).max(0);
                        let (_, raw) = filestore
                            .read_at(&read_block, "output", byte_start, read_len)
                            .ok()?;
                        let text = String::from_utf8_lossy(&raw);
                        let lines: Vec<String> = text
                            .lines()
                            .filter(|l| !l.trim().is_empty())
                            .map(|l| l.to_string())
                            .collect();
                        Some(BlockfileReadRangeResult { lines, total: total_lines })
                    })();
                    if let Some(result) = idx_result {
                        tracing::debug!(
                            block_id = %cmd.block_id,
                            offset,
                            limit,
                            lines = result.lines.len(),
                            "blockfile:read_range via output.idx fast path"
                        );
                        return Ok(Some(serde_json::to_value(&result).unwrap()));
                    }
                }

                // Phase 1.3: Prefer FileStore (persistent, no size cap) over the
                // WPS broker ring buffer (MAX_PERSIST = 4096 events).
                //
                // If FileStore has the file and it is non-empty, read from disk.
                // Otherwise fall back to ring buffer for backward compatibility.
                let filestore_lines = match filestore.stat(&read_block, &cmd.filename) {
                    Ok(Some(ref wf)) if wf.size > 0 => {
                        match filestore.read_file(&read_block, &cmd.filename) {
                            Ok(Some(bytes)) => {
                                let text = String::from_utf8_lossy(&bytes);
                                let lines: Vec<String> = text.lines()
                                    .filter(|l| !l.trim().is_empty())
                                    .map(|l| l.to_string())
                                    .collect();
                                Some(lines)
                            }
                            Ok(None) => None,
                            Err(e) => {
                                tracing::warn!(
                                    block_id = %cmd.block_id,
                                    filename = %cmd.filename,
                                    error = %e,
                                    "blockfile:read_range: filestore read failed, falling back to ring buffer"
                                );
                                None
                            }
                        }
                    }
                    Ok(_) => None, // file absent or empty → fall back
                    Err(e) => {
                        tracing::warn!(
                            block_id = %cmd.block_id,
                            error = %e,
                            "blockfile:read_range: filestore stat failed, falling back to ring buffer"
                        );
                        None
                    }
                };

                let all_lines = if let Some(lines) = filestore_lines {
                    lines
                } else {
                    // Fallback: reconstruct from WPS event ring buffer.
                    // The ring buffer holds at most MAX_PERSIST = 4096 events;
                    // older events are evicted. Offset 0 = oldest retained line.
                    let scope = format!("block:{}", cmd.block_id);
                    let events = broker.read_event_history(
                        crate::backend::wps::EVENT_BLOCK_FILE,
                        &scope,
                        usize::MAX, // broker clamps to MAX_PERSIST internally
                    );

                    let mut lines: Vec<String> = Vec::new();
                    for event in events {
                        let Some(ref event_data) = event.data else { continue };
                        let ev_filename = event_data.get("filename")
                            .and_then(|v| v.as_str()).unwrap_or("");
                        if ev_filename != cmd.filename {
                            continue;
                        }
                        let Some(data64) = event_data.get("data64").and_then(|v| v.as_str()) else { continue };
                        let Ok(bytes) = base64::engine::general_purpose::STANDARD.decode(data64) else { continue };
                        let text = String::from_utf8_lossy(&bytes);
                        for line in text.lines() {
                            if !line.trim().is_empty() {
                                lines.push(line.to_string());
                            }
                        }
                    }
                    lines
                };

                let total = all_lines.len() as u64;
                let clamped_offset = offset.min(all_lines.len());
                let clamped_end = end.min(all_lines.len());
                let lines: Vec<String> = if clamped_offset >= clamped_end {
                    Vec::new()
                } else {
                    all_lines[clamped_offset..clamped_end].to_vec()
                };

                Ok(Some(serde_json::to_value(&BlockfileReadRangeResult {
                    lines,
                    total,
                }).unwrap()))
            })
        }),
    );
}

// ---------------------------------------------------------------------------
// blockfile:read_state — sidecar JSON snapshot read
// Spec: docs/specs/SPEC_AGENT_PANE_STATE_PERSISTENCE_2026_05_15.md §4.6
// ---------------------------------------------------------------------------

fn register_blockfile_read_state(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let filestore = state.filestore.clone();
    engine.register_handler(
        COMMAND_BLOCKFILE_READ_STATE,
        Box::new(move |data, _ctx| {
            let filestore = filestore.clone();
            Box::pin(async move {
                let cmd: CommandBlockfileReadStateData = serde_json::from_value(data)
                    .map_err(|e| format!("blockfile:read_state: {e}"))?;
                if cmd.filename.contains('/') || cmd.filename.contains('\\') || cmd.filename.contains("..") {
                    return Err("blockfile:read_state: filename must not contain path separators".to_string());
                }
                tracing::debug!(block_id = %cmd.block_id, filename = %cmd.filename, "blockfile:read_state");

                let content = match filestore.read_file(&cmd.block_id, &cmd.filename) {
                    Ok(Some(bytes)) => Some(String::from_utf8_lossy(&bytes).into_owned()),
                    Ok(None) => None,
                    Err(e) => {
                        // NotFound is the common case (no snapshot yet). Suppress.
                        if matches!(e, crate::backend::storage::StoreError::NotFound) {
                            None
                        } else {
                            tracing::warn!(block_id = %cmd.block_id, error = %e, "blockfile:read_state: read failed");
                            None
                        }
                    }
                };

                Ok(Some(serde_json::to_value(&BlockfileReadStateResult { content }).unwrap()))
            })
        }),
    );
}

// ---------------------------------------------------------------------------
// blockfile:write_state — sidecar JSON snapshot write (atomic via DB tx)
// Spec: docs/specs/SPEC_AGENT_PANE_STATE_PERSISTENCE_2026_05_15.md §4.3
// ---------------------------------------------------------------------------

fn register_blockfile_write_state(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let filestore = state.filestore.clone();
    engine.register_handler(
        COMMAND_BLOCKFILE_WRITE_STATE,
        Box::new(move |data, _ctx| {
            let filestore = filestore.clone();
            Box::pin(async move {
                let cmd: CommandBlockfileWriteStateData = serde_json::from_value(data)
                    .map_err(|e| format!("blockfile:write_state: {e}"))?;
                if cmd.filename.contains('/') || cmd.filename.contains('\\') || cmd.filename.contains("..") {
                    return Err("blockfile:write_state: filename must not contain path separators".to_string());
                }
                let bytes = cmd.content.as_bytes();
                let bytes_written = bytes.len() as u64;
                tracing::debug!(block_id = %cmd.block_id, filename = %cmd.filename, bytes = bytes_written, "blockfile:write_state");

                // FileStore.write_file is atomic at the DB level (single
                // tx replaces all data parts) — no torn write surfaces.
                // Need make_file first if the sidecar doesn't yet exist.
                use crate::backend::storage::filestore::{FileMeta, FileOpts};
                use crate::backend::storage::StoreError;
                match filestore.write_file(&cmd.block_id, &cmd.filename, bytes) {
                    Ok(()) => {}
                    Err(StoreError::NotFound) => {
                        filestore
                            .make_file(&cmd.block_id, &cmd.filename, FileMeta::default(), FileOpts::default())
                            .map_err(|e| format!("blockfile:write_state: make_file: {e}"))?;
                        filestore
                            .write_file(&cmd.block_id, &cmd.filename, bytes)
                            .map_err(|e| format!("blockfile:write_state: write_file: {e}"))?;
                    }
                    Err(e) => return Err(format!("blockfile:write_state: {e}")),
                }

                Ok(Some(serde_json::to_value(&BlockfileWriteStateResult { bytes_written }).unwrap()))
            })
        }),
    );
}

// ---------------------------------------------------------------------------
// session:archive
// ---------------------------------------------------------------------------

fn register_session_archive_handler(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let wstore = state.wstore.clone();
    let filestore = state.filestore.clone();

    engine.register_handler(
        COMMAND_SESSION_ARCHIVE,
        Box::new(move |data, _ctx| {
            let wstore = wstore.clone();
            let filestore = filestore.clone();
            Box::pin(async move {
                let cmd: CommandSessionArchiveData = serde_json::from_value(data)
                    .map_err(|e| format!("session:archive: {e}"))?;

                tracing::info!(block_id = %cmd.block_id, "session:archive");

                let archive_dir = session_archive::default_archive_dir()
                    .ok_or_else(|| "cannot determine home directory".to_string())?;

                let (archived_bytes, archived_at) = session_archive::archive_session_output(
                    &wstore,
                    &filestore,
                    &cmd.block_id,
                    &archive_dir,
                )?;

                Ok(Some(serde_json::to_value(&SessionArchiveResult {
                    block_id: cmd.block_id,
                    archived_bytes,
                    archived_at,
                }).unwrap()))
            })
        }),
    );
}

// ---------------------------------------------------------------------------
// session:restore
// ---------------------------------------------------------------------------

fn register_session_restore_handler(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let wstore = state.wstore.clone();
    let filestore = state.filestore.clone();

    engine.register_handler(
        COMMAND_SESSION_RESTORE,
        Box::new(move |data, _ctx| {
            let wstore = wstore.clone();
            let filestore = filestore.clone();
            Box::pin(async move {
                let cmd: CommandSessionRestoreData = serde_json::from_value(data)
                    .map_err(|e| format!("session:restore: {e}"))?;

                tracing::info!(block_id = %cmd.block_id, "session:restore");

                let restored_bytes = session_archive::restore_session_output(
                    &wstore,
                    &filestore,
                    &cmd.block_id,
                )?;

                Ok(Some(serde_json::to_value(&SessionRestoreResult {
                    block_id: cmd.block_id,
                    restored_bytes,
                }).unwrap()))
            })
        }),
    );
}

// ---------------------------------------------------------------------------
// session:export
// ---------------------------------------------------------------------------

fn register_session_export_handler(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let wstore = state.wstore.clone();
    let filestore = state.filestore.clone();

    engine.register_handler(
        COMMAND_SESSION_EXPORT,
        Box::new(move |data, _ctx| {
            let wstore = wstore.clone();
            let filestore = filestore.clone();
            Box::pin(async move {
                let cmd: CommandSessionExportData = serde_json::from_value(data)
                    .map_err(|e| format!("session:export: {e}"))?;

                tracing::info!(block_id = %cmd.block_id, "session:export");

                let (raw_bytes, line_count) = session_archive::read_session_output(
                    &wstore,
                    &filestore,
                    &cmd.block_id,
                )?;

                let byte_count = raw_bytes.len() as u64;
                let content = base64::engine::general_purpose::STANDARD.encode(&raw_bytes);

                Ok(Some(serde_json::to_value(&SessionExportResult {
                    content,
                    line_count,
                    byte_count,
                }).unwrap()))
            })
        }),
    );
}

// ---------------------------------------------------------------------------
// session:digest
// ---------------------------------------------------------------------------

fn register_session_digest(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let wstore = state.wstore.clone();
    let filestore = state.filestore.clone();
    let broker = state.broker.clone();

    engine.register_handler(
        COMMAND_SESSION_DIGEST,
        Box::new(move |data, _ctx| {
            let wstore = wstore.clone();
            let filestore = filestore.clone();
            let broker = broker.clone();
            Box::pin(async move {
                let cmd: CommandSessionDigestData = serde_json::from_value(data)
                    .map_err(|e| format!("session:digest: {e}"))?;

                tracing::info!(block_id = %cmd.block_id, force = ?cmd.force, "session:digest");

                let force = cmd.force.unwrap_or(false);

                // Read block meta
                let block: Block = wstore
                    .get(&cmd.block_id)
                    .map_err(|e| format!("session:digest: {e}"))?
                    .ok_or_else(|| format!("BLOCK_NOT_FOUND: {}", cmd.block_id))?;

                // Check for a valid cached digest
                let cached_summary = block.meta.get("session:digest_summary")
                    .and_then(|v| v.as_str())
                    .map(|s| s.to_string());
                let cached_generated_at = block.meta.get("session:digest_generated_at")
                    .and_then(|v| v.as_i64())
                    .unwrap_or(0);
                let digest_last_line_count = block.meta.get("session:digest_last_line_count")
                    .and_then(|v| v.as_u64())
                    .unwrap_or(0);

                // Current line count from meta (O(1))
                let current_line_count = block.meta.get("session:line_count")
                    .and_then(|v| v.as_u64())
                    .unwrap_or(0);

                // Serve cache if: not forced, cached digest exists, AND fewer than 20 new lines
                // since the digest was last generated.
                let lines_since_digest = current_line_count.saturating_sub(digest_last_line_count);
                if !force && cached_summary.is_some() && lines_since_digest < 20 {
                    return Ok(Some(serde_json::to_value(&SessionDigestResult {
                        summary: cached_summary.unwrap(),
                        generated_at: cached_generated_at,
                        cached: true,
                    }).unwrap()));
                }

                // --- Generate a new digest ---

                // Read up to the last 200 lines from FileStore, falling back to the WPS ring buffer.
                let all_lines: Vec<String> = {
                    let filestore_lines = match filestore.stat(&cmd.block_id, "output") {
                        Ok(Some(ref wf)) if wf.size > 0 => {
                            match filestore.read_file(&cmd.block_id, "output") {
                                Ok(Some(bytes)) => {
                                    let text = String::from_utf8_lossy(&bytes);
                                    let lines: Vec<String> = text.lines()
                                        .filter(|l| !l.trim().is_empty())
                                        .map(|l| l.to_string())
                                        .collect();
                                    Some(lines)
                                }
                                _ => None,
                            }
                        }
                        _ => None,
                    };

                    if let Some(lines) = filestore_lines {
                        lines
                    } else {
                        // Fallback: WPS ring buffer
                        let scope = format!("block:{}", cmd.block_id);
                        let events = broker.read_event_history(
                            crate::backend::wps::EVENT_BLOCK_FILE,
                            &scope,
                            usize::MAX,
                        );
                        let mut lines: Vec<String> = Vec::new();
                        for event in events {
                            let Some(ref ed) = event.data else { continue };
                            let fname = ed.get("filename").and_then(|v| v.as_str()).unwrap_or("");
                            if fname != "output" { continue; }
                            if let Some(d64) = ed.get("data64").and_then(|v| v.as_str()) {
                                if let Ok(bytes) = base64::engine::general_purpose::STANDARD.decode(d64) {
                                    let text = String::from_utf8_lossy(&bytes);
                                    for line in text.lines() {
                                        if !line.trim().is_empty() {
                                            lines.push(line.to_string());
                                        }
                                    }
                                }
                            }
                        }
                        lines
                    }
                };

                // Take the last 200 lines
                let n = all_lines.len();
                let start = n.saturating_sub(200);
                let window: Vec<&str> = all_lines[start..].iter().map(|s| s.as_str()).collect();

                if window.is_empty() {
                    return Ok(Some(serde_json::to_value(&SessionDigestResult {
                        summary: String::new(),
                        generated_at: 0,
                        cached: false,
                    }).unwrap()));
                }

                // Extract meaningful text (skip system events and raw stream deltas)
                let extracted = extract_digest_text(&window);

                if extracted.is_empty() {
                    return Ok(Some(serde_json::to_value(&SessionDigestResult {
                        summary: String::new(),
                        generated_at: 0,
                        cached: false,
                    }).unwrap()));
                }

                // Locate the Claude CLI (stored in block meta as "cmd" by runLaunchFlow)
                let cli_path = obj::meta_get_string(&block.meta, "cmd", "");
                if cli_path.is_empty() {
                    tracing::warn!(block_id = %cmd.block_id, "session:digest: no CLI path in meta");
                    return Ok(Some(serde_json::to_value(&SessionDigestResult {
                        summary: String::new(),
                        generated_at: 0,
                        cached: false,
                    }).unwrap()));
                }

                // Build the summarization prompt
                let prompt = format!(
                    "Summarize this AI coding session in 10 words or fewer. Be direct and specific. \
                     Example: \"Fixed auth bug, added dark mode, tests passing.\"\n\n\
                     Session content (last 200 events):\n\n{}",
                    extracted
                );

                // Invoke the Claude CLI and extract the summary text
                let summary = match invoke_cli_for_digest(&cli_path, &prompt, &block.meta).await {
                    Ok(text) => text,
                    Err(e) => {
                        tracing::warn!(block_id = %cmd.block_id, error = %e, "session:digest: CLI invocation failed");
                        String::new()
                    }
                };

                if summary.is_empty() {
                    return Ok(Some(serde_json::to_value(&SessionDigestResult {
                        summary: String::new(),
                        generated_at: 0,
                        cached: false,
                    }).unwrap()));
                }

                // Cache in block meta
                let generated_at = std::time::SystemTime::now()
                    .duration_since(std::time::UNIX_EPOCH)
                    .map(|d| d.as_millis() as i64)
                    .unwrap_or(0);

                let mut meta_update = obj::MetaMapType::new();
                meta_update.insert("session:digest_summary".to_string(), json!(summary.clone()));
                meta_update.insert("session:digest_generated_at".to_string(), json!(generated_at));
                meta_update.insert("session:digest_last_line_count".to_string(), json!(current_line_count));

                if let Err(e) = crate::server::service::update_object_meta(
                    &wstore,
                    &format!("block:{}", cmd.block_id),
                    &meta_update,
                ) {
                    tracing::warn!(block_id = %cmd.block_id, error = %e, "session:digest: failed to cache in meta");
                }

                Ok(Some(serde_json::to_value(&SessionDigestResult {
                    summary,
                    generated_at,
                    cached: false,
                }).unwrap()))
            })
        }),
    );
}

// ---------------------------------------------------------------------------
// session:activity_summary — per-turn live mini-summary via Haiku
// ---------------------------------------------------------------------------

fn register_session_activity_summary(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let wstore = state.wstore.clone();
    let broker = state.broker.clone();

    engine.register_handler(
        COMMAND_SESSION_ACTIVITY_SUMMARY,
        Box::new(move |data, _ctx| {
            let wstore = wstore.clone();
            let broker = broker.clone();
            Box::pin(async move {
                let cmd: CommandActivitySummaryData = serde_json::from_value(data)
                    .map_err(|e| format!("session:activity_summary: {e}"))?;

                let word_target = cmd.word_target.unwrap_or(7).max(3).min(20);

                let block: Block = wstore
                    .get(&cmd.block_id)
                    .map_err(|e| format!("session:activity_summary: {e}"))?
                    .ok_or_else(|| format!("BLOCK_NOT_FOUND: {}", cmd.block_id))?;

                // Read only the most recent ring buffer events — we need the last ~30
                // lines, so 50 events is a generous upper bound without touching the
                // full buffer (which can be large on long sessions).
                let all_lines: Vec<String> = {
                    let scope = format!("block:{}", cmd.block_id);
                    let events = broker.read_event_history(
                        crate::backend::wps::EVENT_BLOCK_FILE,
                        &scope,
                        50,
                    );
                    let mut lines: Vec<String> = Vec::new();
                    for event in events {
                        let Some(ref ed) = event.data else { continue };
                        if ed.get("filename").and_then(|v| v.as_str()).unwrap_or("") != "output" { continue; }
                        if let Some(d64) = ed.get("data64").and_then(|v| v.as_str()) {
                            if let Ok(bytes) = base64::engine::general_purpose::STANDARD.decode(d64) {
                                let text = String::from_utf8_lossy(&bytes);
                                for line in text.lines() {
                                    if !line.trim().is_empty() {
                                        lines.push(line.to_string());
                                    }
                                }
                            }
                        }
                    }
                    lines
                };

                let n = all_lines.len();
                let start = n.saturating_sub(30);
                let window: Vec<&str> = all_lines[start..].iter().map(|s| s.as_str()).collect();

                if window.is_empty() {
                    return Ok(Some(serde_json::to_value(&ActivitySummaryResult {
                        summary: String::new(),
                    }).unwrap()));
                }

                let extracted = extract_digest_text(&window);
                if extracted.is_empty() {
                    return Ok(Some(serde_json::to_value(&ActivitySummaryResult {
                        summary: String::new(),
                    }).unwrap()));
                }

                let cli_path = obj::meta_get_string(&block.meta, "cmd", "");
                if cli_path.is_empty() {
                    tracing::debug!(block_id = %cmd.block_id, "session:activity_summary: no CLI path in meta");
                    return Ok(Some(serde_json::to_value(&ActivitySummaryResult {
                        summary: String::new(),
                    }).unwrap()));
                }

                let prompt = format!(
                    "Summarize in {word_target} words or fewer what is currently being worked on. \
                     Use a short terse phrase with no quotes or punctuation.\n\n\
                     Recent activity:\n\n{extracted}"
                );

                let summary = invoke_cli_for_activity(&cli_path, &prompt, &block.meta).await
                    .unwrap_or_else(|e| {
                        tracing::debug!(block_id = %cmd.block_id, error = %e, "session:activity_summary: CLI failed");
                        String::new()
                    });

                // The frontend writes `term:activity` after receiving this response so it
                // can discard results from turns that were superseded before they returned.
                Ok(Some(serde_json::to_value(&ActivitySummaryResult { summary }).unwrap()))
            })
        }),
    );
}

/// Invoke the Claude CLI with Haiku model for a lightweight per-turn activity summary.
/// Uses `--model claude-haiku-4-5-20251001` and a 15s timeout.
async fn invoke_cli_for_activity(
    cli_path: &str,
    prompt: &str,
    meta: &obj::MetaMapType,
) -> Result<String, String> {
    let auth_env: std::collections::HashMap<String, String> = match meta.get("cmd:env") {
        Some(serde_json::Value::Object(obj_map)) => obj_map
            .iter()
            .filter_map(|(k, v)| v.as_str().map(|s| (k.clone(), s.to_string())))
            .collect(),
        _ => std::collections::HashMap::new(),
    };

    let mut child = crate::server::cli_handlers::make_cli_cmd(cli_path)
        .args(["-p", "--output-format", "stream-json", "--verbose",
               "--model", "claude-haiku-4-5-20251001"])
        .envs(&auth_env)
        .stdin(std::process::Stdio::piped())
        .stdout(std::process::Stdio::piped())
        .stderr(std::process::Stdio::null())
        .kill_on_drop(true)
        .spawn()
        .map_err(|e| format!("failed to spawn activity CLI: {e}"))?;

    if let Some(mut stdin) = child.stdin.take() {
        use tokio::io::AsyncWriteExt;
        stdin.write_all(prompt.as_bytes()).await
            .map_err(|e| format!("activity CLI stdin write: {e}"))?;
        stdin.shutdown().await
            .map_err(|e| format!("activity CLI stdin shutdown: {e}"))?;
    }

    let output = tokio::time::timeout(
        std::time::Duration::from_secs(15),
        child.wait_with_output(),
    )
    .await
    .map_err(|_| "activity CLI timed out after 15s".to_string())?
    .map_err(|e| format!("activity CLI wait: {e}"))?;

    if !output.status.success() {
        return Err(format!("activity CLI exited with status {}", output.status));
    }

    let stdout = String::from_utf8_lossy(&output.stdout);
    let mut last_text = String::new();
    for line in stdout.lines() {
        let Ok(val) = serde_json::from_str::<serde_json::Value>(line) else { continue };
        if val.get("type").and_then(|v| v.as_str()) == Some("assistant") {
            if let Some(content) = val.get("message")
                .and_then(|m| m.get("content"))
                .and_then(|c| c.as_array())
            {
                for block in content {
                    if block.get("type").and_then(|v| v.as_str()) == Some("text") {
                        if let Some(text) = block.get("text").and_then(|v| v.as_str()) {
                            last_text = text.trim().to_string();
                        }
                    }
                }
            }
        }
    }

    if last_text.is_empty() {
        return Err("no text in activity CLI response".to_string());
    }

    Ok(last_text)
}

/// Extract meaningful text from raw stream-json lines for digest summarization.
/// Skips system/result events and raw stream_event deltas; extracts assistant text
/// and tool call summaries.
fn extract_digest_text(lines: &[&str]) -> String {
    let mut parts: Vec<String> = Vec::new();

    for line in lines {
        let Ok(val) = serde_json::from_str::<serde_json::Value>(line) else { continue };

        let msg_type = val.get("type").and_then(|v| v.as_str()).unwrap_or("");

        match msg_type {
            "assistant" => {
                if let Some(content) = val.get("message")
                    .and_then(|m| m.get("content"))
                    .and_then(|c| c.as_array())
                {
                    for block in content {
                        let btype = block.get("type").and_then(|v| v.as_str()).unwrap_or("");
                        if btype == "text" {
                            if let Some(text) = block.get("text").and_then(|v| v.as_str()) {
                                let trimmed = text.trim();
                                if !trimmed.is_empty() {
                                    parts.push(format!("[assistant] {}", trimmed));
                                }
                            }
                        } else if btype == "tool_use" {
                            let tool_name = block.get("name")
                                .and_then(|v| v.as_str())
                                .unwrap_or("unknown");
                            parts.push(format!("[tool] {}", tool_name));
                        }
                    }
                }
            }
            "user" => {
                if let Some(content) = val.get("message")
                    .and_then(|m| m.get("content"))
                    .and_then(|c| c.as_array())
                {
                    for block in content {
                        let btype = block.get("type").and_then(|v| v.as_str()).unwrap_or("");
                        if btype == "tool_result" {
                            let is_error = block.get("is_error")
                                .and_then(|v| v.as_bool())
                                .unwrap_or(false);
                            if is_error {
                                let err_text = block.get("content")
                                    .and_then(|c| c.as_str())
                                    .unwrap_or("(error)")
                                    .chars().take(120).collect::<String>();
                                parts.push(format!("[error] {}", err_text));
                            }
                        } else if btype == "text" {
                            if let Some(text) = block.get("text").and_then(|v| v.as_str()) {
                                let trimmed = text.trim();
                                if !trimmed.is_empty() {
                                    parts.push(format!("[user] {}", trimmed));
                                }
                            }
                        }
                    }
                }
            }
            "result" => {
                if let Some(cost) = val.get("total_cost_usd").and_then(|v| v.as_f64()) {
                    if let Some(turns) = val.get("num_turns").and_then(|v| v.as_u64()) {
                        parts.push(format!("[summary] {} turns, ${:.4} total cost", turns, cost));
                    }
                }
            }
            // Skip: system, stream_event (deltas), rate_limit_event
            _ => {}
        }
    }

    parts.join("\n")
}

/// Invoke the Claude CLI with a prompt and extract the text response.
/// Uses `-p --output-format stream-json --verbose` (non-interactive mode).
async fn invoke_cli_for_digest(
    cli_path: &str,
    prompt: &str,
    meta: &obj::MetaMapType,
) -> Result<String, String> {
    // Inherit auth env from block meta (CLAUDE_CONFIG_DIR, etc.)
    let auth_env: std::collections::HashMap<String, String> = match meta.get("cmd:env") {
        Some(serde_json::Value::Object(obj_map)) => obj_map
            .iter()
            .filter_map(|(k, v)| v.as_str().map(|s| (k.clone(), s.to_string())))
            .collect(),
        _ => std::collections::HashMap::new(),
    };

    // Pipe the prompt via stdin rather than passing it as a CLI arg — Linux
    // caps individual argv entries at MAX_ARG_STRLEN (~128 KB), and a digest
    // over 200 lines of session content can easily exceed that.
    // `kill_on_drop(true)` ensures the child is terminated if the timeout
    // future below is dropped — tokio `Child` does NOT kill on drop by default.
    let mut child = crate::server::cli_handlers::make_cli_cmd(cli_path)
        .args(["-p", "--output-format", "stream-json", "--verbose"])
        .envs(&auth_env)
        .stdin(std::process::Stdio::piped())
        .stdout(std::process::Stdio::piped())
        .stderr(std::process::Stdio::null())
        .kill_on_drop(true)
        .spawn()
        .map_err(|e| format!("failed to spawn digest CLI: {e}"))?;

    if let Some(mut stdin) = child.stdin.take() {
        use tokio::io::AsyncWriteExt;
        stdin
            .write_all(prompt.as_bytes())
            .await
            .map_err(|e| format!("digest CLI stdin write: {e}"))?;
        stdin
            .shutdown()
            .await
            .map_err(|e| format!("digest CLI stdin shutdown: {e}"))?;
    }

    let output = tokio::time::timeout(
        std::time::Duration::from_secs(60),
        child.wait_with_output(),
    )
    .await
    .map_err(|_| "digest CLI timed out after 60s".to_string())?
    .map_err(|e| format!("digest CLI wait: {e}"))?;

    if !output.status.success() {
        return Err(format!("digest CLI exited with status {}", output.status));
    }

    // Parse stream-json output — capture the last assistant text block
    let stdout = String::from_utf8_lossy(&output.stdout);
    let mut last_text = String::new();

    for line in stdout.lines() {
        let Ok(val) = serde_json::from_str::<serde_json::Value>(line) else { continue };
        let msg_type = val.get("type").and_then(|v| v.as_str()).unwrap_or("");
        if msg_type == "assistant" {
            if let Some(content) = val.get("message")
                .and_then(|m| m.get("content"))
                .and_then(|c| c.as_array())
            {
                for block in content {
                    if block.get("type").and_then(|v| v.as_str()) == Some("text") {
                        if let Some(text) = block.get("text").and_then(|v| v.as_str()) {
                            last_text = text.trim().to_string();
                        }
                    }
                }
            }
        }
    }

    if last_text.is_empty() {
        return Err("no text content in digest CLI response".to_string());
    }

    Ok(last_text)
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

/// Resolve a tab ID: use the provided one, or fall back to the first workspace's active tab.
fn resolve_tab_id(wstore: &Store, explicit: Option<&str>) -> Result<String, String> {
    if let Some(tid) = explicit {
        return Ok(tid.to_string());
    }

    // Fall back to first workspace's active tab
    let workspaces: Vec<Workspace> = wstore.get_all::<Workspace>()
        .map_err(|e| format!("agent.open: list workspaces: {e}"))?;

    for ws in &workspaces {
        if !ws.activetabid.is_empty() {
            return Ok(ws.activetabid.clone());
        }
        if let Some(first_tab) = ws.tabids.first() {
            return Ok(first_tab.clone());
        }
    }

    Err("no tabs found in any workspace".to_string())
}

/// Find an existing agent block in a tab by agent ID.
fn find_agent_block(wstore: &Store, tab_id: &str, agent_id: &str) -> Result<Option<Block>, String> {
    let tab: Tab = wstore.must_get(tab_id)
        .map_err(|e| format!("TAB_NOT_FOUND: {e}"))?;

    for block_id in &tab.blockids {
        if let Ok(Some(block)) = wstore.get::<Block>(block_id) {
            let block_agent_id = obj::meta_get_string(&block.meta, "agentId", "");
            if block_agent_id == agent_id {
                return Ok(Some(block));
            }
        }
    }
    Ok(None)
}

/// Atomically allocate an agent working directory.
///
/// Tries to atomically create `desired` via `std::fs::create_dir`. If
/// that fails because the directory already exists, tries `<desired>-1`,
/// `<desired>-2`, …, up to `-99`. The atomic `create_dir` (NOT
/// `create_dir_all` for the leaf) is the reservation mechanism: two
/// concurrent callers competing for the same path race on the OS
/// `mkdir` syscall and one wins; the loser sees `AlreadyExists` and
/// moves on.
///
/// Caller is responsible for distinguishing auto-generated paths from
/// user-specified ones — this function rewrites the path on collision,
/// which would clobber a user's intent if they pointed an agent at
/// `~/projects/myrepo` and that already had a `CLAUDE.md`.
pub fn allocate_agent_workdir(desired: &str) -> Result<String, String> {
    let p = std::path::Path::new(desired);
    if let Some(parent) = p.parent() {
        if !parent.as_os_str().is_empty() {
            std::fs::create_dir_all(parent)
                .map_err(|e| format!("allocate_agent_workdir: parent {}: {e}", parent.display()))?;
        }
    }
    match std::fs::create_dir(p) {
        Ok(()) => return Ok(desired.to_string()),
        Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {}
        Err(e) => return Err(format!("allocate_agent_workdir: create_dir({}): {e}", desired)),
    }
    for n in 1..=99u32 {
        let candidate = format!("{desired}-{n}");
        match std::fs::create_dir(std::path::Path::new(&candidate)) {
            Ok(()) => return Ok(candidate),
            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
            Err(e) => return Err(format!("allocate_agent_workdir: create_dir({candidate}): {e}")),
        }
    }
    Err(format!(
        "allocate_agent_workdir: too many collisions (>99) under {desired}-N — clean up old runs"
    ))
}

/// Write agent config files (CLAUDE.md, .mcp.json, etc.) to the working directory.
fn write_agent_config_files(
    wstore: &Store,
    agent: &crate::backend::storage::AgentDefinition,
    agent_slug: &str,
    work_dir: &str,
) -> Result<(), String> {
    // Load agent content and skills
    let contents = wstore.agent_content_get_all(&agent.id)
        .unwrap_or_default();
    let skills = wstore.agent_skill_list(&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"
                );
            }
        }
    }

    // Inject global memory bundles (Trust Center global brain) into CLAUDE.md.
    // All agents get these regardless of per-agent memory selection. Each
    // section carries a `# [Workspace] <name>` heading (see
    // format_global_brain_block) so the rules are attributable to the
    // workspace and ordered per the Brain tab's sort_order.
    let global_bundles = wstore.bundle_memory_list_global().unwrap_or_default();
    let global_block = crate::backend::storage::format_global_brain_block(&global_bundles);
    if !global_block.is_empty() {
        content_map
            .entry("memory".to_string())
            .and_modify(|existing| {
                *existing = format!("{global_block}\n\n---\n\n{existing}");
            })
            .or_insert(global_block);
    }

    let config_files = crate::backend::agent_config::build_config_files(
        &content_map,
        &skills,
        &agent.name,
        &agent.id,
        agent_slug,
    );

    // 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)
            .map_err(|e| format!("failed to create working dir: {e}"))?;
    }

    for file in &config_files {
        let file_path = base_path.join(&file.filename);
        if let Some(parent) = file_path.parent() {
            if !parent.exists() {
                let _ = std::fs::create_dir_all(parent);
            }
        }
        std::fs::write(&file_path, &file.content)
            .map_err(|e| format!("failed to write {}: {e}", file.filename))?;
    }

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

    Ok(())
}

// ---------------------------------------------------------------------------
// agent.define helpers
// ---------------------------------------------------------------------------

/// Create a stub AgentInstance for a definition, idempotently.
///
/// The stub id is deterministically derived from the definition id so that
/// calling this function multiple times for the same definition is a no-op
/// rather than accumulating duplicate stopped rows in My Agents.
/// Infer a provider slug from a model name prefix.
/// Only maps prefixes that correspond to a registered provider slug.
/// Callers must still validate the result via `providers::get_provider`.
fn infer_provider_from_model(model: &str) -> String {
    let m = model.to_lowercase();
    if m.starts_with("claude") {
        "claude".to_string()
    } else if m.starts_with("gemini") {
        "gemini".to_string()
    } else if m.starts_with("codex") {
        "codex".to_string()
    } else if m.starts_with("qwen") {
        "qwen".to_string()
    } else if m.starts_with("kimi") {
        "kimi".to_string()
    } else {
        // Unknown prefix — return as-is; get_provider will reject it with
        // a "cannot infer provider" error so callers know to set provider explicitly.
        model.to_string()
    }
}

/// Returns `(stub_id, newly_inserted)`. `newly_inserted = false` when the
/// UNIQUE constraint fires (stub already existed); callers use this to avoid
/// broadcasting `agents:changed` on no-op calls.
fn make_stub_idempotent(
    wstore: &crate::backend::storage::store::Store,
    def_id: &str,
    name: &str,
    now: i64,
) -> Result<(String, bool), String> {
    let stub_id = format!("si-{}", def_id.replace('-', ""));
    let inst = AgentInstance {
        id: stub_id.clone(),
        definition_id: def_id.to_string(),
        parent_instance_id: String::new(),
        block_id: String::new(),
        session_id: String::new(),
        status: "stopped".to_string(),
        github_context: String::new(),
        started_at: now,
        ended_at: 0,
        created_at: now,
        identity_id: String::new(),
        memory_id: String::new(),
        instance_name: name.to_string(),
        working_directory: String::new(),
        display_hidden: false,
    };
    match wstore.instance_create(&inst) {
        Ok(_) => Ok((stub_id, true)),
        Err(e) if e.to_string().contains("UNIQUE constraint") => {
            Ok((stub_id, false)) // stub already existed — idempotent
        }
        Err(e) => Err(format!("agent.define: create stub instance: {e}")),
    }
}

// ---------------------------------------------------------------------------
// agent.define
// ---------------------------------------------------------------------------

/// Core logic for the `agent.define` command, shared by the WebSocket RPC
/// handler and the HTTP service dispatch (`("agent", "define")` in service.rs).
/// Persist `system_prompt` and `env` content blobs for a freshly created or
/// updated agent definition.  Errors are logged but not propagated — the
/// definition row is already committed and the caller has already published
/// `agents:changed`, so a content-write failure must not abort the response.
fn persist_define_content(
    wstore: &Store,
    agent_id: &str,
    cmd: &CommandAgentDefineData,
    now: i64,
) {
    if let Some(prompt) = &cmd.system_prompt {
        if !prompt.is_empty() {
            if let Err(e) = wstore.agent_content_set(&AgentContent {
                agent_id: agent_id.to_string(),
                content_type: "agentmd".to_string(),
                content: prompt.clone(),
                updated_at: now,
            }) {
                tracing::warn!(agent_id, err = %e, "agent.define: failed to persist system_prompt (non-fatal)");
            }
        }
    }
    if let Some(env_map) = &cmd.env {
        if !env_map.is_empty() {
            let content = env_map.iter()
                .map(|(k, v)| format!("{}={}", k, v))
                .collect::<Vec<_>>()
                .join("\n");
            if let Err(e) = wstore.agent_content_set(&AgentContent {
                agent_id: agent_id.to_string(),
                content_type: "env".to_string(),
                content,
                updated_at: now,
            }) {
                tracing::warn!(agent_id, err = %e, "agent.define: failed to persist env (non-fatal)");
            }
        }
    }
}

pub(crate) async fn agent_define_core(
    wstore: Arc<Store>,
    broker: Arc<crate::backend::wps::Broker>,
    cmd: CommandAgentDefineData,
) -> Result<AgentDefineResult, String> {
    if cmd.name.trim().is_empty() {
        return Err("agent.define: name is required".to_string());
    }

    // Validate if_exists early so a typo is caught even for new definitions,
    // not only when a matching definition already exists.
    let if_exists = cmd.if_exists.as_deref().unwrap_or("skip");
    if !matches!(if_exists, "skip" | "update" | "error") {
        return Err(format!(
            "agent.define: unknown if_exists value '{if_exists}'; valid: skip, update, error"
        ));
    }

    // Resolve provider: explicit `provider` wins; fall back to inference from
    // `model` prefix; default to "claude" when neither is supplied.
    let provider = if !cmd.provider.is_empty() {
        if providers::get_provider(&cmd.provider).is_none() {
            return Err(format!(
                "agent.define: unknown provider '{}'; valid: claude, codex, gemini, qwen, kimi, openclaw, pi, copilot",
                cmd.provider
            ));
        }
        cmd.provider.clone()
    } else if !cmd.model.is_empty() {
        let inferred = infer_provider_from_model(&cmd.model);
        if providers::get_provider(&inferred).is_none() {
            return Err(format!(
                "agent.define: cannot infer provider from model '{}'; set provider explicitly",
                cmd.model
            ));
        }
        inferred
    } else {
        "claude".to_string()
    };

    let create_stub = cmd.create_instance_stub.unwrap_or(true);

    let now = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap_or_default()
        .as_millis() as i64;

    // Build the new definition struct up-front so agent_def_find_or_insert
    // can use it as both the lookup key and the insert payload.
    // agent_def_find_or_insert holds a single mutex guard for the check +
    // conditional insert — closing the TOCTOU window between list and insert.
    let mut def = AgentDefinition {
        id: uuid::Uuid::new_v4().to_string(),
        slug: String::new(), // resolved by agent_def_find_or_insert
        name: cmd.name.clone(),
        icon: cmd.icon.clone(),
        provider: provider.clone(),
        description: cmd.description.clone(),
        working_directory: cmd.working_directory.clone(),
        shell: cmd.shell.clone(),
        environment: cmd.environment.clone(),
        // Persist the requested model as a CLI flag so the agent launches
        // with the specified model rather than the provider default.
        provider_flags: if cmd.model.is_empty() {
            String::new()
        } else {
            format!("--model {}", cmd.model)
        },
        auto_start: 0,
        restart_on_crash: 0,
        idle_timeout_minutes: 0,
        created_at: now,
        agent_type: cmd.agent_type.clone(),
        agent_bus_id: String::new(),
        is_seeded: 0,
        accounts: String::new(),
        parent_id: String::new(),
        branch_label: String::new(),
        updated_at: now,
        user_hidden: 0,
        container_image: cmd.container_image.clone(),
        container_volumes: cmd.container_volumes.clone(),
        container_name: String::new(), // assigned by ContainerManager on first spawn
    };

    // Atomic check-then-insert.
    // Returns Some(existing) if a row matched by name/slug already exists;
    // None if the row was freshly inserted (def.slug now holds resolved slug).
    let existing_opt = wstore.agent_def_find_or_insert(&mut def)
        .map_err(|e| format!("agent.define: find_or_insert: {e}"))?;

    if let Some(existing) = existing_opt {
        // A definition with this name/slug already exists — apply if_exists policy.
        match if_exists {
            "skip" => {
                // Honor create_instance_stub even on skip: a definition that was
                // created with create_instance_stub=false (or imported via another
                // path) might not have a stub yet; a subsequent idempotent call
                // with create_instance_stub=true should make it visible in My Agents.
                // Only fire agents:changed when the stub was actually newly inserted.
                let (stub_id, stub_new) = if create_stub {
                    match make_stub_idempotent(&wstore, &existing.id, &existing.name, now) {
                        Ok((id, new)) => (Some(id), new),
                        Err(e) => {
                            tracing::warn!(id = %existing.id, err = %e, "agent.define: skip stub failed (non-fatal)");
                            (None, false)
                        }
                    }
                } else {
                    (None, false)
                };
                if stub_new {
                    broker.publish(crate::backend::wps::WaveEvent {
                        event: "agents:changed".to_string(),
                        scopes: vec![],
                        sender: String::new(),
                        persist: 0,
                        data: None,
                    });
                }
                tracing::info!(id = %existing.id, slug = %existing.slug, stub = stub_id.is_some(), "agent.define: skipped (exists)");
                return Ok(AgentDefineResult {
                    definition_id: existing.id.clone(),
                    slug: existing.slug.clone(),
                    action: "skipped".to_string(),
                    instance_stub_id: stub_id,
                });
            }
            "error" => {
                return Err(format!(
                    "agent.define: definition '{}' already exists (if_exists=error)",
                    cmd.name.trim()
                ));
            }
            "update" => {
                let mut updated = existing.clone();
                // provider was already validated/defaulted above; only
                // overwrite if the caller explicitly supplied a provider or model.
                if !cmd.provider.is_empty() || !cmd.model.is_empty() { updated.provider = provider.clone(); }
                // Persist the model as a CLI flag so the agent launches with
                // the requested model rather than the provider default.
                // If the provider changes but no model is supplied, clear stale
                // flags from the old provider so the new provider's default is used.
                if !cmd.model.is_empty() {
                    updated.provider_flags = format!("--model {}", cmd.model);
                } else if !cmd.provider.is_empty() {
                    updated.provider_flags = String::new();
                }
                if !cmd.icon.is_empty()     { updated.icon = cmd.icon.clone(); }
                if !cmd.description.is_empty() { updated.description = cmd.description.clone(); }
                if !cmd.working_directory.is_empty() { updated.working_directory = cmd.working_directory.clone(); }
                if !cmd.shell.is_empty()    { updated.shell = cmd.shell.clone(); }
                if !cmd.environment.is_empty() { updated.environment = cmd.environment.clone(); }
                // name update intentionally omitted — the slug is immutable;
                // renaming would create a slug mismatch. Use updateagent for renames.
                let did_update = wstore.agent_def_update(&mut updated)
                    .map_err(|e| format!("agent.define: update: {e}"))?;
                if !did_update {
                    return Err("agent.define: update: row was deleted between find and update".to_string());
                }
                persist_define_content(&wstore, &updated.id, &cmd, now);
                let stub_id = if create_stub {
                    match make_stub_idempotent(&wstore, &updated.id, &updated.name, now) {
                        Ok((id, _new)) => Some(id),
                        Err(e) => {
                            tracing::warn!(id = %updated.id, err = %e, "agent.define: update stub failed (non-fatal)");
                            None
                        }
                    }
                } else {
                    None
                };
                broker.publish(crate::backend::wps::WaveEvent {
                    event: "agents:changed".to_string(),
                    scopes: vec![],
                    sender: String::new(),
                    persist: 0,
                    data: None,
                });
                tracing::info!(id = %updated.id, slug = %updated.slug, stub = stub_id.is_some(), "agent.define: updated");
                return Ok(AgentDefineResult {
                    definition_id: updated.id.clone(),
                    slug: updated.slug.clone(),
                    action: "updated".to_string(),
                    instance_stub_id: stub_id,
                });
            }
            other => {
                return Err(format!("agent.define: unknown if_exists value '{other}'"));
            }
        }
    }

    // Fresh insert — def.slug is now set by agent_def_find_or_insert.
    // Create the stub first so that listeners handling agents:changed can
    // immediately find the new agent via ListRecentSessionsCommand. The
    // definition is already committed; a stub failure is non-fatal (log +
    // continue) and we still broadcast so callers see the new definition.
    let stub_id = if create_stub {
        match make_stub_idempotent(&wstore, &def.id, &def.name, now) {
            Ok((id, _new)) => Some(id),
            Err(e) => {
                tracing::warn!(id = %def.id, err = %e, "agent.define: stub failed (definition committed, non-fatal)");
                None
            }
        }
    } else {
        None
    };
    broker.publish(crate::backend::wps::WaveEvent {
        event: "agents:changed".to_string(),
        scopes: vec![],
        sender: String::new(),
        persist: 0,
        data: None,
    });
    persist_define_content(&wstore, &def.id, &cmd, now);

    tracing::info!(
        id = %def.id,
        slug = %def.slug,
        stub = stub_id.is_some(),
        "agent.define: created"
    );

    Ok(AgentDefineResult {
        definition_id: def.id.clone(),
        slug: def.slug.clone(),
        action: "created".to_string(),
        instance_stub_id: stub_id,
    })
}

fn register_agent_define(engine: &Arc<WshRpcEngine>, state: &AppState) {
    let wstore = state.wstore.clone();
    let broker = state.broker.clone();

    engine.register_handler(
        COMMAND_AGENT_DEFINE,
        Box::new(move |data, _ctx| {
            let wstore = wstore.clone();
            let broker = broker.clone();
            Box::pin(async move {
                let cmd: CommandAgentDefineData = serde_json::from_value(data)
                    .map_err(|e| format!("agent.define: {e}"))?;
                agent_define_core(wstore, broker, cmd).await
                    .map(|r| Some(serde_json::to_value(&r).unwrap()))
            })
        }),
    );
}

#[cfg(test)]
mod cross_channel_tests {
    use super::*;
    use crate::backend::agent_session::OUTPUT_FILE;
    use crate::backend::storage::filestore::{FileMeta, FileOpts, FileStore};

    fn mem_store() -> Arc<FileStore> {
        Arc::new(FileStore::open_in_memory().unwrap())
    }

    fn seed_output(fs: &Arc<FileStore>, zone: &str, body: &[u8]) {
        fs.make_file(zone, OUTPUT_FILE, FileMeta::default(), FileOpts::default())
            .unwrap();
        fs.append_data(zone, OUTPUT_FILE, body).unwrap();
    }

    fn insert_agent_block(wstore: &Arc<Store>, def_id: &str) -> String {
        let oid = uuid::Uuid::new_v4().to_string();
        let mut meta = MetaMapType::new();
        meta.insert("view".to_string(), serde_json::json!("agent"));
        meta.insert("agentId".to_string(), serde_json::json!(def_id));
        let mut block = Block {
            oid: oid.clone(),
            parentoref: String::new(),
            version: 1,
            runtimeopts: None,
            stickers: None,
            meta,
            subblockids: None,
        };
        wstore.insert(&mut block).expect("insert block");
        oid
    }

    #[test]
    fn global_output_source_falls_back_when_local_empty() {
        let per_channel = mem_store();
        let global = mem_store();
        let wstore = Arc::new(Store::open_in_memory().unwrap());
        let block_id = insert_agent_block(&wstore, "def-cc-1");

        // No local output for the block, but the global zone has content.
        seed_output(&global, "agent:def-cc-1:current", b"{\"type\":\"user\"}\n");

        let resolved = global_output_source(
            &per_channel,
            &Some(global.clone()),
            &wstore,
            &block_id,
            "output",
        );
        let (_store, zone) = resolved.expect("should fall back to global");
        assert_eq!(zone, "agent:def-cc-1:current");
    }

    #[test]
    fn global_output_source_prefers_global_even_when_local_present() {
        // After the Bug-1 fix: even when the local output is non-empty (current
        // session started writing), the global zone is still returned so that
        // cross-channel history load sees the FULL record, not just the current
        // session's lines.
        let per_channel = mem_store();
        let global = mem_store();
        let wstore = Arc::new(Store::open_in_memory().unwrap());
        let block_id = insert_agent_block(&wstore, "def-cc-2");

        seed_output(&per_channel, &block_id, b"{\"type\":\"local\"}\n");
        seed_output(&global, "agent:def-cc-2:current", b"{\"type\":\"global\"}\n");

        let resolved = global_output_source(
            &per_channel,
            &Some(global.clone()),
            &wstore,
            &block_id,
            "output",
        );
        let (_, zone) = resolved.expect("global always preferred when available");
        assert_eq!(zone, "agent:def-cc-2:current");
    }

    #[test]
    fn global_output_source_only_for_output_and_with_global_store() {
        let per_channel = mem_store();
        let global = mem_store();
        let wstore = Arc::new(Store::open_in_memory().unwrap());
        let block_id = insert_agent_block(&wstore, "def-cc-3");
        seed_output(&global, "agent:def-cc-3:current", b"{\"x\":1}\n");

        // Non-"output" filename is never globalized.
        assert!(global_output_source(&per_channel, &Some(global.clone()), &wstore, &block_id, "term").is_none());
        // No global store configured → None.
        assert!(global_output_source(&per_channel, &None, &wstore, &block_id, "output").is_none());
        // Non-agent block id → None.
        assert!(global_output_source(&per_channel, &Some(global), &wstore, "not-a-block", "output").is_none());
    }

    #[test]
    fn global_output_source_suppressed_for_archived_block() {
        // A block archived via the UI/sweep (`session:archived_at` set, local
        // output deleted) must NOT resurrect from the global mirror — it should
        // reopen archived/empty as pre-PR. (reagent P1 #1399.)
        let per_channel = mem_store();
        let global = mem_store();
        let wstore = Arc::new(Store::open_in_memory().unwrap());

        let oid = uuid::Uuid::new_v4().to_string();
        let mut meta = MetaMapType::new();
        meta.insert("view".to_string(), serde_json::json!("agent"));
        meta.insert("agentId".to_string(), serde_json::json!("def-cc-arch"));
        meta.insert(
            crate::backend::session_archive::META_SESSION_ARCHIVED_AT.to_string(),
            serde_json::json!(1_700_000_000_000i64),
        );
        let mut block = Block {
            oid: oid.clone(),
            parentoref: String::new(),
            version: 1,
            runtimeopts: None,
            stickers: None,
            meta,
            subblockids: None,
        };
        wstore.insert(&mut block).expect("insert block");

        // Global zone has content, but the block is archived → no fallback.
        seed_output(&global, "agent:def-cc-arch:current", b"{\"type\":\"user\"}\n");
        assert!(
            global_output_source(&per_channel, &Some(global), &wstore, &oid, "output").is_none(),
            "archived block must not fall back to the global mirror",
        );
    }

    #[test]
    fn global_zone_line_count_counts_non_blank_lines() {
        let global = mem_store();
        let zone = "agent:def-cc-4:current";
        seed_output(&global, zone, b"{\"a\":1}\n{\"b\":2}\n\n{\"c\":3}\n");
        // 3 non-blank NDJSON lines (the blank line is ignored, matching read_range).
        assert_eq!(global_zone_line_count(&global, zone), Some(3));

        // Empty / absent zone → Some(0) / None respectively.
        let empty_zone = "agent:def-empty:current";
        assert_eq!(global_zone_line_count(&global, empty_zone), None);
    }
}


#[cfg(test)]
mod pane_open_reducer_tests {
    use super::*;
    use crate::backend::rpc_types::CommandPaneOpenData;
    use crate::server::tests::test_state;
    use agentmux_common::ipc::{Command, Event};

    async fn dispatch_apply(state: &AppState, cmd: Command) -> Vec<Event> {
        let evs = crate::server::service::dispatch_to_reducer(state, cmd).await;
        for ev in &evs {
            crate::persist_subscriber::apply_event_to_wstore(ev, &state.wstore).unwrap();
        }
        evs
    }

    /// Regression for #1681: the docked `pane.open` path created its block
    /// store-only (`wcore::create_block`), so the block was absent from the
    /// reducer's `state.blocks` and a later TearOffBlock / RedockFloatingPane
    /// was rejected "block not found". Assert the block now lands in `srv_state`
    /// and a tear-off of the freshly-opened pane succeeds end-to-end.
    #[tokio::test]
    async fn docked_pane_open_block_is_in_reducer_and_tears_off() {
        let state = test_state();

        // Workspace + tab through the reducer (→ srv_state AND, via apply, wstore).
        let ws_evs = dispatch_apply(&state, Command::CreateWorkspace { name: "w".into() }).await;
        let ws_id = ws_evs
            .iter()
            .find_map(|e| match e {
                Event::WorkspaceCreated { workspace_id, .. } => Some(workspace_id.clone()),
                _ => None,
            })
            .unwrap();
        let tab_evs = dispatch_apply(
            &state,
            Command::CreateTab { workspace_id: ws_id.clone(), name: "t".into() },
        )
        .await;
        let tab_id = tab_evs
            .iter()
            .find_map(|e| match e {
                Event::TabCreated { tab_id, .. } => Some(tab_id.clone()),
                _ => None,
            })
            .unwrap();

        // Open a docked sysinfo pane (no required args).
        let cmd = CommandPaneOpenData {
            view: "sysinfo".into(),
            file: None,
            url: None,
            cwd: None,
            title: None,
            tab_id: Some(tab_id.clone()),
            split_direction: None,
            split_reference_block_id: None,
            focus: None,
            tree_expanded: None,
            floating: None,
        };
        let res = open_pane(&state, cmd).await.expect("open_pane docked");

        // The block is now visible to the reducer (was the bug: store-only).
        {
            let s = state.srv_state.lock().await;
            assert!(
                s.blocks.contains_key(&res.block_id),
                "docked pane.open block must be tracked in srv_state"
            );
        }

        // And tearing it off no longer hits "block not found".
        let r = crate::sagas::tear_off_block::run(
            &state,
            res.block_id.clone(),
            tab_id.clone(),
            ws_id.clone(),
        )
        .await;
        assert!(r.is_ok(), "tear-off of an opened pane must succeed, got: {:?}", r.err());
    }
}

/// Parse + validate a saved per-agent `ui:zoom` content blob for seeding a new
/// agent block's `term:zoom`. Returns `Some(z)` only for a parseable,
/// non-default (≠ 1.0), in-[0.5, 2.0] zoom (the range the frontend enforces in
/// term.tsx); anything else (default, out of range, garbage) returns `None` so
/// the new block opens at the default 1.0. See SPEC_AGENT_ZOOM_PERSISTENCE §4.2.
fn parse_seed_zoom(raw: &str) -> Option<f64> {
    let z = raw.trim().parse::<f64>().ok()?;
    if (z - 1.0).abs() > f64::EPSILON && (0.5..=2.0).contains(&z) {
        Some(z)
    } else {
        None
    }
}

#[cfg(test)]
mod agent_zoom_seed_tests {
    use super::parse_seed_zoom;

    #[test]
    fn seeds_valid_non_default_zoom() {
        assert_eq!(parse_seed_zoom("1.3"), Some(1.3));
        assert_eq!(parse_seed_zoom("0.5"), Some(0.5));
        assert_eq!(parse_seed_zoom("2"), Some(2.0));
        assert_eq!(parse_seed_zoom("  1.4  "), Some(1.4)); // trims
    }

    #[test]
    fn rejects_default_out_of_range_and_garbage() {
        assert_eq!(parse_seed_zoom("1.0"), None, "default seeds nothing");
        assert_eq!(parse_seed_zoom("1"), None, "default seeds nothing");
        assert_eq!(parse_seed_zoom("2.5"), None, "above range");
        assert_eq!(parse_seed_zoom("0.4"), None, "below range");
        assert_eq!(parse_seed_zoom("abc"), None, "unparseable");
        assert_eq!(parse_seed_zoom(""), None, "empty");
    }
}