trusty-mpm 1.8.2

//! Daemon HTTP API.
//!
//! Why: the CLI, TUI, and Telegram bot are separate processes; they need a
//! transport to the daemon. HTTP/JSON over a loopback port is simple, debuggable
//! with `curl`, and lets the universal hook relay receive events from a tiny
//! forwarder shim with no client library.
//! What: builds the axum [`Router`] — health, session listing, the hook-event
//! relay endpoint, the live event feed, and the per-agent breaker view. State
//! is injected as `Arc<DaemonState>` via axum's `State` extractor.
//! Test: `cargo test -p trusty-mpm-daemon` drives the handlers directly with an
//! in-memory state (no socket bind needed).

use std::{convert::Infallible, path::PathBuf, sync::Arc, time::Duration};

use axum::{
    Json, Router,
    extract::{Path, Query, State},
    response::sse::{Event, KeepAlive, Sse},
    routing::{get, post},
};
use futures::Stream;
use tokio_stream::StreamExt;
use tokio_stream::wrappers::BroadcastStream;
#[cfg(feature = "swagger-ui")]
use utoipa::OpenApi;
#[cfg(feature = "swagger-ui")]
use utoipa_swagger_ui::SwaggerUi;

use crate::core::compress::CompressionLevel;
use crate::core::hook::HookEvent;
use crate::core::project::ProjectInfo;
use crate::core::session::Session;

use super::error::DaemonError;
// #6288: the transport-neutral bodies these handlers and the socket's
// `mpm.*` methods both call. One route, one implementation.
use super::rpc::core_ops;
// #6288 slice 3: the shared bodies for the legacy session, hook, and polled
// event routes. Every handler below is a thin adapter over one of them.
use super::rpc::sessions_legacy_ops as sessions_ops;
use super::state::DaemonState;

/// The SESSCTL control-plane routes (`/api/v1/control/sessions/*`, WI-2 #1593).
///
/// Why: the SESSCTL Phase 2 handlers are a cohesive cluster; keeping them in a
/// sibling module mirrors `coordinator_routes` and keeps `api.rs` focused on
/// routing only.
/// What: five handlers wired to `DaemonState::session_registry` (run, connect,
/// stop, auth, list). Re-exported so `router` refers to them unqualified.
/// Test: `control_routes::tests`.
pub mod control_routes;
pub use control_routes::{
    ctl_auth_session, ctl_connect_session, ctl_list_sessions, ctl_run_session, ctl_stop_session,
};

/// The Claude Code configuration analyzer routes (`/claude-config/*`).
///
/// Why: that endpoint cluster is cohesive and large; keeping it in its own
/// module keeps `api.rs` focused on the core session / hook / tmux surface.
/// The handlers are re-exported below so `router` and `openapi.rs` can keep
/// referring to them as `super::api::<handler>`.
pub mod claude_config_routes;
pub use claude_config_routes::*;

/// `SessionStart`/`SessionEnd` hook correlation (#1744, #4337).
///
/// Why: this cluster grew the #4337 subagent-overwrite guard + stale-id
/// re-sync logic past what `api.rs`'s frozen 1272-SLOC allowlist budget
/// (`.line-cap-allowlist.tsv`) could absorb. It is cohesive and
/// self-contained — both hook handlers are called only from `ingest_hook`
/// below — so it moves out, mirroring `control_routes`/`claude_config_routes`.
/// `pub(crate)` since #6288 slice 3: `ingest_hook`'s body now lives in
/// `daemon::rpc::sessions_legacy_ops` so the socket and HTTP share it, and that
/// module is outside `daemon::api`. Still not `pub` — nothing outside this
/// crate calls these handlers.
pub(crate) mod session_start_correlation;
// Only `api_tests.rs` (via `use super::*;`) calls this directly — a plain
// `use` would be flagged `unused_imports` on the non-test lib target.
#[cfg(test)]
use session_start_correlation::session_end_pane_still_live;
// #6288 slice 3: `SessionId` left this file with the handler bodies that named
// it. `api_tests.rs` still reaches it through `use super::*;` — and imports
// `ControlModel`/`SessionStatus`/`TmuxService` itself — so this one name keeps
// the same `cfg(test)` treatment as the import above.
#[cfg(test)]
use crate::core::session::SessionId;

/// The cross-session coordinator routes (`/api/v1/sessions/context` + `/chat`).
///
/// Why: the coordinator's context and chat endpoints form their own cohesive
/// cluster; keeping them in a sibling module mirrors `claude_config_routes` and
/// keeps `api.rs` focused on the core session / hook / tmux surface. As of #1392
/// these endpoints live under the plural `/api/v1/sessions/*` namespace (the
/// former `/api/v1/coordinator/*` paths are removed); the internal module and
/// handler names keep the `coordinator_` prefix for continuity.
/// The handlers are re-exported so `router` can refer to them as
/// `super::api::<handler>`.
pub mod coordinator_routes;
pub use coordinator_routes::*;

/// The Web control-surface route (`GET /web`, DOC-20 §6 Phase 2 / ONB-3).
///
/// Why: ONB-3 names a Web control surface as a peer of the TUI/Telegram
/// adapters. It is a *thin* presentation layer — a single static browser chat
/// page that drives the EXISTING action-capable `POST /api/v1/sessions/chat`
/// endpoint — so it embeds no session logic. Keeping it in a sibling module
/// mirrors `coordinator_routes` and keeps `api.rs` focused.
/// What: the `web_chat_page` handler (serves the embedded page); re-exported so
/// `router` refers to it as `super::api::web_chat_page`.
/// Test: `web_routes::web_chat_tests` drives the page and the `/web` route.
pub mod web_routes;
pub use web_routes::*;

/// The CSRF/origin guard for the browser-facing, action-capable chat endpoint.
///
/// Why: the Web surface (`GET /web`) drives the state-mutating
/// `POST /api/v1/sessions/chat` with `actions: true` from a browser; without an
/// origin check a malicious cross-origin page could trigger session actions if
/// the daemon were reachable off loopback. Keeping the policy in a sibling module
/// makes it unit-testable in isolation and keeps `coordinator_routes` thin.
/// What: re-exports [`origin_guard::origin_allowed`] so `coordinator_chat` can
/// gate on it.
/// Test: `origin_guard::origin_guard_tests`.
pub mod origin_guard;
pub use origin_guard::origin_allowed;

/// The loopback-only JSON-RPC dispatch endpoint (`POST /rpc`, #1221).
///
/// Why: the `serve --stdio` bridge forwards MCP JSON-RPC envelopes to the durable
/// daemon over this internal channel. It is gated to loopback peers only (the
/// #1221 hard requirement) so a future `0.0.0.0` rebind cannot expose the tool
/// surface. Keeping it in a sibling module mirrors `coordinator_routes` and keeps
/// `api.rs` focused.
pub mod rpc;
pub use rpc::rpc_handler;

/// The router-wide server-side request deadline (#8476).
///
/// Why: no route had a server-side bound, so a stalled handler held its
/// connection until the caller gave up.
/// What: the `from_fn` middleware [`router`] layers over every route, and the
/// per-route deadline table.
/// Test: `request_deadline::tests`.
pub mod request_deadline;

/// The Deliverable/Milestone CRUD routes (`/api/v1/projects/{name}/deliverables`
/// and `.../milestones`, DOC-35 §10.2/§10.5; #2378 + #2380).
///
/// Why: the Deliverable/Milestone ledger is exposed over the same HTTP surface
/// as every other subsystem so any consumer (CLI #2381, TUI #2383, `tm manager`
/// #2109) reads and mutates it deterministically. Keeping the handlers in a
/// sibling module mirrors `coordinator_routes` and keeps `api.rs` focused on
/// routing. The §10.3 status state machine is enforced inside these handlers
/// (#2380). The handlers are re-exported so `router` refers to them unqualified.
/// Test: `deliverable_routes::tests`.
pub mod deliverable_routes;
pub use deliverable_routes::{
    create_deliverable, create_milestone, get_deliverable, get_milestone, list_deliverables,
    list_milestones, patch_deliverable, patch_milestone,
};

/// The managed session-manager routes (`/api/v1/sessions/managed/*`).
///
/// Why: the managed-session API is a cohesive cluster (spawn, list, get,
/// send, answer, attach-cmd, stop/runtime-stop/resume/decommission, activity).
/// The handlers live in [`crate::daemon::managed_routes`]; importing them here
/// lets `router` refer to them unqualified, mirroring the `coordinator_routes`
/// wiring.
use super::managed_routes::{
    adopt_existing_session, answer_session_decision, decommission_ephemeral_route,
    decommission_managed_session, delete_managed_session, fleet_by_project_route, get_attach_cmd,
    get_managed_session, get_project_registry_route, get_session_activity, list_managed_sessions,
    list_projects_registry_route, patch_project_registry_route, project_status_route, proxy_router,
    prune_managed_route, reactivate_managed_session, register_project_registry_route,
    rename_managed_session, resume_managed_session, send_to_session, spawn_session,
    stop_managed_session, stop_managed_session_runtime,
};
// Layer-3 portfolio manager surface (`/api/v1/manager/*`, epic #2109, DOC-36),
// and the peer message bus (`/api/v1/bus/*`, DOC-60 §5.3) — both self-contained
// sub-routers owned by their own modules, so their handlers live beside the
// state they operate on. Test: `daemon::bus::tests`.
use super::{bus::routes::bus_router, manager::manager_router};

