trusty-mpm 1.3.5

//! `session` command handler.
//!
//! Why: session lifecycle operations (start, stop, list, clean, info, events,
//! breakers, pause, resume, catchup, run, output, instructions) form a cohesive
//! group that benefits from a dedicated file.
//! What: the `session` dispatcher function (shared by the canonical `tm
//! sessions` command and its deprecated hidden `tm session` alias, #2116) and
//! its private helpers `emit_managed_alias_notice`, `compose_session_instructions`,
//! plus the crate-visible [`emit_top_level_alias_notice`] the alias's `main.rs`
//! match arm calls. `start` is handled by the [`start`] submodule (protected-path
//! routing, #1916). The managed verbs (`new`/`ls`/`send`/`answer`/`attach`/
//! `stop`/`resume`/`decommission`) route through the shared chat-core layer
//! (`commands::managed_route`); the id-or-name resolution for both managed and
//! project sessions goes through the one canonical `client::resolve_target`.
//! `catchup` is handled by the DOC-28 cutover bridge in the `catchup` submodule.
//! Test: `cli_parses_session_*` / `cli_parses_sessions_*`, `cli_parses_session_catchup`,
//! `compose_session_instructions_*` in `tests.rs`.

// CUTOVER BRIDGE submodule — remove post-migration (#1762)
pub(crate) mod catchup;
mod start;

use serde::Deserialize;

use crate::cli::SessionAction;
use crate::commands::project::resolve_dir;
use crate::formatters::session::{event_summary, print_compression_stats, short_id};
use crate::types::{EventRow, SessionRow};

