trusty-mpm 1.8.2

//! `launch` and `connect` command handlers.
//!
//! Why: these two commands manage the full session lifecycle (deploy + tmux +
//! attach) and are complex enough to warrant a dedicated file.
//! What: `launch` (managed clone + register + tmux + attach), `connect` (register
//! only + idempotent tmux + attach), plus `find_existing_session` helper.
//! Test: `cli_parses_launch`, `cli_parses_connect`, `cli_parses_launch_with_dir`,
//! `cli_parses_connect_with_dir` in `tests.rs`.

use serde::Deserialize;

use crate::commands::project::resolve_dir;
use crate::formatters::banner::{
    fallback_session_name, normalize_workdir, print_launch_banner,
    print_launch_banner_reconnecting, tmux_has_session,
};

/// RAII guard that kills a tmux session on drop unless explicitly disarmed.
///
/// Why: `launch()` and `connect()` create real tmux sessions; if any step after
/// creation fails (e.g. `send-keys` error, or `attach-session` failing because
/// there is no TTY available — which is always the case in integration tests),
/// the session would otherwise be permanently orphaned, filling the host tmux
/// with leaked managed (`tm-*`/`tmpm-*`) sessions (#1815).
/// What: on `drop` while armed, runs `tmux kill-session -t <name>` best-effort
/// (ignores errors, since the session may already be gone). `disarm` turns
/// `drop` into a no-op; call it before returning `Ok(())` so a session that
/// the user successfully attached to persists for future re-attachment.
/// Test: verified by `cargo test -p trusty-mpm --bin tm`; the before/after
/// managed (`tm-*`/`tmpm-*`) session count must be equal after the test run (issue #1815).
struct LaunchSessionGuard {
    name: String,
    armed: bool,
}

impl LaunchSessionGuard {
    /// Construct an armed guard owning `name`.
    ///
    /// Why: callers create the guard immediately after `tmux new-session` so the
    /// cleanup window opens with no gap.
    /// What: stores `name` with `armed = true`.
    /// Test: see module-level doc.
    fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            armed: true,
        }
    }

    /// Transfer ownership away: `drop` becomes a no-op after this call.
    ///
    /// Why: a session the user successfully attached to must NOT be killed when
    /// they detach; disarming transfers lifetime responsibility to the live tmux
    /// server.
    /// What: clears `armed`. Idempotent.
    /// Test: see module-level doc.
    fn disarm(&mut self) {
        self.armed = false;
    }
}

impl Drop for LaunchSessionGuard {
    /// Why: the whole point — any error path between session creation and a
    /// successful `attach-session` must reap the session so it cannot leak.
    /// What: when `armed`, issues `tmux kill-session -t <name>` best-effort.
    /// Never panics — `Drop` must not unwind.
    /// Test: see module-level doc.
    fn drop(&mut self) {
        if !self.armed {
            return;
        }
        // #2398 architecture consolidation: route through the crate's single
        // tmux entry point instead of shelling out independently.
        let _ =
            trusty_mpm::core::tmux::run_tmux(&trusty_mpm::core::tmux::TmuxCommand::KillSession {
                name: self.name.clone(),
            });
    }
}