/// Typed HTTP response bodies for every endpoint.
///
/// Why: keeping the response structs in their own module keeps `api.rs`
/// focused on routing and handler logic. Re-exported so handlers and tests
/// refer to them as `super::api::<Type>`.
pub mod types;
pub use types::*;

/// Build the daemon's HTTP router with shared state injected.
///
/// Why: one place wires every route so `main` stays a thin bootstrap.
/// What: returns an axum `Router` already carrying `Arc<DaemonState>`.
/// Test: `health_endpoint_responds` and the hook-relay tests call handlers via
/// this router's logic.
pub fn router(state: Arc<DaemonState>) -> Router {
    let router = Router::new()
        .route("/health", get(health))
        .route("/sessions", get(list_sessions).post(register_session))
        .route("/api/v1/sessions/connect", post(connect_session))
        .route("/sessions/dead", axum::routing::delete(reap_sessions))
        .route("/sessions/discover", post(discover_sessions))
        .route("/sessions/{id}", get(get_session).delete(remove_session))
        .route("/sessions/{id}/events", get(stream_session_events))
        .route("/sessions/{id}/events/poll", get(session_events))
        .route("/sessions/{id}/pause", post(pause_session))
        .route("/sessions/{id}/resume", post(resume_session))
        .route("/sessions/{id}/command", post(send_command))
        .route("/sessions/{id}/output", get(get_output))
        .route("/sessions/{id}/pane", get(get_output))
        .route("/sessions/{id}/pid", axum::routing::patch(set_session_pid))
        .route("/projects", get(list_projects).post(register_project))
        .route("/projects/current", get(current_project))
        .route("/projects/discover", get(discover_projects))
        // #2114 (DOC-35 §4): registry-B project HTTP surface — the plain-HTTP
        // list/register/get/patch the deterministic `tm projects` CLI (#2115)
        // and `tm projects config` field editor (#2120) call, mirroring the
        // `project_list`/`project_register`/`project_get` MCP tools. The bare
        // `/api/v1/projects` collection route is registered here; the `{name}`
        // point-lookup/PATCH sits below the more specific `/status` and
        // `/deliverables` param routes (matchit disambiguates by segment count).
        .route(
            "/api/v1/projects",
            get(list_projects_registry_route).post(register_project_registry_route),
        )
        .route(
            "/api/v1/projects/{name}",
            get(get_project_registry_route).patch(patch_project_registry_route),
        )
        // #2117 (DOC-35 §4.1): deterministic project status-aggregation rollup —
        // session-state histogram + most-recent activity + config-completeness
        // flags for ONE named project. Pure composition over ProjectRegistry::get
        // + SessionManager::list; no LLM, no cross-project reasoning (§11).
        .route("/api/v1/projects/{name}/status", get(project_status_route))
        .route("/events", get(stream_events))
        .route("/events/poll", get(recent_events))
        .route("/hooks", post(ingest_hook))
        .route("/breakers", get(breakers))
        .route("/optimizer", get(get_optimizer))
        .route("/overseer", get(get_overseer))
        .route("/llm/chat", post(llm_chat))
        // #1392: the cross-session coordinator surface lives under the plural
        // `/api/v1/sessions/*` namespace (unified with `/sessions/managed/*`);
        // the former `/api/v1/coordinator/*` paths are removed. The descriptive
        // leaves (`context`, `chat`) avoid colliding with the managed-session
        // routes below.
        .route("/api/v1/sessions/context", get(coordinator_context))
        // Use the shared `COORDINATOR_CHAT_PATH` constant so the registered route
        // and the browser Web adapter (`web_chat.html`) can never drift (#1503).
        .route(COORDINATOR_CHAT_PATH, post(coordinator_chat))
        // DOC-14 D0.1: `/session-manager/*` aliases resolve to the SAME handlers
        // as the session context/chat endpoints; these are the canonical SM names.
        .route("/api/v1/session-manager/context", get(coordinator_context))
        .route("/api/v1/session-manager/chat", post(coordinator_chat))
        // DOC-20 §6 Phase 2 / ONB-3: the Web control surface — a static browser
        // chat page that drives the action-capable `/api/v1/sessions/chat`
        // endpoint above. Thin adapter; no new session logic.
        .route("/web", get(web_chat_page))
        .route("/tmux/sessions", get(list_tmux_sessions))
        .route("/tmux/sessions/{name}/snapshot", get(tmux_snapshot))
        .route("/tmux/adopt", post(adopt_tmux_session))
        .route("/claude-config", get(get_claude_config))
        .route("/claude-config/apply", post(apply_claude_config))
        .route("/claude-config/restart", post(restart_claude_code))
        .route(
            "/claude-config/checkpoints",
            get(list_checkpoints).post(create_checkpoint),
        )
        .route(
            "/claude-config/checkpoints/{id}",
            axum::routing::delete(delete_checkpoint),
        )
        .route("/claude-config/restore", post(restore_checkpoint))
        .route("/claude-config/profiles", get(list_profiles))
        .route("/claude-config/deploy", post(deploy_profile))
        // The four `/pair/*` verbs and the #4480 delegation query live in
        // sibling sub-routers: this file is grandfathered over the SLOC cap at a
        // frozen budget, so a new route may not simply be appended here.
        .merge(super::pairing_routes::router())
        .merge(super::delegation_routes::router())
        // #6892: the machine-wide builder-slot claim, a sibling sub-router for
        // the same line-cap reason.
        .merge(super::builder_slot_routes::router())
        .route("/api/v1/doctor", get(doctor))
        .route("/api/v1/errors", get(list_errors))
        .route("/api/v1/report-bug", post(report_bug_http))
        // WI-2 #1593: SESSCTL control-plane routes. All literal `/run` and
        // `/{id}/*` leaves are registered before any `managed/{id}` param route
        // so they are never captured as managed-session IDs.
        .route("/api/v1/control/sessions", get(ctl_list_sessions))
        .route("/api/v1/control/sessions/run", post(ctl_run_session))
        .route(
            "/api/v1/control/sessions/{id}/connect",
            post(ctl_connect_session),
        )
        .route("/api/v1/control/sessions/{id}/stop", post(ctl_stop_session))
        .route("/api/v1/control/sessions/{id}/auth", get(ctl_auth_session))
        .route(
            "/api/v1/sessions/managed",
            post(spawn_session).get(list_managed_sessions),
        )
        // #1433: adopt an EXISTING tmux session into the managed store. The literal
        // `/adopt` segment is registered BEFORE the `/{id}` param route so it is
        // never captured as an id (axum prefers literal matches, but ordering here
        // makes the intent explicit). Distinct from the stateless `/tmux/adopt`.
        .route(
            "/api/v1/sessions/managed/adopt",
            post(adopt_existing_session),
        )
        // #1508: bulk teardown + by-state prune. Both literal segments are
        // registered BEFORE the `/{id}` param route so they are never captured as
        // an id (mirroring the `/adopt` ordering above).
        .route(
            "/api/v1/sessions/managed/decommission-ephemeral",
            post(decommission_ephemeral_route),
        )
        .route("/api/v1/sessions/managed/prune", post(prune_managed_route))
        // #1840 orphaned-worktree prune + #4288 report-only reconcile, owned as
        // a pair by `managed_routes::reconcile`. Both are literal segments, so
        // they are matched ahead of the `/{id}` param route below.
        .merge(super::managed_routes::reconcile::worktree_routes())
        // #8942: literal `/supervisor`, the Architect's registration.
        .merge(super::managed_routes::supervisor::supervisor_routes())
        // #1586: fleet-by-project view. Literal `/fleet` registered BEFORE the
        // `/{id}` param route so it is never captured as an id (axum prefers
        // literal matches, but ordering makes the intent explicit).
        .route(
            "/api/v1/sessions/managed/fleet",
            get(fleet_by_project_route),
        )
        .route(
            "/api/v1/sessions/managed/{id}",
            get(get_managed_session)
                .delete(stop_managed_session)
                .patch(rename_managed_session),
        )
        .route("/api/v1/sessions/managed/{id}/send", post(send_to_session))
        // #94: read-only per-session file-change view, derived from the hook
        // event ring buffer. Merged as a sub-router like the two below.
        .merge(super::managed_routes::files::router())
        // #2605: async-spawn progress poll route, merged as a sub-router.
        .merge(super::managed_routes::provision_status::router())
        // #2444: per-session + fleet-wide asset re-sync
        // (`tm sessions sync-assets <id>|--all`), merged as a sub-router —
        // mirrors the `provision_status::router()` merge immediately above.
        .merge(super::managed_routes::sync_assets::router())
        // #9313: `tm sessions rebind <id>|--all` — a record update only.
        .merge(super::managed_routes::rebind::router())
        .route(
            "/api/v1/sessions/managed/{id}/answer",
            post(answer_session_decision),
        )
        .route(
            "/api/v1/sessions/managed/{id}/attach-cmd",
            get(get_attach_cmd),
        )
        .route(
            "/api/v1/sessions/managed/{id}/activity",
            get(get_session_activity),
        )
        .route(
            "/api/v1/sessions/managed/{id}/runtime-stop",
            post(stop_managed_session_runtime),
        )
        .route(
            "/api/v1/sessions/managed/{id}/resume",
            post(resume_managed_session),
        )
        // #2023 C: bare-`tm` in-pane relaunch flips Stopped -> Active in place,
        // with NO tmux mutation — distinct from `/resume` above, which always
        // kills any surviving tmux session and creates a fresh one.
        .route(
            "/api/v1/sessions/managed/{id}/reactivate",
            post(reactivate_managed_session),
        )
        .route(
            "/api/v1/sessions/managed/{id}/decommission",
            post(decommission_managed_session),
        )
        // #2012: hard-delete the session RECORD (distinct from decommission,
        // which stops/reaps). Fail-closed unless `?force=true`.
        .route(
            "/api/v1/sessions/managed/{id}/delete",
            post(delete_managed_session),
        )
        // TELUI-6 (#1440): the local session-manager PROXY surface — the SAME
        // focus/inject/summarize state machine every channel (Telegram, Slack)
        // binds to, exposed here as plain HTTP so it is `curl`-testable before
        // any channel connects. Registrations live with their handlers in
        // `managed_routes::proxy::proxy_router` and are merged here.
        .merge(proxy_router())
        // Layer-3 portfolio manager surface (epic #2109, DOC-36 §3.2), merged as a
        // self-contained sub-router (like the L2 `proxy_router`). Phase 1: the
        // read-only capabilities stub, deterministic rollup, LLM digest, and chat
        // loop. Phase 2: `route-task` (advisory task routing + disambiguation,
        // #2585) and `act` (session launch/inject/summarize propose→confirm, which
        // mutates ONLY on an explicit `confirm: true`, #2586). All curl-testable
        // with no channel/bot token (§4).
        .merge(manager_router())
        // DOC-35 §10.2/§10.5 (#2378 + #2380): Deliverable/Milestone CRUD, nested
        // under the projects namespace. The literal `/deliverables` and
        // `/milestones` segments come before their `/{id}` param routes so a
        // collection request is never captured as an id (mirroring the managed-
        // session `/adopt` ordering above). PATCH on `/{id}` is the `set-status`
        // seam that enforces the §10.3 state machine.
        .route(
            "/api/v1/projects/{name}/deliverables",
            get(list_deliverables).post(create_deliverable),
        )
        .route(
            "/api/v1/projects/{name}/deliverables/{id}",
            get(get_deliverable).patch(patch_deliverable),
        )
        .route(
            "/api/v1/projects/{name}/milestones",
            get(list_milestones).post(create_milestone),
        )
        .route(
            "/api/v1/projects/{name}/milestones/{id}",
            get(get_milestone).patch(patch_milestone),
        )
        // #1221: loopback-only JSON-RPC dispatch for the `serve --stdio` bridge.
        // The handler independently enforces the loopback gate via ConnectInfo.
        .route("/rpc", post(rpc_handler));

    // Gate the in-process Swagger UI explorer behind the `swagger-ui` feature
    // so offline / air-gapped builds (which cannot fetch the swagger-ui static
    // assets) compile cleanly with `--features daemon` alone (closes #1694).
    #[cfg(feature = "swagger-ui")]
    let router = router.merge(
        SwaggerUi::new("/api-docs")
            .url("/api-docs/openapi.json", super::openapi::ApiDoc::openapi()),
    );

    // DOC-60 §5.3: the peer bus owns its own route table (`bus_router`) and is
    // merged in whole, like `manager_router` above.
    // #8476: layered LAST so it wraps every route above, merged ones included.
    router
        .merge(bus_router())
        .layer(axum::middleware::from_fn(request_deadline::enforce))
        .with_state(state)
}