/// `session` subcommand — define and manage sessions within a project.
///
/// Why: a session is a Claude Code instance; operators start, stop, list,
/// reap, and inspect them per project from the shell.
/// What: `Start` routes through [`start::start_session`] (protected-path
/// segregation for a recognized GitHub-backed git repo, in-place
/// `prepare_session` for everything else — see that function's doc for the
/// #1916 rationale); `Stop` and `Resume` are managed-aware (#1218) — they
/// route to the managed runtime-stop/resume endpoints when the id/name
/// resolves to a managed session, falling back to the project-session path
/// otherwise; `Info` resolves a session by id or friendly name; `List` and
/// `Clean` scope to the project directory.
/// Test: `cli_parses_session_start`, `cli_parses_session_stop`,
/// `cli_parses_session_list`, `cli_parses_session_clean`,
/// `cli_parses_session_info`.
pub(crate) async fn session(
    client: &reqwest::Client,
    url: &str,
    action: SessionAction,
) -> anyhow::Result<()> {
    match action {
        SessionAction::Start { dir } => start::start_session(client, url, dir).await?,
        SessionAction::Stop { id_or_name } => {
            // #1218: `stop` is managed-aware. If the argument resolves to a
            // MANAGED session (by id or friendly name) via the canonical
            // chat-core resolver, route to the managed runtime-stop endpoint;
            // otherwise fall back to the project-session DELETE path. This keeps
            // one intuitive verb that does the right thing for both families (the
            // #842 driver skill documents `stop`).
            if let Some(managed_id) =
                crate::commands::managed_route::resolve_managed_match(client, url, &id_or_name)
                    .await
            {
                crate::commands::managed::session_stop(client, url, managed_id).await?;
            } else {
                let resp = client
                    .delete(format!("{url}/sessions/{id_or_name}"))
                    .send()
                    .await?;
                if resp.status() == reqwest::StatusCode::NOT_FOUND {
                    anyhow::bail!("session '{id_or_name}' not found");
                }
                resp.error_for_status()?;
                println!("stopped {id_or_name}");
            }
        }
        SessionAction::List { dir } => {
            let path = resolve_dir(dir)?;
            #[derive(Deserialize)]
            struct Body {
                sessions: Vec<SessionRow>,
            }
            let body: Body = client
                .get(format!("{url}/sessions"))
                .query(&[("project", path.to_string_lossy().as_ref())])
                .send()
                .await?
                .error_for_status()?
                .json()
                .await?;
            if body.sessions.is_empty() {
                // #3822: `tm sessions list` (this command) and `tm sessions
                // ls` are two DIFFERENT, intentionally-scoped subsystems —
                // `list` shows this project's local (pre-session-manager)
                // sessions, `ls` shows daemon-managed sessions (e.g. every
                // session created via `tm sessions new <url>`) from
                // anywhere. A user who ran `sessions new` and then checked
                // with `sessions list` sees an empty result here even
                // though their session is alive and well under `ls` — a
                // repeated support/bug-report source. Nudge toward the
                // command that actually shows managed sessions rather than
                // leaving the empty result unexplained.
                println!("no sessions for {}", path.display());
                println!(
                    "(looking for a session created via `tm sessions new`? try `tm sessions ls`)"
                );
            }
            for s in &body.sessions {
                let status = s.status.as_str().unwrap_or("unknown");
                println!("{} {} {}", short_id(&s.id), status, s.workdir);
            }
        }
        SessionAction::Tui {
            url: tui_url,
            interval_ms,
        } => {
            // #1392: the coordinator TUI is `tm session tui` (formerly the
            // top-level `tm coordinator-tui`). It polls the daemon live, so its
            // `run` is async and runs on the tokio runtime like `tui::run`.
            // `resolve_daemon_url` honours an explicit `--url`, then the lock
            // file, then the default — so we resolve from this subcommand's own
            // `--url`/`TRUSTY_MPM_URL` flag rather than the dispatcher's `url`.
            let resolved = trusty_mpm::core::resolve_daemon_url(tui_url.as_deref());
            trusty_mpm::tui::coordinator::run(resolved, interval_ms).await?;
        }
        SessionAction::Clean { dir } => {
            // `dir` is accepted for symmetry; the daemon reaps globally.
            let _ = resolve_dir(dir)?;
            let body: serde_json::Value = client
                .delete(format!("{url}/sessions/dead"))
                .send()
                .await?
                .error_for_status()?
                .json()
                .await?;
            let removed = body.get("removed").and_then(|v| v.as_u64()).unwrap_or(0);
            println!("reaped {removed} dead session(s)");
        }
        SessionAction::Info { id_or_name } => {
            #[derive(Deserialize)]
            struct Body {
                sessions: Vec<serde_json::Value>,
            }
            let body: Body = client
                .get(format!("{url}/sessions"))
                .send()
                .await?
                .error_for_status()?
                .json()
                .await?;
            let found = body.sessions.iter().find(|s| {
                let id_match = s
                    .get("id")
                    .and_then(|v| v.get("0"))
                    .and_then(|v| v.as_str())
                    == Some(id_or_name.as_str());
                let name_match =
                    s.get("tmux_name").and_then(|v| v.as_str()) == Some(id_or_name.as_str());
                id_match || name_match
            });
            match found {
                Some(s) => println!("{}", serde_json::to_string_pretty(s)?),
                None => {
                    // Fall back: the id/name may belong to a MANAGED session
                    // (SM sessions live in the managed store, not the project-session
                    // store). Fetch the managed list and search there too before
                    // giving up. This fixes the gap where `tm session info <uuid>`
                    // printed "not found" for sessions visible in `tm session ls`.
                    let managed = info_from_managed_store(client, url, &id_or_name).await;
                    match managed {
                        Some(val) => println!("{}", serde_json::to_string_pretty(&val)?),
                        None => anyhow::bail!("session '{id_or_name}' not found"),
                    }
                }
            }
        }
        SessionAction::Instructions { dir } => {
            // Pure local computation — no daemon round-trip needed.
            let path = resolve_dir(dir)?;
            // `resolved_prompt` is the same text written to the stash and
            // passed to `claude --append-system-prompt-file` — the single
            // source of truth for what Claude received (issue #382).
            let (resolved_prompt, _output, _stash) = compose_session_instructions(&path)?;
            print!("{resolved_prompt}");
        }
        SessionAction::Events { id_or_name } => {
            let id = match crate::commands::managed_route::resolve_project_session_id(
                client,
                url,
                &id_or_name,
            )
            .await?
            {
                Some(id) => id,
                None => {
                    anyhow::bail!("session '{id_or_name}' not found");
                }
            };
            #[derive(Deserialize)]
            struct Body {
                events: Vec<EventRow>,
            }
            let body: Body = client
                .get(format!("{url}/sessions/{id}/events/poll"))
                .send()
                .await?
                .error_for_status()?
                .json()
                .await?;
            if body.events.is_empty() {
                println!("no events for session {id_or_name}");
            }
            for e in &body.events {
                println!("{} {} {}", e.at, e.event, event_summary(&e.payload));
            }
        }
        SessionAction::Breakers => {
            #[derive(Deserialize)]
            struct Row {
                agent: String,
                breaker: serde_json::Value,
            }
            #[derive(Deserialize)]
            struct Body {
                breakers: Vec<Row>,
            }
            let body: Body = client
                .get(format!("{url}/breakers"))
                .send()
                .await?
                .error_for_status()?
                .json()
                .await?;
            if body.breakers.is_empty() {
                println!("no circuit breakers");
            } else {
                println!("{:<24} {:<12} FAILURES", "AGENT", "STATE");
                for r in &body.breakers {
                    let state = r
                        .breaker
                        .get("state")
                        .and_then(|v| v.as_str())
                        .unwrap_or("unknown");
                    let failures = r
                        .breaker
                        .get("consecutive_failures")
                        .and_then(|v| v.as_u64())
                        .unwrap_or(0);
                    println!("{:<24} {:<12} {}", r.agent, state, failures);
                }
            }
        }
        // DOC-28 cutover bridge — dispatches to session/catchup.rs
        // CUTOVER BRIDGE — remove post-migration (#1762)
        SessionAction::Catchup { all_projects, full } => {
            catchup::handle_catchup(all_projects, full).await?;
        }
        SessionAction::Pause { id_or_name, note } => {
            let resp = client
                .post(format!("{url}/sessions/{id_or_name}/pause"))
                .json(&serde_json::json!({ "summary": note }))
                .send()
                .await?;
            if resp.status() == reqwest::StatusCode::NOT_FOUND {
                anyhow::bail!("session '{id_or_name}' not found");
            }
            let body: serde_json::Value = resp.error_for_status()?.json().await?;
            let summary = body.get("summary").and_then(|v| v.as_str()).unwrap_or("");
            println!("paused {id_or_name}: {summary}");
        }
        SessionAction::Resume { id_or_name } => {
            // #1218: `resume` is managed-aware (mirrors `Stop`). A managed
            // session id/name routes (via the canonical chat-core resolver) to
            // the managed resume endpoint; anything else falls back to the
            // project-session pause/resume path.
            if let Some(managed_id) =
                crate::commands::managed_route::resolve_managed_match(client, url, &id_or_name)
                    .await
            {
                crate::commands::managed::session_resume(client, url, managed_id).await?;
            } else {
                let resp = client
                    .post(format!("{url}/sessions/{id_or_name}/resume"))
                    .send()
                    .await?;
                match resp.status() {
                    reqwest::StatusCode::NOT_FOUND => {
                        anyhow::bail!("session '{id_or_name}' not found");
                    }
                    reqwest::StatusCode::CONFLICT => {
                        println!("session '{id_or_name}' is not paused");
                    }
                    _ => {
                        resp.error_for_status()?;
                        println!("resumed {id_or_name}");
                    }
                }
            }
        }
        SessionAction::Run {
            id_or_name,
            command,
            summarize,
        } => {
            let mut req = client.post(format!("{url}/sessions/{id_or_name}/command"));
            if summarize {
                req = req.query(&[("compress", "summarise")]);
            }
            let resp = req
                .json(&serde_json::json!({ "command": command }))
                .send()
                .await?;
            match resp.status() {
                reqwest::StatusCode::NOT_FOUND => {
                    anyhow::bail!("session '{id_or_name}' not found");
                }
                reqwest::StatusCode::CONFLICT => {
                    println!("session '{id_or_name}' is stopped");
                }
                _ => {
                    let body: serde_json::Value = resp.error_for_status()?.json().await?;
                    let output = body.get("output").and_then(|v| v.as_str()).unwrap_or("");
                    print!("{output}");
                    print_compression_stats(&body);
                }
            }
        }
        SessionAction::Output {
            id_or_name,
            lines,
            summarize,
        } => {
            let mut query: Vec<(&str, String)> = vec![("lines", lines.to_string())];
            if summarize {
                query.push(("compress", "summarise".to_string()));
            }
            let resp = client
                .get(format!("{url}/sessions/{id_or_name}/output"))
                .query(&query)
                .send()
                .await?;
            if resp.status() == reqwest::StatusCode::NOT_FOUND {
                anyhow::bail!("session '{id_or_name}' not found");
            }
            let body: serde_json::Value = resp.error_for_status()?.json().await?;
            let output = body.get("output").and_then(|v| v.as_str()).unwrap_or("");
            print!("{output}");
            print_compression_stats(&body);
        }
        // ── Managed session-manager actions ──────────────────────────────────
        // All `ls` variants are routed through the direct HTTP path so the
        // `?source_id=` filter and the extended table columns (task, created_at)
        // work regardless of the `--json` flag. `--json` keeps the raw
        // daemon-JSON passthrough byte-for-byte (scripts rely on this).
        SessionAction::Ls {
            terms,
            json,
            source_id,
            current,
            all,
        } => {
            let sid: Option<String> = if current {
                derive_source_id_from_cwd()
            } else {
                source_id
            };
            let (sort, term) = crate::commands::session_picker::parse_ls_terms(&terms);
            // `tm sessions ls <term>` keeps the #3483 all-visible-columns scope;
            // only `tm f` narrows to NAME.
            let filter = term.map(crate::commands::session_picker::SessionFilter::visible);
            crate::commands::managed::session_ls(
                client,
                url,
                json,
                sid.as_deref(),
                all,
                sort,
                filter,
            )
            .await?
        }
        // `activity` stays on the raw path: its CLI output carries confidence,
        // token, cache, and latency detail that `CommandResult::ManagedActivity`
        // does not model, so routing it through chat-core would regress output.
        SessionAction::Activity { id } => {
            crate::commands::managed::session_activity(client, url, id).await?
        }
        SessionAction::PruneIdle { dry_run, json } => {
            crate::commands::prune::prune_idle(client, url, dry_run, json).await?
        }
        // #1508: bulk teardown + by-state prune go through direct HTTP (like
        // `PruneIdle`), not chat-core — they are fleet-wide store operations, not
        // single-session intents.
        SessionAction::DecommissionEphemeral => {
            crate::commands::managed::session_decommission_ephemeral(client, url).await?
        }
        SessionAction::Prune {
            state,
            dry_run,
            include_active,
        } => {
            crate::commands::managed::session_prune(client, url, state, dry_run, include_active)
                .await?
        }
        SessionAction::PruneWorktrees {
            force,
            discard_dirty,
            merged_prs,
        } => {
            // `--force` means "actually delete"; absence means dry-run (#1840).
            // `--discard-dirty` is a SEPARATE opt-in that additionally permits
            // destroying uncommitted/unpushed work (#4091).
            // `--merged-prs` is a THIRD, independent opt-in (#2919) enabling the
            // merged-pull-request reclaim pass. It never implies the other two.
            crate::commands::managed_merged_prs::session_prune_worktrees(
                client,
                url,
                !force,
                discard_dirty,
                merged_prs,
            )
            .await?
        }
        // #4288: the report-only inventory. No `force`/`dry_run` argument
        // exists because the verb has no destructive form.
        SessionAction::ReconcileWorktrees { json } => {
            crate::commands::reconcile_worktrees::session_reconcile_worktrees(client, url, json)
                .await?
        }
        // #2444: re-sync a live session's (or every syncable session's)
        // deployed assets against the current catalog. Fleet-wide store
        // operation like `Prune`/`DecommissionEphemeral` above — direct HTTP,
        // not chat-core.
        SessionAction::SyncAssets { id: Some(id), .. } => {
            crate::commands::sync_assets::session_sync_assets(client, url, id).await?
        }
        SessionAction::SyncAssets { id: None, .. } => {
            crate::commands::sync_assets::session_sync_assets_all(client, url).await?
        }
        // #2012: hard-delete the record; goes through direct HTTP like the
        // other fleet-teardown verbs above (not chat-core — `delete` is a
        // distinct terminal store operation, not a `decommission` alias).
        SessionAction::Delete { id, force } => {
            crate::commands::delete::session_delete(client, url, id, force).await?
        }
        // Rename a managed session. Direct HTTP (PATCH), like `delete` — a
        // distinct store+tmux mutation, not a chat-core intent.
        SessionAction::Rename { arg1, arg2 } => {
            crate::commands::rename::session_rename(client, url, arg1, arg2).await?
        }
        // The deprecated verbose aliases emit their deprecation notice, then
        // route through chat-core exactly like their canonical verb (#1205).
        action @ (SessionAction::ManagedStop { .. }
        | SessionAction::RuntimeStop { .. }
        | SessionAction::ManagedResume { .. }) => {
            emit_managed_alias_notice(&action);
            // `to_command` maps every one of these aliases; `run` therefore
            // always handles it.
            crate::commands::managed_route::run(client, url, &action).await?;
        }
        // Every remaining managed verb (`new`/`ls`/`send`/`answer`/`attach`/
        // `decommission`) routes through the shared chat-core layer. `run`
        // returns `false` only for non-managed variants, which the arms above
        // already handled — so an unrouted variant here is a wiring bug.
        action => {
            debug_assert!(
                crate::commands::managed_route::to_command(&action).is_some(),
                "unrouted session action reached the managed fallthrough: {action:?}"
            );
            crate::commands::managed_route::run(client, url, &action).await?;
        }
    }
    Ok(())
}