/// `launch` subcommand — provision a managed clone and launch a configured session.
///
/// Why: `tm launch` should reproduce the `claude-mpm` experience — one command
/// that provisions a clean managed clone, deploys the framework, registers the
/// session, starts `claude` in a tmux host, and hands the current terminal over
/// to it. The live checkout is NEVER touched: `.claude` is deployed into the managed
/// clone, and the tmux cwd is the managed clone (#1590).
/// What: resolves `dir`, derives the GitHub remote from its origin, provisions a
/// shared base clone under `<repos_root>/<owner>/<repo>/` (resolved via the SAME
/// `inproject::base_clone_path` the daemon uses, so both entry points agree — #1807)
/// plus a per-session worktree, registers the
/// session with the daemon, prints the banner, creates a detached tmux session
/// running `claude` in the managed clone, and `attach`es to it. A remote that
/// does not parse as `owner/repo` errors with a `tm connect` hint; a repository
/// with NO origin remote prints a notice and runs [`connect`] against the
/// checkout itself (#6276) rather than erroring.
///
/// #5274: `worktree` is the operator's explicit request for isolation
/// (`tm launch --worktree`). Without it the session runs in the project's own
/// checkout and no clone is made — the sentence above about the live checkout
/// never being touched describes the `--worktree` branch only.
///
/// `launch_dir` says whether `dir` is an operator cwd still to be resolved or a
/// placement the caller already made; see
/// [`super::managed_workspace::LaunchDir`]. Two of the three callers here reach
/// this function with placement already decided, and resolving it again
/// relocates their session.
/// Test: `cli_parses_launch`, `cli_parses_launch_with_dir`,
/// `cli_parses_launch_with_style`, `cli_parses_launch_with_worktree`,
/// `cli_parses_launch_with_twin`,
/// `a_twin_worktree_launch_is_refused_before_anything_is_touched`;
/// `guided_fallback_prepares_the_session_in_the_worktree_not_the_base_clone`
/// covers the composed fallback path.
#[allow(clippy::too_many_arguments)] // #8878: `twin` is the eighth.
pub(crate) async fn launch(
    client: &reqwest::Client,
    url: &str,
    dir: Option<String>,
    style: Option<String>,
    worktree: bool,
    launch_dir: super::managed_workspace::LaunchDir,
    home: Option<&std::path::Path>, // #8545: production passes `dirs::home_dir()`
    twin: bool,
) -> anyhow::Result<()> {
    super::launch_twin::preflight(twin, worktree)?; // #8878: before anything is touched.
    // 1. Resolve the live source directory (absolute, so the banner is unambiguous).
    let live_path = resolve_dir(dir)?;
    let live_path = live_path.canonicalize().unwrap_or(live_path);

    // #6274: a plain directory becomes a git project here, so step 2 below reads
    // the origin remote of a real repository instead of failing on "not a git
    // repo". A fresh repo has no origin, and since #6276 step 2 starts a session
    // in that checkout rather than stopping there.
    // #7749: a refusal is NOT an error here — the outcome is deliberately
    // discarded, and step 2 then reads `Ok(None)` from a directory with no
    // repository at all, which is the live-checkout plan. That route is pinned
    // by `launch_route_after_a_scan_refusal_falls_through_to_the_live_checkout`;
    // the refusal `ensure_git_repo` prints is the operator's explanation.
    super::auto_git_init::ensure_git_repo(&live_path)?;

    // Auto-register the git project root as a local path alias (non-fatal, silent).
    super::managed_root::try_register_alias(&live_path);
    let live_workdir = live_path.to_string_lossy().to_string();

    // 2. Derive the GitHub identity from the origin remote.
    //    Managed sessions REQUIRE a parseable GitHub remote (#1590). An
    //    unparseable remote is an immediate error that points the user to `tm connect`.
    //    #4734: a git failure gets its own error — telling the operator to run
    //    `tm connect` because there is "no remote" would be false advice.
    // #6276: a repository with NO origin remote starts the session here instead
    // of stopping — `connect` is the live-checkout path this used to name in a
    // refusal, and it needs neither a remote nor a clean tree.
    let raw_origin = trusty_mpm::daemon::managed_routes::inproject::get_origin_url(&live_path)
        .map_err(|e| anyhow::anyhow!(e))?;
    let origin_url = match super::origin_plan::plan_for_origin(raw_origin.as_deref()) {
        super::origin_plan::OriginPlan::LiveCheckout => {
            super::launch_twin::refuse_live_checkout(twin)?; // #8878
            eprintln!("{}", super::origin_plan::live_checkout_notice(&live_path));
            return connect(client, url, Some(live_workdir), home).await;
        }
        // Any origin remote keeps the pre-#6276 path exactly: parse it as
        // owner/repo, or stop with the hint below.
        super::origin_plan::OriginPlan::ManagedClone(u)
        | super::origin_plan::OriginPlan::RefuseNonGitHub(u) => u.to_string(),
    };
    let gh = trusty_common::github_path::parse_github_path(&origin_url)
        .ok_or_else(|| unparseable_origin_refusal(&origin_url))?;
    let source_id = format!("{}/{}", gh.owner, gh.repo);

    // 3. Compute the canonical managed project directory
    //    (<repos_root>/<owner>/<repo>/) via the SAME resolver the daemon's
    //    in-project spawn path uses (`base_clone_path` → `repos_root_from`), so
    //    `tm launch` and daemon-spawned sessions can never diverge (#1807). This
    //    resolver honours the full precedence chain — `TRUSTY_MPM_REPOS_ROOT` env
    //    > `TRUSTY_MPM_WORKSPACE_ROOT` env > config `workspace_root_template` >
    //    built-in `~/trusty-mpm-projects`. The pre-#1807 code called
    //    `workspace_subpath`, which skipped `TRUSTY_MPM_REPOS_ROOT` entirely and
    //    re-introduced the root divergence #1803 set out to eliminate.
    let project_dir =
        trusty_mpm::daemon::managed_routes::inproject::base_clone_path(&gh.owner, &gh.repo);
    let project_dir_str = project_dir.to_string_lossy().to_string();

    // 4. Reconnect check — prefix-match any LIVE session whose workdir lives under
    //    the canonical project dir. The per-session UUID means an exact-match would
    //    never find an existing session; a prefix match reconnects to the last live
    //    session for this project. Liveness is checked inside `find_existing_session`
    //    so ALL candidates are evaluated (not just the first one returned by the
    //    daemon), which correctly handles projects with stale historical sessions.
    if let Some(existing) =
        find_existing_session(client, url, &live_workdir, Some(&project_dir_str)).await
        && !existing.is_empty()
    {
        super::launch_twin::refuse_reattach(twin, &existing)?; // #8878
        print_launch_banner_reconnecting(&live_workdir, &existing);
        crate::commands::tmux_attach::tmux_attach(&existing)?;
        return Ok(());
    }

    // #9091: a broken `[accounts]` table refuses before provisioning.
    super::run_target::accounts_preflight(None, &origin_url)?;

    // 5. --style is not yet honoured in managed mode.
    if style.is_some() {
        tracing::warn!("--style not yet supported for managed launches; ignoring style flag");
        // TODO(follow-up): prepare_session_with_repo_url_and_style
    }

    // 6. Provision the managed workspace using the shared base-clone + per-session
    //    worktree mechanism (#1803). This matches what `tm` (guided default) does
    //    via the daemon's `spawn_managed_inproject` path — both converge on the
    //    SAME base clone at `~/trusty-mpm-projects/<owner>/<repo>/` and the SAME
    //    per-session worktree at `<base>/.worktrees/<session-id>/`.
    //    #5274: the base clone and worktree are provisioned ONLY when the
    //    operator passed `--worktree`. Without it the session runs in the
    //    project's main checkout, matching what the daemon's
    //    `spawn_managed_routed` does for a spawn carrying no worktree request —
    //    the project's `worktree` flag is deliberately not consulted here, since
    //    it governs agent isolation rather than session placement.
    //    `provision_for_launch` also resolves the repo ROOT of `live_path` (so
    //    `tm launch` from a subdirectory deploys to the project, not the
    //    subdirectory) and owns the uncommitted-changes notice, which only
    //    applies when there IS a clone.
    // #8878: the hook judges `CLAUDE_PROJECT_DIR`; the grant is checked for the
    // managed checkout BEFORE provisioning, so a refusal leaves no clone behind.
    let twin_root = twin
        .then(|| super::launch_twin::precheck(&project_dir))
        .transpose()?;
    let session_uuid = trusty_mpm::session_manager::ManagedSessionId::new();
    let workspace = super::managed_workspace::provision_for_launch(
        &origin_url,
        &project_dir,
        &live_path,
        worktree,
        launch_dir,
        &session_uuid,
        home, // #8994: the worktree ledger's home
    )
    .await?;
    let managed_path = workspace.path().to_path_buf();
    if twin_root.is_some() {
        super::launch_twin::confirm_placement(&project_dir, &managed_path)?; // #8878
    }

    // 7. Deploy the `.claude` framework into the worktree (best-effort).
    //     Non-fatal: a deploy failure never aborts the session — the operator can
    //     run `tm install` / `tm catalog sync` to populate agents manually.
    //     #4203: deploy through the isolated seam so the roster lands in the
    //     worktree (the harness cwd, set at step 12) rather than `$HOME` — the
    //     `claude` spawned at step 13 carries `--setting-sources project,local`
    //     and would never read a `$HOME/.claude` deploy.
    let config_dir = {
        match trusty_mpm::core::session_launch::prepare_isolated_session_under(
            &managed_path,
            Some(&origin_url),
            home,
        ) {
            Ok(report) => {
                // Issue #2149: a roster-deploy failure no longer aborts
                // preparation — surface it loudly rather than let it hide.
                // #9011 D4: printed, since `tm launch` has no tracing subscriber
                // and no content would otherwise show no line at all.
                for err in &report.roster_errors {
                    eprintln!(
                        "error: roster provisioning gap for worktree {}: {err}",
                        managed_path.display()
                    );
                }
                // #6649: silent on a clean worktree; one line per unclean kind.
                for notice in &report.asset_notices {
                    println!("  assets: {notice}");
                }
            }
            // #4752: a compiled-prompt write failure is FATAL — refuse the
            // launch rather than start a session whose instructions cannot be
            // inspected. Every other prep failure stays non-fatal (#2149).
            Err(e) if e.is_fatal() => {
                anyhow::bail!("{e}");
            }
            Err(e) => {
                tracing::warn!(
                    "session prep failed for worktree {} (non-fatal): {e}",
                    managed_path.display()
                );
            }
        };
        // #4181: relocate CLAUDE_CONFIG_DIR and seed trust into the file the
        // relocated session actually reads.
        super::launch_home::relocate_config_dir(&managed_path, home)
    };
    let managed_workdir = managed_path.to_string_lossy().to_string();

    // 8. Write project-scoped MPM hooks into the managed clone (NOT the live checkout).
    //    Both steps are best-effort — a failure is logged but never fatal.
    // #5875: this strips the two `~/.claude/settings*.json` files only. It used
    // to walk the whole `$HOME` tree here, which blocked a launch indefinitely.
    super::launch_home::strip_global_hooks(home);
    if let Err(e) = crate::commands::install::write_project_hooks_for_dir(&managed_path, None) {
        eprintln!("warning: could not write project-scoped MPM hooks: {e:#}");
    }

    // 9. (#4752) The former regeneration of
    //     `~/.trusty-mpm/framework/instructions/INSTRUCTIONS.md` is gone. Its
    //     result was assigned and then immediately discarded (`let _ =
    //     instructions_path`), so it only ever wrote a file no launch read —
    //     and that path is now retired: `tm install` deletes a stale copy and
    //     the compiled prompt is per-project. The prompt this session actually
    //     receives is built below and written by `prepare_isolated_session`.

    // Resolve the PM model (config > frontmatter > default).
    // #5207: `load_effective_default` folds the project's committed
    // `.trusty-mpm.toml` and the previously-orphaned `config.yaml`
    // `default_model` into the same chain, so both actually reach a launch
    // instead of being written and ignored. It resolves the framework root
    // internally: the #4203 guard forbids this file from naming the framework
    // paths' default constructor at all, and matches on source text, so even a
    // comment spelling that symbol out would trip it.
    let mpm_cfg = trusty_mpm::core::config::MpmConfig::load_effective_default(Some(&managed_path));
    // #8453: one profile resolution for the prompt, the stamp and the model; a
    // supervisor launches on the Opus tier alias.
    // #9012: the PM instructions are runtime content; none refuses here.
    let content = trusty_mpm::core::content_source::framework_content_for(&managed_path)
        .map_err(|err| anyhow::anyhow!("cannot compose the PM instructions: {err}"))?;
    let cli =
        trusty_mpm::core::session_launch::cli_launch(&content, &managed_path, Some(&origin_url));
    let pm_model = trusty_mpm::core::session_profile::launch_model(cli.profile, &mpm_cfg);

    // Build the `--append-system-prompt` text from the managed clone (where the
    // framework was deployed at session prep). Style is not supported in managed
    // mode so we always pass `None` here.
    // #8286: a PM launch never proceeds without its prompt; refuse on a failed
    // write BEFORE `POST /sessions`, so a refusal leaves no session record.
    let prompt_path = launch_prompt_file(&std::env::temp_dir(), &cli.prompt, &managed_path)?;

    // 10. Register the session with the daemon. The tmux name is derived from
    //    the LIVE project folder so the human-readable name reflects the repo.
    //    `project`/`project_path` are the MANAGED clone path; `source_id` links
    //    this session back to its GitHub identity for future reconnects.
    //    Unknown fields (like `source_id`) are currently ignored by the daemon —
    //    non-breaking forward-compatible addition.
    #[derive(Deserialize)]
    struct Body {
        #[serde(default)]
        name: String,
        /// The registered session's id; `None` when the daemon is unreachable.
        id: Option<trusty_mpm::core::session::SessionId>,
    }
    let folder_name = fallback_session_name(&live_path);
    let (tmux_name, session_id) = match client
        .post(format!("{url}/sessions"))
        .json(&serde_json::json!({
            "project": managed_workdir,
            "project_path": managed_workdir,
            "name": folder_name,
            "source_id": source_id,
        }))
        .send()
        .await
    {
        Ok(resp) => match resp.error_for_status() {
            Ok(resp) => match resp.json::<Body>().await {
                Ok(body) if !body.name.is_empty() => (body.name, body.id),
                Ok(body) => (folder_name.clone(), body.id),
                _ => (folder_name.clone(), None),
            },
            Err(err) => {
                eprintln!("warning: daemon rejected session registration: {err}");
                (folder_name.clone(), None)
            }
        },
        Err(err) => {
            eprintln!("warning: daemon unreachable ({err}); launching without registration");
            (folder_name.clone(), None)
        }
    };

    // #2997: `tm launch` also creates a detached tmux session and types the
    // `claude` line into it via send-keys, so the pane's `claude` is forked by
    // the shared tmux server just like the daemon path — wrap it in the
    // disclaim-exec so tccd blames Claude Code, not the tmux server. No-op off
    // macOS / under TM_DISABLE_SPAWN_DISCLAIM.
    // #7422: compose this session's default-deny MCP config before the line
    // that names it. Fatal — launching without `--mcp-config` would hand the
    // pane the whole shared server map.
    let scoped_mcp =
        super::launch_home::provision_session_mcp(&managed_path, config_dir.as_deref(), home)?;
    // #8308: the launch travels in a mode-0600 spec; the pane types a short
    // line naming it, so no token or path is typed.
    // #4181: `config_dir` selects `--setting-sources user,project,local` and
    // carries the #2246 OAuth token; `None` keeps the pre-#4181 posture.
    let claude_spec = launch_claude_spec(
        &managed_path,
        // #8405: the operator's config decides the renderer.
        trusty_mpm::core::alt_screen::operator_config_root().as_deref(),
        &pm_model,
        Some(prompt_path.as_path()),
        config_dir.as_deref(),
        // #4181: the per-project MCP pins the shared user-scope declarations
        // cannot carry as arguments; #8453: plus the profile stamp.
        &cli.env,
        scoped_mcp.as_deref(),
    );
    let spec_dir = launch_spec_dir(home)?;

    // 11. Print the full-screen robot splash then the rich info panel.
    //     Pass the real managed worktree path so the banner shows the session
    //     directory (not just the base project dir).
    print_launch_banner(
        &live_workdir,
        &tmux_name,
        Some(prompt_path.as_path()),
        Some(&managed_path),
    );

    // 12. Create a detached tmux session rooted at the MANAGED clone directory.
    //     #2398: routes through `core::tmux::create_managed_session`, the
    //     crate's single session-creation choke point — this is what applies
    //     the configured scrollback/mouse ergonomics BEFORE the pane exists
    //     (a bare `tmux new-session` here would silently bypass them, the
    //     exact QA-caught regression this consolidation closes).
    let new_session =
        trusty_mpm::core::tmux::create_managed_session(None, &tmux_name, Some(&managed_workdir));
    let outcome = match new_session {
        Ok(o) if o.output.status.success() => o,
        _ => anyhow::bail!("failed to create tmux session {tmux_name} in {managed_workdir}"),
    };
    if !outcome.options_verified {
        // #3386 review: a caller-visible one-line notice — never silently
        // proceed as if the pane's scrollback limit landed.
        eprintln!(
            "warning: tmux scrollback limit could not be verified for session {tmux_name} — \
             the pane may be capped at tmux's factory 2000-line history-limit instead of the \
             configured value; see issue #3386"
        );
    }
    // RAII guard — disarmed only after successful attach so the session persists
    // when the user detaches normally. On any error path (including attach
    // failing because there is no TTY, which is always the case in tests) the
    // guard's Drop impl reaps the session, preventing leaks (#1815).
    let mut session_guard = LaunchSessionGuard::new(&tmux_name);

    // 13. Start `claude` inside the tmux session.
    let sent =
        trusty_mpm::runtime::cli_launch::send_spec_launch(&tmux_name, &claude_spec, &spec_dir);
    if let Err(e) = sent {
        anyhow::bail!(
            "tmux session {tmux_name} created but failed to start claude: {e} (report this with `tm doctor` output)"
        );
    }

    // 13b. Find the claude process PID inside the tmux pane and report it to
    //      the daemon so it can monitor process liveness.
    // #8878: twin arming needs the PID even when registration failed.
    let claude_pid = (session_id.is_some() || twin_root.is_some())
        .then(|| {
            trusty_mpm::core::process::find_claude_pid_in_tmux(
                &tmux_name,
                10,
                std::time::Duration::from_millis(500),
            )
        })
        .flatten();
    if let Some(root) = &twin_root {
        super::launch_twin::arm(root, claude_pid, &managed_path);
    }
    if let Some(session_id) = session_id {
        if let Some(pid) = claude_pid {
            let _ = client
                .patch(format!("{url}/sessions/{}/pid", session_id.0))
                .json(&serde_json::json!({ "pid": pid }))
                .send()
                .await;
            tracing::info!(
                "claude process PID {pid} registered for session {}",
                session_id.0
            );
        } else {
            tracing::warn!("could not find claude PID for session {tmux_name} after retries");
        }
    }

    // 14. Attach to the session — blocks until the user detaches or exits claude.
    crate::commands::tmux_attach::tmux_attach(&tmux_name)?;
    // Attach succeeded: the user detached normally. Disarm the guard so the
    // session persists and can be resumed with `tmux attach -t <name>`.
    session_guard.disarm();
    Ok(())
}

