agentmux_srv/server/

cli_handlers.rs

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

#[cfg(windows)]
use agentmux_common::win32::NoWindow;
use std::sync::Arc;

use crate::backend::rpc::engine::WshRpcEngine;
use crate::backend::rpc_types::{
    ToolchainEnvReq, ToolchainEnvResult, ToolchainVersionsReq,
    ToolchainPruneItem, ToolchainPruneReq, ToolchainPruneResult, ToolchainPruneSkip,
    WidgetApiResult, WidgetHealthResult,
    CheckCliAuthResult, CommandCheckCliAuthData, CommandResolveCliData, CommandRunCliLoginData,
    EnsureProviderAuthDirReq, EnsureProviderAuthDirResult, ResolveCliResult, RunCliLoginResult,
    COMMAND_CHECK_CLI_AUTH, COMMAND_ENSURE_PROVIDER_AUTH_DIR, COMMAND_RESOLVE_CLI,
};

use super::AppState;

/// Register CLI-related RPC handlers (resolvecli, checkcliauth, runclilogin).
pub fn register_cli_handlers(engine: &Arc<WshRpcEngine>, state: &AppState) {
    // resolvecli → detect or install a CLI tool for an agent provider.
    // Installs are shared across AgentMux versions, keyed by the provider's
    // pinned CLI version: `<shared_dir>/cli/<provider>/<pinned_version>/`,
    // with the legacy `<home>/instances/v<AGENTMUX_VERSION>/cli/<provider>/`
    // as a read-only fallback. One definition for every resolver
    // (`install.start` / `install.check`, `agent.open`, the picker's
    // read-only lookup): `backend::cli_install`.
    // Never falls back to system PATH for npm-backed providers.
    let broker_resolve = state.broker.clone();
    let filestore_resolve = state.filestore.clone();
    let mstore_resolve = state.mstore.clone();
    engine.register_typed(
        COMMAND_RESOLVE_CLI,
        move |cmd: CommandResolveCliData, _ctx| {
            let broker = broker_resolve.clone();
            let notices = CliNotices {
                broker: broker_resolve.clone(),
                filestore: filestore_resolve.clone(),
                mstore: mstore_resolve.clone(),
                block_id: notice_block_id(&cmd),
                agent_id: cmd.agent_id.clone().filter(|a| !a.trim().is_empty()),
                provider: cmd.provider_id.clone(),
            };
            async move {
                const AGENTMUX_VERSION: &str = env!("CARGO_PKG_VERSION");

                tracing::info!(
                    provider = %cmd.provider_id,
                    cli = %cmd.cli_command,
                    block_id = %cmd.block_id,
                    agentmux_version = AGENTMUX_VERSION,
                    "ResolveCli"
                );

                // Install location: shared across AgentMux versions, keyed
                // by the provider's pinned CLI version, with the legacy
                // per-version dir as a read-only fallback — see
                // `backend::cli_install` (SPEC_AGENT_OPEN_LATENCY_2026_09_27.md
                // F1). The backend registry's pin wins over the caller's.
                let paths = agentmux_common::DataPaths::from_env()
                    .ok_or_else(|| "DataPaths::from_env() failed".to_string())?;
                let pinned_version = crate::backend::providers::get_provider(&cmd.provider_id)
                    .map(|p| p.pinned_version.to_string())
                    .unwrap_or_else(|| cmd.pinned_version.clone());
                let install_dir = crate::backend::cli_install::install_dir(&paths, &cmd.provider_id, &pinned_version);
                let provider_dir = install_dir.to_string_lossy().to_string();
                // npm binary path — the only valid location for installed CLIs.
                let npm_bin = crate::backend::cli_install::npm_bin(&install_dir, &cmd.cli_command)
                    .to_string_lossy()
                    .to_string();

                // Step 1: already installed (shared dir, else legacy per-version dir)?
                if let Some(found) = crate::backend::cli_install::find_installed(
                    &paths,
                    &cmd.provider_id,
                    &pinned_version,
                    &cmd.cli_command,
                ) {
                    let found = found.to_string_lossy().to_string();
                    let version = get_cli_version(&found).await;
                    tracing::info!(path = %found, version = %version, "CLI found in local install");
                    notices.observe_version(&version);
                    return Ok(ResolveCliResult {
                        cli_path: found,
                        version,
                        source: "local_install".to_string(),
                    });
                }

                // Step 2: Not in versioned dir — check system PATH for non-npm CLIs.
                if cmd.npm_package.is_empty() {
                    if let Some(path) = resolve_provider_cli_on_path(&cmd.provider_id, &cmd.cli_command).await {
                        let version = get_cli_version(&path).await;
                        tracing::info!(
                            path = %path, version = %version,
                            "CLI found on system PATH"
                        );
                        notices.observe_version(&version);
                        return Ok(ResolveCliResult {
                            cli_path: path,
                            version,
                            source: "system_path".to_string(),
                        });
                    }
                    // This branch fires for PATH-only providers
                    // (`npm_package` empty) whose CLI isn't on the
                    // system PATH. AgentMux can't auto-install these
                    // — emit AMX-CLI-004 with a manual install hint
                    // instead of AMX-CLI-001 ("Click Install now"),
                    // which would point the user at an install
                    // affordance that doesn't apply.
                    let install_hint = if cfg!(target_os = "windows") {
                        cmd.windows_install_command.clone()
                    } else {
                        cmd.unix_install_command.clone()
                    };
                    return Err(agentmux_common::AgentMuxError::CliMissingOnPath {
                        provider: cmd.provider_id.clone(),
                        cli: cmd.cli_command.clone(),
                        install_hint,
                    }
                    .to_wire()
                    .to_string());
                }

                tracing::info!(
                    provider = %cmd.provider_id,
                    npm_package = %cmd.npm_package,
                    pinned_version = %pinned_version,
                    target_dir = %provider_dir,
                    "CLI not found locally, installing via npm"
                );

                {
                    // Verify npm is available before attempting install.
                    let npm_available = if cfg!(windows) {
                        // CREATE_NO_WINDOW (0x08000000) suppresses cmd flash —
                        // see broader fix in this file's other spawns.
                        let mut probe = tokio::process::Command::new("where");
                        probe.arg("npm");
                        #[cfg(windows)]
                        {
                            probe.no_window();
                        }
                        probe.output().await.map(|o| o.status.success()).unwrap_or(false)
                    } else {
                        tokio::process::Command::new("which").arg("npm").output().await
                            .map(|o| o.status.success()).unwrap_or(false)
                    };
                    if !npm_available {
                        return Err(format!(
                            "{} requires Node.js/npm to install. \
                            Install Node.js from https://nodejs.org then restart AgentMux.",
                            cmd.cli_command
                        ));
                    }

                    // One install routine for this and the startup warm-up
                    // (`cli_install::install_pinned_cli`): cross-instance lock
                    // held for npm's whole lifetime — inside the blocking task,
                    // so a timed-out RPC can't release it early — reuse of an
                    // install another instance finished while we waited, and
                    // the completion marker only after the shim is verified.
                    let req = crate::backend::cli_install::NpmInstallRequest {
                        provider_id: cmd.provider_id.clone(),
                        npm_package: cmd.npm_package.clone(),
                        pinned_version: pinned_version.clone(),
                        cli_command: cmd.cli_command.clone(),
                        background: false,
                    };
                    let install_paths = paths.clone();
                    let block_id_install = cmd.block_id.clone();
                    // The pane says it's installing, then how it went: a pane
                    // restored at startup otherwise just starts slower.
                    let install_id = format!("{}-{}-{}", cmd.provider_id, pinned_version, agentmux_common::time::now_ms());
                    let install_started = std::time::Instant::now();
                    notices.install(&install_id, &pinned_version, crate::backend::cli_notice::InstallState::Installing, None, None);
                    let broker_npm = broker.clone();
                    let outcome = tokio::task::spawn_blocking(move || {
                        let on_line = |stream: &'static str, line: &str| {
                            tracing::info!(stream, line = %line, "npm output");
                            if !block_id_install.is_empty() {
                                crate::backend::mps::publish_install_progress(
                                    &broker_npm,
                                    &block_id_install,
                                    line,
                                );
                            }
                        };
                        crate::backend::cli_install::install_pinned_cli(
                            &install_paths,
                            &req,
                            &on_line,
                        )
                    })
                    .await
                    .map_err(|e| format!("npm install task panicked: {e}"))?;
                    match &outcome {
                        Ok(_) => notices.install(
                            &install_id,
                            &pinned_version,
                            crate::backend::cli_notice::InstallState::Installed,
                            Some(install_started.elapsed().as_secs_f64()),
                            None,
                        ),
                        Err(e) => notices.install(
                            &install_id,
                            &pinned_version,
                            crate::backend::cli_notice::InstallState::Failed,
                            None,
                            Some(&e.to_string()),
                        ),
                    }

                    use crate::backend::cli_install::{InstallError, InstallOutcome};
                    let (bin, source) = match outcome {
                        Ok(InstallOutcome::Installed(bin)) => (bin, "installed"),
                        Ok(InstallOutcome::AlreadyInstalled(bin)) => (bin, "local_install"),
                        Err(InstallError::NpmFailed { code }) => {
                            return Err(agentmux_common::AgentMuxError::NpmInstallFailed {
                                package: format!("{}@{}", cmd.npm_package, pinned_version),
                                message: format!(
                                    "exit {}; check the output above",
                                    code.unwrap_or(-1)
                                ),
                            }
                            .to_wire()
                            .to_string());
                        }
                        Err(InstallError::ShimMissing { .. }) => {
                            return Err(agentmux_common::AgentMuxError::CliShimMissing {
                                provider: cmd.provider_id.clone(),
                                expected_path: npm_bin.clone(),
                            }
                            .to_wire()
                            .to_string());
                        }
                        Err(e) => return Err(e.to_string()),
                    };
                    let bin = bin.to_string_lossy().to_string();
                    let version = get_cli_version(&bin).await;
                    tracing::info!(path = %bin, version = %version, source, "CLI installed (npm)");
                    notices.observe_version(&version);
                    Ok(ResolveCliResult {
                        cli_path: bin,
                        version,
                        source: source.to_string(),
                    })
                }
            }
        },
    );

    // checkcliauth → check if a CLI tool is authenticated
    // For Claude: reads ~/.claude/.credentials.json directly (instant, no subprocess).
    // For other providers: falls back to running the CLI auth check command.
    engine.register_typed(
        COMMAND_CHECK_CLI_AUTH,
        |cmd: CommandCheckCliAuthData, _ctx| {
            async move {
                tracing::info!(cli = %cmd.cli_path, "CheckCliAuth");

                // Two-phase auth check for Claude; single-phase for other providers.
                //
                // Phase 1 (fast, <1 ms): read the credentials file to determine whether
                // tokens exist at all. If no file / no tokens → return unauthenticated
                // immediately without spawning the CLI. This avoids a 10+ second cold-start
                // stall when the user is definitely not logged in.
                //
                // Phase 2 (CLI, 10 s timeout): only when tokens ARE present, run
                // `claude auth status --json` to validate them and obtain the real email.
                // This catches expired/revoked tokens — the false-positive that the old
                // file-only fast path missed.
                //
                // Other providers skip Phase 1 and go straight to the CLI (they don't have
                // a predictable credentials file layout).
                //
                // See SPEC_AUTH_CHECK_FALSE_POSITIVE_2026_04_15.md.
                if cmd.cli_path.to_lowercase().contains("claude") {
                    let home = std::env::var("HOME")
                        .or_else(|_| std::env::var("USERPROFILE"))
                        .unwrap_or_default();

                    // REMOVED 2026-08-31 — the first-run bootstrap that copied
                    // the user's global `~/.claude/.credentials.json` into the
                    // isolated CLAUDE_CONFIG_DIR (gated on a
                    // `.agentmux-cred-seeded` sentinel).
                    //
                    // It ran during a routine AUTH CHECK — no login, no user
                    // action, no bound account — so an agent in a fresh
                    // channel silently acquired the operator's personal
                    // credential. That is the most direct of the four
                    // per-channel-isolation bypasses catalogued in
                    // `docs/analysis/ANALYSIS_PER_CHANNEL_AUTH_BYPASSES_2026_08_31.md`
                    // (#4), and the most likely answer to the reported "agents
                    // operate with no account" (it also explains why the
                    // symptom varied by machine — it depended on whether
                    // `~/.claude` happened to hold a valid credential).
                    //
                    // Its original justification
                    // (`docs/retro/retro-provider-auth-isolation-regression-2026-06-05.md`)
                    // predates the "agents never use ~/.claude" requirement
                    // (`SPEC_BLOCK_AMBIENT_HOME_DIR_IDENTITY_BINDING_2026_08_25.md`)
                    // and was never revisited against it.
                    //
                    // An unauthenticated isolated dir must now simply report
                    // `authenticated: false` and let the user log in FOR THIS
                    // CHANNEL. Do not reintroduce an import here: a check must
                    // report state, never mint credentials as a side effect.

                    // §4 INVARIANT (provider-auth-isolation.md): validate the SAME dir
                    // the agent runs in — the isolated CLAUDE_CONFIG_DIR if set, else
                    // global ~/.claude. NEVER "isolated OR global": that "check global /
                    // run isolated" split is the validate-spin regression's root cause
                    // (phase 2 below runs `claude auth status --json` against this exact
                    // dir, so phase 1 must check the same one).
                    let creds_path = cmd
                        .auth_env
                        .get("CLAUDE_CONFIG_DIR")
                        .map(|d| format!("{}/.credentials.json", d))
                        .unwrap_or_else(|| format!("{}/.claude/.credentials.json", home));

                    let tokens_exist = match std::fs::read_to_string(&creds_path) {
                        Ok(content) => serde_json::from_str::<serde_json::Value>(&content)
                            .ok()
                            .map(|json| {
                                let oauth = json.get("claudeAiOauth");
                                let has_token = oauth
                                    .and_then(|o| o.get("accessToken"))
                                    .and_then(|v| v.as_str())
                                    .map(|s| !s.is_empty())
                                    .unwrap_or(false);
                                let has_refresh = oauth
                                    .and_then(|o| o.get("refreshToken"))
                                    .and_then(|v| v.as_str())
                                    .map(|s| !s.is_empty())
                                    .unwrap_or(false);
                                has_token || has_refresh
                            })
                            .unwrap_or(false),
                        Err(_) => false,
                    };

                    // Login/logout robustness diagnostic: snapshot the SAME dir
                    // we validate (token fingerprint is redacted — see
                    // identity::auth_diag). Across login/logout rounds this
                    // surfaces the classic bugs — a check reading a different
                    // dir than login wrote, a token that didn't change after a
                    // re-login, or a credential that outlived a logout. The CLI
                    // verdict is logged separately below; compare the two.
                    // Cover BOTH the isolated dir (CLAUDE_CONFIG_DIR) and the
                    // global-fallback dir (~/.claude) — creds_path/tokens_exist
                    // above use exactly this resolution, so the snapshot always
                    // reflects the dir actually validated (not only the isolated
                    // case). "auth.credstate:" is `muxlog auth` vocabulary.
                    let checked_dir = cmd
                        .auth_env
                        .get("CLAUDE_CONFIG_DIR")
                        .cloned()
                        .unwrap_or_else(|| format!("{home}/.claude"));
                    tracing::info!(
                        "auth.credstate: check {}",
                        crate::identity::auth_diag::snapshot(&checked_dir)
                    );

                    if !tokens_exist {
                        // On macOS the Claude CLI stores credentials in the
                        // Keychain ("Claude Safe Storage"), NOT in
                        // .credentials.json — so a missing file does NOT mean
                        // logged out. Fall through to `claude auth status`, which
                        // reads the Keychain (and does so without a prompt — the
                        // CLI owns that Keychain item). On Windows/Linux the file
                        // IS the credential store, so the fast "definitely not
                        // authenticated" short-circuit stays correct there.
                        #[cfg(not(target_os = "macos"))]
                        {
                            tracing::info!("claude auth check: no credentials in provider dir, skipping CLI");
                            let result = CheckCliAuthResult {
                                authenticated: false,
                                email: None,
                                auth_method: None,
                                raw_output: "no credentials found".to_string(),
                            };
                            return Ok(result);
                        }
                        #[cfg(target_os = "macos")]
                        tracing::info!(
                            "claude auth check: no credentials file — checking Keychain via CLI (macOS)"
                        );
                    } else {
                        // Tokens exist in the provider dir — validate with the CLI (10 s timeout).
                        tracing::info!("claude auth check: credentials found, validating via CLI");
                    }
                }

                let (authenticated, email, auth_method, raw_output) =
                    run_auth_check(&cmd.cli_path, &cmd.auth_check_args, &cmd.auth_env).await?;

                // REMOVED 2026-08-31 (Codex P1 on PR #2878) — the "self-heal a
                // stale isolated Claude credential" step. When validation
                // failed, it copied the user's personal
                // `~/.claude/.credentials.json` into the isolated dir (via
                // `refresh_claude_dir_from_global_if_stale`) whenever the global
                // access token differed, then re-validated ONCE so the agent
                // "recovered" — meaning a channel silently acquired a credential
                // authenticated OUTSIDE it and could then report authenticated
                // with no channel-local login at all.
                //
                // Same source and same end state as the first-run bootstrap
                // removed above, just a different trigger, so removing only that
                // one would have left this per-channel-isolation bypass wide
                // open. See
                // `docs/analysis/ANALYSIS_PER_CHANNEL_AUTH_BYPASSES_2026_08_31.md`
                // (#5).
                //
                // The real failure it was papering over (a global re-login
                // rotating the token and killing the isolated refresh token —
                // the "Pozl 401") is now surfaced honestly: validation fails, the
                // auth card appears, and the user logs in FOR THIS CHANNEL.

                let result = CheckCliAuthResult {
                    authenticated,
                    email,
                    auth_method,
                    raw_output,
                };
                Ok(result)
            }
        },
    );

    // provider.ensureauthdir → create the provider's default (shared) auth dir
    // and apply its isolation guarantees, exactly as agent open does; returns
    // the path for the launch env (e.g. CLAUDE_CONFIG_DIR). Replaces the CEF
    // host's `ensure_auth_dir`, which only created the dir.
    engine.register_typed(
        COMMAND_ENSURE_PROVIDER_AUTH_DIR,
        |req: EnsureProviderAuthDirReq, _ctx| async move {
            let provider = crate::backend::providers::get_provider(&req.provider_id)
                .ok_or_else(|| format!("provider.ensureauthdir: unknown provider {:?}", req.provider_id))?;
            let path = crate::backend::providers::default_auth_dir(provider)?;
            crate::backend::providers::prepare_provider_auth_dir(provider, &path)
                .map_err(|e| format!("provider.ensureauthdir: failed to prepare {path}: {e}"))?;
            Ok(EnsureProviderAuthDirResult { path })
        },
    );

    // runclilogin → spawn CLI login flow, extract OAuth URL from output, return immediately
    engine.register_typed(
        "runclilogin",
        |cmd: CommandRunCliLoginData, _ctx| {
            async move {
                tracing::info!(cli = %cmd.cli_path, args = ?cmd.login_args, "RunCliLogin");

                // Dead path: the active login flow is the CEF host IPC
                // `run_cli_login`, which owns the child's lifecycle (supersede-kill
                // + timeout reaper). This srv-side variant previously spawned a
                // DETACHED, unkillable `auth login` child here — a process leak if
                // ever invoked. It has no live caller; do NOT spawn.
                Ok(RunCliLoginResult { auth_url: None, raw_output: String::new() })
            }
        },
    );

    // toolchain.env — report the environment the srv resolves tools in: the
    // effective PATH, how it was derived (set by the host/srv PATH enricher,
    // see SPEC_TOOLCHAIN_MANAGER §3), and OS/arch. Powers the Toolchain
    // modal's Environment section so PATH problems are diagnosable.
    engine.register_typed(
        "toolchain.env",
        // `Option<_>` -- see `ToolchainEnvReq`: it is what makes both encodings
        // of "no argument" deserialize.
        |_req: Option<ToolchainEnvReq>, _ctx| {
            async move {
                Ok(ToolchainEnvResult {
                    path: std::env::var("PATH").unwrap_or_default(),
                    path_source: std::env::var("AGENTMUX_PATH_SOURCE")
                        .unwrap_or_else(|_| "inherited".to_string()),
                    os: std::env::consts::OS.to_string(),
                    arch: std::env::consts::ARCH.to_string(),
                })
            }
        },
    );

    // toolchain.prune — find (dry run, the default) or remove (an explicit
    // `dry_run: false`, from a user action) provider CLI installs that nothing
    // has used for 30 days and nothing is running. Never runs on its own.
    // SPEC_RUNTIME_MENU_REMAINING_GAPS_2026_10_01.md §5.
    let mstore_prune = state.mstore.clone();
    engine.register_typed(
        "toolchain.prune",
        move |req: Option<ToolchainPruneReq>, _ctx| {
            let mstore = mstore_prune.clone();
            async move {
                let dry_run = req.as_ref().and_then(|r| r.dry_run).unwrap_or(true);
                let only = req.and_then(|r| r.only);
                let paths = agentmux_common::DataPaths::from_env()
                    .ok_or_else(|| "DataPaths::from_env() failed".to_string())?;
                // The commands of every block that records one: the open panes
                // and the ones restored from a layout, which keep the absolute CLI
                // path until they mount.
                let live: Vec<String> = mstore
                    .get_all::<crate::backend::obj::Block>()
                    .map_err(|e| format!("toolchain.prune: {e}"))?
                    .iter()
                    .filter_map(|b| {
                        let mut parts: Vec<String> = Vec::new();
                        if let Some(c) = b.meta.get("cmd").and_then(|v| v.as_str()) {
                            parts.push(c.to_string());
                        }
                        if let Some(a) = b.meta.get("cmd:args").and_then(|v| v.as_array()) {
                            parts.extend(a.iter().filter_map(|v| v.as_str().map(str::to_string)));
                        }
                        (!parts.is_empty()).then(|| parts.join(" "))
                    })
                    .collect();
                let max_idle = crate::backend::cli_prune::DEFAULT_MAX_IDLE;
                let now = std::time::SystemTime::now();
                let run = tokio::task::spawn_blocking(move || {
                    crate::backend::cli_prune::run(&paths, &live, dry_run, only.as_deref(), max_idle, now)
                })
                .await
                .map_err(|e| format!("toolchain.prune: {e}"))?;
                Ok(prune_result(run, dry_run, max_idle))
            }
        },
    );

    // widget.health — HTTP liveness probe for an external widget server running
    // on localhost. The frontend passes { port, health_check_path,
    // health_check_body_contains? } and gets back { healthy, status_code }.
    // Connection-refused or timeout → { healthy: false } (not an RPC error).
    // health_check_body_contains lets callers distinguish services that share
    // a default port (e.g. Flowise and Grafana both default to 3000).
    // Registered with `serde_json::Value` as the REQUEST type rather than a
    // struct. `Value` deserializes from anything, so this is exactly as
    // tolerant as the untyped handler it replaces -- and the handler needs that
    // tolerance: a bad port or path is answered with `healthy: false`, not an
    // RPC error, which a typed request would turn into a deserialize failure.
    //
    // What it buys over `register_handler` is the RESPONSE type, which is the
    // half that was actually drifting.
    engine.register_typed(
        "widget.health",
        |data: serde_json::Value, _ctx| {
            async move {
                let port_raw = data.get("port").and_then(|v| v.as_u64()).unwrap_or(0);
                if port_raw == 0 || port_raw > 65535 {
                    return Ok(WidgetHealthResult { healthy: false, status_code: None });
                }
                let port = port_raw as u16;
                let path = data
                    .get("health_check_path")
                    .and_then(|v| v.as_str())
                    .unwrap_or("/")
                    .to_string();
                let body_contains = data
                    .get("health_check_body_contains")
                    .and_then(|v| v.as_str())
                    .map(|s| s.to_string());
                let url = format!("http://127.0.0.1:{}{}", port, path);
                let client = reqwest::Client::builder()
                    .timeout(std::time::Duration::from_secs(3))
                    .build()
                    .map_err(|e| e.to_string())?;
                match client.get(&url).send().await {
                    Ok(resp) => {
                        let status = resp.status().as_u16();
                        let ok_status = resp.status().is_success();
                        if !ok_status {
                            return Ok(WidgetHealthResult {
                                healthy: false,
                                status_code: Some(status),
                            });
                        }
                        // Optionally verify response body for service identity.
                        let healthy = if let Some(needle) = body_contains {
                            let body = resp.text().await.unwrap_or_default();
                            body.contains(&needle)
                        } else {
                            true
                        };
                        Ok(WidgetHealthResult { healthy, status_code: Some(status) })
                    }
                    Err(_) => Ok(WidgetHealthResult { healthy: false, status_code: None }),
                }
            }
        },
    );

    // widget.api — HTTP proxy to a widget's local server. Bypasses browser CORS
    // restrictions: the frontend sends { port, path, method?, headers?, body? }
    // and gets back { ok, status_code, body, error? }. Agents use this to call
    // ComfyUI /prompt, Grafana /api/query, etc. without needing a CORS header.
    // 30-second timeout accommodates generative tasks (image synthesis, etc.).
    // `Value` request for the same reason as `widget.health` above: an invalid
    // port or path is a `ok: false` ANSWER, not a rejected request.
    engine.register_typed(
        "widget.api",
        |data: serde_json::Value, _ctx| {
            async move {
                let reject = |why: &str| WidgetApiResult {
                    ok: false,
                    status_code: None,
                    body: None,
                    error: Some(why.to_string()),
                };
                let port_raw = data.get("port").and_then(|v| v.as_u64()).unwrap_or(0);
                if port_raw == 0 || port_raw > 65535 {
                    return Ok(reject("invalid port"));
                }
                let port = port_raw as u16;
                let path = data.get("path").and_then(|v| v.as_str()).unwrap_or("/").to_string();
                // Reject paths that could escape localhost: must start with '/',
                // no '@' (user-info injection: 127.0.0.1@evil.com), no backslash,
                // no protocol-relative '//' prefix.
                if !path.starts_with('/') || path.contains('@') || path.contains('\\') || path.starts_with("//") {
                    return Ok(reject("invalid path"));
                }
                let method = data
                    .get("method")
                    .and_then(|v| v.as_str())
                    .unwrap_or("GET")
                    .to_uppercase();
                let body_str = data.get("body").and_then(|v| v.as_str()).map(|s| s.to_string());
                let headers_obj = data.get("headers").and_then(|v| v.as_object()).cloned();

                let url = format!("http://127.0.0.1:{}{}", port, path);
                let client = reqwest::Client::builder()
                    .timeout(std::time::Duration::from_secs(30))
                    .redirect(reqwest::redirect::Policy::none())
                    .build()
                    .map_err(|e| e.to_string())?;

                let mut req = match method.as_str() {
                    "POST" => client.post(&url),
                    "PUT" => client.put(&url),
                    "DELETE" => client.delete(&url),
                    "PATCH" => client.patch(&url),
                    _ => client.get(&url),
                };

                if let Some(headers) = headers_obj {
                    for (k, v) in &headers {
                        if let Some(vs) = v.as_str() {
                            if let (Ok(hn), Ok(hv)) = (
                                reqwest::header::HeaderName::from_bytes(k.as_bytes()),
                                reqwest::header::HeaderValue::from_str(vs),
                            ) {
                                req = req.header(hn, hv);
                            }
                        }
                    }
                }

                if let Some(body) = body_str {
                    req = req
                        .header(reqwest::header::CONTENT_TYPE, "application/json")
                        .body(body);
                }

                match req.send().await {
                    Ok(resp) => {
                        let status = resp.status().as_u16();
                        let body = resp.text().await.unwrap_or_default();
                        Ok(WidgetApiResult {
                            ok: true,
                            status_code: Some(status),
                            body: Some(body),
                            error: None,
                        })
                    }
                    Err(e) => Ok(reject(&e.to_string())),
                }
            }
        },
    );

    // toolchain.versions — fetch the latest published version for a list of npm
    // packages from the npm registry. Input: { packages: [{id, package}] }.
    // Output: { id: "x.y.z" | null, ... }. Each lookup is independent — a
    // network error for one package yields null for that entry, not a failure.
    // 5-second per-request timeout; all lookups run concurrently.
    engine.register_typed(
        "toolchain.versions",
        |req: ToolchainVersionsReq, _ctx| {
            async move {
                let packages = req.packages;

                let client = reqwest::Client::builder()
                    .timeout(std::time::Duration::from_secs(5))
                    .user_agent("agentmux/toolchain-versions")
                    .build()
                    .map_err(|e| e.to_string())?;

                let futs: Vec<_> = packages.into_iter().map(|pkg| {
                    let c = client.clone();
                    async move {
                        let url = format!("https://registry.npmjs.org/{}/latest", pkg.package);
                        let version = match c.get(&url).send().await {
                            Ok(resp) if resp.status().is_success() => {
                                resp.json::<serde_json::Value>().await.ok()
                                    .and_then(|v| v.get("version").and_then(|s| s.as_str()).map(|s| s.to_string()))
                            }
                            _ => None,
                        };
                        (pkg.id, version)
                    }
                }).collect();

                let results = futures_util::future::join_all(futs).await;
                // A map keyed by the caller's own `id`s, so the response type
                // is the map itself rather than a named struct -- there is no
                // fixed set of fields to name.
                let mut out = std::collections::HashMap::new();
                for (id, version) in results {
                    out.insert(id, version);
                }
                Ok(out)
            }
        },
    );
}

