trusty-mpm 1.8.2

//! Unified daemon HTTP client.
//!
//! Why: every trusty-mpm UI (TUI, Telegram bot, CLI) is a separate process from
//! the daemon and must reach it over HTTP. Before this crate the transport was
//! reimplemented per UI; [`DaemonClient`] is the single shared wrapper so a new
//! endpoint is wired exactly once.
//! What: [`DaemonClient`] holds a base URL plus a shared `reqwest::Client` and
//! exposes one async method per daemon endpoint the UIs need — session listing
//! and lifecycle, the event feed, breaker state, the overseer / tmux / config
//! analyzer views, and the pairing handshake. `Self::new` builds that
//! `reqwest::Client` with the bounded connect/request timeouts from
//! [`config`] (issue #2471) so a daemon that accepts a TCP connection but
//! never answers cannot hang a caller forever — before this fix the TUI's
//! poll loop shared a task with keyboard input, so an unbounded hang froze
//! `q`/Ctrl-C too.
//! Test: `cargo test -p trusty-mpm-client` checks URL construction and wire-shape
//! deserialization; live HTTP is exercised by the executor tests against an
//! in-process test daemon and by the daemon's own API tests; `config`'s own
//! tests exercise the timeout bound against a stalled socket.

mod claude_config;
mod config;
pub mod deliverables;
mod error;
mod managed;
pub mod manager;
pub mod projects;
mod session_connect;
pub(crate) mod socket_routes;
// #8942: `tm fleet init`'s Architect registration.
pub mod supervisor;
#[cfg(test)]
mod tests;
// #6288 step 1: the HTTP-or-unix-socket seam every method sends through.
mod transport;
mod types;

pub use transport::{DaemonCallError, DaemonRequest, DaemonResponse, resolve_daemon_socket};

// #4488: re-exported so `connectors::tm` binds the SAME provisioning bound as
// `DaemonClient::spawn_managed_session` rather than keeping its own copy.
pub(crate) use config::PROVISION_REQUEST_TIMEOUT;

// #5830: the `tm` binary is a separate crate from this library, so the
// merged-PR survey bound is re-exported publicly for the same reason
// `default_client` below is a public seam.
pub use config::RECLAIM_SURVEY_REQUEST_TIMEOUT;

// #7313: `tm session disk` lives in the binary crate, so its per-request bound
// is re-exported publicly for the same reason the merged-PR one above is.
pub use config::DISK_SURVEY_REQUEST_TIMEOUT;

pub use types::{
    BreakerRow, ChatMessage, ConfigRecommendation, CoordinatorChatOutcome, CoordinatorContext,
    CoordinatorSession, DiscoveredProjectRow, EventRow, FleetByProjectWireResponse,
    FleetProjectGroupWire, HealthSnapshot, LastSeen, LlmChatOutcome, ManagedActivityResponse,
    ManagedAdoptRequest, ManagedAdoptResponse, ManagedAnswerRequest, ManagedAnswerResponse,
    ManagedAttachCmdResponse, ManagedDecommissionOutcome, ManagedListResponse,
    ManagedSendInputRequest, ManagedSendInputResponse, ManagedSessionSummary, ManagedSpawnRequest,
    ManagedSpawnResponse, ManagedStoreHealth, OverseerSnapshot, PairConfirm, PairRequest,
    PairStatus, SessionRow, TmuxSessionRow,
};

use serde::Deserialize;

/// Build the shared bounded-timeout `reqwest::Client` [`DaemonClient::new`] uses.
///
/// Why: issue #2517 (a live-verify gap in #2471/#2512): the `DaemonClient`
/// used by every daemon-facing UI got bounded connect/request timeouts via
/// [`config::default_client`], but the top-level `tm` CLI in
/// `bin/tm/main.rs` still minted its OWN bare `reqwest::Client::new()` for
/// the gateway-probe / `daemon_healthy` codepaths (`tm status`, `tm start`),
/// which are outside `DaemonClient` entirely. That bare client has no
/// timeout at all, so a daemon that accepts the TCP connection but never
/// answers hangs `tm status` for the OS-level socket timeout (observed
/// 55.63s) instead of the intended ~10s bound. This function is the single
/// public seam a crate-external caller — a `[[bin]]` target is a distinct
/// crate from the library even within the same package, so `pub(crate)`
/// does not reach it — can use to get the exact same bounds without
/// duplicating the constants.
/// What: delegates to [`config::default_client`] (3s connect / 10s request,
/// the same bounds `DaemonClient::new` uses).
/// Test: `config::tests::build_client_bounds_a_stalled_connection` and
/// `config::tests::default_client_uses_default_bounds` cover the underlying
/// bounds; `tests::top_level_default_client_is_bounded_against_a_stalled_daemon`
/// in this module pins that this wrapper is not just a fresh unbounded
/// client in disguise.
pub fn default_client() -> reqwest::Client {
    config::default_client()
}