/// `connect` subcommand — start or attach to a session in the live checkout.
///
/// Why: `tm connect` is the lightweight sibling of `tm launch`. Where `launch`
/// provisions a managed clone, `connect` runs directly in the live checkout without
/// any cloning. This is the recommended path for repos without a GitHub remote, or
/// when the operator needs to work with uncommitted local changes. Issue #2230:
/// `connect` used to deploy NOTHING and launch a bare
/// `claude --dangerously-skip-permissions` with no PM persona — the one launch
/// path that could silently spawn vanilla Claude Code. It now runs the same
/// [`trusty_mpm::core::session_launch::prepare_session`] seam
/// `DaemonClient::launch_session` (the TUI's `/connect`) uses, deploying agents,
/// skills, the project-tier output-style, and the `trusty-memory`/PM-guard
/// project hooks directly into the live checkout — no clone, no git-remote or
/// clean-tree requirement, so repos with no GitHub remote or uncommitted
/// changes (this command's whole reason to exist) still launch.
/// What: resolves `dir`, reconnects to a live session for the directory when
/// one exists, otherwise runs [`trusty_mpm::core::session_launch::prepare_session`]
/// (best-effort — logs and continues on any failure, never aborts the
/// connect), registers the session via `POST /api/v1/sessions/connect`,
/// builds the PM system prompt via
/// [`trusty_mpm::core::session_launch::cli_launch`]
/// and writes it to a temp file (#8286: refusing the connect if it cannot),
/// creates the tmux host idempotently
/// (`tmux new-session -A`), and — only when the session is freshly created —
/// starts `claude` from the launch spec [`connect_claude_spec`] builds (`--append-system-prompt-file`
/// plus the shared `--setting-sources project,local` /
/// `--dangerously-skip-permissions` isolation flags), then `attach`es to it.
/// Test: `cli_parses_connect`, `cli_parses_connect_with_dir`.
pub(crate) async fn connect(
    client: &reqwest::Client,
    url: &str,
    dir: Option<String>,
    home: Option<&std::path::Path>, // #8545: production passes `dirs::home_dir()`
) -> anyhow::Result<()> {
    // 1. Resolve the target directory (absolute, so the banner is unambiguous).
    let path = resolve_dir(dir)?;
    let path = path.canonicalize().unwrap_or(path);
    let workdir = path.to_string_lossy().to_string();

    // Auto-register the git project root as a local path alias (non-fatal, silent).
    super::managed_root::try_register_alias(&path);

    // 1b. Reconnect to an existing LIVE session for this directory if one
    //     exists — `connect` is idempotent by design. No project_dir prefix-match
    //     since `connect` always works on the live checkout. Liveness is checked
    //     inside `find_existing_session` so stale historical sessions don't block.
    if let Some(existing) = find_existing_session(client, url, &workdir, None).await
        && !existing.is_empty()
    {
        // Full-screen robot splash + rich info panel (reconnect mode).
        print_launch_banner_reconnecting(&workdir, &existing);
        crate::commands::tmux_attach::tmux_attach(&existing)?;
        return Ok(());
    }

    // 1c. Deploy the framework directly into the live checkout — agents,
    //     skills, the project-tier output-style, and the
    //     `trusty-memory`/PM-guard project hooks (issue #2230). This is the
    //     SAME `prepare_session` seam `DaemonClient::launch_session` (the
    //     TUI's `/connect`) uses; unlike `tm launch` it performs no
    //     git-remote or clean-tree check at all — only filesystem writes
    //     under `path` — so a repo with no GitHub remote or with uncommitted
    //     changes still launches. Best-effort: a prep failure is logged and
    //     never aborts the connect.
    //     #4203: deploy through the isolated seam so the roster lands in the
    //     live checkout (the harness cwd, set at step 4) rather than `$HOME` —
    //     the `claude` spawned at step 5 carries `--setting-sources
    //     project,local` and would never read a `$HOME/.claude` deploy.
    match trusty_mpm::core::session_launch::prepare_isolated_session_under(&path, None, home) {
        Ok(report) => {
            // #9011 D4: printed — `tm connect` has no tracing subscriber.
            for err in &report.roster_errors {
                eprintln!(
                    "error: roster provisioning gap for {}: {err}",
                    path.display()
                );
            }
            // #6649: silent on a clean checkout; one line per unclean kind.
            for notice in &report.asset_notices {
                println!("  assets: {notice}");
            }
        }
        // #4752: fatal — refuse the connect rather than attach to a session
        // whose compiled instructions could not be written.
        Err(err) if err.is_fatal() => {
            anyhow::bail!("{err}");
        }
        Err(err) => {
            tracing::warn!(
                "session prep failed for {} (non-fatal): {err}",
                path.display()
            );
        }
    }
    // #4181: same relocation `tm launch` performs — `tm connect` reads the same
    // user-tier MCP declaration and needs the same #1269 isolation posture.
    let config_dir = super::launch_home::relocate_config_dir(&path, home);

    // 1d. Build the PM system-prompt text for the live checkout (where 1c just
    //     deployed the framework) and write it to a temp file for
    //     `--append-system-prompt-file` (issue #2230). #8286: a write failure
    //     refuses the connect before the daemon registers anything.
    // #8453: the prompt and the launch stamp come from one profile resolution.
    // #9012: the PM instructions are runtime content; none refuses here.
    let content = trusty_mpm::core::content_source::framework_content_for(&path)
        .map_err(|err| anyhow::anyhow!("cannot compose the PM instructions: {err}"))?;
    let cli = trusty_mpm::core::session_launch::cli_launch(&content, &path, None);
    let prompt_path = connect_prompt_file(&std::env::temp_dir(), &cli.prompt, &path)?;

    // 2. Register the session with the daemon via the connect endpoint. When
    //    the daemon is unreachable we still bring the session up under the
    //    folder-derived name.
    #[derive(Deserialize)]
    struct Body {
        #[serde(default)]
        name: String,
    }
    let folder_name = fallback_session_name(&path);
    let tmux_name = match client
        .post(format!("{url}/api/v1/sessions/connect"))
        .json(&serde_json::json!({
            "project": path,
            "project_path": path,
            "name": folder_name,
        }))
        .send()
        .await
    {
        Ok(resp) => match resp.error_for_status() {
            Ok(resp) => match resp.json::<Body>().await {
                Ok(body) if !body.name.is_empty() => body.name,
                _ => folder_name.clone(),
            },
            Err(err) => {
                eprintln!("warning: daemon rejected session registration: {err}");
                folder_name.clone()
            }
        },
        Err(err) => {
            eprintln!("warning: daemon unreachable ({err}); connecting without registration");
            folder_name.clone()
        }
    };

    // 3. Print the full-screen robot splash + rich info panel before tmux takes over.
    print_launch_banner(&workdir, &tmux_name, Some(prompt_path.as_path()), None);

    // 4. Create the tmux host idempotently. `new-session -A` attaches to an
    //    existing session and creates a detached one (`-d`) otherwise; the
    //    `has-session` probe tells us which happened so `claude` is started
    //    only for a freshly-created session. #2398: routes through
    //    `core::tmux::create_managed_session`, the crate's single session-
    //    creation choke point, so the configured scrollback/mouse ergonomics
    //    are applied before the pane exists.
    let already_running = tmux_has_session(&tmux_name);
    let new_session =
        trusty_mpm::core::tmux::create_managed_session(None, &tmux_name, Some(&workdir));
    let outcome = match new_session {
        Ok(o) if o.output.status.success() => o,
        _ => anyhow::bail!("failed to create tmux session {tmux_name} in {workdir}"),
    };
    if !outcome.options_verified {
        // #3386 review: a caller-visible one-line notice — never silently
        // proceed as if the pane's scrollback limit landed.
        eprintln!(
            "warning: tmux scrollback limit could not be verified for session {tmux_name} — \
             the pane may be capped at tmux's factory 2000-line history-limit instead of the \
             configured value; see issue #3386"
        );
    }
    // Guard only needed for freshly-created sessions; if the session was already
    // running we must NOT kill it on attach failure — another user may be attached.
    let mut session_guard = if already_running {
        None
    } else {
        Some(LaunchSessionGuard::new(&tmux_name))
    };

    // 5. Start `claude` inside a freshly-created session, carrying the PM
    //    system-prompt injection plus the shared isolation flags (#2230).
    if !already_running {
        // #2997: disclaim the pane's `claude` off the shared tmux server (same
        // wrapper the daemon + `tm launch` paths use). No-op off macOS / under
        // TM_DISABLE_SPAWN_DISCLAIM.
        // #7422: same fail-closed composition as `tm launch`.
        let scoped_mcp =
            super::launch_home::provision_session_mcp(&path, config_dir.as_deref(), home)?;
        // #8308: same spec carrier as `tm launch`.
        let claude_spec = connect_claude_spec(
            &path,
            Some(prompt_path.as_path()),
            config_dir.as_deref(),
            // #4181: the per-project MCP pins; #8453: plus the profile stamp.
            &cli.env,
            scoped_mcp.as_deref(),
            // #8405: the operator's config decides the renderer.
            trusty_mpm::core::alt_screen::operator_config_root().as_deref(),
        );
        let spec_dir = launch_spec_dir(home)?;
        let sent =
            trusty_mpm::runtime::cli_launch::send_spec_launch(&tmux_name, &claude_spec, &spec_dir);
        if let Err(e) = sent {
            anyhow::bail!(
                "tmux session {tmux_name} created but failed to start claude: {e} (report this with `tm doctor` output)"
            );
        }
    }

    // 6. Attach — takes over the current terminal until the user detaches.
    crate::commands::tmux_attach::tmux_attach(&tmux_name)?;
    // Attach succeeded: disarm the guard so the session persists for re-attachment.
    if let Some(ref mut g) = session_guard {
        g.disarm();
    }
    Ok(())
}