/// Re-export from shared crate for internal use.
/// Build a provider-CLI command with this instance's identity already stripped.
///
/// Sanitizing HERE rather than at each call site is deliberate. This factory has
/// eight callers across srv (agent spawn, ACP, app-server, persistent
/// controller, session probe, auth check, version probe), and none of them
/// contains a literal `Command::new` — so a grep for spawn constructors, which
/// is how the other sites in this codebase were audited, cannot see them. Five
/// review rounds on PR #3326 each found a spawn the previous fix had missed;
/// this one was invisible to the verification command the spec recommends.
/// A factory is the one place a fix cannot be half-applied.
///
/// Pane policy, not strict: most callers launch an agent CLI that legitimately
/// uses the in-pane helpers. Call sites that spawn the CLI as a plain
/// third-party binary (auth checks, version probes) tighten this to
/// `sanitize_external_command` on top, which only removes more.
pub(crate) fn make_cli_cmd(cli_path: &str) -> tokio::process::Command {
    let mut cmd = agentmux_common::make_cli_cmd(cli_path);
    crate::backend::pane_env::sanitize_process_command(&mut cmd);
    cmd
}

/// `pi --list-models` exits 0 either way; it is signed in when it lists
/// models rather than "No models available".
fn pi_lists_models(success: bool, stdout: &str, stderr: &str) -> bool {
    success && !stdout.contains("No models available") && !stderr.contains("No models available")
}