/// HTTP client for one trusty-mpm daemon.
///
/// Why: a thin wrapper so any UI can be pointed at any daemon address.
/// What: holds the base URL and a shared `reqwest::Client`.
/// Test: `base_url_is_stored`.
#[derive(Debug, Clone)]
pub struct DaemonClient {
    /// Base URL of the daemon, e.g. `http://127.0.0.1:7880`.
    pub(in crate::client::http_client) base: String,
    /// Shared connection-pooling HTTP client.
    pub(in crate::client::http_client) http: reqwest::Client,
    /// The user home `launch_session` prepares under; `None` resolves the
    /// process home. #8545: only a test pins it.
    pub(in crate::client::http_client) home: Option<std::path::PathBuf>,
    /// #6288: the daemon's unix socket; `Some` means every request goes there
    /// and never to `base`/`http`.
    pub(in crate::client::http_client) socket: Option<std::path::PathBuf>,
    /// #9556: `true` when the operator named `base`; re-discovery keeps it.
    pub(in crate::client::http_client) base_url_pinned: bool,
}

impl DaemonClient {
    /// Build a client targeting `base` (e.g. `http://127.0.0.1:7880`).
    ///
    /// Why: a UI is pointed at a daemon address resolved from a flag or the
    /// service lock file. A daemon that accepted the TCP connection but never
    /// answers must not be able to hang the caller indefinitely (issue
    /// #2471) — the TUI polls this client from the same task that reads
    /// keyboard input, so an unbounded client froze `q`/Ctrl-C along with
    /// everything else.
    /// What: stores the base URL and a fresh pooled `reqwest::Client` built
    /// via [`config::default_client`] with bounded connect/request timeouts.
    /// Test: `base_url_is_stored`; the timeout bound itself is covered by
    /// `config::tests::build_client_bounds_a_stalled_connection`.
    pub fn new(base: impl Into<String>) -> Self {
        Self::with_client(config::default_client(), base)
    }

    /// Build a client targeting `base`, REUSING an existing `reqwest::Client`.
    ///
    /// Why: callers that already configured a `reqwest::Client` (custom TLS,
    /// timeouts, proxy, connection pool) must not have that configuration
    /// silently dropped by [`Self::new`] minting a fresh default client. Reusing
    /// the caller's client is cheap — `reqwest::Client` is an `Arc` internally,
    /// so cloning shares the same pool and settings.
    /// What: stores `base` and adopts the passed `client` verbatim as the HTTP
    /// transport.
    /// Test: `with_client_reuses_passed_client` asserts the base is stored and
    /// the client is adopted.
    pub fn with_client(client: reqwest::Client, base: impl Into<String>) -> Self {
        Self {
            base: base.into(),
            http: client,
            home: None,
            socket: None,
            base_url_pinned: false,
        }
    }

    /// Mark [`Self::base_url`] as operator-chosen, so TUI re-discovery keeps it.
    ///
    /// Why (#9556): a TUI started with `--url` / `TRUSTY_MPM_URL` re-resolved
    /// the daemon after one failed poll and moved to whatever daemon the lock
    /// file or the default named — under a sandbox, the live fleet.
    /// What: records `pinned`; [`Self::base_url_pinned`] reads it back. It
    /// does not stop an explicit [`Self::set_base_url`] call.
    /// Test: `rediscover_daemon_keeps_explicit_url`, `rediscover_keeps_explicit_url`.
    pub fn with_pinned_base_url(mut self, pinned: bool) -> Self {
        self.base_url_pinned = pinned;
        self
    }

    /// Whether the base URL came from the operator (#9556); see
    /// [`Self::with_pinned_base_url`].
    pub fn base_url_pinned(&self) -> bool {
        self.base_url_pinned
    }

    /// Pin the user home `launch_session` prepares under (#8545), so a test
    /// never deploys into the operator's home.
    #[cfg(test)]
    pub(crate) fn with_home(mut self, home: &std::path::Path) -> Self {
        self.home = Some(home.to_path_buf());
        self
    }

    /// The base URL this client targets.
    ///
    /// Why: tests and diagnostics need to read back the configured address.
    /// What: returns the stored base URL string.
    /// Test: `base_url_is_stored`.
    pub fn base_url(&self) -> &str {
        &self.base
    }