/// Liveness probe plus the HR-3 catalog-staleness signal.
///
/// Why: liveness alone is not enough for an autonomous runner — DOC-17 §HR-3
/// requires `/health` to SURFACE whether the deployed harness content has drifted
/// from the synced catalog so the TUI can show an indicator and the operator can
/// rebuild. The check is a cheap, offline SHA compare (no network pull on the
/// hot path), and an unreachable/never-synced catalog degrades to `unknown`
/// (never `stale`, never an error) per the spec's "never block" rule. Also
/// surfaces the #2486 `supervised` restart-race signal — a 200 response here
/// does NOT by itself prove launchd owns this process; check `supervised` too.
/// Also surfaces the #2332 `version` field so `tm doctor` can detect a
/// stale, unrestarted daemon running older code than the installed binary.
/// What: returns `status: "ok"` with `catalog_stale`/`catalog_unknown` flags, a
/// small `catalog_changes` summary computed via
/// [`crate::core::update_check::detect_for_framework`] anchored at the daemon's
/// framework root, `supervised` read from `state` (set once at daemon startup
/// by `daemon_run::run_daemon`), and `version` (this process's
/// `CARGO_PKG_VERSION`, a compile-time constant).
/// Test: `health_reports_ok_status`, `health_reports_catalog_unknown_without_catalog`,
/// `health_response_serializes_supervised_field`,
/// `health_response_serializes_version_field`.
#[utoipa::path(
    get,
    path = "/health",
    tag = "config",
    responses((status = 200, description = "Daemon is alive", body = HealthResponse))
)]
pub async fn health(State(state): State<Arc<DaemonState>>) -> Json<HealthResponse> {
    // #6288: the body is shared with `mpm.health` over the Unix socket.
    Json(core_ops::health(&state).await)
}

/// Query parameters for `GET /sessions`.
///
/// Why: `trusty-mpm session list` scopes the listing to one project; an
/// optional `?project=<path>` filter keeps the endpoint usable both ways.
/// What: an optional project path; when absent, all sessions are returned.
/// Test: `list_sessions_filters_by_project`.
#[derive(serde::Deserialize, Default)]
pub struct SessionQuery {
    /// Optional project path to filter sessions by.
    pub project: Option<PathBuf>,
}

/// `GET /sessions` — snapshot of managed sessions, optionally project-scoped.
#[utoipa::path(
    get,
    path = "/sessions",
    tag = "sessions",
    params(("project" = Option<String>, Query, description = "Filter by project path")),
    responses((status = 200, description = "Array of managed sessions", body = [Session]))
)]
pub async fn list_sessions(
    State(state): State<Arc<DaemonState>>,
    Query(query): Query<SessionQuery>,
) -> Json<SessionsResponse> {
    // #6288: the body is shared with `mpm.sessions.list` over the Unix socket.
    Json(sessions_ops::list_sessions(&state, query))
}

/// `GET /events/poll` — JSON snapshot of recent hook events (legacy / fallback).
///
/// Why: SSE-incapable clients (curl in a one-shot script, legacy CLI tooling)
/// still need a way to read the ring buffer. The push-based feed lives at
/// `GET /events`; this endpoint preserves the original synchronous-snapshot
/// contract under a `/poll` suffix for backward compatibility.
/// What: returns the bounded ring buffer of recent [`HookEventRecord`](crate::core::hook::HookEventRecord)s as
/// `{ "events": [...] }`.
/// Test: covered transitively by `hook_relay_ingests_known_event`.
#[utoipa::path(
    get,
    path = "/events/poll",
    tag = "events",
    responses((status = 200, description = "Recent hook events across all sessions"))
)]
pub async fn recent_events(State(state): State<Arc<DaemonState>>) -> Json<EventsResponse> {
    // #6288: the body is shared with `mpm.events.poll` over the Unix socket.
    Json(sessions_ops::recent_events(&state))
}

/// `GET /events` — live SSE stream of every hook event.
///
/// Why: the GUI and other real-time consumers need push notifications when
/// hook events arrive rather than polling `GET /events/poll`. SSE is the
/// lowest-friction streaming protocol for browser and `reqwest` clients —
/// plain HTTP, no upgrade dance, automatic reconnection in the browser.
/// What: subscribes to the daemon's broadcast channel and streams each event
/// as one SSE `data:` line (JSON-encoded). A `KeepAlive` comment ping every
/// 15 seconds prevents idle proxies from closing the connection.
/// Test: `events_sse_streams_one_frame` posts a hook and reads one SSE frame
/// from this handler.
pub async fn stream_events(
    State(state): State<Arc<DaemonState>>,
) -> Sse<impl Stream<Item = Result<Event, Infallible>>> {
    let rx = state.event_subscribe();
    let stream = BroadcastStream::new(rx).filter_map(|result| match result {
        Ok(val) => Some(Ok(Event::default().data(val.to_string()))),
        // Lagged / dropped frames are skipped — the channel intentionally
        // sheds load when a subscriber falls behind.
        Err(_) => None,
    });
    Sse::new(stream).keep_alive(
        KeepAlive::new()
            .interval(Duration::from_secs(15))
            .text("ping"),
    )
}

/// JSON body for registering a session via `POST /sessions`.
///
/// Why: a session created by an external launcher (or the CLI) must announce
/// itself so the dashboard and MCP tools can see it. The GUI's "New Session"
/// button additionally needs the daemon to *spawn* a fresh session — create
/// the tmux host and start `claude` — without going through the CLI; that
/// path is opted into by supplying `workdir`.
/// What: the project directory the session runs in, plus an optional project
/// association, an optional caller-supplied tmux session name, and an
/// optional `workdir` that switches the request from registration-only to
/// spawn mode.
/// Test: `register_and_remove_session` (registration-only),
/// `spawn_session_without_claude_returns_422` (spawn mode failure path),
/// `spawn_session_without_tmux_returns_422` (spawn mode no-tmux path).
#[derive(serde::Deserialize, utoipa::ToSchema)]
pub struct RegisterSession {
    /// Project directory the session was launched in (the session's working
    /// directory). Named `project` to match the CLI `project` argument.
    pub project: String,
    /// Optional project this session belongs to. When present, the session is
    /// associated with that registered project so `session list` can scope to
    /// it.
    #[serde(default)]
    #[schema(value_type = Option<String>)]
    pub project_path: Option<PathBuf>,
    /// Optional caller-supplied tmux session name.
    ///
    /// Why: the CLI computes a `tm-<folder>` name from the project directory
    /// and creates the tmux session under that name; passing it here keeps the
    /// daemon registry's `tmux_name` consistent with the live tmux session.
    /// What: when present and non-empty it is used as the session's
    /// `tmux_name`; when absent the daemon derives one itself.
    #[serde(default)]
    pub name: Option<String>,
    /// Optional working directory in which to spawn a brand-new session.
    ///
    /// Why: the GUI's "New Session" button needs the daemon to create the
    /// tmux host and start `claude` itself — going through the CLI is not an
    /// option from a browser. Presence of `workdir` is the explicit opt-in
    /// for spawn semantics; absence preserves the registration-only behaviour
    /// every other caller (the CLI, `session start`, the hook auto-register
    /// path) depends on.
    /// What: when present, the daemon creates a tmux session in this
    /// directory and launches `claude` inside it; when absent, only
    /// bookkeeping happens.
    /// Test: `spawn_session_without_claude_returns_422`,
    /// `spawn_session_without_tmux_returns_422`.
    #[serde(default)]
    #[schema(value_type = Option<String>)]
    pub workdir: Option<PathBuf>,
}