/// Run the provider auth-check CLI against `auth_env` and parse the verdict.
/// Returns `(authenticated, email, auth_method, raw_output)`. Extracted so the
/// stale-credential self-heal can re-run the exact same check after refreshing.
async fn run_auth_check(
    cli_path: &str,
    auth_check_args: &[String],
    auth_env: &std::collections::HashMap<String, String>,
) -> Result<(bool, Option<String>, Option<String>, String), String> {
    // No check command must never read as signed in: a bare CLI with null
    // stdin often just exits 0 (pi-acp does).
    if auth_check_args.is_empty() {
        return Err("this CLI has no sign-in check".to_string());
    }
    // pi-acp has no status command of its own; the pi beside it does:
    // `pi --list-models` prints "No models available" until a provider is
    // set up (SPEC_PI_HARNESS_VIA_PI_ACP_2026_10_06.md).
    let pi = crate::backend::providers::pi_beside_pi_acp(cli_path);
    // pi-acp itself exits 0 on any flag, so without its pi there is nothing
    // that can answer.
    if pi.is_none() && crate::backend::providers::is_pi_acp(cli_path) {
        return Err("pi is not installed beside pi-acp".to_string());
    }
    let program = pi.as_deref().unwrap_or(cli_path);
    let output = tokio::time::timeout(std::time::Duration::from_secs(10), {
        let mut check_cmd = make_cli_cmd(program);
        // An auth check is the provider CLI acting as a plain third-party
        // binary, not as one of our agents — no endpoint, no credential.
        // (ReAgent P0, round 5, on #3326.)
        crate::backend::pane_env::sanitize_external_command(&mut check_cmd);
        check_cmd.args(auth_check_args);
        for (k, v) in auth_env {
            check_cmd.env(k, v);
        }
        // Null stdin: prevents the CLI from blocking on interactive first-run
        // prompts (onboarding, theme selection) that only appear on a TTY.
        check_cmd.stdin(std::process::Stdio::null());
        check_cmd.output()
    })
    .await
    .map_err(|_| "auth check timed out (10s)".to_string())?
    .map_err(|e| format!("failed to run auth check: {e}"))?;

    let stdout = String::from_utf8_lossy(&output.stdout).to_string();
    let stderr = String::from_utf8_lossy(&output.stderr).to_string();

    let mut email = None;
    let mut auth_method = None;
    let authenticated = if let Ok(json) = serde_json::from_str::<serde_json::Value>(&stdout) {
        // Claude outputs `emailAddress`; other CLIs use `email`. Check both.
        email = json
            .get("emailAddress")
            .or_else(|| json.get("email"))
            .and_then(|v| v.as_str())
            .map(|s| s.to_string());
        auth_method = json
            .get("authMethod")
            .and_then(|v| v.as_str())
            .map(|s| s.to_string());
        json.get("loggedIn").and_then(|v| v.as_bool()).unwrap_or(false)
    } else if pi.is_some() {
        pi_lists_models(output.status.success(), &stdout, &stderr)
    } else {
        output.status.success()
    };
    let raw_output = if !stdout.is_empty() { stdout } else { stderr };
    Ok((authenticated, email, auth_method, raw_output))
}