/// The refusal for an origin remote that names no GitHub owner/repo (#1590).
/// #9124: the origin is shown with its credentials redacted.
/// Test: `launch_refusal_never_quotes_the_origin_token`.
fn unparseable_origin_refusal(origin_url: &str) -> anyhow::Error {
    anyhow::anyhow!(
        "could not parse a GitHub owner/repo from origin remote: {:?}\n\
         Run `tm connect` to start a session in the live checkout instead.",
        trusty_mpm::core::remote_url_redact::redact_stored_url(origin_url)
    )
}

/// Write the PM prompt file `tm connect` hands `claude` (#8286).
///
/// Why: a write failure used to connect without `--append-system-prompt-file`,
/// so the session ran as plain Claude Code. `tm connect` launches a PM (or a
/// supervisor), whose role is this prompt, so there is no optional case.
/// What: [`trusty_mpm::core::model_inject::write_prompt_file_in`] under `dir`
/// (production: the process temp dir); `Err` names the file, the I/O cause
/// and `project`.
/// Test: `connect_prompt_file_refuses_when_the_prompt_file_cannot_be_written`;
/// `connect_refuses_an_unwritable_prompt_before_registering` pins the call-site order.
fn connect_prompt_file(
    dir: &std::path::Path,
    prompt: &str,
    project: &std::path::Path,
) -> anyhow::Result<std::path::PathBuf> {
    trusty_mpm::core::model_inject::write_pm_prompt_file_in(dir, prompt, project, "connect")
}