/// `POST /sessions` — register a new managed session, returning its id.
///
/// Why: registering a session is pure bookkeeping — it records that a session
/// exists so the dashboard and MCP tools can see it. In addition, the GUI's
/// "New Session" button needs the daemon to actually *spawn* a fresh session
/// (create the tmux host and start `claude`) without going through the CLI;
/// supplying `workdir` switches the request into that spawn mode. Sessions
/// without `workdir` are still recorded as pure bookkeeping (no tmux window
/// is created — that behaviour is unchanged so the existing CLI and hook
/// auto-registration paths keep working).
/// What: builds the `Session` record and registers it in state. When `workdir`
/// is present, additionally creates the tmux session via
/// [`TmuxService::spawn_claude`](crate::daemon::services::TmuxService::spawn_claude)
/// and starts `claude` in it; failures map to HTTP 422 (`claude` missing or
/// tmux missing) or 500 (tmux command failed). On success the new session
/// appears immediately in `GET /sessions`.
/// Test: `register_and_remove_session` covers the bookkeeping path;
/// `spawn_session_without_claude_returns_422` and
/// `spawn_session_without_tmux_returns_422` cover the spawn-mode error paths;
/// `spawn_session_registers_session_when_possible` covers the happy/observable
/// state path.
#[utoipa::path(
    post,
    path = "/sessions",
    tag = "sessions",
    request_body = RegisterSession,
    responses(
        (status = 201, description = "Session registered; returns its id and name"),
        (status = 422, description = "Spawn requested but `claude` binary or tmux is unavailable"),
        (status = 500, description = "tmux command failed while creating the session"),
    )
)]
pub async fn register_session(
    State(state): State<Arc<DaemonState>>,
    Json(body): Json<RegisterSession>,
) -> Result<Json<RegisterSessionResponse>, DaemonError> {
    // #6288: the body is shared with `mpm.sessions.register` over the Unix
    // socket; `mpm.sessions.connect` mounts the same body under its own name,
    // exactly as `POST /api/v1/sessions/connect` does here.
    Ok(Json(sessions_ops::register_session(&state, body)?))
}

/// `POST /api/v1/sessions/connect` — register a session for a *connect* (no
/// deployment) launch.
///
/// Why: `tm connect` deliberately skips the framework-deployment sequence that
/// `tm launch` runs (instructions, agents, skills) — it only wants the daemon
/// to start or attach to the tmux-hosted session. The deployment work lives in
/// the client/CLI, not the daemon, so the daemon-side bookkeeping for a
/// `connect` is identical to `register_session`: it records that the session
/// exists. A distinct endpoint keeps the two intents observable on the wire and
/// gives `connect` its own seam should the daemon need to diverge later.
/// What: delegates to [`register_session`] — the daemon does no deployment in
/// either path, so the registration body and response are the same.
/// Test: `connect_session_registers_without_deploy` in `api_tests.rs`.
#[utoipa::path(
    post,
    path = "/api/v1/sessions/connect",
    tag = "sessions",
    request_body = RegisterSession,
    responses((status = 201, description = "Session registered for connect; returns its id and name"))
)]
pub async fn connect_session(
    state: State<Arc<DaemonState>>,
    body: Json<RegisterSession>,
) -> Result<Json<RegisterSessionResponse>, DaemonError> {
    register_session(state, body).await
}

/// `GET /sessions/:id` — fetch a single session's detail.
///
/// Why: clients need to fetch one session without paging through the full
/// `GET /sessions` list — avoids over-fetching and simplifies client state
/// management when the caller already knows the session id.
/// What: parses `id` as a UUID, looks the session up in [`DaemonState`], and
/// returns it as JSON. A malformed id is a `400`; an unknown id is a `404`.
/// Test: `get_session_returns_session`, `get_session_unknown_is_404`.
#[utoipa::path(
    get,
    path = "/sessions/{id}",
    tag = "sessions",
    params(("id" = String, Path, description = "Session UUID")),
    responses(
        (status = 200, description = "Session detail", body = Session),
        (status = 400, description = "Malformed session id"),
        (status = 404, description = "No session with that id"),
    )
)]
pub async fn get_session(
    State(state): State<Arc<DaemonState>>,
    Path(id): Path<String>,
) -> Result<Json<Session>, DaemonError> {
    // #6288: the body is shared with `mpm.sessions.get` over the Unix socket.
    Ok(Json(sessions_ops::get_session(&state, &id)?))
}

/// `DELETE /sessions/:id` — deregister a session AND kill its tmux host.
///
/// Why: a DELETE must actually tear the session down — dropping only the
/// registry entry leaks a live managed (`tm-*`/`tmpm-*`) tmux session on every call (the
/// `full_user_cycle` leak this closes, epic #1452, #1454). Every session is
/// owned by exactly one Session object; deleting it kills the tmux host too.
/// What: resolves `id` as a UUID *or* a friendly `tmux_name` (#7834 — the
/// name-only form used to 400 here while `session info` resolved it), removes
/// the legacy registry entry (404 if neither form resolves),
/// then best-effort kills the tmux session by the entry's `tmux_name` and
/// reconciles the SessionManager store by decommissioning any managed record
/// that shares that exact `tmux_name`. Both teardown steps are best-effort:
/// the session may already be gone, so a kill/decommission failure is logged
/// (to stderr via `tracing` — never stdout, which carries MCP framing) and does
/// NOT fail the HTTP response. The registry removal having succeeded is the
/// contract the caller relies on.
/// Test: `remove_session_by_name_removes_legacy_registry_record`,
/// `remove_session_unknown_name_is_404` — `full_user_cycle` asserts the tmux
/// session is gone after DELETE when tmux is available.
#[utoipa::path(
    delete,
    path = "/sessions/{id}",
    tag = "sessions",
    params(("id" = String, Path, description = "Session UUID or friendly tmux name")),
    responses(
        (status = 200, description = "Session removed and tmux host killed"),
        (status = 404, description = "No session with that id or name"),
    )
)]
pub async fn remove_session(
    State(state): State<Arc<DaemonState>>,
    Path(id): Path<String>,
) -> Result<Json<RemoveSessionResponse>, DaemonError> {
    // #6288: the body — including the best-effort tmux kill and the managed-
    // store reconcile — is shared with `mpm.sessions.delete` over the socket.
    Ok(Json(sessions_ops::remove_session(&state, &id).await?))
}

/// `DELETE /sessions/dead` — reap registry entries with no live tmux session.
///
/// Why: dead sessions accumulate forever otherwise; an operator (or a periodic
/// task) needs a way to prune the registry down to what tmux actually hosts.
/// What: discovers tmux, calls [`DaemonState::reap_dead_sessions`], and returns
/// `{ "removed": <count> }`. If tmux is unavailable nothing is reaped (returns
/// `0`) — reaping against an empty list would wrongly delete every session.
/// Test: `reap_dead_sessions` in `state.rs` covers the core logic.
#[utoipa::path(
    delete,
    path = "/sessions/dead",
    tag = "sessions",
    responses((status = 200, description = "Dead sessions reaped; returns the removed count"))
)]
pub async fn reap_sessions(State(state): State<Arc<DaemonState>>) -> Json<ReapResponse> {
    // #6288: the body is shared with `mpm.sessions.reap` over the Unix socket.
    Json(sessions_ops::reap_sessions(&state))
}

/// JSON body for `PATCH /sessions/{id}/pid`.
///
/// Why: after launching `claude` inside a tmux pane the CLI discovers the real
/// process PID and reports it back so the daemon can monitor process liveness.
/// What: the OS-level `claude` process id.
/// Test: `set_session_pid_records_pid`.
#[derive(serde::Deserialize, utoipa::ToSchema)]
pub struct SetPidRequest {
    /// OS-level `claude` process id discovered inside the session's tmux pane.
    pub pid: u32,
}

/// `PATCH /sessions/{id}/pid` — record the OS-level `claude` process PID.
///
/// Why: a tmux session can outlive the `claude` process inside it; tracking the
/// real PID lets the reaper detect a stopped session. The CLI (and the daemon's
/// own launch path) discover the PID a few seconds after `send-keys` and report
/// it here.
/// What: resolves the session by UUID, sets `session.pid`, and echoes the id
/// and PID. An unknown id is `404`.
/// Test: `set_session_pid_records_pid`, `set_session_pid_unknown_is_404`.
#[utoipa::path(
    patch,
    path = "/sessions/{id}/pid",
    tag = "sessions",
    params(("id" = String, Path, description = "Session UUID")),
    request_body = SetPidRequest,
    responses(
        (status = 200, description = "PID recorded for the session"),
        (status = 404, description = "No session with that id"),
    )
)]
pub async fn set_session_pid(
    State(state): State<Arc<DaemonState>>,
    Path(id): Path<String>,
    Json(body): Json<SetPidRequest>,
) -> Result<Json<SetPidResponse>, DaemonError> {
    // #6288: the body is shared with `mpm.sessions.set_pid` over the socket.
    Ok(Json(sessions_ops::set_session_pid(&state, &id, body.pid)?))
}