// REMOVED 2026-08-31 (Codex P1 on PR #2878): `claude_access_token`,
// `refresh_claude_dir_from_global_if_stale`, and `refresh_dir_from_global` —
// the machinery behind the auth check's "self-heal from the user's global
// ~/.claude" step, together with its `selfheal_tests` module.
//
// Deleted rather than left unused on purpose: a helper whose entire job is
// copying the operator's personal credential into an isolated dir is exactly
// the thing that gets quietly rewired back in later. There is now nothing to
// call. See `docs/analysis/ANALYSIS_PER_CHANNEL_AUTH_BYPASSES_2026_08_31.md`
// (#5) for the full reasoning.
//
// The real condition it recovered from (the "Pozl 401" — a global re-login
// rotating the access token and invalidating the isolated copy's refresh
// token) now surfaces honestly as a failed validation plus an actionable auth
// card, and is fixed by logging in for THIS channel.

/// A PATH-only provider's CLI: on PATH, else in the folder its own installer
/// uses ([`crate::backend::providers::known_install_paths`]), which may not
/// be on this process's PATH until AgentMux restarts.
///
/// A provider that takes its prompt on the command line
/// (`ProviderConfig::prompt_arg_flag`) must run as the real executable: a
/// `.cmd`/`.bat` wrapper is re-parsed by `cmd.exe`, where `&`, `|` or `%` in
/// a prompt could turn into a command. For those the installer's own
/// executable comes first, and a script wrapper on PATH is never used.
pub(crate) async fn resolve_provider_cli_on_path(provider_id: &str, cli_command: &str) -> Option<String> {
    let known = || {
        crate::backend::providers::known_install_paths(provider_id)
            .into_iter()
            .find(|p| p.is_file())
            .map(|p| p.to_string_lossy().into_owned())
    };
    let prompt_in_argv = crate::backend::providers::get_provider(provider_id)
        .and_then(|p| p.prompt_arg_flag())
        .is_some();
    if prompt_in_argv {
        if let Some(path) = known() {
            return Some(path);
        }
        // Every match, not just the first: a `.cmd` shim ahead of the real
        // executable on PATH must not hide it.
        return resolve_cli_candidates_on_path(cli_command)
            .await
            .into_iter()
            .find(|path| !is_script_wrapper(path));
    }
    if let Some(path) = resolve_cli_on_path(cli_command).await {
        return Some(path);
    }
    known()
}