/// Write the PM prompt file `tm launch` hands `claude` (#8286).
///
/// Why: a write failure used to print "launching without prompt" and start a
/// plain Claude Code in the managed clone; a PM launch has no optional prompt.
/// What: [`trusty_mpm::core::model_inject::write_pm_prompt_file_in`] under
/// `dir` (production: the process temp dir); `Err` names the file, the I/O
/// cause and `project`.
/// Test: `launch_prompt_file_refuses_when_the_prompt_file_cannot_be_written`;
/// `launch_refuses_an_unwritable_prompt_before_registering` pins the call-site order.
fn launch_prompt_file(
    dir: &std::path::Path,
    prompt: &str,
    project: &std::path::Path,
) -> anyhow::Result<std::path::PathBuf> {
    trusty_mpm::core::model_inject::write_pm_prompt_file_in(dir, prompt, project, "launch")
}

/// Compose the launch spec `connect` starts a freshly-created tmux pane with.
///
/// Why (issue #2230): before this fix, `connect` sent a bare
/// `claude --dangerously-skip-permissions` with no PM system-prompt injection
/// and no `--setting-sources` isolation — the one launch path that could
/// silently spawn vanilla Claude Code. This gives `connect` the same carrier
/// every other launch path already has. #8308: a spec, not a typed line.
/// What: [`trusty_mpm::runtime::cli_launch::isolated_spec`] rooted at `cwd`,
/// with no `--model` override (`connect` does not resolve a PM model tier);
/// always carries the `--setting-sources` flag matching `config_dir` and
/// `--dangerously-skip-permissions`, plus `--append-system-prompt-file <path>`
/// when `prompt_file` is `Some`.
///
/// #4181: `config_dir` is `Some` whenever the tm-owned config home resolves, in
/// which case the spec relocates `CLAUDE_CONFIG_DIR`, carries the OAuth token
/// and `--setting-sources user,project,local`; `None` (unresolvable home) keeps
/// the pre-#4181 `project,local`.
/// Test: `cli_parses_connect`, `cli_parses_connect_with_dir` (in
/// `tests_behavior_b_tests.rs`) assert both flags are present in the output;
/// `connect_claude_spec_follows_the_configured_renderer` pins the #8405 renderer.
pub(crate) fn connect_claude_spec(
    cwd: &std::path::Path,
    prompt_file: Option<&std::path::Path>,
    config_dir: Option<&std::path::Path>,
    mcp_env: &[(String, String)],
    scoped_mcp: Option<&std::path::Path>,
    config_root: Option<&std::path::Path>,
) -> trusty_mpm::runtime::launch_spec::LaunchSpec {
    isolated_claude_spec(
        cwd,
        None,
        prompt_file,
        config_dir,
        mcp_env,
        scoped_mcp,
        config_root,
    )
}

