mlua_swarm_server/

lib.rs

//! the server lib: axum Router + handler set. Split out as a library so it can
//! be used from both `main.rs` (CLI) and integration tests.
//!
//! # Endpoints
//!
//! - `GET /v1/healthz`
//! - `POST /v1/sessions` / `DELETE /v1/sessions` (= operator attach / detach, Bearer sid)
//! - `POST /v1/tasks` (= unified Flow-form entry, Operator inject supported;
//!   `operator_sid` explicitly pins the task to a registered Operator session, S2).
//!   Also creates a `TaskRecord` + `RunRecord` (issue #13 ID-hierarchy persistence)
//!   and echoes their ids in the response; see the `tasks` module doc.
//! - `GET /v1/tasks` — list every persisted `TaskRecord` (newest first).
//! - `GET /v1/tasks/:id` — a `TaskRecord` plus every `RunRecord` kicked from it.
//! - `POST /v1/tasks/:id/runs` — re-kick an existing Task (new `RunId`, same
//!   `blueprint_ref` / `input_ctx`).
//! - `GET /v1/runs/:id` — a single `RunRecord` (its `step_entries` trace included).
//! - `POST /v1/operators` / `GET /v1/operators/:sid` / `DELETE /v1/operators/:sid` /
//!   `GET /v1/operators/:sid/ws` (WS upgrade) — REST-like Operator login flow,
//!   Bearer-mandatory; the sole WS Operator session route. See `operator_ws::login`
//!   module doc.
//!
//! The Enhance issue axis (`/issues`) lives in the `issues` module; callers merge
//! `build_issues_router` to integrate it into the same server.
//!
//! # The 3 faces of the Operator role (= registered directly on the engine SoT)
//!
//! The engine stateless-executor refactor removed the three
//! `AppState` registries (former `HookRegistry` / `BridgeRegistry` / `OperatorRegistry`);
//! all registration now goes directly to the engine SoT via
//! `engine.register_spawn_hook` / `register_senior_bridge` / `register_operator`.
//! `WSOperatorSession` (in the `operator_ws` module) registers all three traits
//! simultaneously under a single sid — one WS connection covers all 3 faces of
//! the Operator role, the canonical pattern.
//!
//! # `build_*` family
//!
//! - [`build_router`] — minimal entry (= `default_registry()`)
//! - [`build_router_with`] — caller provides a `SpawnerRegistry` and optional `BlueprintStore`
//!
//! The engine should be started with [`default_layer_registry`] (= `Engine::new_with_layers`);
//! otherwise `Blueprint.spawner_hints` is ignored.

#![warn(missing_docs)]

/// HTTP surface for inspecting/registering Blueprint state (`/v1/blueprints/*`).
pub mod blueprints;
/// Server config file support (`~/.mse/config.toml`, CLI > file > default merge).
pub mod config;
/// `/v1/data/*` endpoints (v9 Big Response handling, Store-owner direct path).
pub mod data;
/// `GET /v1/doctor` — read-only startup config / Store snapshot.
pub mod doctor;
/// HTTP surface for the `/v1/enhance/log` axis.
pub mod enhance_log;
/// `EnhanceSetting` HTTP CRUD (`/v1/enhance-settings*`).
pub mod enhance_settings;
/// HTTP surface for the Enhance issue axis (`/v1/issues*`).
pub mod issues;
/// WebSocket Operator Callback IF (`/v1/operators*`).
pub mod operator_ws;
/// HTTP surface for the Task/Run persistence axis (issue #13 ID hierarchy;
/// `GET /v1/tasks`, `GET /v1/tasks/:id`, `POST /v1/tasks/:id/runs`,
/// `GET /v1/runs/:id`). `POST /v1/tasks` itself stays in this module (it is
/// the entry point `tasks_start` shares with the flow-eval path) — see the
/// `tasks` module doc for the split rationale.
pub mod tasks;
/// `/v1/worker/*` endpoints (SubAgent self-fetch path).
pub mod worker;
pub use blueprints::{build_blueprints_router, build_blueprints_router_with_refs};
pub use enhance_log::build_enhance_log_router;
pub use enhance_settings::build_enhance_settings_router;
pub use issues::{build_issues_router, GetIssueResponse, PostIssueRequest, PostIssueResponse};
pub use operator_ws::{
    operators_create, operators_delete, operators_info, operators_ws_connect, ClientMsg,
    OperatorSessionEntry, ServerMsg, WSOperatorSession,
};
pub use tasks::{RunKickRequest, RunKickResponse, TaskDetailResponse};
pub use worker::{worker_prompt, worker_result, PromptQuery, WorkerResultReq};

use axum::{
    extract::State,
    http::{header::AUTHORIZATION, HeaderMap, StatusCode},
    response::{IntoResponse, Response},
    routing::{get, post},
    Json, Router,
};
use mlua_swarm::application::{BlueprintRef, TaskApplication};
use mlua_swarm::blueprint::store::BlueprintStore;
use mlua_swarm::service::TaskLaunchService;
use mlua_swarm::store::run::{RunContext, RunRecord, RunStatus, RunStore};
use mlua_swarm::store::task::{TaskRecord, TaskRecordStatus, TaskStore};
use mlua_swarm::{
    CapToken, Compiler, Engine, LayerRegistry, LuaInProcessSpawnerFactory, MainAIMiddleware,
    OperatorDelegateMiddleware, OperatorSpawnerFactory, Role, RunId, RustFnInProcessSpawnerFactory,
    SeniorEscalationMiddleware, SessionId, SpawnerRegistry, SubprocessProcessSpawnerFactory,
    TaskId,
};
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use std::collections::HashMap;
use std::sync::Arc;
use std::time::Duration;
use tokio::sync::Mutex;

/// In-memory session map backing `/v1/sessions` attach/detach.
///
/// The `sid` handed to the client on this REST path is the token nonce
/// itself (a bearer secret), so the server never uses it as a map key —
/// entries are keyed by its fingerprint
/// (`mlua_swarm::types::token_fingerprint`; issue #14).
#[derive(Default)]
pub struct SessionStore {
    /// Live session tokens keyed by the sid's fingerprint.
    pub map: HashMap<String, CapToken>,
}