    /// Re-point this client at a new daemon base URL.
    ///
    /// Why: the daemon may bind a fresh ephemeral port across a restart, so a
    /// long-lived UI (the TUI) must be able to follow it to the address recorded
    /// in the lock file instead of being stuck on a stale URL and reporting
    /// "daemon unreachable" forever. The pooled `reqwest::Client` is kept; only
    /// the target address changes.
    /// What: overwrites [`Self::base`] with `base`.
    /// Test: `set_base_url_repoints_client`.
    pub fn set_base_url(&mut self, base: impl Into<String>) {
        self.base = base.into();
    }

    /// Fetch the current session list from the daemon.
    ///
    /// Why: every UI's session view refreshes from this.
    /// What: `GET /sessions`, returns the `sessions` array deserialized.
    /// Test: covered by the daemon API tests and the executor tests.
    pub async fn sessions(&self) -> anyhow::Result<Vec<SessionRow>> {
        #[derive(Deserialize)]
        struct Body {
            sessions: Vec<SessionRow>,
        }
        let url = "/sessions".to_string();
        let body: Body = self.get(&url).send().await?.json().await?;
        Ok(body.sessions)
    }

    /// Fetch the recent hook-event feed from the daemon.
    ///
    /// Why: the dashboard's event panel refreshes from this. The push-based
    /// SSE feed lives at `GET /events`; this method polls the legacy snapshot
    /// at `GET /events/poll` for callers that don't stream.
    /// What: `GET /events/poll`, returns the `events` array deserialized.
    /// Test: `events_deserialize_from_record_shape` covers the wire shape.
    pub async fn events(&self) -> anyhow::Result<Vec<EventRow>> {
        #[derive(Deserialize)]
        struct Body {
            events: Vec<EventRow>,
        }
        let url = "/events/poll".to_string();
        let body: Body = self.get(&url).send().await?.json().await?;
        Ok(body.events)
    }

    /// Fetch one session's recent hook events.
    ///
    /// Why: the `/status` command shows a session's last events. The
    /// push-based SSE feed lives at `GET /sessions/{id}/events`; this method
    /// polls the legacy snapshot at `GET /sessions/{id}/events/poll`.
    /// What: `GET /sessions/{id}/events/poll`, returns the `events` array.
    /// Test: covered by the executor's status test.
    pub async fn session_events(&self, id: &str) -> anyhow::Result<Vec<EventRow>> {
        #[derive(Deserialize)]
        struct Body {
            events: Vec<EventRow>,
        }
        let url = format!("/sessions/{id}/events/poll");
        let body: Body = self.get(&url).send().await?.json().await?;
        Ok(body.events)
    }

    /// Fetch every agent's circuit-breaker state from the daemon.
    ///
    /// Why: the dashboard's breaker panel needs the latest breaker snapshot.
    /// What: `GET /breakers`, flattening the nested `breaker` object into a
    /// flat [`BreakerRow`] per agent.
    /// Test: `breakers_deserialize_from_api_shape` covers the wire shape.
    pub async fn breakers(&self) -> anyhow::Result<Vec<BreakerRow>> {
        #[derive(Deserialize)]
        struct WireBreaker {
            state: String,
            consecutive_failures: u32,
        }
        #[derive(Deserialize)]
        struct WireRow {
            agent: String,
            breaker: WireBreaker,
        }
        #[derive(Deserialize)]
        struct Body {
            breakers: Vec<WireRow>,
        }
        let url = "/breakers".to_string();
        let body: Body = self.get(&url).send().await?.json().await?;
        Ok(body
            .breakers
            .into_iter()
            .map(|r| BreakerRow {
                agent: r.agent,
                state: r.breaker.state,
                consecutive_failures: r.breaker.consecutive_failures,
            })
            .collect())
    }

    /// Probe whether the daemon is reachable.
    ///
    /// Why: the TUI greys out its panels when the daemon is down.
    /// What: `GET /health`, true on any 2xx response.
    /// Test: covered by the daemon API tests.
    pub async fn is_healthy(&self) -> bool {
        let url = "/health".to_string();
        matches!(self.get(&url).send().await, Ok(r) if r.status().is_success())
    }