/// `POST /sessions/discover` — auto-discover Claude Code sessions.
///
/// Why: `GET /sessions` only reports daemon-managed sessions; operators run
/// `claude` / `claude-code` / `claude-mpm` / `tm` in tmux panes — and, more
/// commonly, in native Terminal.app windows — that the daemon never created.
/// This endpoint scans both and registers the ones running Claude Code so they
/// appear in the dashboard and the Telegram bot.
/// What: runs [`super::discovery::discover_all`] (tmux panes plus native `ps`
/// processes) and returns `{ "discovered": <count>, "sessions": [name, ...] }`.
/// A missing tmux or `ps` yields a zero count rather than an error.
/// Test: `discover_sessions_returns_count` in `api_tests.rs`.
#[utoipa::path(
    post,
    path = "/sessions/discover",
    tag = "sessions",
    responses((status = 200, description = "tmux sessions running Claude Code, newly registered"))
)]
pub async fn discover_sessions(State(state): State<Arc<DaemonState>>) -> Json<DiscoverResponse> {
    // #6288: the body is shared with `mpm.sessions.discover` over the socket.
    Json(sessions_ops::discover_sessions(&state).await)
}

/// `GET /sessions/:id/events/poll` — JSON snapshot of one session's hook events.
///
/// Why: the push-based per-session feed lives at `GET /sessions/{id}/events`;
/// this endpoint preserves the original synchronous-snapshot contract under
/// a `/poll` suffix for clients that cannot or do not need to stream.
/// What: parses the session id and returns the bounded ring buffer filtered
/// to that session.
/// Test: covered transitively by the `state::tests::hook_history_is_bounded`
/// test, which exercises the underlying `hook_events_for` query.
#[utoipa::path(
    get,
    path = "/sessions/{id}/events/poll",
    tag = "events",
    params(("id" = String, Path, description = "Session UUID")),
    responses(
        (status = 200, description = "Recent hook events for the session"),
        (status = 404, description = "No session with that id"),
    )
)]
pub async fn session_events(
    State(state): State<Arc<DaemonState>>,
    Path(id): Path<String>,
) -> Result<Json<EventsResponse>, DaemonError> {
    // #6288: the body is shared with `mpm.sessions.events_poll` over the socket.
    Ok(Json(sessions_ops::session_events(&state, &id)?))
}

/// `GET /sessions/{id}/events` — live SSE stream of one session's hook events.
///
/// Why: per-session event filtering lets the GUI subscribe to one session's
/// activity without receiving noise from every other concurrent session.
/// What: subscribes to the broadcast channel and forwards only events whose
/// serialized JSON contains the session id (matching the
/// `"session": "<uuid>"` field every [`HookEventRecord`](crate::core::hook::HookEventRecord) carries). A 15-second
/// `KeepAlive` ping keeps idle proxies from closing the connection.
/// Test: `session_events_sse_filters_by_session` posts a hook for one
/// session and confirms only that session's stream sees it.
pub async fn stream_session_events(
    Path(id): Path<String>,
    State(state): State<Arc<DaemonState>>,
) -> Sse<impl Stream<Item = Result<Event, Infallible>>> {
    let rx = state.event_subscribe();
    let stream = BroadcastStream::new(rx).filter_map(move |result| match result {
        Ok(val) => {
            // Include the event only if it mentions this session id. The
            // record serializes its `SessionId` as the UUID string, so a
            // simple substring match is sufficient and avoids a typed parse
            // per frame.
            if val.to_string().contains(&id) {
                Some(Ok(Event::default().data(val.to_string())))
            } else {
                None
            }
        }
        Err(_) => None,
    });
    Sse::new(stream).keep_alive(
        KeepAlive::new()
            .interval(Duration::from_secs(15))
            .text("ping"),
    )
}

/// JSON body for `POST /sessions/{id}/pause`.
///
/// Why: a pause may carry an optional operator note describing where the
/// session was left off; when absent the daemon derives one from pane output.
/// What: an optional free-form summary string.
/// Test: `pause_then_resume_round_trips`.
#[derive(serde::Deserialize, utoipa::ToSchema, Default)]
pub struct PauseRequest {
    /// Optional note about where the session was left off.
    #[serde(default)]
    pub summary: Option<String>,
}

/// `POST /sessions/{id}/pause` — pause a session, saving its state for resume.
///
/// Why: an operator stepping away needs the session frozen with a "where I left
/// off" note that survives a daemon restart.
/// What: resolves the session by UUID or friendly name, captures the last 50
/// pane lines, sets `status = Paused` / `paused_at = now` / `pause_summary`
/// (the request note, or the first 500 chars of the `Summarise`-compressed
/// captured output), and mirrors the pause record to disk via
/// `session_store::save_pause`.
/// Test: `pause_then_resume_round_trips`, `pause_unknown_session_is_404`.
#[utoipa::path(
    post,
    path = "/sessions/{id}/pause",
    tag = "sessions",
    params(("id" = String, Path, description = "Session UUID or friendly name")),
    request_body = PauseRequest,
    responses(
        (status = 200, description = "Session paused; returns the pause summary"),
        (status = 404, description = "No session with that id or name"),
    )
)]
pub async fn pause_session(
    State(state): State<Arc<DaemonState>>,
    Path(id): Path<String>,
    Json(body): Json<PauseRequest>,
) -> Result<Json<PauseResponse>, DaemonError> {
    // #6288: the body is shared with `mpm.sessions.pause` over the Unix socket.
    Ok(Json(sessions_ops::pause_session(
        &state,
        &id,
        body.summary,
    )?))
}

/// `POST /sessions/{id}/resume` — resume a previously-paused session.
///
/// Why: the counterpart to pause; clears the frozen state and the on-disk
/// pause record so the session is active again.
/// What: resolves the session, requires `status == Paused` (else `409`), sets
/// `status = Active` / `paused_at = None` / `pause_summary = None`, and removes
/// the pause file via `session_store::clear_pause`.
/// Test: `pause_then_resume_round_trips`, `resume_unpaused_session_is_409`.
#[utoipa::path(
    post,
    path = "/sessions/{id}/resume",
    tag = "sessions",
    params(("id" = String, Path, description = "Session UUID or friendly name")),
    responses(
        (status = 200, description = "Session resumed"),
        (status = 404, description = "No session with that id or name"),
        (status = 409, description = "Session is not paused"),
    )
)]
pub async fn resume_session(
    State(state): State<Arc<DaemonState>>,
    Path(id): Path<String>,
) -> Result<Json<ResumeResponse>, DaemonError> {
    // #6288: the body is shared with `mpm.sessions.resume` over the socket.
    Ok(Json(sessions_ops::resume_session(&state, &id)?))
}

/// JSON body for `POST /sessions/{id}/command`.
///
/// Why: feeding a command into a session's tmux pane is how the operator (and
/// the Telegram bot) drives Claude Code remotely.
/// What: the command line to type into the pane.
/// Test: `send_command_returns_output_shape`.
#[derive(serde::Deserialize, utoipa::ToSchema)]
pub struct CommandRequest {
    /// The command line to send to the session's tmux pane.
    pub command: String,
}

/// Query parameters for `POST /sessions/{id}/command`.
///
/// Why: the caller may want the captured output summarised before it returns,
/// completing the "summarize output" step of the full user cycle.
/// What: an optional compression level (`off`, `trim`, `summarise`,
/// `caveman`); when absent the raw pane capture is returned unchanged.
/// Test: `send_command_compress_query_defaults_off`.
#[derive(serde::Deserialize, Default)]
pub struct CommandQuery {
    /// Compression level to apply to the captured output before returning.
    /// Values: off, trim, summarise, caveman. Defaults to none (raw output).
    #[serde(default)]
    pub compress: Option<CompressionLevel>,
}

/// `POST /sessions/{id}/command` — send a command to a session's tmux pane.
///
/// Why: remote control of a running session — type a line, let it run, read
/// back what happened.
/// What: resolves the session (`404` if missing, `409` if `Stopped`), sends the
/// command via `TmuxDriver::send_line`, waits 500ms for output to settle, then
/// captures the last 100 pane lines. When `?compress=` is supplied the capture
/// is compressed at that level before returning. tmux errors are logged, not
/// fatal — the endpoint still returns `200` with whatever output was captured.
/// Test: `send_command_returns_output_shape`, `command_to_stopped_session_is_409`.
#[utoipa::path(
    post,
    path = "/sessions/{id}/command",
    tag = "sessions",
    params(
        ("id" = String, Path, description = "Session UUID or friendly name"),
        ("compress" = Option<String>, Query, description = "Compression level: off, trim, summarise, caveman"),
    ),
    request_body = CommandRequest,
    responses(
        (status = 200, description = "Command sent; returns captured pane output"),
        (status = 404, description = "No session with that id or name"),
        (status = 409, description = "Session is stopped"),
    )
)]
pub async fn send_command(
    State(state): State<Arc<DaemonState>>,
    Path(id): Path<String>,
    Query(query): Query<CommandQuery>,
    Json(body): Json<CommandRequest>,
) -> Result<Json<CommandResponse>, DaemonError> {
    // #6288: the body is shared with `mpm.sessions.command` over the socket.
    Ok(Json(
        sessions_ops::send_command(&state, &id, &body.command, query.compress).await?,
    ))
}