/// Shared axum handler state for the whole router. Cloned per-request (all
/// fields are `Arc`/cheap-clone), constructed once in [`build_router_with_ws_factory`].
#[derive(Clone)]
pub struct AppState {
    /// The engine SoT (attach/detach, dispatch, registries).
    pub engine: Engine,
    /// Live `/v1/sessions` attach records (Operator/Worker/etc session tokens).
    pub sessions: Arc<Mutex<SessionStore>>,
    /// Application used at the task entry to resolve `BlueprintRef`. Without a Store, runs in Inline-only mode.
    pub task_app: Arc<TaskApplication>,
    /// When `Some`, on WS connect a new `WSOperatorSession` is automatically registered
    /// with this factory under the sid name (= a `kind=operator` + `operator_ref=<sid>` AgentDef
    /// binds to the `WSOperatorSession` backend).
    /// When `None`, no auto-registration happens; the session is only registered on
    /// `engine.OperatorRegistry` (= only the `OperatorDelegateMiddleware` path is effective;
    /// the `OperatorSpawnerFactory` path is dead).
    pub ws_operator_factory: Option<Arc<OperatorSpawnerFactory>>,
    /// Owner of the Store on the Data path (Big Response handling). Added in v9.
    /// Independent layer — the Engine core and the Domain path (`/v1/worker/result`)
    /// are not involved.
    /// Default = `InMemoryOutputStore` (constructed inside `build_router_with_ws_factory`);
    /// callers can swap in an sqlite/fs backend later (future carry).
    pub data_store: Arc<dyn mlua_swarm::store::output::OutputStore>,
    /// Login-flow session store (`POST /v1/operators` mint records). `sid` →
    /// `OperatorSessionEntry`. This is the sole session store for the WS
    /// Operator role. See `operator_ws::login` module doc.
    pub operator_sessions:
        Arc<Mutex<HashMap<SessionId, Arc<crate::operator_ws::login::OperatorSessionEntry>>>>,
    /// S1 login-flow roles-exclusivity map. Role name → owning `sid`. Checked
    /// (and updated) atomically under a single lock in
    /// `operator_ws::login::operators_create` — a role already present here
    /// causes `POST /v1/operators` to return `409 CONFLICT`. Entries are
    /// released on `DELETE /v1/operators/:sid`.
    pub roles_to_sid: Arc<Mutex<HashMap<String, SessionId>>>,
    /// Persistence for `Task` records (issue #13 ID-hierarchy work-item
    /// identity; see `mlua_swarm::store::task` module doc). Default =
    /// `InMemoryTaskStore` (constructed inside `build_router_full`); callers
    /// can swap in a `SqliteTaskStore` via the `task_store` argument.
    pub task_store: Arc<dyn TaskStore>,
    /// Persistence for `Run` records (one kick of a Task; see
    /// `mlua_swarm::store::run` module doc). Default = `InMemoryRunStore`;
    /// callers can swap in a `SqliteRunStore` via the `run_store` argument.
    pub run_store: Arc<dyn RunStore>,
    /// Public HTTP base URL the server is reachable at (e.g.
    /// `"http://127.0.0.1:7777"`), sourced from the binary at boot time.
    /// When `Some`, `WSOperatorSession` renders it literally into the
    /// Spawn `directive`'s `base_url` line so the receiving operator can
    /// paste the frame into a SubAgent prompt without a `mse_doctor`
    /// detour (issue #8). `None` preserves the historical fallback
    /// (a placeholder that points at `mse_doctor`).
    pub base_url: Option<Arc<str>>,
}

/// Minimal entry point: builds a router with [`default_registry`] and no
/// `BlueprintStore` (Inline-only mode) or `ws_operator_factory`.
pub fn build_router(engine: Engine) -> Router {
    build_router_with(engine, default_registry(), None)
}

/// Default `LayerRegistry` for the server. Hint keys:
/// - `"main_ai"` → `MainAIMiddleware` (= fires SpawnHook before/after)
/// - `"senior_escalation"` → `SeniorEscalationMiddleware` (= on `ok=false`, escalates via `SeniorBridge.ask`)
/// - `"operator_delegate"` → `OperatorDelegateMiddleware` (= when an operator backend is registered, delegates the entire spawn)
///
/// Including any of these keys in `Blueprint.spawner_hints.layers` causes them to
/// be wrapped into a `SpawnerStack` at `service::linker::link` time (= per-launch;
/// the old `engine.bind` global-state path is retired).
/// Callers (the engine builder side) receive it via
/// `Engine::new_with_layers(cfg, mse_server::default_layer_registry())`.
pub fn default_layer_registry() -> LayerRegistry {
    LayerRegistry::new()
        .with_hint("main_ai", |_engine| Arc::new(MainAIMiddleware::new()))
        .with_hint("senior_escalation", |_engine| {
            Arc::new(SeniorEscalationMiddleware::new())
        })
        .with_hint("operator_delegate", |_engine| {
            Arc::new(OperatorDelegateMiddleware::new())
        })
}

/// Build form where the caller supplies a registry and an optional `BlueprintStore`.
/// The Operator callback path (= external HTTP / WS callers acting as an Operator)
/// must be pre-registered via `engine.register_*` (= the engine is the SoT).
/// See the `operator_ws` module doc and `OperatorInfo` (engine-side `ctx.rs`) for details.
pub fn build_router_with(
    engine: Engine,
    registry: SpawnerRegistry,
    store: Option<Arc<dyn BlueprintStore>>,
) -> Router {
    build_router_with_ws_factory(engine, registry, store, None)
}

/// 4-argument variant of `build_router_with`. Passing `ws_operator_factory = Some(arc)`
/// causes each WS connect to auto-register a new `WSOperatorSession` under its sid
/// name with the factory (= a `kind=operator` AgentDef with `operator_ref: <sid>`
/// can then bind to the WS client backend). Callers are expected to also install
/// the same `Arc` into the `SpawnerRegistry` via
/// `reg.register::<OperatorSpawnerFactory>(arc.clone())`.
pub fn build_router_with_ws_factory(
    engine: Engine,
    registry: SpawnerRegistry,
    store: Option<Arc<dyn BlueprintStore>>,
    ws_operator_factory: Option<Arc<OperatorSpawnerFactory>>,
) -> Router {
    build_router_with_ws_factory_and_output(engine, registry, store, ws_operator_factory, None)
}

/// 5-argument variant of [`build_router_with_ws_factory`]. Passing
/// `output_store = Some(arc)` swaps the default `InMemoryOutputStore` for a
/// caller-supplied backend (a `SqliteOutputStore`, for instance). `None`
/// preserves the historical behaviour (fresh in-memory store per call).
pub fn build_router_with_ws_factory_and_output(
    engine: Engine,
    registry: SpawnerRegistry,
    store: Option<Arc<dyn BlueprintStore>>,
    ws_operator_factory: Option<Arc<OperatorSpawnerFactory>>,
    output_store: Option<Arc<dyn mlua_swarm::store::output::OutputStore>>,
) -> Router {
    build_router_full(
        engine,
        registry,
        store,
        ws_operator_factory,
        output_store,
        None,
        None,
        None,
    )
}