/// Whether `path` is a Windows batch script (`.cmd`/`.bat`), which runs
/// through `cmd.exe` and re-parses its arguments.
fn is_script_wrapper(path: &str) -> bool {
    let lower = path.to_ascii_lowercase();
    lower.ends_with(".cmd") || lower.ends_with(".bat")
}

/// Resolve a CLI command on the system PATH.
///
/// Uses `where` on Windows and `which` on Unix. Returns the absolute path
/// if the command is found and exists, otherwise `None`.
///
/// On Windows we pass the bare command name (no `.cmd` suffix) so that
/// `where` resolves the correct extension via PATHEXT. This correctly finds
/// `docker.exe`, `git.exe`, `node.exe` AND `npm.cmd` — previously the
/// hard-coded `.cmd` suffix caused all `.exe`-based tools (docker, git,
/// node) to report as not installed even when present on PATH.
///
/// `where` can return multiple lines (e.g. Node.js ships both an extensionless
/// `npm` Unix shell script and `npm.cmd` on Windows). We filter to the first
/// line whose extension `make_cli_cmd` can actually spawn (.exe / .cmd / .bat).
/// Taking the raw first line would yield the extensionless entry, which
/// `Command::new` cannot run on Windows without a shell.
async fn resolve_cli_on_path(cli_command: &str) -> Option<String> {
    resolve_cli_candidates_on_path(cli_command).await.into_iter().next()
}