    /// Fetch the daemon's catalog-staleness flag from `GET /health` (HR-3).
    ///
    /// Why: the coordinator TUI shows an "updates available" indicator when the
    /// deployed harness content has drifted from the synced catalog (DOC-17
    /// §HR-3). It already polls health on its timer; reading the additive
    /// `catalog_stale` field reuses that one probe rather than adding a request.
    /// What: GETs `/health`, parses the JSON body, and returns `catalog_stale`.
    /// Any transport/parse failure (or an older daemon returning the legacy
    /// string body) yields `false` so the indicator degrades to "no updates"
    /// rather than erroring — staleness never blocks the TUI.
    /// Test: `coord_poll_daemon` integration is exercised against a live daemon;
    /// the parse contract (incl. the missing-field default) is covered by
    /// `catalog_stale_health_body_wire_shape`.
    pub async fn catalog_stale(&self) -> bool {
        let url = "/health".to_string();
        let Ok(resp) = self.get(&url).send().await else {
            return false;
        };
        if !resp.status().is_success() {
            return false;
        }
        #[derive(Deserialize)]
        struct HealthBody {
            #[serde(default)]
            catalog_stale: bool,
        }
        resp.json::<HealthBody>()
            .await
            .map(|b| b.catalog_stale)
            .unwrap_or(false)
    }

    /// Fetch the daemon's full `GET /health` snapshot.
    ///
    /// Why: the `health` verb needs more than the liveness boolean
    /// [`Self::is_healthy`] returns — it surfaces the daemon's liveness word and
    /// the catalog-freshness flags (HR-3) in one probe. Reading them as a typed
    /// struct keeps the verb off raw JSON indexing.
    /// What: GETs `/health`, returns the parsed [`HealthSnapshot`]. `Err` on any
    /// transport or decode failure so the caller renders the daemon as
    /// unreachable rather than panicking. Missing fields default (an older daemon
    /// returning only `status` still parses).
    /// Test: `health_snapshot_deserializes` covers the wire shape; the executor's
    /// `execute_health_*` tests exercise the live and dead-daemon paths.
    pub async fn health_snapshot(&self) -> anyhow::Result<HealthSnapshot> {
        let url = "/health".to_string();
        let snapshot = self
            .get(&url)
            .send()
            .await?
            .error_for_status()?
            .json()
            .await?;
        Ok(snapshot)
    }

    /// Fetch `GET /health` under an explicit per-request bound, keeping the
    /// transport error TYPED.
    ///
    /// Why (#6336): `tm doctor` reports daemon reachability as one check row
    /// with three outcomes — reachable, not running, unresponsive — and only a
    /// typed `reqwest::Error` can tell the last two apart (`is_connect()` means
    /// nothing is listening; anything else means something answered the socket
    /// but not the probe). [`Self::health_snapshot`] flattens both into
    /// `anyhow`, which is right for callers that only need "unreachable" and
    /// wrong for a probe whose whole job is the distinction. The explicit
    /// bound exists because doctor's probe is interactive: the client-level
    /// [`config::DEFAULT_REQUEST_TIMEOUT`] is a correctness ceiling for a
    /// wedged daemon, not a latency budget an operator waits out.
    /// What: same request as [`Self::health_snapshot`], with the per-request
    /// timeout overriding the client default for this call only. A failure
    /// after the connection existed (non-2xx, undecodable body) is
    /// [`DaemonCallError::Failed`]; #6288: over the socket, an absent or
    /// refusing socket is [`DaemonCallError::Unreachable`], naming the path.
    /// Test: `daemon_probe_reports_not_running_when_nothing_listens`
    /// (`src/bin/tm/commands/doctor_daemon_row_tests.rs`).
    pub async fn health_snapshot_within(
        &self,
        timeout: std::time::Duration,
    ) -> Result<HealthSnapshot, DaemonCallError> {
        let resp = self.get("/health").timeout(timeout).send().await?;
        let failed = |source: anyhow::Error| DaemonCallError::Failed {
            target: self.transport_label(),
            source,
        };
        resp.error_for_status()
            .map_err(failed)?
            .json()
            .await
            .map_err(failed)
    }

    /// Pause a session via `POST /sessions/{id}/pause`.
    ///
    /// Why: the dashboard's `p` key pauses the selected session in place.
    /// What: POSTs `{"summary": null}` and returns the `summary` field.
    /// Test: live HTTP is covered by the daemon's session-lifecycle tests.
    pub async fn pause_session(&self, id: &str) -> anyhow::Result<String> {
        let url = format!("/sessions/{id}/pause");
        let body: serde_json::Value = self
            .post(&url)
            .json(&serde_json::json!({ "summary": serde_json::Value::Null }))
            .send()
            .await?
            .error_for_status()?
            .json()
            .await?;
        Ok(body
            .get("summary")
            .and_then(|v| v.as_str())
            .unwrap_or("")
            .to_string())
    }