/// The launch spec `tm launch` and the Architect start their pane with (#8405,
/// #8308).
///
/// Why: the one seam where `tm launch` turns the operator's config into the
/// renderer, split out so a test can drive it from a config root.
/// What: [`connect_claude_spec`] plus `--model <pm_model>`.
/// Test: `launch_claude_spec_follows_the_configured_renderer`.
pub(crate) fn launch_claude_spec(
    cwd: &std::path::Path,
    config_root: Option<&std::path::Path>,
    pm_model: &str,
    prompt_file: Option<&std::path::Path>,
    config_dir: Option<&std::path::Path>,
    mcp_env: &[(String, String)],
    scoped_mcp: Option<&std::path::Path>,
) -> trusty_mpm::runtime::launch_spec::LaunchSpec {
    isolated_claude_spec(
        cwd,
        Some(pm_model),
        prompt_file,
        config_dir,
        mcp_env,
        scoped_mcp,
        config_root,
    )
}

/// Shared body of [`connect_claude_spec`] and [`launch_claude_spec`].
///
/// What: resolves the OAuth token only when `config_dir` relocates the config
/// home (#4181/#2246 — a non-relocated spawn uses the operator's own login),
/// and the renderer from `config_root` (#8405); `scoped_mcp` is the composed
/// default-deny MCP file the caller already wrote (#7422).
fn isolated_claude_spec(
    cwd: &std::path::Path,
    model: Option<&str>,
    prompt_file: Option<&std::path::Path>,
    config_dir: Option<&std::path::Path>,
    mcp_env: &[(String, String)],
    scoped_mcp: Option<&std::path::Path>,
    config_root: Option<&std::path::Path>,
) -> trusty_mpm::runtime::launch_spec::LaunchSpec {
    let token = config_dir.and_then(|_| trusty_mpm::core::oauth_token::resolve_oauth_token());
    trusty_mpm::runtime::cli_launch::isolated_spec(
        cwd,
        &trusty_mpm::runtime::cli_launch::CliLaunch {
            model,
            prompt_file,
            config_dir,
            oauth_token: token.as_deref(),
            mcp_env,
            scoped_mcp,
            alternate_screen: trusty_mpm::core::alt_screen::configured_alternate_screen_in(
                config_root,
            ),
        },
    )
}