/// 8-argument variant of [`build_router_with_ws_factory_and_output`].
/// Passing `base_url = Some(...)` (e.g. `"http://127.0.0.1:7777"`) makes
/// `WSOperatorSession` render the actual server bind into the Spawn
/// directive's `base_url` line, so the receiving operator can copy the
/// frame straight into a SubAgent prompt (issue #8). `None` preserves
/// the historical fallback (`<check with mse_doctor>` placeholder).
/// `task_store` / `run_store` swap the default `InMemoryTaskStore` /
/// `InMemoryRunStore` (issue #13 ID-hierarchy persistence) for a
/// caller-supplied backend (`SqliteTaskStore` / `SqliteRunStore`, for
/// instance); `None` preserves the process-volatile default.
// This is the terminal builder in the `build_router*` delegation chain
// (each variant adds one more caller-overridable store/factory); the
// argument count grows with the number of pluggable backends, not with
// unrelated responsibilities, so a plain allow is preferable to bundling
// them into a config struct only this one function would consume.
#[allow(clippy::too_many_arguments)]
pub fn build_router_full(
    engine: Engine,
    registry: SpawnerRegistry,
    store: Option<Arc<dyn BlueprintStore>>,
    ws_operator_factory: Option<Arc<OperatorSpawnerFactory>>,
    output_store: Option<Arc<dyn mlua_swarm::store::output::OutputStore>>,
    base_url: Option<Arc<str>>,
    task_store: Option<Arc<dyn TaskStore>>,
    run_store: Option<Arc<dyn RunStore>>,
) -> Router {
    let compiler = Compiler::new(registry);
    let launch = Arc::new(TaskLaunchService::new(engine.clone(), compiler));
    let task_app = Arc::new(match store {
        Some(s) => TaskApplication::new(launch, s),
        None => TaskApplication::new_inline_only(launch),
    });
    let data_store: Arc<dyn mlua_swarm::store::output::OutputStore> = match output_store {
        Some(s) => s,
        None => Arc::new(mlua_swarm::store::output::InMemoryOutputStore::new()),
    };
    let task_store: Arc<dyn TaskStore> = match task_store {
        Some(s) => s,
        None => Arc::new(mlua_swarm::store::task::InMemoryTaskStore::new()),
    };
    let run_store: Arc<dyn RunStore> = match run_store {
        Some(s) => s,
        None => Arc::new(mlua_swarm::store::run::InMemoryRunStore::new()),
    };
    let state = AppState {
        engine,
        sessions: Arc::new(Mutex::new(SessionStore::default())),
        task_app,
        ws_operator_factory,
        data_store,
        operator_sessions: Arc::new(Mutex::new(HashMap::new())),
        roles_to_sid: Arc::new(Mutex::new(HashMap::new())),
        task_store,
        run_store,
        base_url,
    };
    Router::new()
        .route("/v1/healthz", get(healthz))
        // session = collection (POST = attach, DELETE = detach, sid via Authorization)
        .route(
            "/v1/sessions",
            post(sessions_attach).delete(sessions_detach),
        )
        // task = flat, single level; authz resolved via Authorization: Bearer <sid>
        .route("/v1/tasks", post(tasks_start).get(tasks::tasks_list))
        .route("/v1/tasks/:id", get(tasks::task_get))
        .route("/v1/tasks/:id/runs", post(tasks::task_rekick))
        .route("/v1/runs/:id", get(tasks::run_get))
        // REST-like Operator login flow (Bearer-mandatory, roles exclusivity).
        // Sole WS Operator session route; see `operator_ws::login` module doc.
        .route("/v1/operators", post(operators_create))
        .route("/v1/operators/:sid/ws", get(operators_ws_connect))
        .route(
            "/v1/operators/:sid",
            get(operators_info).delete(operators_delete),
        )
        // SubAgent self-fetch path (the SubAgent self-fetch design). The SubAgent puts the
        // CapToken handed over via WS Spawn into Bearer and hits the prompt / result
        // endpoints directly over HTTP. See the `worker` module doc for details.
        .route("/v1/worker/prompt", get(worker::worker_prompt))
        .route("/v1/worker/result", post(worker::worker_result))
        // Simplified endpoint (= worker POSTs with just token + raw body; task_id is auto-looked-up)
        .route("/v1/worker/submit", post(worker::worker_submit))
        // Data path (v9 Big Response handling, independent from Domain / verdict flow)
        .route("/v1/data/emit", post(data::data_emit))
        .route(
            "/v1/data/:key",
            get(data::data_get).post(data::data_emit_named),
        )
        .with_state(state)
}

/// Default registry = Subprocess + RustFn (baseline `identity` worker pre-baked) + empty Operator factory.
///
/// `RustFnInProcessSpawnerFactory` gets one baseline entry (`fn_id = "identity"`)
/// baked in via [`mlua_swarm::worker::baseline::extend_with_baseline`]. This
/// is the shared bootstrap / smoke worker SoT across each binary (the server / MCP adapter /
/// one-shot runner) — it structurally replaces the old per-binary inline echo injection.
///
/// Usage: default Task path at server startup. If production needs additional
/// backends, callers bring in a different registry via
/// `build_router_with(engine, custom_registry)`. The enhance flow
/// (= patch-spawner / patch-applier / verifier-router / committer axes) uses
/// [`default_registry_with_enhance_flow`].
///
/// The Operator factory is an empty shell with zero registrations (= sids are
/// dynamically registered per WS connect; see the `operator_ws` module).
pub fn default_registry() -> SpawnerRegistry {
    let rustfn_factory =
        mlua_swarm::worker::baseline::extend_with_baseline(RustFnInProcessSpawnerFactory::new());

    let mut reg = SpawnerRegistry::new();
    reg.register::<SubprocessProcessSpawnerFactory>(Arc::new(SubprocessProcessSpawnerFactory));
    reg.register::<RustFnInProcessSpawnerFactory>(Arc::new(rustfn_factory));
    // Empty `LuaInProcessSpawnerFactory`: no `fn_id` is pre-registered here,
    // but BP agents can still declare `kind: lua` by carrying an inline
    // `spec.source` (or a `$file`-expanded Lua chunk). This lets a BP ship
    // deterministic Lua gates on the vanilla registry, without opting into
    // the enhance flow. See `LuaInProcessSpawnerFactory` docs for the spec
    // shape.
    reg.register::<LuaInProcessSpawnerFactory>(Arc::new(LuaInProcessSpawnerFactory::new()));
    reg.register::<OperatorSpawnerFactory>(Arc::new(OperatorSpawnerFactory::new()));
    reg
}