/// Emit the deprecation notice for a renamed managed lifecycle alias (#1205).
///
/// Why: `managed-stop`/`runtime-stop`/`managed-resume` were renamed to the
/// cleaner `stop`/`resume` family; the old spellings still parse but every
/// invocation must nudge the operator toward the canonical verb. Centralizing the
/// old→new mapping here keeps the routing arm a thin match.
/// What: writes `warning: '<old>' is deprecated; use '<new>'` to stderr for the
/// three deprecated aliases; a no-op for any other action.
/// Test: the message text is asserted by `deprecation_notice_format`; the alias
/// parse paths by `cli_parses_session_managed_stop`/`_runtime_stop`/`_managed_resume`.
fn emit_managed_alias_notice(action: &SessionAction) {
    let pair = match action {
        SessionAction::ManagedStop { .. } => Some(("managed-stop", "stop")),
        SessionAction::RuntimeStop { .. } => Some(("runtime-stop", "stop")),
        SessionAction::ManagedResume { .. } => Some(("managed-resume", "resume")),
        _ => None,
    };
    if let Some((old, new)) = pair {
        crate::commands::managed::deprecation_notice(old, new);
    }
}

/// Emit the deprecation notice for the top-level `session` (singular) alias (#2116).
///
/// Why: `tm session <verb>` is now a hidden deprecated alias of the canonical
/// `tm sessions <verb>` (DOC-35 §2.2/§3.2). Unlike [`emit_managed_alias_notice`],
/// this is a rename of the top-level NOUN, not a specific verb, so it must fire
/// exactly once per invocation regardless of which verb was invoked. `main.rs`
/// calls this from the single `Command::Session` match arm — one call site,
/// executed at most once per process — before dispatching to [`session`], the
/// same handler the canonical `Command::Sessions` arm calls. No functional
/// difference in behavior between the two arms beyond this notice.
/// What: writes `warning: 'session' is deprecated; use 'sessions'` to stderr.
/// Test: `tm_session_singular_prints_deprecation_notice_once` /
/// `tm_sessions_plural_prints_no_deprecation_notice` (integration tests,
/// `tests/tm_sessions_alias_notice.rs`) drive the real binary and assert the
/// notice appears exactly once for the singular form and not at all for the
/// plural; `top_level_alias_notice_message` in `tests.rs` asserts the exact text.
pub(crate) fn emit_top_level_alias_notice() {
    crate::commands::managed::deprecation_notice("session", "sessions");
}