/// Where a CLI launch under `home` writes its spec (#8308).
///
/// What: [`trusty_mpm::runtime::cli_launch::spec_dir`]; an error when no home
/// resolves, because there is then nowhere owner-only to put the credentials.
pub(crate) fn launch_spec_dir(
    home: Option<&std::path::Path>,
) -> anyhow::Result<std::path::PathBuf> {
    trusty_mpm::runtime::cli_launch::spec_dir(home).ok_or_else(|| {
        anyhow::anyhow!("cannot start claude: no home directory to hold its launch spec (#8308)")
    })
}

/// Find the first LIVE session whose `workdir` matches `workdir` (exact) or lies
/// under `project_dir` (prefix, for managed-clone reconnect).
///
/// Why: `tm launch` uses a managed clone with a per-session UUID subdirectory, so
/// exact-matching `workdir` would never reconnect; a prefix-match on the canonical
/// `project_dir` (`~/trusty-mpm-projects/<owner>/<repo>`) reconnects to the last
/// live session for the same project. `tm connect` always passes `project_dir =
/// None` so it retains the original exact-match semantics.
/// Liveness (`tmux has-session`) is checked HERE (not at the call site) so ALL
/// candidates are evaluated — not just the first workdir-matching one. This prevents
/// a project with stale historical sessions from blocking reconnect to a later live one.
/// What: fetches `GET /sessions`, iterates all rows, skips empty tmux names and
/// sessions where `tmux has-session` fails, and returns the first matching live
/// session's `tmux_name`. `workdir`/`project_dir` matching is delegated to
/// [`session_matches_workdir`]. Returns `None` when the daemon is unreachable or no
/// live matching session exists.
/// Test: `session_matches_workdir_*` unit tests cover the matching logic;
/// `normalize_workdir_strips_trailing_slash` covers the normalization invariant.
async fn find_existing_session(
    client: &reqwest::Client,
    url: &str,
    workdir: &str,
    project_dir: Option<&str>,
) -> Option<String> {
    /// One session row including its tmux name, as returned by `GET /sessions`.
    #[derive(Deserialize)]
    struct Row {
        #[serde(default)]
        workdir: String,
        #[serde(default)]
        tmux_name: String,
    }

    let resp = client.get(format!("{url}/sessions")).send().await.ok()?;
    let rows: Vec<Row> = resp.error_for_status().ok()?.json().await.ok()?;
    rows.into_iter()
        .find(|r| {
            !r.tmux_name.is_empty()
                && session_matches_workdir(&r.workdir, workdir, project_dir)
                && tmux_has_session(&r.tmux_name)
        })
        .map(|r| r.tmux_name)
}