/// Every spawnable match for `cli_command` on PATH that exists, in PATH order.
async fn resolve_cli_candidates_on_path(cli_command: &str) -> Vec<String> {
    let which_result = if cfg!(windows) {
        let mut probe = tokio::process::Command::new("where");
        probe.arg(cli_command);
        #[cfg(windows)]
        {
            probe.no_window();
        }
        probe.output().await
    } else {
        tokio::process::Command::new("which").arg(cli_command).output().await
    };
    match which_result {
        Ok(out) if out.status.success() => spawnable_candidates(&String::from_utf8_lossy(&out.stdout), cfg!(windows))
            .into_iter()
            .filter(|p| std::path::Path::new(p).exists())
            .collect(),
        _ => Vec::new(),
    }
}

/// The lines of `where`/`which` output a spawn can use. On Windows that is
/// the ones `make_cli_cmd` can run (.exe / .cmd / .bat), skipping e.g. the
/// extensionless `npm` shell script; elsewhere `which` prints one path.
fn spawnable_candidates(stdout: &str, windows: bool) -> Vec<String> {
    let lines = stdout.lines().map(str::trim).filter(|l| !l.is_empty());
    if windows {
        lines
            .filter(|l| {
                let lo = l.to_lowercase();
                lo.ends_with(".exe") || lo.ends_with(".cmd") || lo.ends_with(".bat")
            })
            .map(str::to_string)
            .collect()
    } else {
        lines.take(1).map(str::to_string).collect()
    }
}

/// The CLI notices one `ResolveCli` call can put in its pane
/// (`backend::cli_notice`, SPEC_LAUNCH_CONTEXT_WORKSPACE_RULE_AND_STARTUP_FILES_2026_09_30.md
/// §6.3). A probe with no `block_id` (the picker, the Toolchain pane) puts
/// nothing anywhere.
struct CliNotices {
    broker: std::sync::Arc<crate::backend::mps::Broker>,
    filestore: std::sync::Arc<crate::backend::storage::filestore::FileStore>,
    mstore: std::sync::Arc<crate::backend::storage::store::Store>,
    /// The pane being launched (`notice_block_id`, else `block_id`).
    block_id: String,
    /// The agent being launched, when the caller says; else the pane's
    /// `agentId` meta.
    agent_id: Option<String>,
    provider: String,
}