    /// Resume a session via `POST /sessions/{id}/resume`.
    ///
    /// Why: the dashboard's `r` key resumes the selected paused session.
    /// What: POSTs to the resume endpoint and discards the response body.
    /// Test: live HTTP is covered by the daemon's session-lifecycle tests.
    pub async fn resume_session(&self, id: &str) -> anyhow::Result<()> {
        let url = format!("/sessions/{id}/resume");
        self.post(&url).send().await?.error_for_status()?;
        Ok(())
    }

    /// Stop a session via `DELETE /sessions/{id}`.
    ///
    /// Why: the dashboard's `x` key and the `/kill` command stop a session.
    /// What: sends a DELETE to the session endpoint; returns `Ok(true)` when the
    /// session existed, `Ok(false)` on a 404, `Err` on transport failure.
    /// Test: covered by the executor's kill test.
    pub async fn kill_session(&self, id: &str) -> anyhow::Result<bool> {
        let url = format!("/sessions/{id}");
        let resp = self.delete(&url).send().await?;
        if resp.status() == reqwest::StatusCode::NOT_FOUND {
            return Ok(false);
        }
        resp.error_for_status()?;
        Ok(true)
    }

    /// Stop a session, discarding the found/missing distinction.
    ///
    /// Why: the TUI's `x` key only needs success-or-error feedback.
    /// What: calls [`Self::kill_session`] and maps the result to `()`.
    /// Test: covered by the executor's kill test.
    pub async fn stop_session(&self, id: &str) -> anyhow::Result<()> {
        self.kill_session(id).await.map(|_| ())
    }

    /// Capture recent session output via `GET /sessions/{id}/output`.
    ///
    /// Why: the dashboard's `o` key snapshots the selected session's pane.
    /// What: `GET /sessions/{id}/output?lines={lines}`, returns the `output`
    /// field from the 200 response.
    /// Test: live HTTP is covered by the daemon's session-lifecycle tests.
    pub async fn session_output(&self, id: &str, lines: u32) -> anyhow::Result<String> {
        let url = format!("/sessions/{id}/output");
        let body: serde_json::Value = self
            .get(&url)
            .query(&[("lines", lines)])
            .send()
            .await?
            .error_for_status()?
            .json()
            .await?;
        Ok(body
            .get("output")
            .and_then(|v| v.as_str())
            .unwrap_or("")
            .to_string())
    }

    /// Send a command into a session's tmux pane via `POST /sessions/{id}/command`.
    ///
    /// Why: the Telegram `/send` command and the TUI's `/send` drive a running
    /// Claude Code session remotely — type a prompt, read back the pane.
    /// What: POSTs `{ command }`; returns `Ok(Some(output))` with the captured
    /// pane text on success, `Ok(None)` when the session is unknown (`404`), and
    /// `Err` on transport failure.
    /// Test: covered by the daemon's session-command tests.
    pub async fn send_session_command(
        &self,
        id: &str,
        command: &str,
    ) -> anyhow::Result<Option<String>> {
        let url = format!("/sessions/{id}/command");
        let resp = self
            .post(&url)
            .json(&serde_json::json!({ "command": command }))
            .send()
            .await?;
        if resp.status() == reqwest::StatusCode::NOT_FOUND {
            return Ok(None);
        }
        let body: serde_json::Value = resp.error_for_status()?.json().await?;
        Ok(Some(
            body.get("output")
                .and_then(|v| v.as_str())
                .unwrap_or("")
                .to_string(),
        ))
    }

    /// Fetch the overseer status via `GET /overseer`.
    ///
    /// Why: the `/overseer` command reports oversight status.
    /// What: returns the enabled flag, handler name, and decision counts.
    /// Test: covered by the executor's overseer test.
    pub async fn overseer_status(&self) -> anyhow::Result<OverseerSnapshot> {
        let url = "/overseer".to_string();
        let body: serde_json::Value = self.get(&url).send().await?.json().await?;
        let o = &body["overseer"];
        let decisions = &o["decisions"];
        Ok(OverseerSnapshot {
            enabled: o["enabled"].as_bool().unwrap_or(false),
            handler: o["handler"].as_str().unwrap_or("?").to_string(),
            decisions: (
                decisions["allow"].as_u64().unwrap_or(0),
                decisions["block"].as_u64().unwrap_or(0),
                decisions["flag"].as_u64().unwrap_or(0),
            ),
        })
    }