/// Derive the `owner/repo` source_id from a git directory for `--current`.
///
/// Why: extracted from `derive_source_id_from_cwd` so the git-remote resolution
/// is unit-testable with a path argument rather than the process cwd (which would
/// require `std::env::set_current_dir`, a process-global, non-thread-safe call).
/// What: runs `git -C <dir> config --get remote.origin.url` and parses the result
/// via `parse_github_path`. Returns `Some("owner/repo")` on success; `None` when
/// not in a git repo or the remote URL is not a GitHub URL.
/// Test: `derive_source_id_from_cwd_returns_none_without_git` (unit).
fn derive_source_id_from_path(dir: &std::path::Path) -> Option<String> {
    let url = trusty_mpm::daemon::managed_routes::inproject::get_origin_url(dir)?;
    let gh = trusty_common::github_path::parse_github_path(&url)?;
    Some(format!("{}/{}", gh.owner, gh.repo))
}

/// Derive the `owner/repo` source_id from the process cwd for `--current`.
///
/// Why: thin wrapper over `derive_source_id_from_path` for the CLI call site;
/// separating cwd resolution from git-remote parsing keeps the impl testable.
/// What: reads `std::env::current_dir()` and delegates to `derive_source_id_from_path`.
/// Returns `Some("owner/repo")` on success; `None` on any failure (both cases silently
/// ignored — the caller treats None as "no filter").
/// Test: `derive_source_id_from_cwd_returns_none_without_git` (unit via path variant).
pub(crate) fn derive_source_id_from_cwd() -> Option<String> {
    derive_source_id_from_path(&std::env::current_dir().ok()?)
}