/// Query parameters for `GET /sessions/{id}/output`.
///
/// Why: the caller chooses how much scrollback to capture and whether to
/// summarise it; defaults keep the endpoint usable with no query string.
/// What: an optional line count (defaulting to 50 when absent) and an optional
/// compression level applied to the capture before returning.
/// Test: `get_output_returns_output_shape`, `output_query_defaults`.
#[derive(serde::Deserialize, Default)]
pub struct OutputQuery {
    /// Number of trailing pane lines to capture (default 50 when absent).
    #[serde(default)]
    pub lines: Option<u32>,
    /// Compression level to apply to the captured output before returning.
    /// Values: off, trim, summarise, caveman. Defaults to none (raw output).
    #[serde(default)]
    pub compress: Option<CompressionLevel>,
}

/// `GET /sessions/{id}/output` — capture the current tmux pane output.
///
/// Why: the dashboard and the Telegram bot show a session's recent output
/// without sending it a command.
/// What: resolves the session (`404` if missing), captures the last `?lines=N`
/// pane lines (default 50), optionally compresses it at `?compress=`, and
/// returns `{ output, lines, original_bytes, compressed_bytes, compress_level,
/// input_box }`. `input_box` (#8407) is `empty`, `suggestion` or `typed`, or
/// `null` when the box could not be read. tmux being unavailable yields an
/// empty `output` rather than an error.
/// Test: `get_output_returns_output_shape`, `output_unknown_session_is_404`.
#[utoipa::path(
    get,
    path = "/sessions/{id}/output",
    tag = "sessions",
    params(
        ("id" = String, Path, description = "Session UUID or friendly name"),
        ("lines" = Option<u32>, Query, description = "Trailing lines to capture (default 50)"),
        ("compress" = Option<String>, Query, description = "Compression level: off, trim, summarise, caveman"),
    ),
    responses(
        (status = 200, description = "Captured pane output"),
        (status = 404, description = "No session with that id or name"),
    )
)]
pub async fn get_output(
    State(state): State<Arc<DaemonState>>,
    Path(id): Path<String>,
    Query(query): Query<OutputQuery>,
) -> Result<Json<OutputResponse>, DaemonError> {
    // #6288: the body is shared with `mpm.sessions.output` and its
    // `mpm.sessions.pane` alias over the Unix socket, mirroring the two HTTP
    // routes that already point here.
    Ok(Json(sessions_ops::get_output(
        &state,
        &id,
        query.lines,
        query.compress,
    )?))
}

/// `GET /breakers` — every agent's circuit-breaker state.
#[utoipa::path(
    get,
    path = "/breakers",
    tag = "config",
    responses((status = 200, description = "Array of per-agent circuit-breaker states"))
)]
pub async fn breakers(State(state): State<Arc<DaemonState>>) -> Json<BreakersResponse> {
    // #6288: the body is shared with `mpm.breakers` over the Unix socket.
    Json(core_ops::breakers(&state))
}

/// JSON body for the universal hook relay endpoint.
///
/// Why: the forwarder shim posts raw Claude Code hook events here; a typed
/// body documents the contract.
/// What: session id, the Claude Code event name, and the opaque payload.
/// Test: `hook_relay_ingests_known_event`.
#[derive(serde::Deserialize, utoipa::ToSchema)]
pub struct HookPost {
    /// Session the event came from (UUID string).
    pub session_id: String,
    /// Claude Code event, e.g. `PreToolUse`. Deserialization rejects any name
    /// that is not a known [`HookEvent`] variant, so an unknown event is a
    /// `400` before the handler runs.
    #[schema(value_type = String)]
    pub event: HookEvent,
    /// Raw event payload (shape varies per event).
    #[serde(default)]
    #[schema(value_type = Object)]
    pub payload: serde_json::Value,
}

/// `POST /hooks` — universal hook relay; ingests one Claude Code hook event.
///
/// Why: this is how the daemon achieves full observability — a forwarder shim
/// configured for *all* 32 hook events posts each one here. It is also the
/// enforcement point for the optional session overseer.
/// What: parses the session id and event name. On a `SessionStart` event for
/// an unknown session it auto-registers that session (this is how a claude
/// session announces itself to the daemon — connection-driven registration,
/// not `POST /sessions`). It then runs the overseer on tool-use events
/// (auditing every decision; a `Block` returns `403` early), compresses
/// `PostToolUse` output, then appends a `HookEventRecord` to the ring buffer.
/// Rejects malformed ids with `400`.
/// Test: `hook_relay_ingests_known_event`, `hook_relay_rejects_unknown_event`,
/// `overseer_blocks_pre_tool_use`, `session_start_auto_registers_session`.
#[utoipa::path(
    post,
    path = "/hooks",
    tag = "internal",
    request_body = HookPost,
    responses(
        (status = 200, description = "Hook event accepted"),
        (status = 400, description = "Unknown event name or malformed session id"),
        (status = 403, description = "Overseer blocked the event"),
    )
)]
pub async fn ingest_hook(
    State(state): State<Arc<DaemonState>>,
    Json(post): Json<HookPost>,
) -> Result<Json<HookAcceptedResponse>, DaemonError> {
    // #6288: the body — auto-registration, the #1744 correlation, and the
    // overseer veto — is shared with `mpm.hooks.ingest` over the Unix socket.
    Ok(Json(sessions_ops::ingest_hook(&state, post).await?))
}

/// `GET /overseer` — current session-overseer configuration and status.
///
/// Why: the CLI and dashboard surface whether oversight is active and which
/// strategy is in force.
/// What: returns `{ "overseer": { "enabled": <bool>, "handler": <str> } }`,
/// where `handler` is the active strategy name reported by the overseer.
/// Test: `get_overseer_returns_status`.
#[utoipa::path(
    get,
    path = "/overseer",
    tag = "config",
    responses((status = 200, description = "Overseer enabled flag and handler type"))
)]
pub async fn get_overseer(State(state): State<Arc<DaemonState>>) -> Json<OverseerResponse> {
    // #6288: the body is shared with `mpm.overseer` over the Unix socket.
    Json(core_ops::overseer(&state))
}

/// `POST /llm/chat` — send a message to the LLM chat assistant.
///
/// Why: the Telegram bot routes free-text (non-command) messages here, and the
/// TUI's `/chat` command does the same; both want a conversational endpoint
/// that reuses the overseer's already-resolved OpenRouter credentials.
/// What: requires a configured LLM overseer (else `503`), runs
/// [`LlmOverseer::chat`](crate::daemon::manager::chat) over the client-supplied history, and returns the
/// assistant reply plus the updated history. The daemon stays stateless about
/// chat sessions — the caller owns the history.
/// Test: `llm_chat_without_overseer_is_503`.
#[utoipa::path(
    post,
    path = "/llm/chat",
    tag = "config",
    request_body = LlmChatRequest,
    responses(
        (status = 200, description = "Assistant reply and updated history"),
        (status = 503, description = "LLM chat is not configured on this daemon"),
    )
)]
pub async fn llm_chat(
    State(state): State<Arc<DaemonState>>,
    Json(body): Json<LlmChatRequest>,
) -> Result<Json<LlmChatResponse>, DaemonError> {
    // #6288: the body is shared with `mpm.llm.chat` over the Unix socket.
    Ok(Json(core_ops::llm_chat(&state, body).await?))
}

/// `GET /optimizer` — current token-use optimizer configuration.
///
/// Why: the CLI and dashboard surface the active compression tuning. The
/// config is now framework-managed on disk (`optimizer.toml`); this endpoint
/// is read-only introspection of the daemon's in-memory copy of it.
/// What: returns `{ "optimizer": <OptimizerConfig>, "scope": <note> }`. The
/// `scope` note states that the level only affects observability history and
/// proxied calls, never native Claude Code sessions (issue #1944).
/// Test: e2e `optimizer_default_config`.
#[utoipa::path(
    get,
    path = "/optimizer",
    tag = "config",
    responses((status = 200, description = "Current token-use optimizer configuration"))
)]
pub async fn get_optimizer(State(state): State<Arc<DaemonState>>) -> Json<OptimizerResponse> {
    // #6288: the body is shared with `mpm.optimizer` over the Unix socket.
    Json(core_ops::optimizer(&state))
}

/// JSON body for registering a project via `POST /projects`.
///
/// Why: `trusty-mpm project init` announces a working directory to the daemon
/// so sessions started there can be associated with it.
/// What: the absolute path of the project's working directory.
/// Test: `register_and_list_projects`.
#[derive(serde::Deserialize, utoipa::ToSchema)]
pub struct RegisterProject {
    /// Absolute path to the project's working directory.
    #[schema(value_type = String)]
    pub path: PathBuf,
}

/// `POST /projects` — register a project, returning its `ProjectInfo`.
///
/// Why: the daemon owns the project registry; `project init` posts the
/// resolved directory here.
/// What: delegates to [`DaemonState::register_project`] and returns the
/// stored info as JSON.
/// Test: `register_and_list_projects`.
#[utoipa::path(
    post,
    path = "/projects",
    tag = "projects",
    request_body = RegisterProject,
    responses((status = 201, description = "Project registered", body = ProjectInfo))
)]
pub async fn register_project(
    State(state): State<Arc<DaemonState>>,
    Json(body): Json<RegisterProject>,
) -> Json<ProjectInfo> {
    // #6288: the body is shared with `mpm.projects.register`.
    Json(crate::daemon::rpc::registry::projects::register_project_op(
        &state, body.path,
    ))
}

