trusty-mpm 1.8.2

//! `tm` / `trusty-mpm` — unified MPM CLI entry point.
//!
//! Why: this file is intentionally thin. All logic is in the submodules below;
//! `main` only parses arguments, sets up tracing for long-running modes, and
//! dispatches to the appropriate handler function.
//! What: module declarations, lazy HELP initializer, `main()` with clap
//! dispatch.
//! Test: `cargo test -p trusty-mpm` runs the full suite in `tests.rs`.

// docs.rs builds a release's documentation once, from the uploaded tarball,
// so a broken intra-doc link is baked into that version forever and only a new
// release can correct it. Deny keeps this crate at zero rather than letting the
// ratchet in `scripts/check_rustdoc_links.sh` absorb a new one.
#![deny(rustdoc::broken_intra_doc_links)]

mod cli;
mod cli_manager;
mod commands;
mod formatters;
mod generate;
mod gh_identity;
mod tracing_setup;
mod types;
mod watch_dispatch;

use std::io::IsTerminal as _;

use clap::Parser;
use cli::{Cli, Command};
use commands::{
    agent::agent,
    compress::run_compress,
    daemon::{restart, run_daemon, start, stop_daemon},
    generate::generate,
    hooks::clean as hooks_clean,
    install::install,
    launch::{connect, launch},
    managed_workspace::LaunchDir,
    manager::manager,
    memory::memory,
    misc::{attach_cmd, coordinator, hook, optimizer, overseer, validate},
    project::project,
    projects::projects,
    services::services,
    slack::slack,
    telegram::telegram,
};
use trusty_mpm::client::DaemonClient;

#[cfg(test)]
#[path = "test_support.rs"]
mod test_support;

#[cfg(test)]
#[path = "tests.rs"]
mod tests;

#[cfg(test)]
#[path = "tests_behavior_a_tests.rs"]
mod tests_behavior_a;

// #9340: the `tm memory import*` parse tests, split so `tests.rs` stays capped.
#[cfg(test)]
#[path = "memory_import_cli_tests.rs"]
mod memory_import_cli_tests;

// #6887: the divert CLI pair, split out so `tests_behavior_a_tests.rs` stays capped.
#[cfg(test)]
#[path = "divert_cli_tests.rs"]
mod divert_cli_tests;

#[cfg(test)]
#[path = "install_policy_tests.rs"]
mod install_policy_tests;

// #6441: parse-layer coverage for the bare `tm <github-url>` form. Its own
// file rather than `tests.rs` because the `infer_subcommands` /
// `external_subcommand` precedence it pins is one cohesive claim.
#[cfg(test)]
#[path = "tests_behavior_bare_run_tests.rs"]
mod tests_behavior_bare_run;

#[cfg(test)]
#[path = "tests_behavior_b_tests.rs"]
mod tests_behavior_b;

#[cfg(test)]
#[path = "tests_behavior_c_tests.rs"]
mod tests_behavior_c;

#[cfg(test)]
#[path = "tests_behavior_d_tests.rs"]
mod tests_behavior_d;

// #7224: the `tm ls` connector's parse + picker/TUI gate tests, split out
// when `tests_behavior_d_tests.rs` crossed the 3000-SLOC test cap.
#[cfg(test)]
#[path = "tests_behavior_d_ls_connector_tests.rs"]
mod tests_behavior_d_ls_connector;

// #7224: the errored-session stop-then-delete route, split out for the same
// reason — `tests_behavior_d_tests.rs` has no room left under the test cap.
#[cfg(test)]
#[path = "tests_behavior_d_stop_delete_tests.rs"]
mod tests_behavior_d_stop_delete;

// #9097: the `tm f` CLI parse tests, split out when `tests_behavior_d_tests.rs`
// crossed the 3000-SLOC test cap again.
#[cfg(test)]
#[path = "tests_behavior_d_f_cli_tests.rs"]
mod tests_behavior_d_f_cli;

// #9313: `tm sessions rebind` parse tests; `tests_behavior_d_tests.rs` is full.
#[cfg(test)]
#[path = "tests_behavior_rebind_tests.rs"]
mod tests_behavior_rebind;

#[cfg(test)]
#[path = "tests_behavior_e_tests.rs"]
mod tests_behavior_e;

#[cfg(test)]
#[path = "tests_behavior_generate_tests.rs"]
mod tests_behavior_generate;

#[cfg(test)]
#[path = "tests_behavior_hooks_tests.rs"]
mod tests_behavior_hooks;

#[cfg(test)]
#[path = "tests_behavior_repair_tests.rs"]
mod tests_behavior_repair;

#[cfg(test)]
#[path = "tests_behavior_reset_agents_tests.rs"]
mod tests_behavior_reset_agents;