    /// List every tmux session on the daemon host via `GET /tmux/sessions`.
    ///
    /// Why: the `/tmux` command lists internal and external tmux sessions and
    /// flags which are already managed so it can offer to adopt the rest.
    /// What: returns one [`TmuxSessionRow`] per session; the daemon payload may
    /// be plain strings or origin-tagged objects, both of which are accepted. A
    /// session is `managed` when its `origin` field is `trusty_mpm`.
    /// Test: `tmux_session_row_accepts_name`.
    pub async fn tmux_sessions(&self) -> anyhow::Result<Vec<TmuxSessionRow>> {
        let url = "/tmux/sessions".to_string();
        let body: serde_json::Value = self.get(&url).send().await?.json().await?;
        let sessions = body["sessions"].as_array().cloned().unwrap_or_default();
        Ok(sessions
            .iter()
            .filter_map(|s| {
                let name = s
                    .get("name")
                    .and_then(|v| v.as_str())
                    .or_else(|| s.as_str())?;
                let managed = s.get("origin").and_then(|v| v.as_str()) == Some("trusty_mpm");
                Some(TmuxSessionRow {
                    name: name.to_string(),
                    managed,
                })
            })
            .collect())
    }

    /// Discover Claude Code projects via `GET /projects/discover`.
    ///
    /// Why: the `/projects` command lists projects mined from
    /// `~/.claude/projects/` so an operator can register one without typing a
    /// path.
    /// What: `GET /projects/discover`, returns the `projects` array deserialized
    /// into [`DiscoveredProjectRow`]s.
    /// Test: covered by the executor's projects test.
    pub async fn discover_projects(&self) -> anyhow::Result<Vec<DiscoveredProjectRow>> {
        #[derive(Deserialize)]
        struct Body {
            #[serde(default)]
            projects: Vec<DiscoveredProjectRow>,
        }
        let url = "/projects/discover".to_string();
        let body: Body = self.get(&url).send().await?.json().await?;
        Ok(body.projects)
    }

    /// Register a project via `POST /projects`.
    ///
    /// Why: the `/projects` keyboard's "Set Active" button registers a
    /// discovered project with the daemon.
    /// What: POSTs `{"path": <path>}`; returns `Ok(())` on a 2xx response.
    /// Test: covered by the executor's projects test.
    pub async fn register_project(&self, path: &str) -> anyhow::Result<()> {
        let url = "/projects".to_string();
        self.post(&url)
            .json(&serde_json::json!({ "path": path }))
            .send()
            .await?
            .error_for_status()?;
        Ok(())
    }

    /// Capture a tmux pane snapshot via `GET /tmux/sessions/{name}/snapshot`.
    ///
    /// Why: the `/snapshot` command shows a tmux pane's recent output.
    /// What: returns the snapshot text, or `Ok(None)` when the session is
    /// unknown / tmux is unavailable (the daemon answers 404).
    /// Test: covered by the daemon's tmux tests.
    pub async fn snapshot_tmux_session(&self, name: &str) -> anyhow::Result<Option<String>> {
        let url = format!("/tmux/sessions/{name}/snapshot");
        let resp = self.get(&url).send().await?;
        if !resp.status().is_success() {
            return Ok(None);
        }
        let body: serde_json::Value = resp.json().await?;
        Ok(Some(snapshot_text(&body["snapshot"])))
    }

    /// Adopt an external tmux session via `POST /tmux/adopt`.
    ///
    /// Why: brings a session trusty-mpm did not create under oversight.
    /// What: POSTs the session name; returns `Ok(true)` on success, `Ok(false)`
    /// when the session was not found.
    /// Test: covered by the daemon's tmux tests.
    pub async fn adopt_tmux_session(&self, name: &str) -> anyhow::Result<bool> {
        let url = "/tmux/adopt".to_string();
        let resp = self
            .post(&url)
            .json(&serde_json::json!({ "session": name }))
            .send()
            .await?;
        Ok(resp.status().is_success())
    }

    /// Auto-discover tmux sessions running Claude Code via
    /// `POST /sessions/discover`.
    ///
    /// Why: the `/discover` command (TUI and Telegram) triggers a daemon scan
    /// of every tmux pane and adopts the ones running Claude Code.
    /// What: POSTs to `/sessions/discover`; returns the count of newly-adopted
    /// sessions reported by the daemon.
    /// Test: `discover_sessions_returns_count` in the daemon's `api_tests.rs`.
    pub async fn discover_sessions(&self) -> anyhow::Result<usize> {
        let url = "/sessions/discover".to_string();
        let body: serde_json::Value = self
            .post(&url)
            .send()
            .await?
            .error_for_status()?
            .json()
            .await?;
        Ok(body
            .get("discovered")
            .and_then(serde_json::Value::as_u64)
            .unwrap_or(0) as usize)
    }