/// Opt-in registry that merges [`default_registry`] with the enhance flow
/// (Lua factory + AgentBlock factory).
///
/// Selected via the `the server` CLI flag `--enable-enhance-flow`. The enhance
/// flow is a separate-axis wrapper: the Lua factory (= 3 Lua workers + 3 primitive
/// bridges) and the AgentBlock factory (= patch-spawner path, expects
/// `assets/operator_scripts/blueprint_patch_spawner.lua` + `ANTHROPIC_API_KEY`)
/// are baked in as pipeline defaults. The baseline RustFn (`identity`) is pre-baked
/// the same way as in `default_registry`.
pub fn default_registry_with_enhance_flow() -> SpawnerRegistry {
    let lua_factory =
        mlua_swarm::enhance::blueprint::extend_factory(LuaInProcessSpawnerFactory::new());
    // The Factory is stateless (= 1 process → 1 factory shared by all AgentDefs).
    // Per-agent specialization (script_path / project_root, etc.) goes through AgentDef.spec.
    // The enhance-flow patch-spawner is declared literally in agents[].spec of `default_blueprint.yaml`.
    let agent_block_factory =
        mlua_swarm::worker::agent_block::AgentBlockInProcessSpawnerFactory::new();
    let rustfn_factory =
        mlua_swarm::worker::baseline::extend_with_baseline(RustFnInProcessSpawnerFactory::new());

    let mut reg = SpawnerRegistry::new();
    reg.register::<SubprocessProcessSpawnerFactory>(Arc::new(SubprocessProcessSpawnerFactory));
    reg.register::<RustFnInProcessSpawnerFactory>(Arc::new(rustfn_factory));
    reg.register::<LuaInProcessSpawnerFactory>(Arc::new(lua_factory));
    reg.register::<mlua_swarm::worker::agent_block::AgentBlockInProcessSpawnerFactory>(Arc::new(
        agent_block_factory,
    ));
    reg.register::<OperatorSpawnerFactory>(Arc::new(OperatorSpawnerFactory::new()));
    reg
}

// ─── handlers ────────────────────────────────────────────────────────────

async fn healthz() -> &'static str {
    "ok"
}

#[derive(Deserialize)]
struct AttachReq {
    agent_id: String,
    role: String,
    ttl_secs: u64,
}

#[derive(Serialize)]
struct AttachResp {
    session_id: String,
    role: String,
}

async fn sessions_attach(
    State(state): State<AppState>,
    Json(req): Json<AttachReq>,
) -> Result<Json<AttachResp>, ApiError> {
    let role = parse_role(&req.role)?;
    let token = state
        .engine
        .attach(req.agent_id, role, Duration::from_secs(req.ttl_secs))
        .await
        .map_err(ApiError::engine)?;
    // The wire `session_id` stays the nonce (Bearer credential contract);
    // the server-side map key is its fingerprint (issue #14).
    let sid = token.nonce.clone();
    let key = token.fingerprint();
    state.sessions.lock().await.map.insert(key, token);
    Ok(Json(AttachResp {
        session_id: sid,
        role: req.role,
    }))
}

async fn sessions_detach(
    State(state): State<AppState>,
    headers: HeaderMap,
) -> Result<StatusCode, ApiError> {
    let sid = extract_bearer(&headers)?;
    let token = take_session_token(&state, &sid).await?;
    state
        .engine
        .detach(&token)
        .await
        .map_err(ApiError::engine)?;
    Ok(StatusCode::NO_CONTENT)
}

// ─── Unified /v1/tasks schema (= flow-eval path, Operator inject supported) ───────

/// `/v1/tasks` POST schema. Uses the flow-eval path and supports Operator inject
/// (kind / spawn_hook / senior_bridge). Expressing a one-shot task as a 1-Step
/// Blueprint is the only correct model.
///
/// `pub` (issue #19 ST5) so its `schemars`-derived JSON Schema can be
/// generated cross-crate by `mlua-swarm-cli`'s `mse://api/http-endpoints`
/// MCP resource; fields stay module-private (no public field-level API
/// surface is intended).
#[derive(Deserialize, schemars::JsonSchema)]
pub struct TaskLaunchRequest {
    /// `BlueprintRef` selects Inline (a full Blueprint value) or Id (a
    /// store lookup). Left opaque here — its own schema nests the full
    /// `Blueprint` schema (owned by `mse://api/blueprint-schema`), and
    /// mixing the two into this HTTP-endpoint resource would violate
    /// their separation of concerns (see the resource's module doc).
    #[schemars(with = "Value")]
    blueprint: BlueprintRef,
    /// flow.ir's initial `ctx` — every `Step.in` `$.<path>` reads from
    /// here. This field's role is limited to the flow-ir eval seed
    /// (issue #19); the Task-level execution context lives in the
    /// sibling top-level fields below (`project_root` / `work_dir` /
    /// `task_metadata`), promoted out of `init_ctx` to remove the
    /// prior "free bag nested in free JSON" duplication.
    ///
    /// Backward compat: the pre-#19 shape — the same three keys nested
    /// directly inside this object — is still honored as a fallback
    /// when the sibling field is absent; see `run_flow_form`'s 2-stage
    /// resolution and `TaskInputMiddleware::from_init_ctx`.
    #[schemars(with = "Value")]
    init_ctx: Value,
    /// Task-level project root (issue #19 canonical Task IF field —
    /// promoted out of `init_ctx`). Takes priority over a same-named
    /// key nested inside `init_ctx` (backward-compat fallback).
    #[serde(default)]
    project_root: Option<String>,
    /// Task-level working directory (issue #19), same priority rule as
    /// `project_root`.
    #[serde(default)]
    work_dir: Option<String>,
    /// Task-level arbitrary metadata bag (issue #19), same priority
    /// rule as `project_root`.
    #[serde(default)]
    #[schemars(with = "Option<Value>")]
    task_metadata: Option<Value>,
    /// TTL in seconds. When unspecified (`None`), falls back in this order:
    /// (1) `metadata.default_run_ttl_secs` from the resolved BP,
    /// (2) if absent, the server global `default_run_ttl()` (1800s).
    #[serde(default)]
    ttl_secs: Option<u64>,
    #[serde(default)]
    operator: Option<OperatorReq>,
    /// Explicit Operator session sid (or role alias) this task's entire Spawn
    /// stream should be routed to (runtime Operator match stage 1).
    ///
    /// When `Some`, it is validated at request time against
    /// `state.engine.list_operator_ids()` (the live `engine.operators`
    /// registry key set): an unknown/never-registered id returns `400`
    /// immediately — this is a deliberate hard-fail, in contrast to
    /// `OperatorDelegateWrapped::spawn`, which silently falls through to
    /// `inner.spawn` on a registry miss. A sid that *was* registered but has
    /// since disconnected (WS `tx` cleared, session entry retained for
    /// reconnect) passes this check and surfaces as an explicit dispatch-time
    /// error instead (`WSOperatorSession::send_and_await` returns `Err` when
    /// `tx` is `None`), which also propagates as a request failure rather
    /// than a silent fallback.
    ///
    /// On success this value **overrides** `operator.operator_backend_id`
    /// (last-write-wins, `operator_sid` takes priority) before the flow is
    /// dispatched — see `run_flow_form`. Dispatch still only delegates if the
    /// Blueprint opts into `spawner_hints.layers = ["operator_delegate"]`
    /// (unchanged precondition, same as the existing `operator_backend_id`
    /// field).
    ///
    /// When unset, behavior is unchanged: whatever
    /// `operator.operator_backend_id` / BP-level `operator_ref` alias
    /// resolution already does still applies.
    #[serde(default)]
    operator_sid: Option<String>,
    /// Human-facing description of the work item (e.g. "resolve issue #10"),
    /// stashed verbatim into the minted `TaskRecord.goal`. Omitted / `None`
    /// stores an empty string — the flow-eval path itself never reads it.
    #[serde(default)]
    goal: Option<String>,
}