/// Return true when `session_workdir` matches `target` exactly OR lies under `project_dir`.
///
/// Why: extracted from `find_existing_session` so the matching logic can be unit-tested
/// independently of the HTTP client call. Both the exact-match (live-checkout, `connect`)
/// and the prefix-match (managed clone, `launch`) branches are exercised this way.
/// What: normalizes all three paths (trailing-slash strip via `normalize_workdir`), then
/// checks (a) exact equality or (b) when `project_dir` is `Some`, that the session workdir
/// starts with `<normalized_project_dir>/` — the trailing slash prevents a false match
/// where `/owner/repo-extra/<id>` matches `/owner/repo`.
/// Test: `session_matches_workdir_prefix_and_exact` below.
fn session_matches_workdir(session_workdir: &str, target: &str, project_dir: Option<&str>) -> bool {
    let w = normalize_workdir(session_workdir);
    let t = normalize_workdir(target);
    if w == t {
        return true;
    }
    let Some(proj) = project_dir else {
        return false;
    };
    let mut prefix = normalize_workdir(proj);
    if !prefix.ends_with('/') {
        prefix.push('/');
    }
    w.starts_with(prefix.as_str())
}

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

    /// #9124: the unparseable-origin refusal reaches the terminal; it never
    /// quotes the origin's token.
    #[test]
    fn launch_refusal_never_quotes_the_origin_token() {
        const TOKEN: &str = "ghp_9124LaunchSyntheticToken00000";
        let origin = format!("https://octo:{TOKEN}@gitlab.example/acme/widget.git");
        let msg = unparseable_origin_refusal(&origin).to_string();
        assert!(!msg.contains(TOKEN), "the token reached the refusal");
        assert!(
            msg.contains("https://***@gitlab.example/acme/widget.git"),
            "{msg}"
        );
    }

    /// #8286: `tm launch` refuses, naming the file and the cause, instead of
    /// launching "without prompt".
    #[test]
    fn launch_prompt_file_refuses_when_the_prompt_file_cannot_be_written() {
        let tmp = tempfile::tempdir().expect("tempdir");
        let not_a_dir = tmp.path().join("not-a-dir");
        std::fs::write(&not_a_dir, "").expect("plant a file where the prompt dir goes");
        let err = launch_prompt_file(&not_a_dir, "prompt", tmp.path())
            .expect_err("a launch without its PM prompt must be refused")
            .to_string();
        assert!(
            err.contains(&*not_a_dir.to_string_lossy())
                && err.contains("os error")
                && err.contains("refusing to launch"),
            "the refusal must name the prompt file, the I/O cause and the launch: {err}"
        );
    }

    /// #8286: `tm connect` refuses, naming the file and the cause, instead of
    /// connecting without its PM prompt.
    #[test]
    fn connect_prompt_file_refuses_when_the_prompt_file_cannot_be_written() {
        let tmp = tempfile::tempdir().expect("tempdir");
        let not_a_dir = tmp.path().join("not-a-dir");
        std::fs::write(&not_a_dir, "").expect("plant a file where the prompt dir goes");
        let err = connect_prompt_file(&not_a_dir, "prompt", tmp.path())
            .expect_err("a connect without its PM prompt must be refused")
            .to_string();
        assert!(
            err.contains(&*not_a_dir.to_string_lossy()) && err.contains("os error"),
            "the refusal must name the prompt file and the I/O cause: {err}"
        );
    }

    /// Exact-match: a session whose workdir equals the live checkout directory must match.
    ///
    /// Why: `tm connect` (and the pre-#1590 `tm launch`) used exact-match semantics;
    /// this test locks in that existing behaviour so the refactor cannot regress it.
    /// Test: this function IS the test.
    #[test]
    fn session_matches_workdir_exact() {
        assert!(session_matches_workdir(
            "/home/bob/projects/trusty-tools",
            "/home/bob/projects/trusty-tools",
            None
        ));
        // Trailing slashes are normalized away before comparison.
        assert!(session_matches_workdir(
            "/home/bob/projects/trusty-tools/",
            "/home/bob/projects/trusty-tools",
            None
        ));
    }

    /// Prefix-match: a session under `project_dir/<uuid>` must match when `project_dir` is provided.
    ///
    /// Why: `tm launch` provisions clones at `<project_dir>/<session_uuid>/`; reconnect
    /// must find the existing session without knowing the UUID. The prefix is
    /// `<project_dir>/` (with trailing slash) so `/owner/repo-extra/<id>` does NOT
    /// falsely match `/owner/repo`.
    /// Test: this function IS the test.
    #[test]
    fn session_matches_workdir_prefix_and_exact() {
        let project_dir = "/home/bob/trusty-mpm-projects/owner/repo";
        let session_wd = "/home/bob/trusty-mpm-projects/owner/repo/.worktrees/abc-123-uuid";

        // Prefix match: session workdir is under project_dir (in .worktrees/) → match.
        assert!(session_matches_workdir(
            session_wd,
            "/other/live/dir",
            Some(project_dir)
        ));

        // Exact match against live workdir also works (no project_dir needed).
        assert!(session_matches_workdir(session_wd, session_wd, None));

        // No-match: different project dir — must NOT match.
        assert!(!session_matches_workdir(
            "/home/bob/trusty-mpm-projects/owner/repo-extra/abc-123-uuid",
            "/other/live/dir",
            Some(project_dir)
        ));

        // No-match: project_dir is None and workdir differs — no match.
        assert!(!session_matches_workdir(
            session_wd,
            "/other/live/dir",
            None
        ));
    }

    /// Trailing-slash normalization: a session workdir with a trailing slash must
    /// still match (regression guard for `normalize_workdir`).
    ///
    /// Why: paths with trailing slashes appear in real daemon responses; stripping
    /// them before comparison prevents false negatives.
    /// Test: this function IS the test.
    #[test]
    fn session_matches_workdir_strips_trailing_slash() {
        assert!(session_matches_workdir(
            "/home/bob/project/",
            "/home/bob/project",
            None
        ));
    }

    /// No-remote error message: when project_dir prefix does not match the session
    /// workdir, the caller (launch) will not reconnect and will provision a new clone.
    /// This test asserts the guard against false-prefix matching.
    ///
    /// Why: without the trailing-`/` guard, `/owner/repo-extra/id` could match
    /// `/owner/repo` via a simple `starts_with` check.
    /// Test: this function IS the test.
    #[test]
    fn session_matches_workdir_no_false_prefix_match() {
        let project_dir = "/projects/owner/repo";
        // `/owner/repo-extra/<id>` must NOT match `/owner/repo`.
        assert!(!session_matches_workdir(
            "/projects/owner/repo-extra/some-uuid",
            "/other/live",
            Some(project_dir)
        ));
        // `/owner/repo/.worktrees/<id>` MUST match `/owner/repo`.
        assert!(session_matches_workdir(
            "/projects/owner/repo/.worktrees/some-uuid",
            "/other/live",
            Some(project_dir)
        ));
    }
}