    /// Request a one-time pairing code via `POST /pair/request`.
    ///
    /// Why: `tm pair` asks the local daemon for a code to type into the bot.
    /// What: POSTs an empty body; returns the generated code and its TTL.
    /// Test: covered by the executor's pairing test.
    pub async fn pair_request(&self) -> anyhow::Result<PairRequest> {
        let url = "/pair/request".to_string();
        let body: PairRequest = self
            .post(&url)
            .send()
            .await?
            .error_for_status()?
            .json()
            .await?;
        Ok(body)
    }

    /// Confirm a pairing code via `POST /pair/confirm`.
    ///
    /// Why: the bot's `/pair <code>` flow registers its chat with the daemon.
    /// What: POSTs the code and chat id; returns the success / error result.
    /// Test: covered by the executor's pairing test.
    pub async fn pair_confirm(&self, code: &str, chat_id: i64) -> anyhow::Result<PairConfirm> {
        let url = "/pair/confirm".to_string();
        let body: PairConfirm = self
            .post(&url)
            .json(&serde_json::json!({ "code": code, "chat_id": chat_id }))
            .send()
            .await?
            .json()
            .await?;
        Ok(body)
    }

    /// Send a chat message to the daemon's LLM assistant via `POST /llm/chat`.
    ///
    /// Why: free-text Telegram messages and the TUI's `/chat` command route to
    /// the daemon's conversational endpoint; the UI owns the rolling history
    /// and threads it through each turn. The daemon answers synchronously
    /// only after its own upstream LLM round trip completes, which is bounded
    /// at up to 120s (`OPENROUTER_REQUEST_TIMEOUT_SECS` in
    /// `trusty_common::chat::openai_compat::providers`) — [`config::DEFAULT_REQUEST_TIMEOUT`]
    /// would abort a legitimate slow completion before the daemon's own
    /// timeout even fires, so this call opts into
    /// [`config::CHAT_REQUEST_TIMEOUT`] instead (issue #2471's audit of
    /// long-running endpoints).
    /// What: POSTs `{ message, history }` with the chat-scoped request
    /// timeout; returns `Ok(Some(outcome))` with the reply and updated
    /// history on success, `Ok(None)` when the daemon answers `503` (LLM chat
    /// not configured), and `Err` on transport failure.
    /// Test: `llm_chat_response_deserializes` covers the wire shape.
    pub async fn llm_chat(
        &self,
        message: &str,
        history: &[ChatMessage],
    ) -> anyhow::Result<Option<LlmChatOutcome>> {
        let url = "/llm/chat".to_string();
        let resp = self
            .post(&url)
            .json(&serde_json::json!({ "message": message, "history": history }))
            .timeout(config::CHAT_REQUEST_TIMEOUT)
            .send()
            .await?;
        if resp.status() == reqwest::StatusCode::SERVICE_UNAVAILABLE {
            return Ok(None);
        }
        let outcome: LlmChatOutcome = resp.error_for_status()?.json().await?;
        Ok(Some(outcome))
    }

    /// Fetch the cross-session coordinator snapshot.
    ///
    /// Why: the TUI/GUI coordinator sidebar refreshes its session list from the
    /// daemon's activity snapshot — every session with its status and a
    /// recent-output excerpt.
    /// What: `GET /api/v1/sessions/context`, returns the deserialized
    /// [`CoordinatorContext`]; `Err` on a transport or decode failure.
    /// Test: `coordinator_context_deserializes` covers the wire shape.
    pub async fn coordinator_context(&self) -> anyhow::Result<CoordinatorContext> {
        let url = "/api/v1/sessions/context".to_string();
        let context = self
            .get(&url)
            .send()
            .await?
            .error_for_status()?
            .json()
            .await?;
        Ok(context)
    }