/// Operator inject sub-schema of [`TaskLaunchRequest`] (`kind` / `id` /
/// `spawn_hook_id` / `senior_bridge_id` / `operator_backend_id` /
/// `per_agent_kinds`). `pub` for the same cross-crate schema-generation
/// reason as `TaskLaunchRequest`.
#[derive(Deserialize, Default, schemars::JsonSchema)]
pub struct OperatorReq {
    /// `main_ai` / `automate` / `composite`. This is the "Runtime Global"
    /// tier of the 4-tier `OperatorKind` cascade (see `mlua_swarm
    /// ::ctx::collapse_operator_kind`); when unspecified, falls through to
    /// the BP-level tiers (`OperatorDef.kind` / `Blueprint
    /// .default_operator_kind`) instead of eagerly defaulting to `automate`.
    #[serde(default)]
    kind: Option<String>,
    /// Operator id at attach time (= sessions tracking key in the EventLog); unspecified defaults to `"http-run"`.
    #[serde(default)]
    id: Option<String>,
    /// Name of a hook pre-registered via `engine.register_spawn_hook`; `None` if unspecified.
    #[serde(default)]
    spawn_hook_id: Option<String>,
    /// Name of a bridge pre-registered via `engine.register_senior_bridge`; `None` if unspecified.
    #[serde(default)]
    senior_bridge_id: Option<String>,
    /// Name of an Operator backend pre-registered via `engine.register_operator`
    /// (= the path that delegates the entire spawn to an external Operator);
    /// `None` if unspecified. When `kind == MainAi/Composite` and this id is `Some`,
    /// `OperatorDelegateMiddleware` bypasses `inner.spawn` and calls `operator.execute` instead.
    /// This is a different axis from `operator.id` (= session tracking label);
    /// `operator_backend_id` is the registry lookup key.
    #[serde(default)]
    operator_backend_id: Option<String>,
    /// "Runtime Agent-level" tier (highest priority) of the `OperatorKind`
    /// cascade — per-agent override, keyed by `AgentDef.name`, value is
    /// `main_ai` / `automate` / `composite` (same parsing as `kind`).
    /// `None` / absent means no per-agent override.
    #[serde(default)]
    per_agent_kinds: Option<HashMap<String, String>>,
}

/// Parse a wire-level kind string (`"main_ai"` / `"automate"` / `"composite"`)
/// into `OperatorKind`. Shared by `OperatorReq.kind` and
/// `OperatorReq.per_agent_kinds` values.
fn parse_operator_kind_str(s: &str) -> Result<mlua_swarm::OperatorKind, ApiError> {
    use mlua_swarm::OperatorKind;
    match s {
        "main_ai" => Ok(OperatorKind::MainAi),
        "composite" => Ok(OperatorKind::Composite),
        "automate" => Ok(OperatorKind::Automate),
        other => Err(ApiError::bad_request(format!(
            "operator kind: unknown value '{other}' (expected main_ai|automate|composite)"
        ))),
    }
}

/// `/v1/tasks` POST response body. `pub` for the same cross-crate
/// schema-generation reason as [`TaskLaunchRequest`].
#[derive(Serialize, schemars::JsonSchema)]
pub struct TaskLaunchResponse {
    /// The final flow.ir `ctx` after every `Step.out` has been written.
    #[schemars(with = "Value")]
    final_ctx: Value,
    /// Debug-formatted `BlueprintVersion` the run resolved against, when
    /// the Blueprint came from a store lookup (`None` for `Inline` refs).
    bound_version: Option<String>,
    /// Resolved TTL (seconds) actually applied to the run. Exposes the
    /// 3-layer cascade (request body → BP metadata → server default) so
    /// clients can verify which value took effect without re-deriving it.
    effective_ttl_secs: u64,
    /// Which layer of the TTL cascade won.
    ttl_source: TtlSource,
    /// The `TaskRecord` minted for this request (issue #13 ID-hierarchy
    /// persistence). `GET /v1/tasks/:id` re-fetches it; `POST
    /// /v1/tasks/:id/runs` re-kicks it under a fresh `RunId`.
    #[schemars(with = "String")]
    task_id: TaskId,
    /// The `RunRecord` minted for this specific kick. `GET /v1/runs/:id`
    /// re-fetches it (`step_entries` included).
    #[schemars(with = "String")]
    run_id: RunId,
}

/// Which layer of the TTL cascade (request body → BP metadata → server
/// default) resolved [`TaskLaunchResponse::effective_ttl_secs`]. `pub` for
/// the same cross-crate schema-generation reason as `TaskLaunchRequest`.
#[derive(Serialize, Clone, Copy, Debug, PartialEq, Eq, schemars::JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum TtlSource {
    /// The request body's `ttl_secs` was set explicitly.
    RequestBody,
    /// The request body omitted `ttl_secs`; the resolved Blueprint's
    /// `metadata.default_run_ttl_secs` was set.
    BpMetadata,
    /// Both the request body and the Blueprint metadata omitted a TTL;
    /// the server-global `default_run_ttl()` (1800s) applied.
    ServerDefault,
}