/// Return true when `session` matches `id_or_name` by id or tmux name.
///
/// Why: extracted from `info_from_managed_store` so the match predicate is
/// unit-testable without requiring an HTTP call.
/// What: compares `session["id"]` and `session["name"]` against `id_or_name`;
/// returns true on either match.
/// Test: `info_managed_fallback_matches_by_id_and_name`.
fn matches_session(session: &serde_json::Value, id_or_name: &str) -> bool {
    let id_match = session.get("id").and_then(|v| v.as_str()) == Some(id_or_name);
    let name_match = session.get("name").and_then(|v| v.as_str()) == Some(id_or_name);
    id_match || name_match
}

/// Fetch the managed session list and find a session matching `id_or_name`.
///
/// Why: `tm session info` queries the project-session store first; managed
/// sessions live in a separate store and return 404 there. This fallback
/// prevents the confusing "not found" message for sessions that ARE visible in
/// `tm session ls`. Non-404 HTTP errors are logged as warnings so daemon 5xx
/// responses are not silently swallowed as "not found".
/// What: GETs `/api/v1/sessions/managed`, searches by id-exact then name-exact
/// via `matches_session`, returns the first match as a `serde_json::Value`.
/// Returns `None` when the daemon is unreachable, returns a non-success status,
/// or no session matches.
/// Test: `info_managed_fallback_matches_by_id_and_name` (unit on match predicate);
/// HTTP path covered by the integration test.
async fn info_from_managed_store(
    client: &reqwest::Client,
    url: &str,
    id_or_name: &str,
) -> Option<serde_json::Value> {
    let resp = client
        .get(format!("{url}/api/v1/sessions/managed"))
        .send()
        .await
        .ok()?;
    let status = resp.status();
    if !status.is_success() {
        if status != reqwest::StatusCode::NOT_FOUND {
            tracing::warn!(
                "managed store lookup failed with HTTP {status} — \
                 'session not found' may mask a daemon error"
            );
        }
        return None;
    }
    let raw = resp.text().await.ok()?;
    let resp: serde_json::Value = serde_json::from_str(&raw).ok()?;
    let sessions = resp.get("sessions")?.as_array()?;
    sessions
        .iter()
        .find(|s| matches_session(s, id_or_name))
        .cloned()
}