/// The pane a resolve's notices go to: the launch target when the caller
/// names one (a quick fork resolves from its source pane), else `block_id`.
fn notice_block_id(cmd: &CommandResolveCliData) -> String {
    cmd.notice_block_id
        .as_deref()
        .map(str::trim)
        .filter(|b| !b.is_empty())
        .unwrap_or(&cmd.block_id)
        .to_string()
}

impl CliNotices {
    fn install(
        &self,
        install_id: &str,
        version: &str,
        state: crate::backend::cli_notice::InstallState,
        seconds: Option<f64>,
        error: Option<&str>,
    ) {
        if self.block_id.is_empty() {
            return;
        }
        let frame = crate::backend::cli_notice::install_frame(install_id, &self.provider, version, state, seconds, error);
        crate::backend::cli_notice::append_to_pane(&self.broker, &self.filestore, &self.mstore, &self.block_id, &frame);
    }

    /// Record the version this pane's agent is about to run. Claude reports
    /// the version it actually runs in its own `system/init` frame, which
    /// covers every spawn path (`persistent/stdout_reader.rs`), so it is observed
    /// there and not here.
    fn observe_version(&self, raw_version: &str) {
        if self.block_id.is_empty() || self.provider == "claude" {
            return;
        }
        let Some(version) = crate::backend::cli_notice::version_token(raw_version) else { return };
        let (broker, filestore, mstore) = (self.broker.clone(), self.filestore.clone(), self.mstore.clone());
        let (block_id, provider, agent_id) = (self.block_id.clone(), self.provider.clone(), self.agent_id.clone());
        tokio::task::spawn_blocking(move || {
            crate::backend::cli_notice::observe_and_notify(
                &broker,
                &filestore,
                &mstore,
                &block_id,
                agent_id.as_deref(),
                &provider,
                &version,
            );
        });
    }
}

async fn get_cli_version(cli_path: &str) -> String {
    let result = tokio::time::timeout(
        std::time::Duration::from_secs(5),
        {
            let mut c = make_cli_cmd(cli_path);
            // Version probe — same reasoning as the auth check above.
            crate::backend::pane_env::sanitize_external_command(&mut c);
            c.arg("--version").stdin(std::process::Stdio::null());
            c.output()
        },
    ).await;
    match result {
        Ok(Ok(output)) if output.status.success() => {
            String::from_utf8_lossy(&output.stdout).trim().to_string()
        }
        Ok(_) => "unknown".to_string(),
        Err(_) => {
            tracing::warn!(cli_path = %cli_path, "get_cli_version timed out after 5s");
            "unknown".to_string()
        }
    }
}

/// The wire form of a prune [`crate::backend::cli_prune::Run`].
fn prune_result(
    run: crate::backend::cli_prune::Run,
    dry_run: bool,
    max_idle: std::time::Duration,
) -> ToolchainPruneResult {
    use crate::backend::cli_prune::Candidate;
    let item = |c: &Candidate| ToolchainPruneItem {
        dir: c.dir.to_string_lossy().into_owned(),
        provider: c.provider.clone(),
        version: c.version.clone(),
        legacy: c.legacy,
        bytes: c.bytes,
        idle_days: c.idle.as_secs() / 86_400,
    };
    let removed_dirs: std::collections::HashSet<&std::path::PathBuf> = run
        .report
        .iter()
        .flat_map(|r| r.removed.iter().map(|(d, _)| d))
        .collect();
    ToolchainPruneResult {
        dry_run,
        scan_ok: run.scan_ok,
        candidates: run.plan.prunable.iter().map(item).collect(),
        reclaimable_bytes: run.plan.reclaimable_bytes(),
        removed: run
            .plan
            .prunable
            .iter()
            .filter(|c| removed_dirs.contains(&c.dir))
            .map(item)
            .collect(),
        skipped: run
            .report
            .iter()
            .flat_map(|r| r.skipped.iter())
            .map(|(d, why)| ToolchainPruneSkip { dir: d.to_string_lossy().into_owned(), reason: why.clone() })
            .collect(),
        kept: run.plan.kept.len() as u32,
        max_idle_days: (max_idle.as_secs() / 86_400) as u32,
    }
}

#[cfg(test)]
mod tests {

    /// `where` lists every match; a `.cmd` shim first must not hide the
    /// `.exe` after it, which the prompt-argument branch then picks.
    #[test]
    fn every_spawnable_match_is_kept_in_path_order() {
        let out = [r"C:\Users\u\bin\agy", r"C:\Users\u\bin\agy.cmd", r"D:\tools\agy.exe", ""].join("\r\n");
        assert_eq!(
            super::spawnable_candidates(&out, true),
            vec![r"C:\Users\u\bin\agy.cmd".to_string(), r"D:\tools\agy.exe".to_string()]
        );
        let first_real = super::spawnable_candidates(&out, true)
            .into_iter()
            .find(|p| !super::is_script_wrapper(p));
        assert_eq!(first_real.as_deref(), Some(r"D:\tools\agy.exe"));
        assert_eq!(super::spawnable_candidates("/usr/bin/agy\n", false), vec!["/usr/bin/agy".to_string()]);
    }