/// Unified `/v1/tasks` POST entry (= Flow form only).
/// Runs `Blueprint.flow` to completion via flow eval in a single round-trip.
/// One-shot tasks are also expressed as a 1-Step Blueprint. Operator
/// (kind / spawn_hook / senior_bridge) can be injected per request body.
/// `operator_sid` (S2, runtime Operator match stage 1) additionally
/// lets the caller pin the task to a specific already-registered Operator
/// session sid, bypassing BP-level alias lookup — see `TaskLaunchRequest` doc.
async fn tasks_start(
    State(state): State<AppState>,
    Json(req): Json<TaskLaunchRequest>,
) -> Result<Json<TaskLaunchResponse>, ApiError> {
    let resp = run_flow_form(&state, req).await?;
    Ok(Json(resp))
}

/// Flow-form path (= via `TaskApplication::handle_with_run`).
/// Core handler behind the `/v1/tasks` entry (`tasks_start`).
///
/// Engine stateless-executor refactor: the per-request
/// sub_engine + 3-registry propagate loop is retired; the startup-built
/// `state.task_app` (= a `TaskLaunchService` wrap around `state.engine`) is
/// used directly. The Operator callback IF (`spawn_hook_id` /
/// `senior_bridge_id` / `operator_backend_id`) is registered on
/// `state.engine.register_*` at WS connect time — the engine is the SoT.
/// See the `operator_ws` module doc for details.
async fn run_flow_form(
    state: &AppState,
    req: TaskLaunchRequest,
) -> Result<TaskLaunchResponse, ApiError> {
    use mlua_swarm::application::{BlueprintRef as AppBlueprintRef, TaskApplicationInput};
    use mlua_swarm::OperatorKind;

    // Snapshot everything the TaskRecord needs before `req.blueprint` /
    // `req.init_ctx` are moved into the dispatch path below.
    let blueprint_ref_json = serde_json::to_value(&req.blueprint)
        .map_err(|e| ApiError::bad_request(format!("blueprint snapshot: {e}")))?;
    let input_ctx_snapshot = req.init_ctx.clone();
    let goal = req.goal.clone().unwrap_or_default();

    // issue #19 ST2: resolve the Task-level canonical fields
    // (`project_root` / `work_dir` / `task_metadata`) once, at the wire
    // boundary. Sibling top-level fields on the request body take
    // priority; the pre-#19 shape (same key nested inside `init_ctx`) is
    // only a fallback for legacy callers. The result is threaded straight
    // through as `TaskApplicationInput.task_input` — `init_ctx` itself is
    // NOT mutated, so it stays a pure flow-ir eval seed identical to
    // whatever the caller sent.
    let task_input_spec = build_task_input_spec_from_request(&req);
    // Issue #19 ST4: snapshot the resolved spec into the `TaskRecord` (JSON,
    // same "bare `Value`" rationale as `blueprint_ref_json` /
    // `input_ctx_snapshot` above) so `POST /v1/tasks/:id/runs` can resolve
    // it back out on rekick without re-deriving it from a since-stale
    // request body. Cloned rather than computed from `task_input_spec`
    // after the fact — the original is still moved into
    // `TaskApplicationInput.task_input` below.
    let task_input_spec_snapshot = task_input_spec
        .clone()
        .map(|spec| serde_json::to_value(&spec))
        .transpose()
        .map_err(|e| ApiError::bad_request(format!("task_input_spec snapshot: {e}")))?;
    let init_ctx = req.init_ctx.clone();

    let mut op_req = req.operator.unwrap_or_default();

    // S2: explicit `operator_sid` override (runtime Operator match stage 1).
    // Resolved *before* building `operator_kind` / dispatching so an
    // unknown sid fails fast with a 400, never silently falling back to the
    // BP-level alias lookup. See `TaskLaunchRequest::operator_sid` doc for the
    // disconnected-vs-unknown distinction.
    if let Some(sid) = &req.operator_sid {
        let known_ids = state.engine.list_operator_ids().await;
        if !known_ids.iter().any(|id| id == sid) {
            return Err(ApiError::bad_request(format!(
                "operator_sid: no such registered operator session '{sid}'"
            )));
        }
        op_req.operator_backend_id = Some(sid.clone());
    }

    // "Runtime Global" tier: `Some(_)` — including `Some(Automate)` — is
    // always an explicit request that outranks the BP-level tiers; an
    // absent/unset `kind` in the request body stays `None`, leaving the
    // BP-level tiers (`OperatorDef.kind` / `Blueprint.default_operator_kind`)
    // to decide instead of eagerly defaulting to `Automate`.
    let operator_kind = op_req
        .kind
        .as_deref()
        .map(parse_operator_kind_str)
        .transpose()?;
    let operator_id = op_req.id.unwrap_or_else(|| "http-run".to_string());
    // "Runtime Agent-level" tier: per-agent overrides. Absent/empty = no
    // override for any agent, letting the BP-level tiers decide per agent.
    let mut operator_kind_overrides: HashMap<String, OperatorKind> = HashMap::new();
    for (agent, kind_str) in op_req.per_agent_kinds.take().unwrap_or_default() {
        operator_kind_overrides.insert(agent, parse_operator_kind_str(&kind_str)?);
    }

    let blueprint: AppBlueprintRef = match req.blueprint {
        AppBlueprintRef::Inline { value } => AppBlueprintRef::Inline { value },
        AppBlueprintRef::Id { id, version } => AppBlueprintRef::Id { id, version },
    };

    // TTL resolution cascade: (1) request body value, (2) BP metadata `default_run_ttl_secs`,
    // (3) server global default (`default_run_ttl()`, 1800s).
    let (ttl_secs, ttl_source) = match req.ttl_secs {
        Some(v) => (v, TtlSource::RequestBody),
        None => {
            let (resolved_bp, _ver) = state
                .task_app
                .resolve(&blueprint)
                .await
                .map_err(|e| ApiError::bad_request(format!("bp resolve: {e}")))?;
            match resolved_bp.metadata.default_run_ttl_secs {
                Some(v) => (v, TtlSource::BpMetadata),
                None => (default_run_ttl(), TtlSource::ServerDefault),
            }
        }
    };

    // issue #13 ID-hierarchy persistence: mint the work-item identity (Task)
    // and this kick's identity (Run) *before* dispatching, so a Task/Run
    // pair always exists even if the flow itself fails mid-way (the
    // Failed-status paths below still have a row to update).
    let task_id = TaskId::new();
    let run_id = RunId::new();
    let now = tasks::now_secs();
    state
        .task_store
        .create(TaskRecord {
            id: task_id.clone(),
            goal,
            blueprint_ref: blueprint_ref_json,
            input_ctx: input_ctx_snapshot,
            task_input_spec: task_input_spec_snapshot,
            status: TaskRecordStatus::Running,
            created_at: now,
            updated_at: now,
        })
        .await
        .map_err(ApiError::engine)?;
    state
        .run_store
        .create(RunRecord {
            id: run_id.clone(),
            task_id: task_id.clone(),
            status: RunStatus::Running,
            step_entries: Vec::new(),
            operator_sid: req.operator_sid.clone(),
            result_ref: None,
            created_at: now,
            updated_at: now,
        })
        .await
        .map_err(ApiError::engine)?;

    let run_ctx = RunContext {
        run_id: run_id.clone(),
        run_store: state.run_store.clone(),
    };
    let outcome = state
        .task_app
        .handle_with_run(
            TaskApplicationInput {
                blueprint,
                operator_id: operator_id.clone(),
                role: Role::Operator,
                ttl: Duration::from_secs(ttl_secs),
                init_ctx,
                operator_kind,
                bridge_id: op_req.senior_bridge_id,
                hook_id: op_req.spawn_hook_id,
                operator_backend_id: op_req.operator_backend_id,
                operator_kind_overrides,
                task_input: task_input_spec,
            },
            Some(run_ctx),
        )
        .await;

    let out = tasks::finalize_run(state, &task_id, &run_id, outcome)
        .await
        .map_err(|e| ApiError::bad_request(format!("run: {e}")))?;

    Ok(TaskLaunchResponse {
        final_ctx: out.final_ctx,
        bound_version: out.bound_version.map(|v| format!("{:?}", v)),
        effective_ttl_secs: ttl_secs,
        ttl_source,
        task_id,
        run_id,
    })
}