/// Run the instruction merge pipeline and stash the override-resolved PM prompt.
///
/// Why: `session start` and `session instructions` both need the effective PM
/// prompt — the text actually delivered to `claude --append-system-prompt-file`.
/// The old code returned `output.merged` (the legacy pipeline: INSTRUCTIONS.md +
/// delegation authority + CLAUDE.md) for display, while stashing `resolve_pm_prompt`
/// separately. That caused `tm session instructions` to print content that differed
/// from what Claude received, which is exactly the divergence issue #382 describes.
/// The single source of truth for "what claude receives" is `resolve_pm_prompt`;
/// the display and the stash must both come from it.
/// #4832: `fw` is gone — the pipeline no longer reads a framework path, so the
/// parameter had no remaining use.
/// What: builds a [`PipelineInput`] and runs [`build_instructions`] to ensure
/// `CLAUDE.md` is seeded (the side-effect we still need); resolves the PM prompt
/// via [`crate::core::instruction_overrides::resolve_pm_prompt`]; writes it to
/// `<project>/.trusty-mpm/last-instructions.md`; returns the resolved prompt text,
/// the `PipelineOutput` metadata flags, and the stash path.
/// Test: `compose_session_instructions_display_matches_stash`,
/// `compose_session_instructions_display_matches_live_prompt`.
pub(crate) fn compose_session_instructions(
    project_dir: &std::path::Path,
) -> anyhow::Result<(
    String,
    trusty_mpm::core::instruction_pipeline::PipelineOutput,
    std::path::PathBuf,
)> {
    use trusty_mpm::core::instruction_pipeline::{PipelineInput, build_instructions};

    // Run the legacy pipeline for its side-effects: seed CLAUDE.md if absent
    // and populate the metadata flags (agent_count, claude_md_created, …).
    let input = PipelineInput {
        // #4588: the roster is resolved from the project by the one shared
        // resolver, not from a directory named here — naming one tier is what
        // made the printed count disagree with the delivered roster.
        project_dir: project_dir.to_path_buf(),
        claude_md_path: project_dir.join("CLAUDE.md"),
    };
    let output = build_instructions(&input)?;

    // The single source of truth for the live PM prompt is
    // `build_system_prompt_for`, NOT the bare `resolve_pm_prompt`. The launcher
    // applies HR-4 output-style version-fallback injection on top of the resolved
    // prompt (issue #1409), so `tm session instructions` must show — and the
    // stash must hold — that SAME injected text. Writing the pre-injection
    // `resolve_pm_prompt` here made the display/stash diverge from the real launch
    // prompt whenever `claude` was absent/old (injection fires), the same #382
    // divergence this function was written to prevent. Routing through
    // `build_system_prompt_for` keeps display, stash, and launch identical
    // regardless of Claude Code version.
    let resolved_prompt = trusty_mpm::core::session_launch::build_system_prompt_for(project_dir);
    // #4832: the harness ROOT, not `project_dir` — a worktree must never grow
    // its own `.trusty-mpm/`.
    let stash_dir = trusty_mpm::core::harness_root::harness_dir(project_dir);
    std::fs::create_dir_all(&stash_dir)?;
    let stash = stash_dir.join("last-instructions.md");
    std::fs::write(&stash, &resolved_prompt)?;

    Ok((resolved_prompt, output, stash))
}

// Unit tests live in session_tests.rs (test-file budget: 1500 SLOC).
#[cfg(test)]
#[path = "session_tests.rs"]
mod tests;