#[cfg(test)]
#[path = "tests_behavior_skill_tiers_tests.rs"]
mod tests_behavior_skill_tiers;

// #7102: `install_then_deploy_deploys_skills`, split out so
// `tests_behavior_a_tests.rs` stays under the 500-SLOC cap.
#[cfg(test)]
#[path = "tests_behavior_install_skills_tests.rs"]
mod tests_behavior_install_skills;

#[cfg(test)]
#[path = "tests_behavior_2890_skills_tests.rs"]
mod tests_behavior_2890_skills;

#[cfg(test)]
#[path = "tests_behavior_2903_skills_tests.rs"]
mod tests_behavior_2903_skills;

#[cfg(test)]
#[path = "tests_behavior_2911_documentation_style_tests.rs"]
mod tests_behavior_2911_documentation_style;

#[cfg(test)]
#[path = "tests_behavior_rust_build_performance_tests.rs"]
mod tests_behavior_rust_build_performance;

#[cfg(test)]
#[path = "tests_projects.rs"]
mod tests_projects;

#[cfg(test)]
#[path = "tests_projects_config_tests.rs"]
mod tests_projects_config_tests;

#[cfg(test)]
#[path = "tests_manager.rs"]
mod tests_manager;

#[cfg(test)]
#[path = "tests_project_trust_tests.rs"]
mod tests_project_trust;

// #5544: the mechanical guard that keeps `$HOME` writers out of this target.
#[cfg(test)]
#[path = "env_isolation_tests.rs"]
mod env_isolation_tests;

/// Lazy-loaded help configuration for "did you mean?" suggestions (issue #216).
///
/// Why: the YAML help bundle is checked in as a string literal; loading it
/// lazily avoids any parse work on the (common) fast path where every argument
/// is valid.
/// What: parses `help.yaml` once on first access via `std::sync::LazyLock`.
/// Test: the suggestion path is exercised indirectly by the clap parse tests.
static HELP: std::sync::LazyLock<trusty_common::help::HelpConfig> =
    std::sync::LazyLock::new(|| {
        trusty_common::help::load_help(include_str!("../../../help.yaml"))
            .expect("trusty-mpm help.yaml is bundled and valid")
    });