/// issue #19 ST2 direct sibling-field resolver — extracts the three
/// Task-level canonical fields (`project_root` / `work_dir` /
/// `task_metadata`) once at the wire boundary. Sibling top-level body
/// fields take priority; the pre-#19 shape (same key nested inside
/// `init_ctx`) is only a fallback for legacy callers. Unlike the ST1
/// `resolve_task_level_init_ctx` bridge this replaced, `init_ctx` is
/// NOT mutated — the resolved values are handed straight to
/// [`mlua_swarm::service::TaskLaunchInput::task_input`], keeping
/// `init_ctx` a pure flow-ir eval seed.
///
/// Returns `None` when all three fields resolve to `None` (no
/// middleware is layered onto the spawner stack downstream — the
/// [`mlua_swarm::middleware::task_input::TaskInputMiddleware::new_from_fields`]
/// contract).
fn build_task_input_spec_from_request(
    req: &TaskLaunchRequest,
) -> Option<mlua_swarm::service::TaskInputSpec> {
    let project_root = req.project_root.clone().or_else(|| {
        req.init_ctx
            .get("project_root")
            .and_then(Value::as_str)
            .map(String::from)
    });
    let work_dir = req.work_dir.clone().or_else(|| {
        req.init_ctx
            .get("work_dir")
            .and_then(Value::as_str)
            .map(String::from)
    });
    let task_metadata = req.task_metadata.clone().or_else(|| {
        req.init_ctx
            .get("task_metadata")
            .filter(|v| v.is_object())
            .cloned()
    });

    if project_root.is_none() && work_dir.is_none() && task_metadata.is_none() {
        None
    } else {
        Some(mlua_swarm::service::TaskInputSpec {
            project_root,
            work_dir,
            task_metadata,
        })
    }
}

// ─── helpers ─────────────────────────────────────────────────────────────

async fn take_session_token(state: &AppState, sid: &str) -> Result<CapToken, ApiError> {
    // `sid` on this path is the token nonce itself (a bearer secret), so
    // both the map key and the not-found diagnostic use its fingerprint
    // (issue #14 — never echo the nonce back in an error body).
    let key = mlua_swarm::types::token_fingerprint(sid);
    state
        .sessions
        .lock()
        .await
        .map
        .remove(&key)
        .ok_or_else(|| ApiError::not_found(format!("session: fp={key}")))
}

/// Extracts sid from `Authorization: Bearer <sid>`. Strict — does not accept any other scheme prefix.
fn extract_bearer(headers: &HeaderMap) -> Result<String, ApiError> {
    let v = headers
        .get(AUTHORIZATION)
        .ok_or_else(|| ApiError::bad_request("missing Authorization header".into()))?
        .to_str()
        .map_err(|_| ApiError::bad_request("invalid Authorization header encoding".into()))?;
    let sid = v
        .strip_prefix("Bearer ")
        .ok_or_else(|| ApiError::bad_request("Authorization must be 'Bearer <sid>'".into()))?
        .trim();
    if sid.is_empty() {
        return Err(ApiError::bad_request("Bearer sid is empty".into()));
    }
    Ok(sid.to_string())
}

fn parse_role(s: &str) -> Result<Role, ApiError> {
    match s.to_ascii_lowercase().as_str() {
        "operator" => Ok(Role::Operator),
        "worker" => Ok(Role::Worker),
        "observer" => Ok(Role::Observer),
        "senior" => Ok(Role::Senior),
        other => Err(ApiError::bad_request(format!("unknown role: {other}"))),
    }
}

// ─── error type ──────────────────────────────────────────────────────────

/// Uniform error response type for the handlers in this module. Converts to
/// a JSON `{"error": message}` body with the given status via [`IntoResponse`].
#[derive(Debug)]
pub struct ApiError {
    status: StatusCode,
    message: String,
}

impl ApiError {
    /// Wraps an engine-side error as `500 Internal Server Error`.
    pub fn engine(e: impl std::fmt::Display) -> Self {
        Self {
            status: StatusCode::INTERNAL_SERVER_ERROR,
            message: format!("engine: {e}"),
        }
    }
    /// Builds a `404 Not Found` with the given message.
    pub fn not_found(m: String) -> Self {
        Self {
            status: StatusCode::NOT_FOUND,
            message: m,
        }
    }
    /// Builds a `400 Bad Request` with the given message.
    pub fn bad_request(m: String) -> Self {
        Self {
            status: StatusCode::BAD_REQUEST,
            message: m,
        }
    }
}

impl IntoResponse for ApiError {
    fn into_response(self) -> Response {
        (self.status, Json(json!({"error": self.message}))).into_response()
    }
}

fn default_run_ttl() -> u64 {
    // 1800s (= 30 min). Prevents op_token expiry across a flow.ir multi-step chain
    // (= 5+ SubAgent dispatches at 30–60s each). Origin: the observed fvloop smoke
    // where a post-gate mock-commit dispatch blew past 300s and expired — sibling of worker_token TTL.
    1800
}