/// `GET /projects` — snapshot of every registered project.
#[utoipa::path(
    get,
    path = "/projects",
    tag = "projects",
    responses((status = 200, description = "Array of registered projects", body = [ProjectInfo]))
)]
pub async fn list_projects(State(state): State<Arc<DaemonState>>) -> Json<ProjectsResponse> {
    // #6288: the body is shared with `mpm.projects.list`.
    Json(crate::daemon::rpc::registry::projects::list_projects_op(
        &state,
    ))
}

/// Query parameters for `GET /projects/current`.
///
/// Why: the daemon cannot see the caller's cwd; the CLI passes the resolved
/// path so the daemon can look the project up.
/// What: the path to resolve a project for.
/// Test: `current_project_found_and_missing`.
#[derive(serde::Deserialize)]
pub struct CurrentProjectQuery {
    /// Path whose registered project should be returned.
    pub path: PathBuf,
}

/// `GET /projects/current?path=<dir>` — the project registered for `path`.
///
/// Why: `trusty-mpm project info` shows the current directory's project; the
/// daemon resolves the path against its registry.
/// What: returns the matching `ProjectInfo`, or `404` when `path` is not a
/// registered project.
/// Test: `current_project_found_and_missing`.
#[utoipa::path(
    get,
    path = "/projects/current",
    tag = "projects",
    params(("path" = String, Query, description = "Directory whose project to resolve")),
    responses(
        (status = 200, description = "The project registered for the path", body = ProjectInfo),
        (status = 404, description = "Path is not a registered project"),
    )
)]
pub async fn current_project(
    State(state): State<Arc<DaemonState>>,
    Query(query): Query<CurrentProjectQuery>,
) -> Result<Json<ProjectInfo>, DaemonError> {
    // #6288: the body is shared with `mpm.projects.current`.
    Ok(Json(
        crate::daemon::rpc::registry::projects::current_project_op(&state, &query.path)?,
    ))
}

/// `GET /projects/discover` — projects mined from `~/.claude/projects/`.
///
/// Why: rather than register every repo by hand, the operator wants trusty-mpm
/// to enumerate the projects Claude Code already knows about and offer them for
/// one-tap registration (the Telegram `/projects` command consumes this).
/// What: runs [`ProjectDiscovery::discover`](crate::core::project_discovery::ProjectDiscovery::discover), maps each row to a
/// [`DiscoveredProjectInfo`] (path as a string, last-session time as an
/// ISO-8601 string), and returns them newest-session-first. The discovery
/// itself never fails — an absent directory yields an empty list.
/// Test: `discover_projects_returns_array`.
#[utoipa::path(
    get,
    path = "/projects/discover",
    tag = "projects",
    responses((status = 200, description = "Projects discovered from Claude Code config"))
)]
pub async fn discover_projects(
    State(_state): State<Arc<DaemonState>>,
) -> Json<DiscoverProjectsResponse> {
    // #6288: the body is shared with `mpm.projects.discover`.
    Json(crate::daemon::rpc::registry::projects::discover_projects_op())
}

// ---- universal tmux session management ---------------------------------

/// `GET /tmux/sessions` — every tmux session on the host, origin-tagged.
///
/// Why: trusty-mpm manages *all* tmux sessions, not just the ones it created;
/// the dashboard needs the full list with an origin label so it can offer to
/// adopt external sessions.
/// What: runs `TmuxDriver::list_all_sessions` and returns
/// `{ "sessions": [ExternalSession, ...] }`. tmux being unavailable yields an
/// empty array rather than an error.
/// Test: `list_tmux_sessions_returns_array`.
#[utoipa::path(
    get,
    path = "/tmux/sessions",
    tag = "tmux",
    responses((status = 200, description = "All tmux sessions with origin labels"))
)]
pub async fn list_tmux_sessions(
    State(state): State<Arc<DaemonState>>,
) -> Json<TmuxSessionsResponse> {
    // #6288: the body is shared with `mpm.tmux.sessions` over the Unix socket.
    Json(core_ops::list_tmux_sessions(&state))
}

/// `GET /tmux/sessions/{name}/snapshot` — capture any session's current state.
///
/// Why: the dashboard inspects any session (internal or external) without
/// attaching to it.
/// What: runs `TmuxDriver::monitor_session` for the last 100 pane lines and
/// returns the [`SessionSnapshot`](crate::daemon::tmux::SessionSnapshot). A missing session or absent tmux is `404`.
/// Test: `tmux_snapshot_unknown_session_is_404` (covers the no-tmux path).
#[utoipa::path(
    get,
    path = "/tmux/sessions/{name}/snapshot",
    tag = "tmux",
    params(("name" = String, Path, description = "tmux session name")),
    responses(
        (status = 200, description = "Session snapshot"),
        (status = 404, description = "Session not found or tmux unavailable"),
    )
)]
pub async fn tmux_snapshot(
    State(state): State<Arc<DaemonState>>,
    Path(name): Path<String>,
) -> Result<Json<TmuxSnapshotResponse>, DaemonError> {
    // #6288: the body is shared with `mpm.tmux.snapshot` over the Unix socket.
    Ok(Json(core_ops::tmux_snapshot(&state, &name)?))
}

/// JSON body for `POST /tmux/adopt`.
///
/// Why: adopting an external session needs only its name.
/// What: the tmux session name to bring under oversight.
/// Test: `adopt_tmux_session_handles_missing`.
#[derive(serde::Deserialize, utoipa::ToSchema)]
pub struct AdoptRequest {
    /// tmux session name to adopt.
    pub session: String,
}

/// `POST /tmux/adopt` — register an external tmux session for oversight.
///
/// Why: trusty-mpm should watch sessions it did not create; adoption is the
/// explicit, non-destructive opt-in for that.
/// What: runs `TmuxDriver::adopt_session` (which captures the session's shape
/// without modifying it) and returns the [`AdoptedSession`](crate::daemon::tmux::AdoptedSession). A missing session
/// or absent tmux is `404`.
/// Test: `adopt_tmux_session_handles_missing`.
#[utoipa::path(
    post,
    path = "/tmux/adopt",
    tag = "tmux",
    request_body = AdoptRequest,
    responses(
        (status = 200, description = "Session adopted; returns its captured state"),
        (status = 404, description = "Session not found or tmux unavailable"),
    )
)]
pub async fn adopt_tmux_session(
    State(state): State<Arc<DaemonState>>,
    Json(body): Json<AdoptRequest>,
) -> Result<Json<AdoptResponse>, DaemonError> {
    // #6288: the body is shared with `mpm.tmux.adopt` over the Unix socket.
    Ok(Json(core_ops::adopt_tmux(&state, body)?))
}

// ---- bot pairing --------------------------------------------------------

/// `POST /pair/request` — generate a one-time Telegram-bot pairing code.
///
/// Why: pairing the Telegram bot to this daemon needs an out-of-band shared
/// secret; `tm pair` calls this on the local daemon to obtain a short code the
/// operator then types into the bot.
/// What: generates a six-character code (stored with a five-minute TTL) and
/// returns `{ "code", "expires_in_seconds" }`.
/// Test: `pair_request_returns_code`.
#[utoipa::path(
    post,
    path = "/pair/request",
    tag = "config",
    responses((status = 200, description = "A one-time pairing code and its TTL"))
)]
pub async fn pair_request(
    State(state): State<Arc<DaemonState>>,
) -> Json<super::services::PairCode> {
    // #6288: the body is shared with `mpm.pair.request`.
    Json(crate::daemon::rpc::registry::pairing::request_op(&state))
}

/// JSON body for `POST /pair/confirm`.
///
/// Why: confirming a pairing needs the operator's code and the Telegram chat id
/// to bind.
/// What: the six-character code and the chat id.
/// Test: `pair_confirm_validates_code`.
#[derive(serde::Deserialize, utoipa::ToSchema)]
pub struct PairConfirmRequest {
    /// The one-time pairing code issued by `POST /pair/request`.
    pub code: String,
    /// The Telegram chat id to pair with this daemon.
    pub chat_id: i64,
}

/// `POST /pair/confirm` — confirm a pairing code and register the chat.
///
/// Why: the Telegram bot's `/pair <code>` flow validates the operator's code so
/// push alerts have an authenticated destination.
/// What: validates `code` against the outstanding code within its TTL; on
/// success stores `chat_id` and returns `{ "success": true, "chat_id" }`,
/// otherwise `{ "success": false, "error": "invalid or expired code" }`.
/// Test: `pair_confirm_validates_code`, `pair_confirm_rejects_bad_code`.
#[utoipa::path(
    post,
    path = "/pair/confirm",
    tag = "config",
    request_body = PairConfirmRequest,
    responses((status = 200, description = "Pairing result (success flag and chat id or error)"))
)]
pub async fn pair_confirm(
    State(state): State<Arc<DaemonState>>,
    Json(body): Json<PairConfirmRequest>,
) -> Json<PairConfirmResponse> {
    // #6288: the body is shared with `mpm.pair.confirm`.
    Json(crate::daemon::rpc::registry::pairing::confirm_op(
        &state, &body,
    ))
}