    /// Send a message to the cross-session coordinator.
    ///
    /// Why: the coordinator is the operator's one conversational surface over
    /// every session — a `@prefix:` message routes a command at a named
    /// session, a plain message is answered by the LLM with full session
    /// context, and when `actions` is `true` the session-manager may invoke
    /// managed-session verbs INLINE (#1283) so natural language can DRIVE the
    /// fleet, not merely describe it. The UI owns the rolling chat history and
    /// threads it through.
    /// What: POSTs `{ message, history, actions }` to `/api/v1/sessions/chat`;
    /// the `actions` flag opts into the action-capable SM branch. Returns
    /// `Ok(Some(outcome))` on success, `Ok(None)` when the daemon answers `503`
    /// (LLM not configured for a non-prefixed message), and `Err` on transport
    /// failure. On the action path the outcome's `actions_taken` lists any verbs
    /// that ran. Like [`Self::llm_chat`], this waits on the daemon's own
    /// upstream LLM round trip (up to 120s), so it opts into
    /// [`config::CHAT_REQUEST_TIMEOUT`] rather than the shorter client
    /// default (issue #2471).
    /// Test: `coordinator_chat_outcome_deserializes`,
    /// `coordinator_chat_serializes_actions_flag` cover the wire shape.
    pub async fn coordinator_chat(
        &self,
        message: &str,
        history: &[ChatMessage],
        actions: bool,
    ) -> anyhow::Result<Option<CoordinatorChatOutcome>> {
        let url = "/api/v1/sessions/chat".to_string();
        let resp = self
            .post(&url)
            .json(&coordinator_chat_body(message, history, actions))
            .timeout(config::CHAT_REQUEST_TIMEOUT)
            .send()
            .await?;
        if resp.status() == reqwest::StatusCode::SERVICE_UNAVAILABLE {
            return Ok(None);
        }
        let outcome: CoordinatorChatOutcome = resp.error_for_status()?.json().await?;
        Ok(Some(outcome))
    }

    /// Query pairing status via `GET /pair/status`.
    ///
    /// Why: the `/start` command branches on whether the daemon is paired.
    /// What: `GET /pair/status`, returns the paired flag and chat id.
    /// Test: covered by the executor's pairing test.
    pub async fn pair_status(&self) -> anyhow::Result<PairStatus> {
        let url = "/pair/status".to_string();
        let body: PairStatus = self.get(&url).send().await?.json().await?;
        Ok(body)
    }

    /// Run the full system diagnostic via `GET /api/v1/doctor`.
    ///
    /// Why: the `tm doctor` CLI command and the Telegram `/doctor` command both
    /// need the daemon's verdict on whether the trusty-mpm stack is correctly
    /// wired; this is the one transport call behind both.
    /// What: `GET /api/v1/doctor`, passing the caller's `project` path so the
    /// daemon can scope the instruction-pipeline probe. Returns the parsed
    /// [`DoctorReport`](crate::client::DoctorReport); `Err` on a transport or decode failure.
    ///
    /// #5111: carries [`config::DOCTOR_REQUEST_TIMEOUT`] rather than the
    /// client-level default. The handler runs the full check battery inline and
    /// measured 10.2–10.3s here, so the 10s default hung up on a healthy daemon
    /// and every caller reported it unreachable.
    /// Test: covered by the executor's doctor test.
    pub async fn doctor(
        &self,
        project: Option<&str>,
    ) -> anyhow::Result<crate::core::doctor::DoctorReport> {
        let url = "/api/v1/doctor".to_string();
        let mut request = self.get(&url).timeout(config::DOCTOR_REQUEST_TIMEOUT);
        if let Some(project) = project {
            request = request.query(&[("project", project)]);
        }
        let report = request.send().await?.error_for_status()?.json().await?;
        Ok(report)
    }
}

/// Build the `POST /api/v1/sessions/chat` request body.
///
/// Why: extracting the body shape from [`DaemonClient::coordinator_chat`] makes
/// the `actions` opt-in serializable and unit-testable without a live HTTP
/// round-trip — the wire contract is what the daemon's
/// `CoordinatorChatRequest` reads, so it must be pinned by a test.
/// What: returns a JSON object with `message`, `history`, and the `actions`
/// boolean (the flag that routes the action-capable SM branch when `true`).
/// Test: `coordinator_chat_serializes_actions_flag`.
fn coordinator_chat_body(
    message: &str,
    history: &[ChatMessage],
    actions: bool,
) -> serde_json::Value {
    serde_json::json!({
        "message": message,
        "history": history,
        "actions": actions,
    })
}

/// Render a tmux snapshot JSON value as a flat text block.
///
/// Why: the daemon's snapshot payload may be a plain string or an object with a
/// `content` / `lines` field; a UI needs a single string.
/// What: returns the string form, joining a `lines` array if present.
/// Test: covered indirectly by `snapshot_tmux_session`.
pub(crate) fn snapshot_text(snapshot: &serde_json::Value) -> String {
    if let Some(s) = snapshot.as_str() {
        return s.to_string();
    }
    if let Some(content) = snapshot.get("content").and_then(|v| v.as_str()) {
        return content.to_string();
    }
    if let Some(lines) = snapshot.get("lines").and_then(|v| v.as_array()) {
        return lines
            .iter()
            .filter_map(|l| l.as_str())
            .collect::<Vec<_>>()
            .join("\n");
    }
    snapshot.to_string()
}