/// TTL cascade resolve helper (Blueprint metadata → server default fallback).
/// Second-stage fallback, called when the POST `/v1/tasks` body does not set `ttl_secs`.
/// (1) If BP metadata `default_run_ttl_secs` is `Some`, use it.
/// (2) If `None`, fall back to the server global `default_run_ttl()` (1800s).
///
/// # Full cascade (combined in `run_flow_form`)
///
/// - request body `ttl_secs=Some(v)` → v (this helper is not called)
/// - request body `None` + metadata `Some(v)` → v
/// - request body `None` + metadata `None` → `default_run_ttl()` = 1800s
#[cfg(test)]
fn resolve_ttl_from_metadata(metadata_ttl: Option<u64>) -> u64 {
    metadata_ttl.unwrap_or_else(default_run_ttl)
}

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

    /// TTL cascade case 1: when the request body sets it, that value is used as-is
    /// (upper branch that does not go through the helper; semantic verify of the
    /// `Some(v) => v` direct-return path in `run_flow_form`).
    #[test]
    fn ttl_cascade_request_body_wins_over_metadata() {
        let req_ttl: Option<u64> = Some(100);
        let metadata_ttl: Option<u64> = Some(3600);
        let effective = match req_ttl {
            Some(v) => v,
            None => resolve_ttl_from_metadata(metadata_ttl),
        };
        assert_eq!(
            effective, 100,
            "request body ttl_secs=100 must win over metadata=3600 (cascade priority (1) > (2))"
        );
    }

    /// TTL cascade case 2: request body omitted + BP metadata `Some(N)` → `N` is effective.
    #[test]
    fn ttl_cascade_metadata_used_when_body_missing() {
        let req_ttl: Option<u64> = None;
        let metadata_ttl: Option<u64> = Some(3600);
        let effective = match req_ttl {
            Some(v) => v,
            None => resolve_ttl_from_metadata(metadata_ttl),
        };
        assert_eq!(
            effective, 3600,
            "body None + metadata=3600 must resolve to 3600 (cascade (2))"
        );
    }

    /// TTL cascade case 3: request body omitted + BP metadata `None` → server default (1800s).
    #[test]
    fn ttl_cascade_server_default_when_both_missing() {
        let req_ttl: Option<u64> = None;
        let metadata_ttl: Option<u64> = None;
        let effective = match req_ttl {
            Some(v) => v,
            None => resolve_ttl_from_metadata(metadata_ttl),
        };
        assert_eq!(
            effective,
            default_run_ttl(),
            "body None + metadata None must fall back to default_run_ttl() = 1800s"
        );
        assert_eq!(effective, 1800, "default_run_ttl() literal = 1800s");
    }

    /// Helper unit: metadata `None` → 1800 (server default expansion).
    #[test]
    fn resolve_ttl_from_metadata_none_returns_server_default() {
        assert_eq!(resolve_ttl_from_metadata(None), 1800);
    }

    /// Helper unit: metadata `Some(N)` → `N` (server default ignored).
    #[test]
    fn resolve_ttl_from_metadata_some_returns_value() {
        assert_eq!(resolve_ttl_from_metadata(Some(7200)), 7200);
        assert_eq!(resolve_ttl_from_metadata(Some(60)), 60);
    }

    // ──────────────────────────────────────────────────────────────────
    // issue #19 ST2: `build_task_input_spec_from_request` direct resolver
    // ──────────────────────────────────────────────────────────────────

    fn task_req(
        init_ctx: Value,
        project_root: Option<&str>,
        work_dir: Option<&str>,
        task_metadata: Option<Value>,
    ) -> TaskLaunchRequest {
        TaskLaunchRequest {
            blueprint: BlueprintRef::Id {
                id: mlua_swarm::blueprint::store::BlueprintId::new("ut"),
                version: Default::default(),
            },
            init_ctx,
            project_root: project_root.map(String::from),
            work_dir: work_dir.map(String::from),
            task_metadata,
            ttl_secs: None,
            operator: None,
            operator_sid: None,
            goal: None,
        }
    }

    /// (a) Sibling fields only — no legacy keys in `init_ctx` — are
    /// returned in the `TaskInputSpec` unchanged. `init_ctx` itself is
    /// untouched by this resolver (checked separately at the call site).
    #[test]
    fn build_task_input_spec_from_request_returns_sibling_fields_when_present() {
        let req = task_req(
            json!({"free": "form"}),
            Some("/repo/sibling"),
            Some("/repo/sibling/work"),
            Some(json!({"issue": 19})),
        );
        let spec = build_task_input_spec_from_request(&req).expect("spec must be Some");
        assert_eq!(spec.project_root.as_deref(), Some("/repo/sibling"));
        assert_eq!(spec.work_dir.as_deref(), Some("/repo/sibling/work"));
        assert_eq!(spec.task_metadata, Some(json!({"issue": 19})));
    }

    /// (b) No sibling fields — the pre-#19 shape (same 3 keys nested
    /// inside `init_ctx`) is used as the fallback source.
    #[test]
    fn build_task_input_spec_from_request_falls_back_to_legacy_init_ctx_shape() {
        let req = task_req(
            json!({
                "project_root": "/repo/legacy",
                "work_dir": "/repo/legacy/work",
                "task_metadata": {"issue": 17},
            }),
            None,
            None,
            None,
        );
        let spec = build_task_input_spec_from_request(&req).expect("spec must be Some");
        assert_eq!(spec.project_root.as_deref(), Some("/repo/legacy"));
        assert_eq!(spec.work_dir.as_deref(), Some("/repo/legacy/work"));
        assert_eq!(spec.task_metadata, Some(json!({"issue": 17})));
    }

    /// (c) Both present — the sibling field must win over the legacy
    /// `init_ctx`-nested value.
    #[test]
    fn build_task_input_spec_from_request_sibling_wins_over_legacy_shape() {
        let req = task_req(
            json!({
                "project_root": "/repo/legacy",
                "work_dir": "/repo/legacy/work",
                "task_metadata": {"issue": 17},
            }),
            Some("/repo/sibling"),
            Some("/repo/sibling/work"),
            Some(json!({"issue": 19})),
        );
        let spec = build_task_input_spec_from_request(&req).expect("spec must be Some");
        assert_eq!(
            spec.project_root.as_deref(),
            Some("/repo/sibling"),
            "sibling field must win over the legacy init_ctx-nested value"
        );
        assert_eq!(spec.work_dir.as_deref(), Some("/repo/sibling/work"));
        assert_eq!(spec.task_metadata, Some(json!({"issue": 19})));
    }

    /// (d) All three fields absent from both sibling and legacy shapes —
    /// resolver returns `None`, and no middleware is layered downstream.
    #[test]
    fn build_task_input_spec_from_request_returns_none_when_no_fields_present() {
        let req = task_req(json!({"unrelated": "value"}), None, None, None);
        assert!(build_task_input_spec_from_request(&req).is_none());
    }
}