/// `GET /pair/status` — report whether a Telegram chat is paired.
///
/// Why: the bot's `/start` command branches on whether the daemon is already
/// paired so it shows either a welcome-and-pair prompt or a ready message.
/// What: returns `{ "paired": <bool>, "chat_id": <i64 or null> }`.
/// Test: `pair_status_reports_unpaired`.
#[utoipa::path(
    get,
    path = "/pair/status",
    tag = "config",
    responses((status = 200, description = "Pairing status (paired flag and chat id)"))
)]
pub async fn pair_status(
    State(state): State<Arc<DaemonState>>,
) -> Json<super::services::PairStatus> {
    // #6288: the body is shared with `mpm.pair.status`.
    Json(crate::daemon::rpc::registry::pairing::status_op(&state))
}

/// `POST /pair/reset` — clear the Telegram pairing.
///
/// Why: an operator unpairing the bot must drop the binding both in memory and
/// on disk so a daemon restart does not restore it from `pairing.json`.
/// What: delegates to
/// [`PairingService::reset`](crate::daemon::services::PairingService::reset) and
/// returns `{ "reset": true }`.
/// Test: `pair_reset_clears_pairing` in `api_tests.rs`.
#[utoipa::path(
    post,
    path = "/pair/reset",
    tag = "config",
    responses((status = 200, description = "Pairing cleared"))
)]
pub async fn pair_reset(State(state): State<Arc<DaemonState>>) -> Json<PairResetResponse> {
    // #6288: the body is shared with `mpm.pair.reset`.
    Json(crate::daemon::rpc::registry::pairing::reset_op(&state))
}

// ---- diagnostics --------------------------------------------------------

/// Query parameters for `GET /api/v1/doctor`.
///
/// Why: the instruction-pipeline probe must be scoped to a specific project
/// (`<project>/.trusty-mpm/last-instructions.md`); the daemon cannot see the
/// caller's cwd, so the CLI passes the resolved path here.
/// What: an optional `project` path; when absent the instruction probe reports
/// a warning rather than a definitive result.
/// Test: `doctor_endpoint_returns_report`.
#[derive(serde::Deserialize, Default)]
pub struct DoctorQuery {
    /// Optional project directory to scope the instruction-pipeline probe to.
    pub project: Option<PathBuf>,
}

/// `GET /api/v1/doctor` — run the full trusty-mpm stack diagnostic.
///
/// Why: a misconfigured stack fails in confusing ways; one endpoint that runs
/// every "is this wired correctly?" probe gives operators (and the `tm doctor`
/// CLI / Telegram `/doctor` command) a single actionable verdict.
/// What: delegates to [`super::doctor::run_doctor_for_manager`], which probes
/// the instruction pipeline, agent and skill deployment, the trusty-memory /
/// trusty-search sidecars, AND orphaned git worktrees (#1840). The endpoint
/// always returns `200` — individual failures live in the report's per-check
/// statuses, not the HTTP status. `tm doctor` no longer calls this route at all
/// (#6336) — it runs the same battery in-process — but Telegram `/doctor`,
/// Slack `/doctor`, and any other HTTP consumer still do.
/// Test: `doctor_endpoint_returns_report`.
#[utoipa::path(
    get,
    path = "/api/v1/doctor",
    tag = "config",
    params(("project" = Option<String>, Query, description = "Project directory to scope the instruction probe to")),
    responses((status = 200, description = "Full diagnostic report"))
)]
pub async fn doctor(
    State(state): State<Arc<DaemonState>>,
    Query(query): Query<DoctorQuery>,
) -> Json<crate::core::doctor::DoctorReport> {
    // #6288: the body is shared with `mpm.doctor` over the Unix socket.
    Json(core_ops::doctor(&state, query).await)
}

// ── Bug-reporting HTTP endpoints (Phase 2 surface + Phase 3 filing) ──────────

/// Query parameters for `GET /api/v1/errors`.
///
/// Why: the caller controls how many errors to return; the daemon caps it at
///      100 to prevent oversized responses.
/// What: optional `limit` field; defaults to 20 when absent.
/// Test: `list_errors_returns_array` in `api_tests.rs`.
#[derive(serde::Deserialize, Default)]
pub struct ErrorsQuery {
    /// Maximum number of errors to return (default 20, max 100).
    #[serde(default)]
    pub limit: Option<u64>,
}

/// `GET /api/v1/errors` — list recently captured errors from all daemon stores.
///
/// Why: sub-agents that cannot use MCP tools directly can still browse captured
///      errors over plain HTTP before deciding to file a bug report.
/// What: aggregates and deduplicates errors from all known daemon JSONL stores,
///       returns them sorted by most-recent occurrence. Always returns `200`.
/// Test: `list_errors_returns_array` in `api_tests.rs`.
#[utoipa::path(
    get,
    path = "/api/v1/errors",
    tag = "bug-reporting",
    params(("limit" = Option<u64>, Query, description = "Max errors to return (default 20, max 100)")),
    responses((status = 200, description = "Deduplicated error list"))
)]
pub async fn list_errors(
    State(state): State<Arc<DaemonState>>,
    Query(query): Query<ErrorsQuery>,
) -> Json<ErrorsResponse> {
    // #6288: the body is shared with `mpm.errors.list` over the Unix socket.
    Json(core_ops::list_errors(&state, query))
}

/// JSON body for `POST /api/v1/report-bug`.
///
/// Why: a local request struct with `utoipa::ToSchema` lets the handler slot
///      into the utoipa-axum dispatch without special traits on the shared type.
/// What: the fingerprint and confirm flag; mirrors `bug_report::types::ReportBugRequest`.
/// Test: `report_bug_no_confirm_returns_preview` in `api_tests.rs`.
#[derive(serde::Deserialize, utoipa::ToSchema)]
pub struct ReportBugApiRequest {
    /// SHA-256 hex fingerprint (64 chars) from `GET /api/v1/errors`.
    pub fingerprint: String,
    /// Must be `true` to actually file; `false` or absent → preview only.
    #[serde(default)]
    pub confirm: bool,
}

/// The scrubbed-preview builder, now shared with `mpm.report_bug` (#6288).
///
/// Why a re-export rather than a move outright: `api_tests` reaches it as
/// `super::to_wire_preview`, and the HTTP tests must keep passing unmodified.
pub use super::rpc::core_ops::to_wire_preview;

/// `POST /api/v1/report-bug` — file or preview a bug report via HTTP.
///
/// Why: sub-agents spawned by Claude Code's Agent tool do not inherit MCP
///      connections; they need an HTTP fallback to file bug reports. This
///      endpoint mirrors the `report_bug` MCP tool's consent gate.
///
/// Fixes implemented here:
///   - Fix 1 (#498, P0): token resolved via the full chain (`ResolvedProvider`
///     — PAT env → token file → GitHub App → NoToken) instead of the narrower
///     `EnvFileTokenProvider`, so the GitHub App path is now reachable.
///   - Fix 2 (P1): `confirm:false` now includes the scrubbed preview
///     (title/body/labels/scrub_changes) in the response so HTTP clients can
///     inspect before consenting.
///   - Fix 3 (P2): the `RateLimitGuard` is checked before filing; a blocked
///     call returns `{ filed:false, rate_limited:true, note:… }` without
///     hitting the GitHub API.  After a successful filing `record_filed` is
///     called.  Rate-limit state-file failures are non-fatal (logged only).
///
/// What: when `confirm:false` (or absent), returns a preview-only response
///       (`filed:false`, `preview:{…}`). When `confirm:true`, resolves the
///       token via the full provider chain, checks the rate-limit guard, then
///       calls the GitHub filing client. A missing token returns
///       `filed:false` with an actionable note; a blocked rate-limit returns
///       `filed:false, rate_limited:true`; a missing fingerprint returns
///       `filed:false` with a "not found" note.
/// Test: `report_bug_no_confirm_includes_preview`,
///       `report_bug_rate_limited_returns_not_filed` in `api_tests.rs`.
#[utoipa::path(
    post,
    path = "/api/v1/report-bug",
    tag = "bug-reporting",
    request_body = ReportBugApiRequest,
    responses(
        (status = 200, description = "Filing result or graceful failure; always 200"),
    )
)]
pub async fn report_bug_http(
    State(state): State<Arc<DaemonState>>,
    Json(body): Json<ReportBugApiRequest>,
) -> Json<ReportBugHttpResponse> {
    // #6288: the body is shared with `mpm.report_bug` over the Unix socket.
    Json(core_ops::report_bug(&state, body).await)
}

/// Handler unit tests.
///
/// Why: the suite is large enough that keeping it in `api.rs` pushed the file
/// past a maintainable size; a `#[path]`-linked sibling keeps the handler
/// surface readable while the tests still see the private helpers via
/// `super::*`.
/// Test: this *is* the test module.
// #6288 slice 3: `apply_compression` and its label helper moved to
// `daemon::rpc::sessions_legacy_ops` with the two handler bodies that use them.
// `api_tests.rs` reaches them through its `use super::*;`, so re-export the
// names here rather than editing the cases. Test-only: nothing in the non-test
// lib target references them any more.
#[cfg(test)]
pub(crate) use super::rpc::sessions_legacy_ops::{apply_compression, compression_level_label};

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

/// Session-Manager endpoint tests (DOC-14 SM-7).
///
/// Why: the SM-path `coordinator/chat` rewire + the `/session-manager/*` aliases
/// have their own focused suite; keeping it in a sibling file keeps `api_tests.rs`
/// under its SLOC cap while these tests still see the private handler surface via
/// `super::*`.
/// Test: this *is* the SM endpoint test module.
#[cfg(test)]
#[path = "coordinator_sm_tests.rs"]
mod coordinator_sm_tests;