/// Binary entry point.
///
/// Why: separation of concerns — `main` owns the lifecycle (arg parsing,
/// tracing init, exit codes) while the handlers own the domain logic.
/// What: tries to parse via `clap::Parser::try_parse`, prints a "did you
/// mean?" hint on an unknown-subcommand error, then dispatches.
///
/// #2118: a bare `tm projects` (no verb) on an interactive terminal is
/// intercepted HERE, before `Cli::try_parse()` even runs, and launches the
/// 4-pane project-control-plane TUI skeleton. The interception happens this
/// early — rather than by relaxing `ProjectsAction` to `Option` and branching
/// inside the dispatcher — specifically so `tm projects <verb>` and a
/// non-interactive bare `tm projects` both flow through the completely
/// unmodified clap definition: the latter must keep failing with a clap usage
/// error (exit code 2), unchanged from the pre-#2118 behavior. (The EXACT
/// clap `ErrorKind` — and therefore the exact rendered wording — for that
/// bare-invocation usage error is not itself a stable cross-environment
/// property of this unmodified definition; see `tests_projects::
/// cli_rejects_bare_projects_with_a_usage_error`'s doc for the evidence. The
/// invariant this interception actually depends on, and the one that IS
/// stable, is the non-zero exit code.) "Interactive" requires BOTH stdin and
/// stdout to be real terminals (`commands::projects::should_launch_bare_tui`)
/// — stdout alone is not enough: a supervisor/wrapper that redirects stdin
/// from `/dev/null` while leaving stdout attached to a pty would otherwise
/// launch a raw-mode TUI with no keyboard path able to exit it. See
/// `commands::projects::should_launch_bare_tui` and
/// `commands::projects::launch_bare_tui`.
/// Test: integration tests in `tests.rs` exercise every dispatch branch; the
/// #2118 interception gate is unit tested in `commands::projects::tests`.
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // #7889: the pm-guard hook's decision deadline is measured from here.
    let started = std::time::Instant::now();
    // Why: parse via `try_parse` so we can attach the workspace-shared
    // "did you mean?" suggestion (issue #216) before exiting on a clap error.
    let argv: Vec<String> = std::env::args().collect();

    // #2118: see this function's module doc for why this runs before parsing.
    // Requires BOTH stdin and stdout to be real terminals — stdout alone is
    // not a safe interactivity signal (see the module doc).
    if commands::projects::should_launch_bare_tui(
        &argv,
        std::io::stdin().is_terminal(),
        std::io::stdout().is_terminal(),
    ) {
        return commands::projects::launch_bare_tui().await;
    }

    let cli = match Cli::try_parse() {
        Ok(cli) => cli,
        Err(e) => {
            e.print().ok();
            if matches!(
                e.kind(),
                clap::error::ErrorKind::InvalidSubcommand | clap::error::ErrorKind::UnknownArgument
            ) {
                trusty_common::help::print_suggestion_hint(&argv, &HELP);
            }
            std::process::exit(e.exit_code());
        }
    };

    // #2405 (LOW fix from PR #2528 review): the universal `config` credential
    // CLI is a lightweight, daemon-less command. Dispatch it BEFORE any
    // daemon-URL resolution (#2517's bounded client + gateway-first
    // `resolve_daemon_url_via_gateway` probe below) so `tm config keys …`
    // never pays a loopback daemon probe or the tracing/migration setup that
    // follows. Mirrors the tagent/tga early config short-circuit (#2405).
    if let Some(Command::Config(cmd)) = cli.command {
        return cmd.run().await;
    }
    // #8261: `tm build-lease` wraps every heavy build the hook rewrites, so it
    // runs before any tracing, migration or gateway probe — its latency is paid
    // by every build on the machine.
    if let Some(Command::BuildLease(args)) = cli.command {
        commands::build_lease::run(args).await
    }
    // #8436: `tm fleet` is daemon-less — no gateway probe, no migration.
    if let Some(Command::Fleet { action }) = cli.command {
        return commands::fleet::run(action).await;
    }
    // #8939: `tm env` is daemon-less too, and prints no value.
    if let Some(Command::Env { action }) = cli.command {
        return commands::env_file::run(action);
    }
    // #7521: `tm secrets` talks to the trusty-secrets socket, not the daemon.
    // #8378 PR-C: `tm content` is daemon-less as well.
    match cli.command {
        Some(Command::Secrets { action }) => return commands::secrets::run(action).await,
        Some(Command::Content { action }) => return commands::content::run(action).await,
        // #8994: `tm worktrees` reads and appends the worktree ledger only.
        Some(Command::Worktrees(args)) => return commands::worktrees::run(args).await,
        _ => {}
    }

    // #2997: the internal disclaim-exec shim is the lightweight leaf a managed
    // tmux pane routes `claude` through so it is spawned with macOS TCC
    // responsibility disclaimed. It must run BEFORE any daemon-URL resolution,
    // tracing/migration setup, or client construction below — it is a bare
    // `posix_spawn` + wait that exits with the child's code and never talks to
    // the daemon. (Emitted into the pane command by
    // `trusty_mpm::core::spawn_disclaim::disclaim_pane_command`.)
    if let Some(Command::InternalSpawnDisclaimed {
        launch_spec,
        argv: spawn_argv,
    }) = cli.command
    {
        // #4398 HIGH (critic review on PR #4431): `infer_subcommands` makes
        // clap resolve ANY unambiguous prefix of "internal-spawn-disclaimed"
        // to this hidden variant — see `commands::spawn_disclaimed::
        // invoked_literally`'s doc for the full rationale. Reject anything
        // that didn't arrive via the exact, full spelling before ever
        // reaching the disclaimed-spawn leaf.
        if !commands::spawn_disclaimed::invoked_literally(&argv) {
            eprintln!(
                "error: '{}' must be invoked by its exact name, not an abbreviation",
                trusty_mpm::core::spawn_disclaim::PANE_DISCLAIM_SUBCOMMAND
            );
            std::process::exit(2);
        }
        // #8233: the managed form. A spec that cannot be used must be LOUD in
        // the pane and must not launch anything — the pane is the only place an
        // operator will look, and the daemon's post-send check turns the absent
        // runtime into an errored record.
        if let Some(path) = launch_spec {
            if let Err(e) = commands::spawn_disclaimed::run_launch_spec(&path) {
                eprintln!("tm: {e:#}");
                std::process::exit(1);
            }
            return Ok(());
        }
        return commands::spawn_disclaimed::run(spawn_argv);
    }

    // Long-running daemon mode: init file-rotating tracing + bug-capture layer
    // (identical to the former trusty-mpmd binary). Short-lived CLI invocations
    // skip subscriber init entirely — they have no meaningful log volume and
    // there is no global registry yet to conflict with.
    //
    // Both guards must live for the full duration of `main`:
    //   - `_daemon_log_guard`: the non-blocking writer's WorkerGuard; dropping
    //     it flushes and joins the background I/O thread — early drop silently
    //     discards buffered log records.
    //   - `_error_store`: the ErrorStore handle returned by `bug_capture_layer`.
    //     The capture ring is Arc-backed but the *write* end is held by the
    //     tracing layer, while the *read* end lives in `_error_store`. Dropping
    //     `_error_store` before `main` returns means any consumer (MCP preview,
    //     HTTP endpoint, future DaemonState slot) that tries to read the ring
    //     after the store is gone will get an empty result. Phase 2 (#478) will
    //     move `_error_store` into `DaemonState`; until then it must be kept
    //     alive at main-scope.
    //
    // Both are declared unconditionally (as Option) so the borrow checker is
    // satisfied regardless of which cfg branch runs.
    #[cfg(feature = "daemon")]
    let mut _daemon_log_guard: Option<tracing_appender::non_blocking::WorkerGuard> = None;
    // Why: `_error_store` carries the read half of the bug-capture ring buffer.
    // Binding it here (not inside the inner block below) keeps it alive until
    // `main` returns, matching the original trusty-mpmd binary's lifetime.
    // What: holds the `ErrorStore` returned by `bug_capture_layer`; the write
    // half lives inside the tracing layer registered with the global subscriber.
    // Test: dropping this before `run_daemon` completes would cause the capture
    // ring to appear empty on any subsequent read; the daemon integration tests
    // exercise the full tracing→capture→preview path via HTTP.
    #[cfg(feature = "daemon")]
    let mut _error_store: Option<trusty_common::error_capture::ErrorStore> = None;

    // #4573: `tm sessions instructions` is where an operator asks "why didn't my
    // CLAUDE.md override apply?", and every line of the code written to answer
    // that is `tracing` — which went nowhere, because only the daemon/supervisor
    // branch below ever registered a subscriber. See `tracing_setup` for the full
    // rationale and for why the writer is explicitly stderr.
    tracing_setup::init_cli_diagnostics_if_wanted(&cli.command);

    // Long-running modes (daemon, supervisor) get the full file-rotating tracing
    // + bug-capture layer; short-lived CLI invocations skip subscriber init.
    if matches!(
        cli.command,
        Some(Command::Daemon { .. }) | Some(Command::Supervisor { .. })
    ) {
        #[cfg(feature = "daemon")]
        {
            // #6569: the rotated file sink plus, under launchd, NO stderr layer
            // — launchd's own StandardErrorPath capture was writing every line
            // a second time to a file nothing rotates. `tracing_setup` owns the
            // whole composition and the sink decision behind it.
            let (guard, store) = tracing_setup::init_daemon_tracing()?;
            // Both handles must outlive this block: the guard flushes the
            // non-blocking appender, and the store is the read half of the
            // capture ring (see the comments on their declarations above).
            _daemon_log_guard = Some(guard);
            _error_store = Some(store);
        }
        // #4573: shares `tracing_setup`'s stderr-only builder with the CLI
        // inspection path — the two were byte-for-byte the same builder.
        #[cfg(not(feature = "daemon"))]
        tracing_setup::init_stderr_only("info");
    }

    // #1905: one-time migration removing stale pre-rename `mpm-*` skill
    // directories left over from the mpm-*→tm-* skill rename. Gated on a
    // marker file (`~/.trusty-mpm/migrations.json`) so it does real work at
    // most once per machine, then becomes a single cheap file read on every
    // later `tm` invocation — this is deliberately NOT a permanent
    // `tm doctor` check (see `core::doctor::run_doctor`'s doc comment).
    {
        let paths = trusty_mpm::core::paths::FrameworkPaths::default();
        trusty_mpm::core::stale_skills::run_stale_mpm_skills_migration_once(
            &paths.root,
            &paths.claude_skills_dir(),
        );
    }

    // #6288 step 1: the sandbox-reached commands run over the daemon's unix
    // socket only, so they never reach the TCP gateway probe below.
    if commands::socket_dispatch::takes(&cli.command) {
        return commands::socket_dispatch::run(cli).await;
    }

    // #2517: the top-level CLI client must carry the same bounded
    // connect/request timeouts `DaemonClient` uses (issue #2471/#2512) — a
    // bare `reqwest::Client::new()` here has NO timeout, so `tm status`
    // against a daemon that accepts the TCP connection but never answers
    // hung for the OS-level socket timeout (observed 55.63s live-verify)
    // instead of the intended ~10s bound. `daemon_healthy` (used by `tm
    // status`/`tm start`) and the gateway probe below both send through
    // this SAME client, so both are now bounded too.
    let client = trusty_mpm::client::http_client::default_client();
    // Resolve the daemon URL once with gateway-first probing:
    //   1. Explicit --url/TRUSTY_MPM_URL, whenever it was actually supplied
    //      (`cli.url` is `Option<String>` — see its doc, #2487) → use it
    //      directly, bypassing the gateway entirely. There is no comparison
    //      against DEFAULT_DAEMON_URL: `Some` here always means the operator
    //      made a real choice, even one that happens to equal the default URL
    //      verbatim. Before #2487 `cli.url` was a plain `String` with
    //      `default_value = DEFAULT_URL`, so an explicit
    //      `TRUSTY_MPM_URL=http://127.0.0.1:7880` was indistinguishable from
    //      "nothing was set" and fell through to the gateway probe below —
    //      silently rerouting every `tm` subcommand (including `tm projects
    //      config … set`) through the trusty-console proxy on port 7788
    //      instead of the daemon on 7880.
    //   2. trusty-console gateway (`http://{console}/api/mpm`) if the console is
    //      running and the daemon is reachable through it (#1849 Phase 2).
    //   3. Lock file (daemon may bind to an ephemeral port) → default.
    // The gateway path routes all `tm` traffic through the unified web UI while
    // preserving full direct-fallback behaviour when the console is absent.
    // Stale TRUSTY_MPM_URL values (#1731) are still probed before falling back.
    //
    // #1737 note: this top-level resolution is deliberately NOT gated on
    // explicit-URL reachability, even though an explicit override never falls
    // back here (step (a) of the gateway resolver returns it verbatim — see
    // that function's doc). `tm hook` has an intentional FAIL-OPEN contract
    // that must survive an unreachable `--url`/`TRUSTY_MPM_URL` — a Claude
    // Code hook must never fail the user's turn because the best-effort
    // daemon POST could not connect (see `tests/tm_hook_idle_parking.rs`,
    // which asserts exit 0 even for `--url http://127.0.0.1:1`); a blanket
    // probe-and-abort here would regress it. A command that instead wants
    // "explicit URL must be reachable, error otherwise" semantics calls
    // [`trusty_mpm::core::resolve_daemon_url_for_cli`] itself, on top of this
    // shared resolution, before running any of its own fallback-prone logic —
    // `commands::guided::run_guided_default` (the bare `tm` dispatch target
    // below) does exactly that: it was the one LIVE instance of the #1737
    // silent-fallback bug (its daemon-autostart step ignores whichever URL it
    // is handed and always re-resolves implicitly), so it now probes
    // `explicit` up front and errors — translated to exit 75 below — instead
    // of silently auto-starting/reconnecting to a different daemon.
    let url = trusty_mpm::core::resolve_daemon_url_via_gateway(&client, cli.url.as_deref()).await;
    // #7166: captured before `cli.command` is moved into the match below —
    // `--account` is a `global = true` flag (see `cli::Cli::account`'s doc),
    // so it binds regardless of where in the invocation it appeared.
    let account = cli.account.clone();
    // #8914: a token for `--account` is read from stdin once, before dispatch.
    let account_token = if cli.account_token_stdin {
        Some(commands::session_account::read_stdin_token(
            std::io::stdin().lock(),
        )?)
    } else {
        None
    };
    let token = account_token.as_deref();
    // Why: handlers return `anyhow::Result`; we capture the dispatch result here
    // so the top-level boundary can translate the typed `PruneError::SmUnavailable`
    // (issue #1313) into the documented exit code 75. Doing the `process::exit`
    // here — rather than inside the async `prune_idle` — guarantees no live async
    // resource (the reqwest client, JoinSet tasks) is skipped over by exiting.
    let explicit_url = cli.url.as_deref();
    let result = match cli.command {
        None => commands::guided::run_guided_default(&client, &url, explicit_url).await,
        // #6288 step 1: dispatched over the socket before URL resolution.
        Some(
            Command::Status
            | Command::Health
            | Command::Doctor { .. }
            | Command::Ticket { .. }
            | Command::Pr { .. },
        ) => unreachable!("socket commands are dispatched before daemon-URL resolution"),
        Some(Command::Start) => start(&client, &url).await,
        Some(Command::Serve { stdio }) => {
            if stdio {
                // #1221: MCP stdio bridge — forward JSON-RPC to the daemon's
                // loopback POST /rpc, auto-starting the daemon and reconnecting
                // with backoff. This is the `.mcp.json` entry point.
                commands::serve_stdio::run_stdio_bridge().await
            } else {
                start(&client, &url).await
            }
        }
        Some(Command::Stop) => stop_daemon().await,
        Some(Command::Restart) => restart(&client, &url).await,
        Some(Command::Project { action }) => project(&client, &url, action).await,
        // #2116: `sessions` (plural) is the canonical top-level command.
        // #8914: the global `--account` is applied, never dropped.
        // #6288: only `tui` and `disk` still arrive here (step 2).
        Some(Command::Sessions { action }) => {
            let account = account.as_deref();
            let daemon = DaemonClient::with_client(client.clone(), url.clone());
            commands::session_account::session_as_account(&daemon, action, account, token).await
        }
        Some(Command::Projects { action }) => projects(&client, &url, action).await,
        Some(Command::Manager { action }) => manager(&client, &url, action).await,
        // #2116: `session` (singular) is a hidden deprecated alias of `sessions`.
        // The notice fires here — exactly once per invocation, regardless of
        // which verb was invoked — before dispatching to the identical handler.
        Some(Command::Session { action }) => {
            commands::session::emit_top_level_alias_notice();
            let account = account.as_deref();
            let daemon = DaemonClient::with_client(client.clone(), url.clone());
            commands::session_account::session_as_account(&daemon, action, account, token).await
        }
        Some(Command::Events) => commands::misc::events(&client, &url).await,
        Some(Command::Validate { path, repair }) => validate(path, repair).await,
        Some(Command::Hooks { action }) => {
            use cli::HooksAction;
            match action {
                HooksAction::Clean { path, force } => hooks_clean(path, force),
            }
        }
        Some(Command::Agent { action }) => agent(action).await,
        Some(Command::Generate { action }) => generate(action).await,
        Some(Command::Tui {
            url: tui_url,
            interval_ms,
            single_pane,
        }) => {
            // #9556: an explicit `--url` is pinned; #6483: multipane by default.
            let client = trusty_mpm::tui::client_for(tui_url.as_deref());
            trusty_mpm::tui::run_initial_view_with(client, interval_ms, None, single_pane).await
        }
        Some(Command::Telegram { cmd }) => telegram(&url, cmd).await,
        Some(Command::Slack { cmd }) => slack(cmd).await,
        Some(Command::Install {
            force,
            reset_agents,
            reset_agents_workspaces,
            reconcile_skills,
        }) => {
            install(
                force,
                reset_agents,
                reset_agents_workspaces,
                reconcile_skills,
            )
            .await
        }
        Some(Command::Reinstall(args)) => commands::reinstall::run(args).await,
        Some(Command::Hook {
            pm_guard,
            divert_check,
            prompt_feedback,
        }) => {
            if pm_guard {
                commands::pm_guard::pm_guard(&url, started).await
            // #6887: a separate hook mode, not a pm-guard variant.
            } else if divert_check {
                commands::divert_check::divert_check().await
            // #7688: likewise — the capture never relays to the daemon.
            } else if prompt_feedback {
                commands::prompt_feedback_hook::prompt_feedback_hook().await
            } else {
                hook(&client, &url).await
            }
        }
        // #7688: the read-back for what the capture above collected.
        Some(Command::PromptFeedback(args)) => commands::prompt_feedback_cli::run(args).await,
        // #6887: the cheap worker `--divert-check` steers the agent to.
        Some(Command::Divert { action }) => commands::divert::run(action).await,
        Some(Command::Memory { action }) => memory(action).await,
        Some(Command::Compress { tool }) => run_compress(&tool).await,
        // #5843: `tm wait` owns its own exit codes (0/75/1/2), so it never
        // returns here — the `!` it yields coerces into this match's type.
        Some(Command::Wait(args)) => commands::wait::run(args),
        // #8261: normally dispatched before daemon resolution above; kept so
        // the match stays exhaustive without a panic arm.
        Some(Command::BuildLease(args)) => commands::build_lease::run(args).await,
        Some(Command::Daemon {
            addr,
            tailscale,
            mcp,
            force,
            sandbox,
        }) => run_daemon(addr, tailscale, mcp, force, sandbox).await,
        Some(Command::Supervisor {
            interval,
            auto_resume,
            no_classify,
        }) => commands::supervisor::run_supervisor(interval, auto_resume, no_classify).await,
        Some(Command::Launch {
            dir,
            style,
            worktree,
            twin,
            // `--dir` (or the process cwd) is the operator's, not a resolved
            // placement: ADR-0037's rule applies here and only here (#5836).
        }) => {
            // #8914: `tm launch --account X` pins X on the checkout first.
            if let Some(login) = account.as_deref() {
                let target = commands::project::resolve_dir(dir.clone())?;
                let daemon = DaemonClient::with_client(client.clone(), url.clone());
                commands::session_account::pin_account_for_dir(&daemon, &target, login, token)
                    .await?;
            }
            let home = dirs::home_dir();
            launch(
                &client,
                &url,
                dir,
                style,
                worktree,
                LaunchDir::OperatorCwd,
                home.as_deref(),
                twin, // #8878: only an operator's `tm launch --twin` arms.
            )
            .await
        }
        Some(Command::Connect { dir }) => {
            connect(&client, &url, dir, dirs::home_dir().as_deref()).await
        }
        Some(Command::Attach {
            target,
            json,
            single_pane,
        }) => attach_cmd(&client, &url, &target, json, single_pane, explicit_url).await,
        Some(Command::Optimizer { action }) => optimizer(&client, &url, action).await,
        Some(Command::Overseer { action }) => overseer(&client, &url, action).await,
        // #8436: dispatched before daemon resolution above; kept exhaustive.
        Some(Command::Fleet { action }) => commands::fleet::run(action).await,
        Some(Command::Env { action }) => commands::env_file::run(action),
        Some(Command::Secrets { action }) => commands::secrets::run(action).await,
        Some(Command::Content { action }) => commands::content::run(action).await,
        Some(Command::Worktrees(args)) => commands::worktrees::run(args).await, // #8994
        Some(Command::Coordinator { message, action }) => {
            // DOC-14 SM-STDIO (#1291): `tm sm serve --stdio` runs the JSON-RPC
            // over STDIO adapter; a plain `tm sm <message>` chats as before.
            match action {
                Some(action) => commands::sm_serve::run_sm_serve(action).await,
                None => match message {
                    Some(message) => coordinator(&url, message).await,
                    None => Err(anyhow::anyhow!(
                        "provide a message (`tm sm <message>`) or a subcommand \
                         (`tm sm serve --stdio`)"
                    )),
                },
            }
        }
        Some(Command::Services { action }) => services(action),
        Some(Command::Repair { action }) => commands::repair::dispatch(&client, &url, action).await,
        Some(Command::Auth { action }) => commands::auth::dispatch(action),
        Some(Command::Catalog { action }) => commands::managed::catalog(action).await,
        Some(Command::Issue { cmd, system }) => commands::issue::issue(cmd, system),
        Some(Command::Watch { cmd }) => watch_dispatch::dispatch_watch(&client, &url, cmd).await,
        // #1045: the metaharness boots standalone (no daemon, no HTTP client).
        // The handler is async because `meta run` (#1049/#1051) launches a real
        // `claude` tmux session and `--demo` polls for it to exit. A demo
        // verification failure/timeout returns `Err`, which `main` maps to a
        // non-zero process exit (the #1051 acceptance criterion).
        Some(Command::Meta { action }) => commands::meta::meta(action).await,

        // DOC-24: standalone managed driver commands.
        // Each command resolves ManagedPaths once at entry (closes #1566):
        // --root flag > TRUSTY_MPM_ROOT env > XDG config file > default.
        // #4912: positionals are `<url> [alias]`, with the legacy `<alias> <url>`
        // order still accepted — the handler detects which one is the URL.
        Some(Command::Register {
            url: repo_spec,
            alias,
            force,
            root,
        }) => {
            let paths = commands::managed_root::resolve_managed_paths(root.as_deref())?;
            commands::standalone::register_cmd(&paths, &repo_spec, alias.as_deref(), force)?;
            // #7166: `tm register` accepts the same `--account`/embedded
            // `<login>@owner/repo` selector `tm run` does. The DOC-24
            // standalone registry this command writes to (`registry.json`)
            // has no account concept, so the selection — when present — is
            // ALSO persisted onto the daemon's registry-B project record
            // (the same idempotent upsert `run_managed`/`tm projects
            // register --gh-account` use), which is what
            // `resolve_gh_account_env_for_registry` actually reads at
            // spawn/relaunch time. Best-effort: the standalone registration
            // above already succeeded, so a daemon-registry hiccup here is
            // reported but never fails an otherwise-successful `tm register`.
            let resolved_account = commands::register_args::resolve_account(
                account.as_deref(),
                commands::register_args::embedded_account(&repo_spec),
            )?;
            if let Some(resolved_account) = resolved_account {
                let repo_url = commands::register_args::resolved_url(&repo_spec)?;
                let name = trusty_mpm::project::derive_name_from_url(&repo_url)
                    .or_else(|| alias.clone())
                    .unwrap_or_else(|| repo_url.clone());
                // #7166 review follow-up CRITICAL/HIGH: shared with
                // `run_managed`'s post-clone step — see that call site's doc.
                commands::projects::registry::auto_persist_account_selection(
                    &client,
                    &url,
                    name,
                    repo_url,
                    &resolved_account,
                    "registered",
                )
                .await;
            }
            Ok(())
        }
        Some(Command::Ls {
            terms,
            projects,
            json,
            source_id,
            current,
            all,
            attached,
            no_prune,
            plain,
            root,
        }) => {
            if projects {
                // #2311: `--projects`/`-p` preserves the DOC-24 alias/project list.
                // `terms` (the sort/filter grammar) is session-mode only; ignored here.
                let paths = commands::managed_root::resolve_managed_paths(root.as_deref())?;
                commands::standalone::ls_cmd(&paths, json)
            } else {
                // #2311: bare `tm ls` is the interactive managed-session connector
                // (TTY-aware; static + pipeable when non-TTY / --json / --all / 0).
                let (sort, term) = commands::session_picker::parse_ls_terms(&terms);
                // #3483 scope: `tm ls <term>` matches every visible column.
                let filter = term.map(commands::session_picker::SessionFilter::visible);
                commands::session_ls_connector::run_ls_connector(
                    &client, &url, json, source_id, current, all, attached, plain, sort, filter,
                    no_prune,
                )
                .await
            }
        }
        // `tm f [pattern]` — the type-to-filter picker. It gates on TTY-ness
        // BEFORE touching raw mode and degrades to the static filtered table.
        Some(Command::F(args)) => {
            commands::session_picker_filter::run_f_command(&client, &url, args).await
        }
        Some(Command::Load { alias, root }) => {
            let paths = commands::managed_root::resolve_managed_paths(root.as_deref())?;
            commands::standalone::load_cmd(&paths, &alias)
        }
        // #4990: `tm run` now carries two disjoint targets. A repo shape
        // (`<owner>/<repo>` or a full URL) cold-starts a DAEMON-MANAGED session;
        // a registry alias keeps the unchanged DOC-24 standalone behaviour. The
        // routing decision lives in `run_target` so it is unit-testable.
        Some(Command::Run { target, task, root }) => {
            commands::run_target::run(&client, &url, &target, task, root, account, token).await
        }
        // #6441: a leading token that matched no subcommand. A repo shape runs
        // the same cold start as `tm run`; anything else is a typo and gets
        // clap's usage error back.
        Some(Command::External(ref tokens)) => {
            let (external, argv) = (tokens.as_slice(), argv.as_slice());
            commands::run_target::run_external(&client, &url, external, argv, &HELP, account, token)
                .await
        }
        Some(Command::Path { alias, root }) => {
            let paths = commands::managed_root::resolve_managed_paths(root.as_deref())?;
            commands::standalone::path_cmd(&paths, &alias)
        }
        Some(Command::ShellInit { shell }) => commands::shell_init::run_shell_init(shell),
        Some(Command::Login { root }) => {
            let paths = commands::managed_root::resolve_managed_paths(root.as_deref())?;
            commands::standalone::login_cmd(&paths)
        }
        Some(Command::Rm { alias, root }) => {
            let paths = commands::managed_root::resolve_managed_paths(root.as_deref())?;
            commands::standalone::rm_cmd(&paths, &alias)
        }
        Some(Command::Update { alias, root }) => {
            let paths = commands::managed_root::resolve_managed_paths(root.as_deref())?;
            commands::standalone::update_cmd(&paths, alias.as_deref())
        }
        Some(Command::Sessctl { action }) => {
            commands::sessctl::dispatch(&client, &url, action).await
        }
        Some(Command::Statusline) => commands::statusline::run_statusline(),
        Some(Command::CommitTrailers(args)) => commands::commit_trailers::run(&args),
        Some(Command::Banner { reconnecting }) => {
            commands::banner::run_banner_preview(reconnecting)
        }
        // `tm mcp …` is a direct, daemon-less command family (like the standalone
        // driver): it edits the tm-owned config dir's `.claude.json` on disk.
        Some(Command::Mcp { cmd }) => commands::mcp::dispatch(cmd).await,
        // Unreachable at runtime: `Command::Config` is dispatched — and
        // `cli.command` returned early — before this match ever runs (see the
        // #2405 early short-circuit above, right after `Cli::try_parse`).
        // The arm still must exist for match exhaustiveness over `Command`.
        Some(Command::Config(_)) => unreachable!("config dispatched before daemon-URL resolution"),
        // Unreachable for the same reason as `Config`: the #2997 disclaim-exec
        // shim returned early right after `Config` above, before this match.
        Some(Command::InternalSpawnDisclaimed { .. }) => {
            unreachable!("internal-spawn-disclaimed dispatched before daemon-URL resolution")
        }
    };

    // #6288: `tm session prune-idle`'s exit-75 translation moved with it to
    // `commands::socket_dispatch::run`.
    // #1737: the bare `tm` guided default returns `DaemonUrlError::Unreachable`
    // when an EXPLICIT `--url`/`TRUSTY_MPM_URL` fails its reachability probe
    // (see `commands::guided::run_guided_default`'s guard, which already
    // printed the message — this arm only translates the exit code, mirroring
    // the `PruneError::SmUnavailable` block above so the two "target
    // unavailable" conventions exit identically).
    if let Err(err) = &result
        && err
            .downcast_ref::<trusty_mpm::core::DaemonUrlError>()
            .is_some()
    {
        std::process::exit(trusty_mpm::core::exit_codes::EXIT_UNAVAILABLE);
    }
    result
}