    #[test]
    fn pi_is_signed_in_only_when_it_lists_models() {
        let none = "No models available. Use /login to log into a provider via OAuth or API key.";
        assert!(!super::pi_lists_models(true, none, ""));
        assert!(!super::pi_lists_models(true, "", none));
        assert!(!super::pi_lists_models(false, "", ""));
        assert!(super::pi_lists_models(true, "anthropic/claude-sonnet-4-6
", ""));
    }

    #[tokio::test]
    async fn pi_acp_without_its_pi_is_refused_not_read_as_signed_in() {
        let dir = tempfile::tempdir().unwrap();
        let acp = dir.path().join(if cfg!(windows) { "pi-acp.cmd" } else { "pi-acp" });
        std::fs::write(&acp, "").unwrap();
        let args = vec!["--list-models".to_string()];
        let err = super::run_auth_check(&acp.to_string_lossy(), &args, &Default::default()).await.unwrap_err();
        assert!(err.contains("not installed beside pi-acp"), "{err}");
    }

    #[tokio::test]
    async fn an_empty_check_command_is_refused_not_read_as_signed_in() {
        let err = super::run_auth_check("pi-acp", &[], &Default::default()).await.unwrap_err();
        assert!(err.contains("no sign-in check"), "{err}");
    }

    /// A prompt passed through one of these is re-parsed by `cmd.exe`.
    #[test]
    fn batch_scripts_are_script_wrappers_and_executables_are_not() {
        for p in [r"C:\Users\u\bin\agy.cmd", r"C:\x\AGY.CMD", r"C:\x\run.bat"] {
            assert!(super::is_script_wrapper(p), "{p}");
        }
        for p in [r"C:\Users\u\AppData\Local\agy\bin\agy.exe", "/home/u/.local/bin/agy", r"C:\x\cmd\agy.exe"] {
            assert!(!super::is_script_wrapper(p), "{p}");
        }
    }
    use super::*;

    fn resolve_cmd(block_id: &str, notice_block_id: Option<&str>) -> CommandResolveCliData {
        CommandResolveCliData {
            provider_id: "qwen".to_string(),
            cli_command: "qwen".to_string(),
            npm_package: "@qwen-code/qwen-code".to_string(),
            pinned_version: "0.24.0".to_string(),
            windows_install_command: String::new(),
            unix_install_command: String::new(),
            block_id: block_id.to_string(),
            notice_block_id: notice_block_id.map(str::to_string),
            agent_id: None,
        }
    }

    /// CLI notices go to the pane being launched: a quick fork resolves from
    /// its source pane (`block_id`) but names its new pane (Codex on #4128).
    #[test]
    fn cli_notices_go_to_the_launch_target() {
        assert_eq!(notice_block_id(&resolve_cmd("source", Some("fork"))), "fork");
        assert_eq!(notice_block_id(&resolve_cmd("source", None)), "source");
        assert_eq!(notice_block_id(&resolve_cmd("source", Some("  "))), "source");
    }

    /// An unknown provider is refused before anything touches the disk.
    #[tokio::test]
    async fn ensure_provider_auth_dir_rejects_an_unknown_provider() {
        let state = crate::server::tests::test_state();
        let (engine, mut out) = WshRpcEngine::new();
        register_cli_handlers(&engine, &state);
        engine.handle_message(crate::backend::rpc_types::RpcMessage {
            command: COMMAND_ENSURE_PROVIDER_AUTH_DIR.to_string(),
            reqid: "r1".to_string(),
            data: Some(serde_json::json!({ "provider_id": "no-such-provider" })),
            ..Default::default()
        });
        let resp = tokio::time::timeout(std::time::Duration::from_secs(2), out.recv())
            .await
            .unwrap()
            .unwrap();
        assert!(resp.data.is_none(), "{resp:?}");
        assert!(resp.error.contains("unknown provider"), "{resp:?}");
    }

    /// All seven cli/toolchain/widget commands record their request and
    /// response types.
    ///
    /// The two widget commands are the interesting entries. They read their
    /// payload field-by-field off a `serde_json::Value` and turn a bad port or
    /// path into an `ok: false` ANSWER rather than an error, so they cannot
    /// take a struct request. Earlier slices concluded such handlers had to
    /// stay on `register_handler` entirely -- but `Value` deserializes from
    /// anything, so registering it AS the request type is exactly as tolerant
    /// while still recording the response. That is what this asserts.
    #[tokio::test]
    async fn register_typed_records_every_cli_command() {
        let state = crate::server::tests::test_state();
        let (engine, _rx) = WshRpcEngine::new();
        register_cli_handlers(&engine, &state);
        let schema = engine.schema_json();
        let rows = schema.as_array().unwrap();
        let find = |cmd: &str| {
            rows.iter()
                .find(|r| r["command"] == cmd)
                .unwrap_or_else(|| panic!("{cmd} missing from the schema"))
        };

        for (cmd, req, resp) in [
            (COMMAND_RESOLVE_CLI, "CommandResolveCliData", "ResolveCliResult"),
            (COMMAND_CHECK_CLI_AUTH, "CommandCheckCliAuthData", "CheckCliAuthResult"),
            ("runclilogin", "CommandRunCliLoginData", "RunCliLoginResult"),
            (COMMAND_ENSURE_PROVIDER_AUTH_DIR, "EnsureProviderAuthDirReq", "EnsureProviderAuthDirResult"),
            ("toolchain.versions", "ToolchainVersionsReq", "HashMap<alloc::string::String, core::option::Option<alloc::string::String>>"),
        ] {
            let row = find(cmd);
            assert_eq!(row["requestName"], req, "{cmd} request");
            assert!(
                row["responseName"].as_str().unwrap().contains(resp.split('<').next().unwrap()),
                "{cmd} response should mention {resp}, got {:?}",
                row["responseName"],
            );
        }

        // The widget pair: `Value` request, named response.
        for cmd in ["widget.health", "widget.api"] {
            let row = find(cmd);
            assert_eq!(
                row["requestName"], "Value",
                "{cmd} keeps a Value request so a bad port stays an answer, not an error",
            );
        }
        assert_eq!(find("widget.health")["responseName"], "WidgetHealthResult");
        assert_eq!(find("widget.api")["responseName"], "WidgetApiResult");

        // `toolchain.env` takes no argument, so `Option<_>` of an empty struct.
        let env = find("toolchain.env");
        let env_req = env["requestName"].as_str().unwrap();
        assert!(
            env_req.starts_with("core::option::Option<") && env_req.contains("ToolchainEnvReq"),
            "toolchain.env should take Option<ToolchainEnvReq>, got {env_req:?}",
        );
        assert_eq!(env["responseName"], "ToolchainEnvResult");
    }

    /// A `Value` request really does accept everything, which is the whole
    /// reason it is safe to use here. If this ever stops holding, the two
    /// widget commands silently start rejecting payloads they used to answer.
    #[test]
    fn a_value_request_deserializes_from_any_payload() {
        for payload in [
            serde_json::json!({ "port": 3000 }),
            serde_json::json!({ "port": "not a number" }),
            serde_json::json!({}),
            serde_json::json!([1, 2, 3]),
            serde_json::Value::Null,
        ] {
            serde_json::from_value::<serde_json::Value>(payload.clone())
                .unwrap_or_else(|e| panic!("{payload} should deserialize as Value, got {e}"));
        }
    }

    /// `toolchain.env`'s `pathSource` is camelCase on the wire while every
    /// other field in that response is lowercase, so it needs BOTH
    /// `serde(rename)` and `ts(rename)` -- ts-rs does not read the serde one.
    /// Without the second the generated key is `path_source`, which nothing
    /// sends and nothing reads, and every gate still passes.
    #[test]
    fn toolchain_env_reports_path_source_as_camel_case() {
        let v = serde_json::to_value(ToolchainEnvResult {
            path: "/usr/bin".to_string(),
            path_source: "inherited".to_string(),
            os: "linux".to_string(),
            arch: "x86_64".to_string(),
        })
        .unwrap();
        assert_eq!(v["pathSource"], "inherited");
        assert!(v.get("path_source").is_none(), "the Rust field name must not reach the wire: {v}");

        // Match the DECLARATION, not any mention: the doc comment on this
        // field names `path_source` on purpose (explaining why the rename
        // exists), and a bare substring check matched that instead of the
        // field and failed on a correct binding.
        let ts = <ToolchainEnvResult as ts_rs::TS>::inline(&ts_rs::Config::from_env());
        assert!(ts.contains("pathSource: string"), "generated TS lost the rename: {ts}");
        assert!(
            !ts.contains("path_source: string"),
            "generated TS kept the Rust name as a field: {ts}",
        );
    }
}