car_server_core/

handler.rs

//! WebSocket connection handler — bidirectional JSON-RPC.
//!
//! Tool callback flow:
//! 1. Client submits proposal via proposal.submit
//! 2. Runtime encounters a ToolCall action
//! 3. WsToolExecutor sends tools.execute request to client via shared write half
//! 4. WsToolExecutor awaits response on a oneshot channel
//! 5. Client executes tool locally, sends JSON-RPC response back
//! 6. Handler receives the response, resolves the oneshot
//! 7. Runtime continues execution with the tool result

use crate::session::{A2aRouteAuth, ChatGoalState, ServerState, WsChannel};
use car_proto::*;
use car_verify;
use futures::{SinkExt, StreamExt};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use sha2::{Digest, Sha256};
use std::collections::HashMap;
use std::net::SocketAddr;
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use std::sync::Arc;
use tokio::net::TcpStream;
use tokio::sync::Mutex;
use tokio_tungstenite::{accept_async, tungstenite::Message};
use tracing::{error, info, instrument};

#[cfg(test)]
struct CredentialFanoutTestGate {
    ready: tokio::sync::Notify,
    release: tokio::sync::Notify,
}

#[cfg(test)]
fn credential_fanout_test_gate() -> &'static CredentialFanoutTestGate {
    static GATE: std::sync::OnceLock<CredentialFanoutTestGate> = std::sync::OnceLock::new();
    GATE.get_or_init(|| CredentialFanoutTestGate {
        ready: tokio::sync::Notify::new(),
        release: tokio::sync::Notify::new(),
    })
}

#[cfg(test)]
async fn pause_credential_fanout_for_test() {
    if std::env::var_os("CAR_TEST_PAUSE_CREDENTIAL_FANOUT").is_some() {
        let gate = credential_fanout_test_gate();
        gate.ready.notify_one();
        gate.release.notified().await;
    }
}

#[cfg(not(test))]
async fn pause_credential_fanout_for_test() {}

#[cfg(test)]
fn credential_handoff_test_gate() -> &'static CredentialFanoutTestGate {
    static GATE: std::sync::OnceLock<CredentialFanoutTestGate> = std::sync::OnceLock::new();
    GATE.get_or_init(|| CredentialFanoutTestGate {
        ready: tokio::sync::Notify::new(),
        release: tokio::sync::Notify::new(),
    })
}

#[cfg(test)]
async fn pause_credential_handoff_for_test() {
    if std::env::var_os("CAR_TEST_PAUSE_CREDENTIAL_HANDOFF").is_some() {
        let gate = credential_handoff_test_gate();
        gate.ready.notify_one();
        gate.release.notified().await;
    }
}

#[cfg(not(test))]
async fn pause_credential_handoff_for_test() {}

fn credential_event_is_eligible(
    session: &crate::session::ClientSession,
    transport_auth_required: bool,
    host_role_required: bool,
) -> bool {
    (!transport_auth_required || session.authenticated.load(Ordering::Acquire))
        && (!host_role_required || session.is_host.load(Ordering::Acquire))
        && session.negotiated_protocol_version.load(Ordering::Acquire)
            == car_proto::PROTOCOL_VERSION
}

fn credential_status_advances(
    previous: Option<car_auth::CredentialReadStatus>,
    next: car_auth::CredentialReadStatus,
) -> bool {
    let Some(previous) = previous else {
        return true;
    };
    if next.generation != previous.generation {
        return next.generation > previous.generation;
    }
    previous.state == car_auth::CredentialReadStatusState::Pending
        && next.state != car_auth::CredentialReadStatusState::Pending
}

#[derive(Debug, Clone, Deserialize)]
#[allow(dead_code)]
pub struct JsonRpcMessage {
    #[serde(default)]
    pub jsonrpc: String,
    #[serde(default)]
    pub method: Option<String>,
    #[serde(default)]
    pub params: Value,
    #[serde(default)]
    pub id: Value,
    // Response fields
    #[serde(default)]
    pub result: Option<Value>,
    #[serde(default)]
    pub error: Option<Value>,
}

#[derive(Debug, Serialize)]
pub struct JsonRpcResponse {
    pub jsonrpc: &'static str,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub result: Option<Value>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<JsonRpcError>,
    pub id: Value,
}

#[derive(Debug, Serialize)]
pub struct JsonRpcError {
    pub code: i32,
    pub message: String,
}

impl JsonRpcResponse {
    pub fn success(id: Value, result: Value) -> Self {
        Self {
            jsonrpc: "2.0",
            result: Some(result),
            error: None,
            id,
        }
    }
    pub fn error(id: Value, code: i32, message: &str) -> Self {
        Self {
            jsonrpc: "2.0",
            result: None,
            error: Some(JsonRpcError {
                code,
                message: message.to_string(),
            }),
            id,
        }
    }
}

/// The `-32001 auth required` body, naming the file the client should actually
/// read.
///
/// It used to name the three per-platform defaults unconditionally. That is the
/// wrong file for any daemon started with `CAR_HOME`: the token directory moves
/// under the state root (see `car_daemon_client::auth_token`, which resolves
/// `CAR_HOME` ahead of the per-platform branches), so an operator running an
/// isolated daemon was sent to the *primary's* token — the one credential
/// `CAR_HOME` exists to stop the two daemons from sharing. Names the path, never
/// the token value.
fn auth_required_message() -> String {
    const PREFIX: &str = "auth required: send `session.auth` with the per-launch token";
    const SUFFIX: &str = "as the first frame on this connection";
    match car_home::override_root() {
        Some(root) => format!(
            "{PREFIX} from {} {SUFFIX} (CAR_HOME is set, so this daemon's token \
             lives under its own state root, not the default per-platform directory)",
            root.join("ai.parslee.car").join("auth-token").display(),
        ),
        None => format!(
            "{PREFIX} from ~/Library/Application Support/ai.parslee.car/auth-token \
             (macOS), $XDG_RUNTIME_DIR/ai.parslee.car/auth-token (Linux), or \
             %LOCALAPPDATA%\\ai.parslee.car\\auth-token (Windows) {SUFFIX} \
             (setting CAR_HOME moves the token under that state root instead)"
        ),
    }
}

// ---------------------------------------------------------------------------
// Param-extraction helpers
//
// Every JSON-RPC handler pulls fields off `req.params` (a `serde_json::Value`).
// Before these helpers each arm hand-rolled the same three shapes — a required
// string (`.get(f).and_then(|v| v.as_str()).ok_or_else(|| "f is required")`), an
// optional string, and a full typed deserialize — with per-call-site error
// wording. These centralize the pattern and the wording so the ~200 call sites
// read uniformly and a new handler can't invent a fourth phrasing.
// ---------------------------------------------------------------------------

/// A required string field, or a uniform invalid-params error that names the
/// missing field. The prefix is classified as JSON-RPC -32602 at the dispatch
/// boundary.
pub(crate) fn require_str<'a>(params: &'a Value, field: &str) -> Result<&'a str, String> {
    params
        .get(field)
        .and_then(|v| v.as_str())
        .ok_or_else(|| format!("invalid params: {field} is required"))
}

/// An optional string field (absent or non-string → `None`).
pub(crate) fn opt_str<'a>(params: &'a Value, field: &str) -> Option<&'a str> {
    params.get(field).and_then(|v| v.as_str())
}

/// An optional string field with a fallback default.
pub(crate) fn str_or<'a>(params: &'a Value, field: &str, default: &'a str) -> &'a str {
    params
        .get(field)
        .and_then(|v| v.as_str())
        .unwrap_or(default)
}

/// Deserialize the whole params object into `T`, with a uniform
/// `"invalid params: …"` error. The typed-params companion to [`require_str`].
pub(crate) fn typed_params<T: serde::de::DeserializeOwned>(params: &Value) -> Result<T, String> {
    serde_json::from_value(params.clone()).map_err(|e| format!("invalid params: {e}"))
}

/// Convenience wrapper for the standalone `car-server` binary: accepts
/// the WebSocket handshake on a raw [`TcpStream`] then delegates to
/// [`run_dispatch`]. Embedders that already have a handshake-completed
/// `WebSocketStream` skip this and call `run_dispatch` directly.
#[instrument(
    name = "ws.connection",
    skip_all,
    fields(peer = %peer),
)]
pub async fn handle_connection(
    stream: TcpStream,
    peer: SocketAddr,
    state: Arc<ServerState>,
) -> Result<(), Box<dyn std::error::Error>> {
    let ws_stream = accept_async(stream).await?;
    let (write, read) = ws_stream.split();
    run_dispatch(read, Box::pin(write), peer.to_string(), state).await
}

/// Convenience wrapper for the daemon-as-default Unix-socket
/// listener. Same shape as [`handle_connection`] but accepts a
/// `UnixStream` — used by the per-user UDS listener in
/// `car-server::main` (default transport for FFI thin clients,
/// since UDS is faster + permission-scoped vs localhost TCP).
///
/// Unix-only — `tokio::net::UnixStream` is gated on
/// `cfg(all(unix, feature = "net"))`. On Windows the daemon binds
/// only the TCP listener (loopback) and this entry point is
/// compiled out; consumers must use `handle_connection` instead.
#[cfg(unix)]
#[instrument(
    name = "ws.connection",
    skip_all,
    fields(peer = %peer),
)]
pub async fn handle_connection_unix(
    stream: tokio::net::UnixStream,
    peer: String,
    state: Arc<ServerState>,
) -> Result<(), Box<dyn std::error::Error>> {
    let ws_stream = tokio_tungstenite::accept_async(stream).await?;
    let (write, read) = ws_stream.split();
    run_dispatch(read, Box::pin(write), peer, state).await
}

fn handler_default_deadline_secs() -> u64 {
    std::env::var("CAR_HANDLER_TIMEOUT")
        .ok()
        .and_then(|s| s.trim().parse::<u64>().ok())
        .unwrap_or(1800)
}

/// Per-request server-side deadline. A wedged handler that never completes
/// otherwise hangs the calling client forever (try/catch can't catch a hang) —
/// the incident class this guards against. Policy errs toward NOT killing real
/// work:
///   - Genuinely UNBOUNDED methods (streams, subscriptions, run-loops, voice
///     turns) are EXEMPT (None) — they legitimately stay open indefinitely.
///   - Bounded, CANCELLATION-SAFE reads (list/get/query/count, auth/handshake)
///     get a tight deadline so a wedge recovers quickly — dropping a read
///     mid-flight can't corrupt state.
///   - EVERYTHING ELSE — including MUTATING memory ops (add_fact/persist/
///     consolidate, which mutate-then-persist) and all agentic/inference/
///     workflow/automation methods, and any method not explicitly classified —
///     gets a GENEROUS default, which is well above any legitimate duration, so
///     real work is never killed yet a true infinite wedge is still reaped. We
///     do NOT pull mutating handlers into the tight bucket, because a mid-flight
///     drop there could leave in-memory and on-disk state divergent. Override
///     the default via CAR_HANDLER_TIMEOUT (seconds).
///   - `proposal.submit` additionally RAISES that default when the submitted
///     proposal's own action budgets exceed it — see
///     [`proposal_submit_deadline_secs`]. The generous default used to be
///     justified by "the client itself caps proposal.submit at ~900s"; #265
///     deleted that premise by deriving the client read deadline from the
///     proposal's budgets, so a flat server deadline would re-reap server-side
///     exactly what the client patiently waits for.
///
/// NOTE: timeout cancels the handler future at an .await point — it reaps async
/// hangs (e.g. a lock().await that never acquires). It cannot preempt a handler
/// blocked inside a synchronous syscall with no .await; those need spawn_blocking.
// ---- Deadline policy table (auditable in one place; covered by tests below) ----
// Unbounded by design — streams/subscriptions/run-loops/voice turns. Any NEW
// indefinitely-blocking method MUST add its token here or it will inherit the
// generous default and be killed.
// `heal.run` is exempt because its own internals are bounded and the handler
// default is NOT: the per-item ceiling is 2700s against a 1800s default, so
// every sweep that actually did work was dropped mid-session. A dropped future
// cannot clean up, and `heal_runner` has already taken the session's
// `JoinHandle` — dropping it DETACHES the coder session rather than aborting
// it, leaving it editing the operator's repository with `coder.cancel` disarmed
// while the next cadence tick starts a second session on the same branch. The
// operation bounds itself (item ceiling, panel ceiling, single-sweep lock);
// what it cannot survive is being cut in half.
const DEADLINE_EXEMPT_SUBSTRINGS: &[&str] = &[
    "stream",
    "subscribe",
    "run_loop",
    "dispatch_turn",
    "heal.run",
];
// Credential-backed auth operations are daemon-owned, not merely deadline
// exempt. Their core futures carry no connection/session/channel and survive a
// socket close; only their response waiters live in `conn_tasks`.
const DAEMON_OWNED_AUTH_METHODS: &[&str] = &[
    "auth.authority_hint",
    "auth.start",
    "auth.complete",
    "auth.completion_status",
    "auth.snapshot",
    "auth.status",
    "auth.switch_org",
    "auth.accounts",
    "auth.switch_account",
    "auth.remove_account",
    "auth.logout",
];
// FAST = bounded, CANCELLATION-SAFE reads only. Mutating/heavy methods are
// deliberately omitted so they take the safe generous default — a mid-flight
// drop on a mutator could diverge in-memory vs on-disk state. The suffixes are a
// heuristic: any NEW .list/.get/.query/.count that mutates or does heavy I/O
// must be excluded (it then falls through to the safe default).
const DEADLINE_FAST_SUFFIXES: &[&str] = &[".list", ".get", ".query", ".count"];
const DEADLINE_FAST_PREFIXES: &[&str] = &["auth."];
const DEADLINE_FAST_EXACT: &[&str] = &[
    "agents.health",
    // Bounded read of the installed admission rules. The *setter* is
    // deliberately absent: it mutates, so it takes the safe generous default.
    "memory.admission_table",
    "memory.evaluate",
    "memory.intervene",
    "server.handshake",
    "session.auth",
    "session.init",
];
const DEADLINE_FAST_SECS: u64 = 180;
/// Transport grace added on top of a `proposal.submit`'s derived action budget,
/// so the daemon's handler deadline fires strictly *after* the executor's own
/// per-action waits.
///
/// What this guarantees unconditionally is the hop that matters: the daemon
/// never abandons a submit the executor is still legitimately spending budget
/// on. `car-engine`'s `execute_with_retry` reaps a single attempt at
/// `timeout_ms`; this deadline reaps the whole submit no earlier than
/// `Σ(budget × attempts) + 15s`.
///
/// Keep this value STRICTLY SMALLER than the client's 30s
/// `car_daemon_client::proxy::PROPOSAL_TRANSPORT_GRACE_SECS`, so that wherever
/// the two derivations both dominate their floors, the daemon answers first and
/// the caller sees an explicit `-32004` rather than an opaque transport timeout.
/// That full innermost-first ordering — executor → daemon handler → client —
/// only holds once the derived term clears both floors (Σ above roughly 1785s,
/// this default minus this grace). Below it the client's 900s floor is smaller
/// than this 1800s default and the client gives up first. That inversion
/// predates the derivation and harms nothing: the client's floor still strictly
/// exceeds the executor's worst case there, so no in-budget work is killed —
/// only a genuinely wedged handler surfaces as a transport timeout instead of
/// `-32004`.
const PROPOSAL_DEADLINE_GRACE_SECS: u64 = 15;
/// `max_retries` assumed for a `failure_behavior: "retry"` action that does not
/// pin one. Mirrors `car_ir`'s private `default_max_retries()` (3), pinned to it
/// by `derived_retry_default_matches_car_ir` below. The executor runs
/// `max_retries + 1` attempts for a retry action, so the default worst case is
/// 4 attempts, not 3 — the same undercount #265 fixed on the client side.
const DEFAULT_PROPOSAL_MAX_RETRIES: u64 = 3;
/// JSON-RPC application error for a handler abandoned by the daemon's own
/// deadline. Clients must distinguish this ambiguous outcome from a handler
/// that replied with a terminal failure.
const HANDLER_DEADLINE_ERROR_CODE: i32 = -32004;

/// Protocol v2 made the Parslee browser-login lifecycle attempt-bound. An old
/// host may understand `host.subscribe` and `auth.start` but not the required
/// `auth.complete`/reconciliation contract, so those surfaces must stay hidden
/// until this connection has proved exact wire compatibility.
fn requires_protocol_handshake(method: &str) -> bool {
    method == "host.subscribe"
        || method.starts_with("auth.")
        || method == "diagnostics.secret_store_activity"
        || method == "session.clear_halt"
        || method == "infer.cancel"
        || method == "infer.deadline"
        || method == "runs.cancel"
        || matches!(
            method,
            "agent_permissions.set_tool"
                | "agent_permissions.reset_tool"
                | "agent_permissions.evaluate_tool"
        )
        // The feedback.* surface is protocol-v2-native (PAR-1): a legacy host
        // has no consent UI for it, so it stays hidden pre-negotiation.
        || method == "feedback.compose_preview"
        || method == "feedback.submit"
        || method == "feedback.status"
        || method == "feedback.list"
}

fn session_has_capability(session: &crate::session::ClientSession, capability: &str) -> bool {
    session
        .negotiated_capabilities
        .read()
        .map(|capabilities| capabilities.contains(capability))
        .unwrap_or(false)
}

/// The `feedback.*` surface is capability-gated like every sibling surface
/// (`infer.cancel`, `runs.resume`, …): a session that completed the v3
/// handshake WITHOUT negotiating `feedback.v1` cannot spool reports or read
/// submission summaries. The refusal carries the standard mismatch prefix so
/// bundled clients classify it the same way as the other gated methods.
fn require_feedback_capability(session: &crate::session::ClientSession) -> Result<(), String> {
    if session_has_capability(session, car_proto::FEEDBACK_CAPABILITY) {
        Ok(())
    } else {
        Err(format!(
            "{} negotiate `{}` as a required or optional capability before calling `feedback.*`",
            car_proto::PROTOCOL_CAPABILITY_MISMATCH_MESSAGE_PREFIX,
            car_proto::FEEDBACK_CAPABILITY
        ))
    }
}

fn require_agent_tool_override_capability(
    session: &crate::session::ClientSession,
) -> Result<(), String> {
    if session_has_capability(session, car_proto::AGENT_TOOL_OVERRIDES_CAPABILITY) {
        Ok(())
    } else {
        Err(format!(
            "this operation requires negotiated capability {}",
            car_proto::AGENT_TOOL_OVERRIDES_CAPABILITY
        ))
    }
}

// ---- WebSocket keepalive (server-side ping/liveness) ----
// tokio-tungstenite sends no automatic pings, so a silently-dead connection
// (TCP half-open, no close frame) on a QUIET stream is never noticed and its
// subscriber/registry state leaks until daemon restart. We ping periodically;
// any inbound frame (incl. the pong) refreshes the liveness clock; no frame for
// KEEPALIVE_DEAD_AFTER (or a failed ping write) → the connection is dead.
const KEEPALIVE_PING_INTERVAL: std::time::Duration = std::time::Duration::from_secs(30);
const KEEPALIVE_DEAD_AFTER: std::time::Duration = std::time::Duration::from_secs(90); // ~3 missed pings
const KEEPALIVE_WRITE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10); // matches drain task
const DEFAULT_INFER_TOTAL_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(600);
/// Maximum time the daemon keeps a composed auth-state response waiter:
/// 30s bounded in-process coordinator queue + 30s cross-process auth lock +
/// one 15s authoritative read + one 15s reservation/claim/terminal publication
/// + 5s scheduling margin. The state operation itself is daemon-owned;
/// exceeding this response bound never drops its coordinator guard or blocking
/// worker.
const AUTH_STATE_RESPONSE_DEADLINE: std::time::Duration = std::time::Duration::from_secs(95);
const AUTH_COMPLETE_PRE_REDEMPTION_RETRY_PREFIX: &str =
    "auth coordination deadline before redemption; safe to retry auth.complete";
const AUTH_START_RETRY_PREFIX: &str =
    "auth.start coordination deadline before reservation; safe to retry auth.start serially";
const AUTH_STATUS_RETRY_PREFIX: &str =
    "auth.completion_status coordination deadline; retry the proof read serially";
/// Native hosts reconcile an accepted or ambiguous completion for 480 seconds.
/// This server-side mirror exists only to prove that the daemon's bounded
/// retry/worker/proof/hydration composition continues to fit inside that
/// external horizon.
#[cfg(test)]
const AUTH_COMPLETION_HOST_RECONCILIATION_HORIZON: std::time::Duration =
    std::time::Duration::from_secs(480);

fn is_daemon_owned_auth_method(method: &str) -> bool {
    DAEMON_OWNED_AUTH_METHODS.contains(&method)
}

fn server_deadline_for(method: &str, params: &Value) -> Option<std::time::Duration> {
    if DEADLINE_EXEMPT_SUBSTRINGS
        .iter()
        .any(|s| method.contains(s))
    {
        return None;
    }
    let fast = DEADLINE_FAST_SUFFIXES.iter().any(|s| method.ends_with(s))
        || DEADLINE_FAST_PREFIXES.iter().any(|p| method.starts_with(p))
        || DEADLINE_FAST_EXACT.contains(&method);
    let secs = if fast {
        DEADLINE_FAST_SECS
    } else if method == "proposal.submit" {
        proposal_submit_deadline_secs(params)
    } else {
        handler_default_deadline_secs()
    };
    Some(std::time::Duration::from_secs(secs))
}

fn inference_total_timeout() -> std::time::Duration {
    std::env::var("CAR_INFER_TIMEOUT_SECS")
        .ok()
        .and_then(|value| value.parse::<u64>().ok())
        .map(std::time::Duration::from_secs)
        .unwrap_or(DEFAULT_INFER_TOTAL_TIMEOUT)
}

/// Server-side deadline for `proposal.submit`, derived from the budgets the
/// submitted proposal actually declares instead of a flat per-method constant.
///
/// `proposal.submit` blocks on the whole DAG — every action's tool callback,
/// every retry attempt. #265 taught the client to size its read deadline from
/// those same budgets, which deleted the premise the flat generous default here
/// rested on ("the client itself caps proposal.submit at ~900s"). Left flat,
/// this deadline abandoned a legitimately in-budget proposal with `-32004`
/// while `car-engine`'s `execute_with_retry` was still on an attempt and the
/// client was still patiently reading — the #259/#265 reap class relocated one
/// layer inward. One retried action with a 10-minute budget is already 2400s,
/// past the 1800s default.
///
/// The derivation ONLY RAISES: the result is
/// `max(handler_default_deadline_secs(), Σ + grace)`, so a short proposal, or
/// params carrying no parseable proposal, keeps exactly the generous default it
/// had before. `CAR_HANDLER_TIMEOUT` keeps its meaning as that default/floor —
/// it is deliberately NOT a ceiling here, because capping the daemon below the
/// executor's own budget is the bug this fixes.
fn proposal_submit_deadline_secs(params: &Value) -> u64 {
    let default_secs = handler_default_deadline_secs();
    match derive_proposal_budget_secs(params) {
        0 => default_secs,
        derived => default_secs.max(derived.saturating_add(PROPOSAL_DEADLINE_GRACE_SECS)),
    }
}

/// Cumulative daemon-side budget of a `proposal.submit`, in seconds, derived
/// from `proposal.actions[*].timeout_ms`. Returns 0 when no proposal/actions
/// are parseable, which the caller reads as "keep the generous default".
///
/// Mirrors `car_daemon_client::proxy::derive_proposal_budget_secs` so the two
/// layers agree on what "in budget" means. Independent same-level actions run
/// concurrently, so a level's true cost is the `max` of its actions rather than
/// the sum — but the DAG is not reconstructed here. The conservative
/// `Σ(budget × attempts)` upper bound is taken instead: over-waiting only delays
/// reaping a genuinely wedged handler, while under-waiting kills real work.
///
/// One term neither this nor the client's copy counts: the executor's
/// inter-attempt backoff sleeps. At the built-in defaults
/// (`RETRY_BASE_DELAY_MS` 100, factor 2) a 4-attempt action sleeps 0.7s total,
/// far inside the grace. Only a harness-config `retry_backoff_ms` override
/// (`None` by default, so unreachable on any default path) could push the sum
/// past it — if that knob ever gets a live call site, fold the backoff series
/// into this derivation rather than widening the grace.
fn derive_proposal_budget_secs(params: &Value) -> u64 {
    let Some(actions) = params
        .get("proposal")
        .and_then(|p| p.get("actions"))
        .and_then(|a| a.as_array())
    else {
        return 0;
    };
    if actions.is_empty() {
        return 0;
    }

    // Saturating throughout so a pathological `timeout_ms` can't wrap the
    // accumulator into a *shorter* deadline than the flat default.
    let mut total_ms: u64 = 0;
    for action in actions {
        let budget_ms = action
            .get("timeout_ms")
            .and_then(|v| v.as_u64())
            .unwrap_or(crate::session::DEFAULT_TOOL_TIMEOUT_MS);
        total_ms =
            total_ms.saturating_add(budget_ms.saturating_mul(proposal_action_attempts(action)));
    }

    // ms → secs rounding UP, so a sub-second remainder never truncates the
    // derived deadline below what the executor is allowed to spend.
    total_ms.div_ceil(1000)
}

/// Worst-case attempt count the executor will run for one action.
///
/// Mirrors `car_engine::executor::execute_with_retry` (and the client's
/// `car_daemon_client::proxy::action_attempts`): a `failure_behavior: "retry"`
/// action runs `max_retries + 1` attempts — the initial try plus up to
/// `max_retries` retries, so 4 at the default, NOT 3 — and every other behavior
/// (`abort`, `skip`, or unset → `abort`) runs exactly once. Always `>= 1`.
fn proposal_action_attempts(action: &Value) -> u64 {
    let is_retry = action
        .get("failure_behavior")
        .and_then(|v| v.as_str())
        .map(|s| s.eq_ignore_ascii_case("retry"))
        .unwrap_or(false);

    if is_retry {
        action
            .get("max_retries")
            .and_then(|v| v.as_u64())
            .unwrap_or(DEFAULT_PROPOSAL_MAX_RETRIES)
            .saturating_add(1)
    } else {
        1
    }
}

#[derive(Debug)]
enum HandlerFailure {
    Dispatch(String),
    MethodNotFound(String),
    InvalidParams(String),
    Deadline(String),
    /// Something in front of the model declined the request's content. Carries
    /// its own JSON-RPC code so a consumer can tell a policy ruling from a
    /// crash — see [`car_proto::CONTENT_REFUSED_ERROR_CODE`].
    ContentRefused(String),
    ProtocolCapability(String),
    CatalogPrecondition(String),
    RunOwnershipConflict(String),
    RunTraceCorruption(String),
}

impl HandlerFailure {
    /// Classify a handler's dispatch error string.
    ///
    /// This is the READER half of a writer/reader pair — the writer is
    /// [`inference_dispatch_error`], which tags a typed
    /// `InferenceError::ContentRefused` with
    /// [`car_proto::CONTENT_REFUSED_MESSAGE_PREFIX`] on the way out of the
    /// handler. The two must agree on that prefix, the same way
    /// `car_inference::stream::error_tags` pairs its writer and reader. The
    /// decode happens in exactly ONE place (here) so there is a single line to
    /// keep in sync, and the typed classification is still done where the typed
    /// error actually exists rather than by sniffing text.
    fn from_dispatch(message: String) -> Self {
        if message.starts_with("unknown method:") {
            Self::MethodNotFound(message)
        } else if message.starts_with("invalid params:") {
            Self::InvalidParams(message)
        } else if message.starts_with(car_proto::CONTENT_REFUSED_MESSAGE_PREFIX) {
            Self::ContentRefused(message)
        } else if message.starts_with(car_proto::PROTOCOL_CAPABILITY_MISMATCH_MESSAGE_PREFIX) {
            Self::ProtocolCapability(message)
        } else if message.starts_with(car_proto::CATALOG_PRECONDITION_MISMATCH_MESSAGE_PREFIX) {
            Self::CatalogPrecondition(message)
        } else if message.starts_with(car_proto::RUN_OWNERSHIP_CONFLICT_MESSAGE_PREFIX) {
            Self::RunOwnershipConflict(message)
        } else if message.starts_with(car_proto::RUN_TRACE_CORRUPTION_MESSAGE_PREFIX) {
            Self::RunTraceCorruption(message)
        } else {
            Self::Dispatch(message)
        }
    }

    fn json_rpc_code(&self) -> i32 {
        match self {
            Self::Dispatch(_) => -32603,
            Self::MethodNotFound(_) => -32601,
            Self::InvalidParams(_) => -32602,
            Self::Deadline(_) => HANDLER_DEADLINE_ERROR_CODE,
            Self::ContentRefused(_) => car_proto::CONTENT_REFUSED_ERROR_CODE,
            Self::ProtocolCapability(_) => car_proto::PROTOCOL_CAPABILITY_MISMATCH_ERROR_CODE,
            Self::CatalogPrecondition(_) => car_proto::CATALOG_PRECONDITION_MISMATCH_ERROR_CODE,
            Self::RunOwnershipConflict(_) => car_proto::RUN_OWNERSHIP_CONFLICT_ERROR_CODE,
            Self::RunTraceCorruption(_) => car_proto::RUN_TRACE_CORRUPTION_ERROR_CODE,
        }
    }

    fn message(&self) -> &str {
        match self {
            Self::Dispatch(message)
            | Self::MethodNotFound(message)
            | Self::InvalidParams(message)
            | Self::Deadline(message)
            | Self::ContentRefused(message)
            | Self::ProtocolCapability(message)
            | Self::CatalogPrecondition(message)
            | Self::RunOwnershipConflict(message)
            | Self::RunTraceCorruption(message) => message,
        }
    }
}

fn json_rpc_response_for_handler_result(
    id: Value,
    result: Result<Value, HandlerFailure>,
) -> JsonRpcResponse {
    match result {
        Ok(value) => JsonRpcResponse::success(id, value),
        Err(error) => JsonRpcResponse::error(id, error.json_rpc_code(), error.message()),
    }
}

async fn dispatch_with_server_deadline<F>(
    method: &str,
    params: &Value,
    dispatch: F,
) -> Result<Value, HandlerFailure>
where
    F: std::future::Future<Output = Result<Value, String>>,
{
    match server_deadline_for(method, params) {
        Some(deadline) => match tokio::time::timeout(deadline, dispatch).await {
            Ok(result) => result.map_err(HandlerFailure::from_dispatch),
            Err(_) => Err(HandlerFailure::Deadline(format!(
                "handler '{}' exceeded the server-side deadline of {}s and was abandoned",
                method,
                deadline.as_secs()
            ))),
        },
        None => dispatch.await.map_err(HandlerFailure::from_dispatch),
    }
}

async fn await_daemon_owned_auth_result(
    method: &str,
    result_rx: tokio::sync::oneshot::Receiver<Result<Value, HandlerFailure>>,
) -> Result<Value, HandlerFailure> {
    let receive = async {
        match result_rx.await {
            Ok(result) => result,
            Err(_) => Err(HandlerFailure::Dispatch(format!(
                "daemon-owned auth operation `{method}` stopped before publishing a result"
            ))),
        }
    };
    if !matches!(
        method,
        "auth.start" | "auth.complete" | "auth.completion_status"
    ) {
        return receive.await;
    }

    tokio::time::timeout(AUTH_STATE_RESPONSE_DEADLINE, receive)
        .await
        .unwrap_or_else(|_| match method {
            "auth.complete" => Err(HandlerFailure::Deadline(format!(
                "auth.complete durable claim outcome is ambiguous after {}s; do not replay the \
                 authorization code and reconcile the exact attempt through auth.completion_status",
                AUTH_STATE_RESPONSE_DEADLINE.as_secs()
            ))),
            "auth.start" => Err(HandlerFailure::Deadline(format!(
                "auth.start reservation outcome is ambiguous after {}s; the daemon-owned \
                 reservation continues, so do not overlap another auth.start",
                AUTH_STATE_RESPONSE_DEADLINE.as_secs()
            ))),
            _ => Err(HandlerFailure::Deadline(format!(
                "handler 'auth.completion_status' exceeded its {}s response deadline; \
                 daemon-owned reconciliation continues and a later proof read is safe",
                AUTH_STATE_RESPONSE_DEADLINE.as_secs()
            ))),
        })
}

fn classified_auth_failure(method: &str, error: car_auth::AuthOperationError) -> HandlerFailure {
    match error {
        car_auth::AuthOperationError::CoordinationDeadline(detail) => {
            let message = match method {
                "auth.complete" => format!("{AUTH_COMPLETE_PRE_REDEMPTION_RETRY_PREFIX}: {detail}"),
                "auth.start" => format!("{AUTH_START_RETRY_PREFIX}: {detail}"),
                "auth.completion_status" => format!("{AUTH_STATUS_RETRY_PREFIX}: {detail}"),
                _ => format!(
                    "{method} coordination deadline before state work; retry the request safely: \
                     {detail}"
                ),
            };
            HandlerFailure::Deadline(message)
        }
        car_auth::AuthOperationError::Terminal(message) => HandlerFailure::from_dispatch(message),
    }
}

#[cfg(test)]
mod assistant_identity_tests {
    use super::assistant_identity_wire;
    use car_identity::AssistantIdentity;

    #[test]
    fn the_wire_shape_carries_everything_a_host_needs_to_address_the_assistant() {
        // Hosts match wake phrases LOCALLY (their matcher has to work before
        // the daemon answers), so the daemon has to hand them the derived alias
        // list rather than only the name. Sending just the name is how Swift,
        // Kotlin, and Rust drifted into three different lists in the first
        // place.
        let identity = AssistantIdentity::new("Jarvis")
            .expect("valid name")
            .with_spellings(vec!["jervis".into()])
            .expect("valid spellings");
        let wire = assistant_identity_wire(&identity);

        assert_eq!(wire["name"], "Jarvis");
        assert_eq!(wire["spellings"][0], "jervis");
        assert_eq!(wire["brand"], car_identity::BRAND_NAME);

        let aliases: Vec<String> =
            serde_json::from_value(wire["aliases"].clone()).expect("aliases");
        for expected in ["jarvis", "hey jarvis", "jervis", "hey jervis"] {
            assert!(
                aliases.contains(&expected.to_string()),
                "{expected} missing from {aliases:?}"
            );
        }
    }

    #[test]
    fn the_brand_travels_alongside_the_name_never_instead_of_it() {
        // Store copy is contractually "Parslee Core" (docs/mobile-app-store-release.md).
        // A host that renders brand copy needs both values, not a merged one.
        let wire = assistant_identity_wire(&AssistantIdentity::new("Friday").unwrap());
        assert_eq!(wire["name"], "Friday");
        assert_eq!(wire["brand"], "Parslee Core");
    }
}

#[cfg(test)]
mod deadline_policy_tests {
    use super::{
        auth_completion_network_with_deadline, auth_completion_value,
        await_daemon_owned_auth_result, classified_auth_failure, dispatch_with_server_deadline,
        handler_default_deadline_secs, inference_dispatch_error, is_daemon_owned_auth_method,
        json_rpc_response_for_handler_result, select_auth_start_api_base, server_deadline_for,
        stream_dispatch_error, HandlerFailure, AUTH_COMPLETE_PRE_REDEMPTION_RETRY_PREFIX,
        AUTH_COMPLETION_HOST_RECONCILIATION_HORIZON, AUTH_START_RETRY_PREFIX,
        AUTH_STATE_RESPONSE_DEADLINE, AUTH_STATUS_RETRY_PREFIX, DAEMON_OWNED_AUTH_METHODS,
        DEADLINE_FAST_SECS, DEFAULT_PROPOSAL_MAX_RETRIES, HANDLER_DEADLINE_ERROR_CODE,
        PROPOSAL_DEADLINE_GRACE_SECS,
    };
    use serde_json::{json, Value};
    use std::time::Duration;

    #[test]
    fn auth_start_base_precedence_is_passive_and_does_not_read_secrets() {
        const SENTINEL: &str = "CAR_AUTH_START_BASE_CONTRACT_CHILD";
        if std::env::var_os(SENTINEL).is_none() {
            let status = std::process::Command::new(std::env::current_exe().unwrap())
                .arg("--exact")
                .arg(
                    "handler::deadline_policy_tests::auth_start_base_precedence_is_passive_and_does_not_read_secrets",
                )
                .arg("--nocapture")
                .env(SENTINEL, "1")
                .status()
                .expect("spawn isolated auth.start base contract");
            assert!(status.success(), "isolated auth.start contract failed");
            return;
        }

        let before = car_secrets::secret_store_activity();

        assert_eq!(
            select_auth_start_api_base(
                &json!({ "api_base": " https://explicit.example.test/ " }),
                Some("https://environment.example.test/"),
            ),
            "https://explicit.example.test"
        );
        assert_eq!(
            select_auth_start_api_base(
                &json!({ "api_base": "   " }),
                Some(" https://environment.example.test/ "),
            ),
            "https://environment.example.test"
        );
        assert_eq!(
            select_auth_start_api_base(&json!({}), Some("  ")),
            car_auth::DEFAULT_API_BASE
        );
        assert_eq!(car_secrets::secret_store_activity(), before);
    }

    /// One `tool_call` action in the wire shape `proposal.submit` receives.
    fn action(timeout_ms: u64, failure_behavior: &str) -> Value {
        json!({
            "id": "a1",
            "type": "tool_call",
            "tool": "shell",
            "parameters": {},
            "failure_behavior": failure_behavior,
            "timeout_ms": timeout_ms,
        })
    }

    fn submit_params(actions: Vec<Value>) -> Value {
        json!({ "proposal": { "id": "p1", "goal": "g", "actions": actions } })
    }

    /// A single retried action with a 10-minute budget runs four attempts
    /// (`max_retries` 3 + the initial try) — 2400s of daemon-side work that the
    /// executor and, since #265, the client both permit. Keying the handler
    /// deadline on the method name alone abandoned it at the flat 1800s
    /// default with `-32004` while the work was still legitimately in budget.
    #[test]
    fn proposal_submit_deadline_covers_a_retried_actions_full_budget() {
        let params = submit_params(vec![action(600_000, "retry")]);
        let deadline =
            server_deadline_for("proposal.submit", &params).expect("proposal.submit is bounded");

        // 4 attempts × 600s.
        assert!(
            deadline > Duration::from_secs(2400),
            "must outlast the executor's own 2400s worst case, got {deadline:?}"
        );
        assert!(
            deadline > Duration::from_secs(1800),
            "must RAISE the flat 1800s generous default, got {deadline:?}"
        );
        assert_eq!(
            deadline,
            Duration::from_secs(2400 + PROPOSAL_DEADLINE_GRACE_SECS)
                .max(Duration::from_secs(handler_default_deadline_secs())),
            "derived deadline is the action budget plus the server transport grace"
        );
    }

    /// Chained actions add up: the derivation is the conservative
    /// `Σ(budget × attempts)` upper bound, so a multi-step proposal whose sum
    /// passes the default raises the deadline past that sum too.
    #[test]
    fn proposal_submit_deadline_covers_chained_action_budgets() {
        let params = submit_params(vec![
            action(900_000, "abort"),
            action(900_000, "abort"),
            action(300_000, "skip"),
        ]);
        let sum = Duration::from_secs(900 + 900 + 300);
        let deadline =
            server_deadline_for("proposal.submit", &params).expect("proposal.submit is bounded");

        assert!(
            deadline > sum,
            "chained budgets summing to {sum:?} must not be reaped, got {deadline:?}"
        );
        assert!(
            deadline > Duration::from_secs(1800),
            "a 2100s chain must RAISE the flat 1800s default, got {deadline:?}"
        );
        assert_eq!(
            deadline,
            (sum + Duration::from_secs(PROPOSAL_DEADLINE_GRACE_SECS))
                .max(Duration::from_secs(handler_default_deadline_secs()))
        );
    }

    /// The derivation only ever RAISES: a short proposal keeps exactly the
    /// generous default it had before, so no method gets a tighter deadline
    /// than it had.
    #[test]
    fn a_short_proposal_keeps_exactly_the_generous_default() {
        let params = submit_params(vec![action(5_000, "abort")]);
        assert_eq!(
            server_deadline_for("proposal.submit", &params),
            Some(Duration::from_secs(handler_default_deadline_secs())),
            "5s of budget must not lower the deadline below the generous default"
        );
    }

    /// An action that declares no `timeout_ms` is budgeted at the daemon's own
    /// `tool_callback_timeout(None)` bound, so the derivation tracks what the
    /// executor will actually wait.
    #[test]
    fn actions_without_an_explicit_budget_use_the_daemon_tool_default() {
        let params = json!({
            "proposal": {
                "actions": [
                    { "id": "a1", "type": "tool_call", "failure_behavior": "retry" },
                    { "id": "a2", "type": "tool_call", "failure_behavior": "retry" },
                ]
            }
        });
        // 2 actions × 4 attempts × 300s = 2400s.
        let expected = 2 * 4 * (crate::session::DEFAULT_TOOL_TIMEOUT_MS / 1000);
        assert_eq!(
            server_deadline_for("proposal.submit", &params),
            Some(
                Duration::from_secs(expected + PROPOSAL_DEADLINE_GRACE_SECS)
                    .max(Duration::from_secs(handler_default_deadline_secs()))
            )
        );
    }

    /// The reap ordering is executor → daemon handler → client, innermost
    /// first. This server grace must therefore stay strictly below the client's
    /// `car_daemon_client::proxy::PROPOSAL_TRANSPORT_GRACE_SECS` (30s) — named
    /// here rather than imported, because car-server-core must not take a
    /// dependency on the daemon client to assert an ordering invariant.
    #[test]
    fn server_grace_is_strictly_inside_the_client_transport_grace() {
        assert!(
            PROPOSAL_DEADLINE_GRACE_SECS < 30,
            "server grace must fire before the client's 30s PROPOSAL_TRANSPORT_GRACE_SECS"
        );
    }

    /// Pins the locally-mirrored retry default to `car_ir`'s own serde default,
    /// which is private — deserializing a minimal action is how we read it.
    #[test]
    fn derived_retry_default_matches_car_ir() {
        let action: car_ir::Action = serde_json::from_value(json!({
            "id": "a1",
            "type": "tool_call",
            "tool": "shell",
        }))
        .expect("minimal action should deserialize");
        assert_eq!(u64::from(action.max_retries), DEFAULT_PROPOSAL_MAX_RETRIES);
    }

    #[test]
    fn classifies_methods_into_expected_buckets() {
        let default = Duration::from_secs(handler_default_deadline_secs());
        let fast = Duration::from_secs(DEADLINE_FAST_SECS);

        // Unbounded → exempt (no deadline).
        for m in [
            "infer_stream",
            "runs.subscribe",
            "scheduler.run_loop",
            "voice.dispatch_turn",
            "voice.tts_stream.start",
        ] {
            assert_eq!(
                server_deadline_for(m, &Value::Null),
                None,
                "{m} should be exempt"
            );
        }
        for method in DAEMON_OWNED_AUTH_METHODS {
            assert!(
                is_daemon_owned_auth_method(method),
                "{method} must bypass connection-owned dispatch"
            );
        }
        // Bounded, cancellation-safe reads → fast.
        for m in [
            "memory.query",
            "memory.evaluate",
            "memory.intervene",
            "agents.list",
            "meeting.get",
            "runs.list",
            "agents.health",
            "server.handshake",
        ] {
            assert_eq!(
                server_deadline_for(m, &Value::Null),
                Some(fast),
                "{m} should be fast"
            );
        }
        // Mutating / heavy / agentic → generous default (NOT the tight bucket).
        // `proposal.submit` is in this list with `Value::Null` params: a
        // proposal whose budget is not parseable still takes the generous
        // default, exactly as before the budget derivation landed.
        for m in [
            "memory.persist",
            "memory.add_fact",
            "memory.update_status",
            "memory.maintain",
            "memory.save_knowledge",
            "memory.save_procedural",
            "memory.delete",
            "memory.consolidate",
            "proposal.submit",
            "workflow.run",
            "multi.swarm",
        ] {
            assert_eq!(
                server_deadline_for(m, &Value::Null),
                Some(default),
                "{m} should take the generous default"
            );
        }
    }

    #[tokio::test(start_paused = true)]
    async fn bounded_handler_deadline_has_a_distinct_json_rpc_code() {
        let task = tokio::spawn(async {
            dispatch_with_server_deadline(
                "memory.query",
                &Value::Null,
                std::future::pending::<Result<Value, String>>(),
            )
            .await
        });

        tokio::time::advance(Duration::from_secs(DEADLINE_FAST_SECS)).await;
        let failure = task
            .await
            .expect("deadline task should join")
            .expect_err("pending handler should exceed its deadline");

        assert!(matches!(failure, HandlerFailure::Deadline(_)));
        assert_eq!(failure.json_rpc_code(), HANDLER_DEADLINE_ERROR_CODE);
    }

    #[test]
    fn auth_state_response_bound_exceeds_every_serial_storage_component() {
        let component_total = car_auth::AUTH_COORDINATOR_QUEUE_TIMEOUT
            + car_auth::AUTH_PROCESS_LOCK_TIMEOUT
            + car_auth::AUTH_STATE_OPERATION_BUDGET
            + car_auth::AUTH_STATE_OPERATION_BUDGET;
        assert!(
            AUTH_STATE_RESPONSE_DEADLINE > component_total,
            "auth state response bound must include scheduling margin"
        );
    }

    #[test]
    fn one_safe_preclaim_retry_and_proof_fit_the_host_reconciliation_horizon() {
        // One explicit safe retry may consume the first coordinator queue
        // timeout before a second request reaches the claim. The worker lease
        // clock starts after the authoritative read and includes claim
        // publication plus every redemption/commit phase.
        let first_safe_retry_budget =
            car_auth::AUTH_COORDINATOR_QUEUE_TIMEOUT + car_auth::AUTH_PROCESS_LOCK_TIMEOUT;
        let pre_lease_claim_budget = car_auth::AUTH_COORDINATOR_QUEUE_TIMEOUT
            + car_auth::AUTH_PROCESS_LOCK_TIMEOUT
            + car_auth::AUTH_STATE_OPERATION_BUDGET;
        let hydration_reserve = Duration::from_secs(30);
        let total_budget = first_safe_retry_budget
            + pre_lease_claim_budget
            + car_auth::LOGIN_ATTEMPT_WORKER_TTL
            + AUTH_STATE_RESPONSE_DEADLINE
            + hydration_reserve;

        assert!(
            total_budget < AUTH_COMPLETION_HOST_RECONCILIATION_HORIZON,
            "one safe preclaim retry must still expire, prove, and hydrate before the host stops"
        );
    }

    #[tokio::test(start_paused = true)]
    async fn proof_response_timeout_reports_that_daemon_reconciliation_continues() {
        let (_result_tx, result_rx) = tokio::sync::oneshot::channel();
        let task = tokio::spawn(await_daemon_owned_auth_result(
            "auth.completion_status",
            result_rx,
        ));

        tokio::time::advance(AUTH_STATE_RESPONSE_DEADLINE).await;
        let failure = task
            .await
            .expect("proof response task should join")
            .expect_err("an unpublished proof must hit its explicit response bound");

        assert!(matches!(failure, HandlerFailure::Deadline(_)));
        assert_eq!(failure.json_rpc_code(), HANDLER_DEADLINE_ERROR_CODE);
        assert!(failure.message().contains("reconciliation continues"));
    }

    #[tokio::test(start_paused = true)]
    async fn auth_start_and_complete_have_explicit_state_response_bounds() {
        for method in ["auth.start", "auth.complete"] {
            let (_result_tx, result_rx) = tokio::sync::oneshot::channel();
            let task = tokio::spawn(await_daemon_owned_auth_result(method, result_rx));

            tokio::time::advance(AUTH_STATE_RESPONSE_DEADLINE).await;
            let failure = task
                .await
                .expect("auth response task should join")
                .expect_err("unpublished auth state response must hit its explicit bound");

            assert_eq!(failure.json_rpc_code(), HANDLER_DEADLINE_ERROR_CODE);
            assert!(failure.message().contains("95s"), "{method}: {failure:?}");
        }
    }

    #[test]
    fn coordination_deadlines_are_retryable_but_terminal_state_errors_are_not() {
        for (method, prefix) in [
            ("auth.start", AUTH_START_RETRY_PREFIX),
            ("auth.complete", AUTH_COMPLETE_PRE_REDEMPTION_RETRY_PREFIX),
            ("auth.completion_status", AUTH_STATUS_RETRY_PREFIX),
        ] {
            let failure = classified_auth_failure(
                method,
                car_auth::AuthOperationError::CoordinationDeadline("contended".into()),
            );
            assert_eq!(failure.json_rpc_code(), HANDLER_DEADLINE_ERROR_CODE);
            assert!(failure.message().starts_with(prefix), "{failure:?}");
        }

        let failure = classified_auth_failure(
            "auth.completion_status",
            car_auth::AuthOperationError::Terminal("corrupt state".into()),
        );
        assert_eq!(failure.json_rpc_code(), -32603);
        assert_eq!(failure.message(), "corrupt state");
    }

    #[tokio::test(start_paused = true)]
    async fn auth_completion_network_phase_has_an_injectable_total_deadline() {
        let task = tokio::spawn(auth_completion_network_with_deadline(
            Duration::from_secs(1),
            std::future::pending::<Result<(), String>>(),
        ));

        tokio::time::advance(Duration::from_secs(1)).await;
        let error = task
            .await
            .expect("network deadline task should join")
            .expect_err("stalled auth network work must time out");

        assert_eq!(
            error,
            "Parslee login network phase timed out after 1s; no credentials were saved"
        );
    }

    #[test]
    fn protocol_routing_failures_use_standard_json_rpc_codes() {
        let unknown =
            HandlerFailure::from_dispatch("unknown method: future.namespace.call".to_string());
        assert!(matches!(unknown, HandlerFailure::MethodNotFound(_)));
        assert_eq!(unknown.json_rpc_code(), -32601);

        let invalid = HandlerFailure::from_dispatch("invalid params: key is required".to_string());
        assert!(matches!(invalid, HandlerFailure::InvalidParams(_)));
        assert_eq!(invalid.json_rpc_code(), -32602);

        let wire =
            serde_json::to_value(json_rpc_response_for_handler_result(json!(7), Err(invalid)))
                .expect("serialize response");
        assert_eq!(wire["error"]["code"], -32602);
        assert_eq!(wire["error"]["message"], "invalid params: key is required");
    }

    #[tokio::test]
    async fn ordinary_handler_failure_remains_internal_error() {
        let failure = dispatch_with_server_deadline(
            "auth.complete",
            &Value::Null,
            std::future::ready(Err("token exchange failed".to_string())),
        )
        .await
        .expect_err("handler failure should propagate");

        assert!(matches!(failure, HandlerFailure::Dispatch(_)));
        assert_eq!(failure.json_rpc_code(), -32603);
    }

    #[test]
    fn a_gateway_content_refusal_survives_the_trip_to_its_own_error_code() {
        let refusal = car_inference::InferenceError::ContentRefused {
            provider: "parslee".to_string(),
            kind: Some("invalid_request_error".to_string()),
            code: Some("content_policy_violation".to_string()),
            message: "The response was filtered due to the prompt triggering the content \
                      management policy"
                .to_string(),
        };

        // Writer (handler) → reader (dispatcher). This round trip is what stops
        // the two halves of the prefix contract from drifting apart.
        let failure = HandlerFailure::from_dispatch(inference_dispatch_error(&refusal));

        assert!(matches!(failure, HandlerFailure::ContentRefused(_)));
        assert_eq!(
            failure.json_rpc_code(),
            car_proto::CONTENT_REFUSED_ERROR_CODE
        );
        // The gateway's own classification must still be readable by an
        // operator — tagging adds a prefix, it does not replace the detail.
        assert!(
            failure.message().contains("code=content_policy_violation"),
            "{failure:?}"
        );
        assert!(
            failure
                .message()
                .starts_with(car_proto::CONTENT_REFUSED_MESSAGE_PREFIX),
            "{failure:?}"
        );
    }

    #[test]
    fn ordinary_inference_failures_are_not_classified_as_content_refusals() {
        // Over-classification is the dangerous direction: a crash mislabelled as
        // a policy refusal tells a benchmark to score it and a retry loop to
        // give up on work that would have succeeded. The first string is the
        // literal #796 symptom the fix was reported against.
        let generic: Vec<car_inference::InferenceError> = vec![
            car_inference::InferenceError::InferenceFailed("managed inference failed".to_string()),
            car_inference::InferenceError::InferenceFailed(
                "content refused by the operator's local policy".to_string(),
            ),
            car_inference::InferenceError::ModelNotFound("gpt-5.6-sol".to_string()),
            car_inference::InferenceError::TokenizationError("bad utf-8 boundary".to_string()),
        ];

        // The exact string #796 was reported against must still be an internal
        // error, not a refusal.
        assert_eq!(
            generic[0].to_string(),
            "inference failed: managed inference failed"
        );

        for error in &generic {
            let failure = HandlerFailure::from_dispatch(inference_dispatch_error(error));
            assert!(
                matches!(failure, HandlerFailure::Dispatch(_)),
                "must stay a generic dispatch failure: {failure:?}"
            );
            assert_eq!(failure.json_rpc_code(), -32603, "{failure:?}");
        }
    }

    #[test]
    fn a_refusal_that_lands_mid_stream_reaches_the_same_error_code() {
        // What `infer_stream` actually has at this point: not a typed error, but
        // the flattened text `car_inference::stream` wrote, tags and all.
        let flattened = "The response was filtered due to the prompt triggering the content \
                         management policy (type=invalid_request_error, \
                         code=content_policy_violation)";

        let failure = HandlerFailure::from_dispatch(stream_dispatch_error(flattened.to_string()));

        assert!(matches!(failure, HandlerFailure::ContentRefused(_)));
        assert_eq!(
            failure.json_rpc_code(),
            car_proto::CONTENT_REFUSED_ERROR_CODE
        );
        // Tagging prefixes; it must not eat the gateway's own text.
        assert!(failure.message().contains(flattened), "{failure:?}");
    }

    #[test]
    fn an_untagged_stream_failure_is_not_promoted_to_a_refusal() {
        // The safe direction: no classification tags means no verdict. A crash
        // mislabelled as a policy ruling tells a harness to score it and a retry
        // loop to give up on work that would have succeeded.
        for plain in [
            "managed inference failed",
            "upstream connection reset",
            // Prose that merely TALKS about content policy is not a tag.
            "the model discussed content policy at length",
            // A tag block that carries no refusal classification.
            "boom (type=server_error, code=internal)",
        ] {
            let failure = HandlerFailure::from_dispatch(stream_dispatch_error(plain.to_string()));
            assert!(
                matches!(failure, HandlerFailure::Dispatch(_)),
                "must stay generic: {failure:?}"
            );
            assert_eq!(failure.json_rpc_code(), -32603, "{failure:?}");
        }
    }

    #[test]
    fn a_content_refusal_is_distinguishable_from_a_handler_deadline() {
        let refusal = HandlerFailure::from_dispatch(inference_dispatch_error(
            &car_inference::InferenceError::ContentRefused {
                provider: "parslee".to_string(),
                kind: None,
                code: None,
                message: "declined".to_string(),
            },
        ));
        let deadline = HandlerFailure::Deadline("handler deadline".to_string());

        assert_eq!(
            refusal.json_rpc_code(),
            car_proto::CONTENT_REFUSED_ERROR_CODE
        );
        assert_eq!(deadline.json_rpc_code(), HANDLER_DEADLINE_ERROR_CODE);
        assert_ne!(refusal.json_rpc_code(), deadline.json_rpc_code());
        assert_ne!(refusal.json_rpc_code(), -32603);
    }

    #[test]
    fn deadline_failure_serializes_as_the_actual_json_rpc_envelope() {
        let response = json_rpc_response_for_handler_result(
            json!(42),
            Err(HandlerFailure::Deadline("handler deadline".to_string())),
        );
        let wire = serde_json::to_value(response).expect("serialize response");

        assert_eq!(
            wire,
            json!({
                "jsonrpc": "2.0",
                "error": {
                    "code": HANDLER_DEADLINE_ERROR_CODE,
                    "message": "handler deadline",
                },
                "id": 42,
            })
        );
    }

    #[test]
    fn attempt_completion_wire_value_carries_the_generation_and_session() {
        let record = car_auth::AuthCompletionRecord {
            attempt_id: "attempt-7".to_string(),
            generation: 19,
            account_id: Some("account-b".to_string()),
            session: Some(r#"{"Account":{"Id":"account-b"}}"#.to_string()),
        };

        assert_eq!(
            auth_completion_value(&record),
            json!({
                "state": "complete",
                "attempt_id": "attempt-7",
                "generation": 19,
                "account_id": "account-b",
                "session": {"Account": {"Id": "account-b"}},
            })
        );
    }
}

/// Transport-neutral entry point: drives the JSON-RPC dispatch loop
/// against an already-handshake-completed split WebSocket. Generic
/// over the read half (any `Stream<Item = Result<Message, WsError>>`)
/// and the write half (a [`WsSink`](crate::session::WsSink) — type-erased so this function
/// doesn't templatize every downstream consumer of `WsChannel`).
///
/// `peer` is a free-form string ("127.0.0.1:1234" for TCP,
/// "uds:/path/sock" for UDS, "axum:..." for embedders) — used only
/// for tracing fields, never for dispatch logic.
#[instrument(
    name = "ws.dispatch",
    skip_all,
    fields(client_id = tracing::field::Empty, peer = %peer),
)]
pub async fn run_dispatch<R>(
    mut read: R,
    write: crate::session::WsSink,
    peer: String,
    state: Arc<ServerState>,
) -> Result<(), Box<dyn std::error::Error>>
where
    R: futures::Stream<Item = Result<Message, tokio_tungstenite::tungstenite::Error>>
        + Unpin
        + Send,
{
    let client_id = uuid::Uuid::new_v4().simple().to_string()[..12].to_string();
    tracing::Span::current().record("client_id", client_id.as_str());

    info!("New connection from {}", peer);

    let channel = Arc::new(WsChannel {
        write: Mutex::new(write),
        pending: Mutex::new(HashMap::new()),
        active_actions: Mutex::new(HashMap::new()),
        next_id: AtomicU64::new(1),
    });

    // Refusing the connection is the intended outcome of a malformed
    // `~/.car/policies/*.toml` (see `session::apply_project_policies`): a
    // client that connects anyway would be running under a rule set the
    // operator wrote and the daemon silently did not apply.
    let session = match state.create_session(&client_id, channel.clone()).await {
        Ok(session) => session,
        Err(e) => {
            error!("refusing connection from {}: {}", peer, e);
            return Err(e.into());
        }
    };

    // car#209: per-request handlers are spawned detached (below) and
    // each clones `Arc<ClientSession>` → `Arc<WsChannel>`. A bare
    // `tokio::spawn` outlives the connection, so a slow/hung handler
    // pins the split sink and the inbound socket lingers in CLOSED
    // until the daemon hits EMFILE. Own them in a per-connection
    // `JoinSet` so every in-flight handler is aborted the instant the
    // WS drops (`abort_all` in the cleanup block; `JoinSet`'s Drop
    // also aborts on any early return), releasing the FD immediately.
    let mut conn_tasks: tokio::task::JoinSet<()> = tokio::task::JoinSet::new();

    // Every authenticated client receives the same non-secret OpenRouter
    // authority stream. This is deliberately connection-wide rather than
    // flow-scoped: a mutation on client B must promptly supersede a delayed
    // response on client A. Hosts compare `authority_generation` before flow
    // correlation, so ordering remains deterministic across WebSockets.
    let mut openrouter_updates = crate::openrouter_auth::subscribe_authority_updates();
    let openrouter_session = session.clone();
    let openrouter_auth_required = state.auth_token.get().is_some();
    conn_tasks.spawn(async move {
        loop {
            if openrouter_updates.changed().await.is_err() {
                break;
            }
            if openrouter_auth_required
                && !openrouter_session
                    .authenticated
                    .load(std::sync::atomic::Ordering::Acquire)
            {
                continue;
            }
            let Some(status) = openrouter_updates.borrow_and_update().clone() else {
                continue;
            };
            let notification = serde_json::json!({
                "jsonrpc": "2.0",
                "method": "openrouter.auth.event",
                "params": status,
            });
            let Ok(text) = serde_json::to_string(&notification) else {
                continue;
            };
            if openrouter_session
                .channel
                .write
                .lock()
                .await
                .send(Message::Text(text.into()))
                .await
                .is_err()
            {
                break;
            }
        }
    });

    // Parslee credential reads are process-owned and may be initiated by a
    // different host connection or by request-time routing. Fan their
    // secret-free generation/status stream only to a connection that has
    // completed both transport authentication and host-management
    // authorization. A managed non-host must learn nothing from this channel.
    let credential_session = session.clone();
    let credential_transport_auth_required = state.auth_token.get().is_some();
    let credential_host_role_required = state.host_token.get().is_some();
    let (credential_activation_tx, mut credential_activation_rx) =
        tokio::sync::watch::channel(false);
    let (credential_ready_tx, credential_ready_rx) = tokio::sync::watch::channel(false);
    let (credential_lag_tx, mut credential_lag_rx) = tokio::sync::oneshot::channel();
    conn_tasks.spawn(async move {
        pause_credential_fanout_for_test().await;
        let mut credential_lag_tx = Some(credential_lag_tx);

        // Do not register an ordered event subscriber until this connection is
        // authorized to receive the stream. This makes pre-auth/non-host
        // traffic incapable of filling a queue whose later close could be
        // mistaken for an eligible-host overflow. Authentication and protocol
        // negotiation only move forward during a connection, and the task is
        // aborted by connection cleanup if eligibility is never reached.
        while !credential_event_is_eligible(
            &credential_session,
            credential_transport_auth_required,
            credential_host_role_required,
        ) {
            if credential_activation_rx.changed().await.is_err() {
                return;
            }
        }

        // Atomically capture the retained process snapshot and register the
        // lossless stream. The credential layer linearizes every publication
        // as either snapshot state from before registration or queued state
        // from after it. Generation/state deduplication below still rejects a
        // duplicate or terminal-to-pending regression defensively.
        let car_auth::CredentialReadEventHandoff {
            snapshot,
            events: mut credential_events,
        } = car_auth::subscribe_credential_read_event_handoff();
        pause_credential_handoff_for_test().await;
        let mut reconciled = snapshot.into_iter();
        let mut last_status = None;
        let _ = credential_ready_tx.send(true);
        loop {
            let status = match reconciled.next() {
                Some(status) => status,
                None => {
                    let closed = credential_events.closed();
                    tokio::select! {
                        biased;
                        reason = closed => {
                            if let Some(sender) = credential_lag_tx.take() {
                                let _ = sender.send(reason);
                            }
                            break;
                        }
                        event = credential_events.recv() => match event {
                            Ok(status) => status,
                            Err(reason) => {
                                if let Some(sender) = credential_lag_tx.take() {
                                    let _ = sender.send(reason);
                                }
                                break;
                            }
                        }
                    }
                }
            };
            if !credential_status_advances(last_status, status) {
                continue;
            }
            let notification = serde_json::json!({
                "jsonrpc": "2.0",
                "method": "auth.credential.event",
                "params": status,
            });
            let Ok(text) = serde_json::to_string(&notification) else {
                continue;
            };
            let closed = credential_events.closed();
            tokio::select! {
                biased;
                reason = closed => {
                    if let Some(sender) = credential_lag_tx.take() {
                        let _ = sender.send(reason);
                    }
                    break;
                }
                result = async {
                    credential_session
                        .channel
                        .write
                        .lock()
                        .await
                        .send(Message::Text(text.into()))
                        .await
                } => {
                    if result.is_err() {
                        break;
                    }
                    last_status = Some(status);
                }
            }
        }
    });

    // Server-side WebSocket keepalive. See KEEPALIVE_* consts: tokio-tungstenite
    // emits no automatic pings, so a SILENTLY dead connection (TCP half-open, no
    // close frame) on a QUIET stream is never noticed — its drain task parks on
    // recv() and its registry entries leak until the daemon restarts. We ping on
    // an interval; a live client (even a quiet one) answers with a pong, which —
    // like any inbound frame — refreshes `last_inbound`. No frame for
    // KEEPALIVE_DEAD_AFTER, or a failed/timed-out ping write, means the peer is
    // gone → break into the SINGLE cleanup path below (deregisters subscribers,
    // aborts in-flight handlers). This is the "ping timeout" case the cleanup
    // comment anticipates.
    let mut keepalive = tokio::time::interval(KEEPALIVE_PING_INTERVAL);
    keepalive.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
    // `interval`'s first tick is immediate; consume it so the first ping fires a
    // full interval after connect (never racing a client's opening request).
    keepalive.tick().await;
    let mut last_inbound = tokio::time::Instant::now();
    loop {
        // Reap finished handlers so a long-lived connection doesn't
        // retain their `JoinHandle`s unbounded (memory, not FDs).
        while conn_tasks.try_join_next().is_some() {}

        // INVARIANT: every arm yields a `Message` or diverges (break/continue).
        // `read.next()` and `keepalive.tick()` are both cancellation-safe, so the
        // loser of each select is simply re-polled next iteration with no loss.
        let msg = tokio::select! {
            closed = &mut credential_lag_rx => {
                match closed {
                    Ok(reason) => info!(
                        client = %client_id,
                        ?reason,
                        "credential event subscriber closed; terminating connection"
                    ),
                    Err(_) => info!(
                        client = %client_id,
                        "credential event monitor ended; terminating connection"
                    ),
                }
                break;
            }
            maybe = read.next() => match maybe {
                // Any inbound frame — text, binary, ping, or the pong our
                // keepalive provokes — proves the peer is alive.
                Some(Ok(m)) => {
                    last_inbound = tokio::time::Instant::now();
                    m
                }
                // car#209: on an abrupt transport error (peer reset / network
                // drop — the trader crash-loop case) `read.next()` yields
                // `Some(Err(_))`. The old `let msg = msg?;` propagated that
                // out of the function, *skipping the cleanup block below*, so
                // `state.sessions` (+ the host/a2ui/chat registries) kept the
                // session + channel — and thus the socket FD — forever. Break
                // instead: every disconnect, clean or not, runs the single
                // cleanup path. `None` = the stream ended cleanly.
                Some(Err(e)) => {
                    info!("read error from {}: {}; closing", client_id, e);
                    break;
                }
                None => break,
            },
            _ = keepalive.tick() => {
                if last_inbound.elapsed() >= KEEPALIVE_DEAD_AFTER {
                    info!(
                        "keepalive: no frames from {} for {}s; closing",
                        client_id,
                        last_inbound.elapsed().as_secs()
                    );
                    break;
                }
                // Provoke a pong from a quiet-but-alive client. The timeout wraps
                // the lock acquisition AND the send: `channel.write` is shared
                // with the dispatch handlers' `send_response` (an unbounded
                // write), so a handler wedged on a full TCP buffer can hold the
                // lock until its own 180s deadline — bounding only the send would
                // let the read loop park on `.lock().await` and defeat the 90s
                // liveness contract. Elapsed here covers a stuck lock or a stuck
                // socket; either way the peer is treated as gone.
                let sent = tokio::time::timeout(KEEPALIVE_WRITE_TIMEOUT, async {
                    let mut guard = channel.write.lock().await;
                    guard.send(Message::Ping(Vec::new().into())).await
                })
                .await;
                if !matches!(sent, Ok(Ok(()))) {
                    info!("keepalive: ping to {} failed/timed out; closing", client_id);
                    break;
                }
                continue;
            }
        };
        if msg.is_text() {
            let text = match msg.to_text() {
                Ok(t) => t,
                Err(e) => {
                    info!("non-text frame from {}: {}; closing", client_id, e);
                    break;
                }
            };
            let parsed: JsonRpcMessage = match serde_json::from_str(text) {
                Ok(m) => m,
                Err(e) => {
                    send_response(
                        &session.channel,
                        JsonRpcResponse::error(Value::Null, -32700, &format!("Parse error: {}", e)),
                    )
                    .await
                    .ok();
                    continue;
                }
            };

            // Is this a response to a pending tool callback?
            if parsed.method.is_none() && (parsed.result.is_some() || parsed.error.is_some()) {
                if let Some(id_str) = parsed.id.as_str() {
                    let mut pending = session.channel.pending.lock().await;
                    if let Some(tx) = pending.remove(id_str) {
                        let tool_resp = if let Some(result) = parsed.result {
                            ToolExecuteResponse {
                                action_id: id_str.to_string(),
                                output: Some(result),
                                error: None,
                                terminal: false,
                            }
                        } else {
                            let err_msg = parsed
                                .error
                                .as_ref()
                                .and_then(|e| e.get("message"))
                                .and_then(|m| m.as_str())
                                .unwrap_or("unknown error")
                                .to_string();
                            // Terminality is an additive typed bit in error.data,
                            // never a word inferred from the human message.
                            let terminal = parsed
                                .error
                                .as_ref()
                                .and_then(|error| error.get("data"))
                                .and_then(|data| data.get("terminal"))
                                .and_then(Value::as_bool)
                                .unwrap_or(false);
                            ToolExecuteResponse {
                                action_id: id_str.to_string(),
                                output: None,
                                error: Some(err_msg),
                                terminal,
                            }
                        };
                        let _ = tx.send(tool_resp);
                        continue;
                    }
                }
            }

            // Per-agent daemon-method scope. This is the ONE admission point:
            // it runs before notification interceptors, the handshake-gated
            // dispatch, host-management admission, approval admission, and the
            // method handler table. A denied request therefore cannot trigger
            // any method-specific side effect. Notifications are dropped
            // without a response, as JSON-RPC requires.
            if let Some(method) = parsed.method.as_deref() {
                if !agent_method_scope_allows(&session, method) {
                    if !parsed.id.is_null() {
                        let response = JsonRpcResponse::error(
                            parsed.id.clone(),
                            AGENT_METHOD_NOT_ALLOWED_ERROR_CODE,
                            &format!("{AGENT_METHOD_NOT_ALLOWED_MESSAGE_PREFIX}`{method}`"),
                        );
                        let _ = send_response(&session.channel, response).await;
                    }
                    info!(
                        client = %client_id,
                        method = %method,
                        "agent_method_not_allowed: scoped supervised-agent session denied before dispatch"
                    );
                    continue;
                }
            }

            // Agent → host chat-event interceptor. `agent.chat.event`
            // notifications coming up the WS from a connected agent
            // are forwarded to the originating host's channel as
            // `agents.chat.event`. Lives ahead of the regular method
            // dispatch so the dispatcher doesn't reply with
            // "method-not-found" on what is a fire-and-forget
            // notification (no id). See
            // `docs/proposals/agent-chat-surface.md`.
            if try_forward_agent_chat_event(&parsed, &state).await {
                continue;
            }

            // Agent → drawer browser pushes (`browser.producer.presentation`,
            // `browser.producer.frame`). Notifications too, for the same
            // reason: they carry no id, so they must be consumed here rather
            // than answered with a method-not-found nobody is listening for.
            if crate::browser_relay::try_handle_producer_push(&parsed, &state, &session).await {
                continue;
            }

            // Otherwise it's a client request
            if let Some(method) = &parsed.method {
                info!(method = %method, "dispatching JSON-RPC method");

                // Auth gate (Parslee-ai/car-releases#32). When the
                // server has an auth token installed, every method
                // other than `session.auth` is rejected on
                // unauthenticated sessions and the connection is
                // closed after the error response goes out. When no
                // token is installed (default), this branch never
                // fires — preserves pre-#32 behaviour.
                if state.auth_token.get().is_some()
                    && !session
                        .authenticated
                        .load(std::sync::atomic::Ordering::Acquire)
                    && method != "session.auth"
                {
                    let resp =
                        JsonRpcResponse::error(parsed.id.clone(), -32001, &auth_required_message());
                    let _ = send_response(&session.channel, resp).await;
                    info!(client = %client_id, method = %method,
                        "rejecting non-auth method on unauthenticated session; closing");
                    break;
                }

                // Supervised-agent auth binds a token-specific method scope.
                // Run that form inline so a second already-buffered frame
                // cannot race the scope write on an auth-disabled daemon and
                // observe the legacy unrestricted `None`. Generic daemon-token
                // and host-token auth keep the existing spawned path below.
                if method == "session.auth"
                    && parsed
                        .params
                        .get("agent_id")
                        .and_then(Value::as_str)
                        .is_some()
                {
                    let result = dispatch_with_server_deadline(
                        method,
                        &parsed.params,
                        handle_session_auth(&parsed, &session, &state),
                    )
                    .await;
                    if result.is_ok()
                        && credential_event_is_eligible(
                            &session,
                            credential_transport_auth_required,
                            credential_host_role_required,
                        )
                    {
                        let _ = credential_activation_tx.send(true);
                        let mut ready = credential_ready_rx.clone();
                        while !*ready.borrow_and_update() {
                            if ready.changed().await.is_err() {
                                break;
                            }
                        }
                    }
                    let response = json_rpc_response_for_handler_result(parsed.id, result);
                    let _ = send_response(&session.channel, response).await;
                    continue;
                }

                // Protocol negotiation is connection-scoped and follows
                // transport auth: an auth-enabled daemon still requires
                // `session.auth` as frame #1, then `server.handshake`, then
                // host/auth application calls. Handle negotiation inline so
                // the version state is committed before its success response
                // is observable; the client may safely send `host.subscribe`
                // as soon as it receives that response.
                if method == "server.handshake" {
                    let (response, handshake_succeeded) =
                        match handle_server_handshake(&parsed, &session) {
                            Ok(result) => {
                                (JsonRpcResponse::success(parsed.id.clone(), result), true)
                            }
                            Err(error) => (
                                JsonRpcResponse::error(
                                    parsed.id.clone(),
                                    error.code,
                                    &error.message,
                                ),
                                false,
                            ),
                        };
                    if handshake_succeeded
                        && credential_event_is_eligible(
                            &session,
                            credential_transport_auth_required,
                            credential_host_role_required,
                        )
                    {
                        let _ = credential_activation_tx.send(true);
                        let mut ready = credential_ready_rx.clone();
                        while !*ready.borrow_and_update() {
                            if ready.changed().await.is_err() {
                                break;
                            }
                        }
                    }
                    let _ = send_response(&session.channel, response).await;
                    continue;
                }

                if requires_protocol_handshake(method)
                    && session
                        .negotiated_protocol_version
                        .load(std::sync::atomic::Ordering::Acquire)
                        != car_proto::PROTOCOL_VERSION
                {
                    let message = format!(
                        "{} call `server.handshake` with {{\"protocol_version\":{}}} \
                         and wait for an exact-version success before `{}`",
                        car_proto::PROTOCOL_HANDSHAKE_REQUIRED_MESSAGE_PREFIX,
                        car_proto::PROTOCOL_VERSION,
                        method,
                    );
                    let response = JsonRpcResponse::error(
                        parsed.id.clone(),
                        car_proto::PROTOCOL_HANDSHAKE_REQUIRED_ERROR_CODE,
                        &message,
                    );
                    let _ = send_response(&session.channel, response).await;
                    info!(
                        client = %client_id,
                        method = %method,
                        "rejecting handshake-gated method before negotiation"
                    );
                    continue;
                }

                // Apply the exported host-management set at the dispatcher
                // boundary before any handler can run. Individual handlers
                // retain their local authority checks as defense in depth; the
                // capability generator derives the set from those real call
                // sites and tests it against this shared client/daemon list.
                if crate::HOST_MANAGEMENT_METHODS.contains(&method.as_str()) {
                    if let Err(error) = require_approval_authority(&session, &state) {
                        let response = json_rpc_response_for_handler_result(
                            parsed.id.clone(),
                            Err(HandlerFailure::Dispatch(error)),
                        );
                        let _ = send_response(&session.channel, response).await;
                        continue;
                    }
                }

                // Approval gate (audit 2026-05). High-risk methods —
                // anything that drives macOS automation or sends
                // messages on the user's behalf — must be acked by
                // the user via `host.resolve_approval` before they
                // dispatch. The gate raises an `approval.requested`
                // host event the local UI can render approve/deny on,
                // then parks until resolved or the configured
                // timeout fires. Returns a JSON-RPC error and
                // continues the dispatch loop on deny / timeout —
                // no connection close, since the caller may want to
                // retry with revised parameters.
                if state.approval_gate.requires_approval(method.as_str()) {
                    match gate_high_risk_method(method.as_str(), &parsed.params, &state).await {
                        Ok(()) => {}
                        Err(reason) => {
                            let resp = JsonRpcResponse::error(parsed.id.clone(), -32003, &reason);
                            let _ = send_response(&session.channel, resp).await;
                            info!(
                                client = %client_id,
                                method = %method,
                                reason = %reason,
                                "approval gate blocked dispatch"
                            );
                            continue;
                        }
                    }
                }

                // Credential-backed auth operations own durable coordinator /
                // keychain state, so the connection must never own their core
                // futures. Authorize while this session is present, then move
                // only owned request/state data into the ServerState task set.
                // The oneshot waiter (when there is one) is connection-owned and
                // is aborted on disconnect, so no late response can retain or
                // leak into a later WebSocket.
                if is_daemon_owned_auth_method(method) {
                    let response_id = parsed.id.clone();
                    if let Err(error) = require_approval_authority(&session, &state) {
                        let response = json_rpc_response_for_handler_result(
                            response_id,
                            Err(HandlerFailure::Dispatch(error)),
                        );
                        let _ = send_response(&session.channel, response).await;
                        continue;
                    }

                    let method_owned = method.clone();
                    let method_for_waiter = method_owned.clone();
                    let parsed_owned = parsed;
                    let state_owned = state.clone();
                    let result_rx = state
                        .spawn_durable_operation(method_owned.clone(), async move {
                            dispatch_daemon_owned_auth(
                                method_owned.as_str(),
                                &parsed_owned,
                                &state_owned,
                            )
                            .await
                        })
                        .await;
                    let response_channel = session.channel.clone();
                    conn_tasks.spawn(async move {
                        let result =
                            await_daemon_owned_auth_result(method_for_waiter.as_str(), result_rx)
                                .await;
                        let response = json_rpc_response_for_handler_result(response_id, result);
                        let _ = send_response(&response_channel, response).await;
                    });
                    continue;
                }

                // Spawn the per-method dispatch in a task so the read
                // loop keeps reading frames. Without this, methods
                // that trigger server-initiated `tools.execute`
                // callbacks (`proposal.submit`, `workflow.run`,
                // `multi.*` paths that fire a registered tool)
                // deadlock the connection: the handler awaits the
                // callback response on a oneshot, but the response is
                // another frame on this same read half — which the
                // synchronous `.await` here would prevent the loop
                // from ever picking up. Surfaced by the
                // `executeProposal: echo tool via JS callback` smoke
                // (#173). Response ordering becomes id-keyed (the
                // JSON-RPC demuxing contract) rather than
                // arrival-ordered.
                let session_task = session.clone();
                let state_task = state.clone();
                let method_owned = method.clone();
                let parsed_task = parsed;
                let credential_activation_tx_task = credential_activation_tx.clone();
                let credential_ready_rx_task = credential_ready_rx.clone();
                // car#209: owned by the per-connection JoinSet so it's
                // aborted on disconnect instead of leaking the channel.
                conn_tasks.spawn(async move {
                    let session = session_task;
                    let state = state_task;
                    let parsed = parsed_task;
                    // The identity this connection authenticated as, resolved
                    // ONCE per frame. Read here rather than inside each arm for
                    // two reasons: a `session.agent_id.lock().await` in argument
                    // position keeps the guard alive for the whole arm body —
                    // including the handler's own `await`, which for
                    // `agents.wait` is caller-controlled — and one read per
                    // frame cannot disagree with itself the way thirteen
                    // independent acquisitions can. The six mutating
                    // `agents.*` handlers deliberately receive the session and
                    // clone this identity again inside their short authority
                    // check: that keeps the host/agent dependency explicit at
                    // the handler call site and drops the guard before any
                    // supervisor await.
                    let bound_agent = session.agent_id.lock().await.clone();
                    let bound_agent = bound_agent.as_deref();
                    // INVARIANT: arms must be pure tail expressions — no `?`,
                    // `return`, or `continue` — since they now live inside this
                    // `async` block, not the surrounding loop/fn.
                    let dispatch = async {
                        match method_owned.as_str() {
                            "session.auth" => handle_session_auth(&parsed, &session, &state).await,
                            "capabilities.list" => Ok(handle_capabilities_list(
                                bound_agent,
                                session.is_host.load(std::sync::atomic::Ordering::Acquire),
                            )),
                            "parslee.auth" => handle_parslee_auth(&state).await,
                            "parslee.capabilities" => crate::parslee_capabilities::discover().await,
                            "parslee.m365.generate_document" => {
                                crate::parslee_m365::generate_document(&parsed.params).await
                            }
                            "openrouter.status" => handle_openrouter_status(&session, &state),
                            "openrouter.auth_start" => {
                                handle_openrouter_auth_start(&parsed, &session, &state).await
                            }
                            "openrouter.auth_cancel" => {
                                handle_openrouter_auth_cancel(&parsed, &session, &state)
                            }
                            "openrouter.disconnect" => {
                                handle_openrouter_disconnect(&session, &state).await
                            }
                            "session.init" => handle_session_init(&parsed, &session).await,
                            "session.bindSandbox" => {
                                handle_session_bind_sandbox(&parsed, &session, &state).await
                            }
                            "session.bindSubstrate" => {
                                handle_session_bind_substrate(&parsed, &session, &state).await
                            }
                            "session.clear_halt" => handle_session_clear_halt(&session).await,
                            "host.subscribe" => handle_host_subscribe(&session, &state).await,
                            "supervision.subscribe" => {
                                handle_supervision_subscribe(&parsed, &session, &state).await
                            }
                            "supervision.unsubscribe" => {
                                handle_supervision_unsubscribe(&session, &state).await
                            }
                            "supervision.pending" => handle_supervision_pending(&state).await,
                            "supervision.decide" => {
                                handle_supervision_decide(&parsed, &state).await
                            }
                            "host.agents" => handle_host_agents(&session, &state).await,
                            "host.events" => handle_host_events(&parsed, &session).await,
                            "host.approvals" => handle_host_approvals(&session).await,
                            "host.register_agent" => {
                                handle_host_register_agent(&parsed, &session).await
                            }
                            "host.unregister_agent" => {
                                handle_host_unregister_agent(&parsed, &session).await
                            }
                            "host.set_status" => handle_host_set_status(&parsed, &session).await,
                            "host.register_device" => {
                                handle_host_register_device(&parsed, &session).await
                            }
                            "host.update_device" => {
                                handle_host_update_device(&parsed, &session).await
                            }
                            "host.devices" => handle_host_devices(&session).await,
                            "mobile.runtime" => handle_mobile_runtime(&state).await,
                            "host.notify" => handle_host_notify(&parsed, &session).await,
                            "host.request_approval" => {
                                handle_host_request_approval(&parsed, &session).await
                            }
                            "host.resolve_approval" => {
                                handle_host_resolve_approval(&parsed, &session).await
                            }
                            "tools.register" => handle_tools_register(&parsed, &session).await,
                            "tools.list" => handle_tools_list(&session).await,
                            "tools.unregister" => handle_tools_unregister(&parsed, &session).await,
                            "tools.poll" => handle_tools_poll(&parsed, &session).await,
                            "tools.cancel" => handle_tools_cancel(&parsed, &session).await,
                            "tools.stream.subscribe" => {
                                handle_tools_stream_subscribe(&session).await
                            }
                            "proposal.submit" => {
                                handle_proposal_submit(&parsed, &session, &state).await
                            }
                            "policy.register" => handle_policy_register(&parsed, &session).await,
                            "policy.unregister" => {
                                handle_policy_unregister(&parsed, &session).await
                            }
                            "policy.list" => handle_policy_list(&parsed, &session).await,
                            "session.policy.open" => handle_session_policy_open(&session).await,
                            "session.policy.close" => {
                                handle_session_policy_close(&parsed, &session).await
                            }
                            "verify" => handle_verify(&parsed, &session).await,
                            "verify.monte_carlo" => {
                                handle_verify_monte_carlo(&parsed, &session).await
                            }
                            "permission.get_tier" => handle_permission_get_tier(&session).await,
                            "permission.set_tier" => {
                                handle_permission_set_tier(&parsed, &session, &state).await
                            }
                            "permission.classify" => {
                                handle_permission_classify(&parsed, &session).await
                            }
                            "permission.evaluate" => {
                                handle_permission_evaluate(&parsed, &session, &state).await
                            }
                            "permission.pending" => {
                                handle_permission_pending(&parsed, &session, &state).await
                            }
                            "permission.approve" => {
                                handle_permission_decision(&parsed, &session, &state, true).await
                            }
                            "permission.reject" => {
                                handle_permission_decision(&parsed, &session, &state, false).await
                            }
                            "agent_permissions.get" => {
                                crate::agent_permissions::handle_get(&parsed)
                            }
                            "agent_permissions.set" => {
                                require_agent_permissions_authority(&session, &state).await?;
                                crate::agent_permissions::handle_set(&parsed)
                            }
                            "agent_permissions.set_default" => {
                                require_agent_permissions_authority(&session, &state).await?;
                                crate::agent_permissions::handle_set_default(&parsed)
                            }
                            "agent_permissions.reset" => {
                                require_agent_permissions_authority(&session, &state).await?;
                                crate::agent_permissions::handle_reset(&parsed)
                            }
                            "agent_permissions.evaluate" => {
                                crate::agent_permissions::handle_evaluate(&parsed)
                            }
                            "agent_permissions.set_tool" => {
                                require_agent_permissions_authority(&session, &state).await?;
                                require_agent_tool_override_capability(&session)?;
                                handle_agent_permission_set_tool(&parsed, &state).await
                            }
                            "agent_permissions.reset_tool" => {
                                require_agent_permissions_authority(&session, &state).await?;
                                require_agent_tool_override_capability(&session)?;
                                crate::agent_permissions::handle_reset_tool(&parsed)
                            }
                            "agent_permissions.evaluate_tool" => {
                                require_agent_permissions_authority(&session, &state).await?;
                                require_agent_tool_override_capability(&session)?;
                                handle_agent_permission_evaluate_tool(&parsed, &state).await
                            }
                            // Multi-device sync + execution lease (B6).
                            "sync.status" => handle_sync_status(&state).await,
                            "sync.append" => handle_sync_append(&parsed, &state).await,
                            "sync.record_turn" => handle_sync_record_turn(&parsed, &state).await,
                            "sync.record_intent" => {
                                handle_sync_record_intent(&parsed, &state, &session).await
                            }
                            "sync.pump" => handle_sync_pump(&state).await,
                            "sync.knowledge" => handle_sync_knowledge(&parsed, &state).await,
                            "sync.checkpoint" => handle_sync_checkpoint(&state).await,
                            "sync.rebase" => handle_sync_rebase(&state).await,
                            "sync.transcript" => handle_sync_transcript(&parsed, &state).await,
                            "sync.resume" => handle_sync_resume(&parsed, &state).await,
                            "sync.assistant_checkpoint.put" => {
                                handle_sync_assistant_checkpoint_put(&parsed, &state).await
                            }
                            "sync.assistant_checkpoint.get" => {
                                handle_sync_assistant_checkpoint_get(&parsed, &state).await
                            }
                            "sync.assistant_action.put" => {
                                handle_sync_assistant_action_put(&parsed, &state).await
                            }
                            "sync.assistant_action.get" => {
                                handle_sync_assistant_action_get(&parsed, &state).await
                            }
                            "sync.fence_check" => {
                                handle_sync_fence_check(&parsed, &state, &session).await
                            }
                            "lease.acquire" => {
                                handle_lease_acquire(&parsed, &state, &session).await
                            }
                            "lease.renew" => handle_lease_renew(&parsed, &state, &session).await,
                            "lease.release" => {
                                handle_lease_release(&parsed, &state, &session).await
                            }
                            "lease.status" => {
                                handle_lease_status(&parsed, &state, bound_agent).await
                            }
                            "messaging.config.get" => {
                                handle_messaging_config_get(&parsed, &session, &state).await
                            }
                            "messaging.config.set" => {
                                handle_messaging_config_set(&parsed, &session, &state).await
                            }
                            "messaging.pairing.start" => {
                                handle_messaging_pairing_start(&parsed, &session, &state).await
                            }
                            "messaging.pairing.status" => {
                                handle_messaging_pairing_status(&parsed, &session, &state).await
                            }
                            "messaging.status" => {
                                handle_messaging_status(&parsed, &session, &state).await
                            }
                            "messaging.test_send" => {
                                handle_messaging_test_send(&parsed, &session, &state).await
                            }
                            "state.get" => handle_state_get(&parsed, &session).await,
                            "state.set" => handle_state_set(&parsed, &session).await,
                            "state.exists" => handle_state_exists(&parsed, &session).await,
                            "state.keys" => handle_state_keys(&parsed, &session).await,
                            "state.snapshot" => handle_state_snapshot(&parsed, &session).await,
                            "memory.add_fact" => handle_memory_add_fact(&parsed, &session).await,
                            "memory.set_admission_table" => {
                                handle_memory_set_admission_table(&parsed, &session).await
                            }
                            "memory.admission_table" => {
                                handle_memory_admission_table(&parsed, &session).await
                            }
                            "memory.update_status" => {
                                handle_memory_update_status(&parsed, &session).await
                            }
                            "memory.maintain" => handle_memory_maintain(&parsed, &session).await,
                            "memory.save_knowledge" => {
                                handle_memory_save_knowledge(&parsed, &session).await
                            }
                            "memory.save_procedural" => {
                                handle_memory_save_procedural(&parsed, &session).await
                            }
                            "memory.delete" => handle_memory_delete(&parsed, &session).await,
                            "memory.query" => handle_memory_query(&parsed, &session).await,
                            "memory.evaluate" => handle_memory_evaluate(&parsed, &session).await,
                            "memory.intervene" => handle_memory_intervene(&parsed, &session).await,
                            "memory.build_context" => {
                                handle_memory_build_context(&parsed, &session).await
                            }
                            "memory.build_context_fast" => {
                                handle_memory_build_context_fast(&parsed, &session).await
                            }
                            "memory.consolidate" => handle_memory_consolidate(&session).await,
                            "memory.utility_get" => handle_memory_utility_get(&session).await,
                            "memory.utility_set" => {
                                handle_memory_utility_set(&parsed, &session).await
                            }
                            "cascade.run" => handle_cascade_run(&parsed, &session, &state).await,
                            "evolution.plan" => {
                                handle_evolution_plan(&parsed, &session, &state).await
                            }
                            "evolution.run" => {
                                handle_evolution_run(&parsed, &session, &state).await
                            }
                            "selfheal.status" => handle_selfheal_status(&state).await,
                            "selfheal.detections" => {
                                handle_selfheal_detections(&parsed, &state).await
                            }
                            "selfheal.dismiss" => handle_selfheal_dismiss(&parsed, &state).await,
                            "selfheal.fix" => handle_selfheal_fix(&parsed, &state).await,
                            "selfheal.run" => handle_selfheal_run(&state).await,
                            "heal.status" => handle_heal_status(&state).await,
                            "heal.run" => handle_heal_run(&state).await,
                            "memory.fact_count" => handle_memory_fact_count(&session).await,
                            "memory.persist" => handle_memory_persist(&parsed, &session).await,
                            "memory.load" => handle_memory_load(&parsed, &session).await,
                            "skill.ingest" => handle_skill_ingest(&parsed, &session).await,
                            "skill.find" => handle_skill_find(&parsed, &session).await,
                            "skill.report" => handle_skill_report(&parsed, &session).await,
                            "skill.gate_deployment" => {
                                handle_skill_gate_deployment(&parsed, &session).await
                            }
                            "skill.enforce_deployment" => {
                                handle_skill_enforce_deployment(&parsed, &session, &state).await
                            }
                            "skill.ingest_governed" => {
                                handle_skill_ingest_governed(&parsed, &session, &state).await
                            }
                            "skill.adopt_pack" => {
                                handle_skill_adopt_pack(&parsed, &session, &state).await
                            }
                            "skill.repair" => handle_skill_repair(&parsed, &session).await,
                            "skills.ingest_distilled" => {
                                handle_skills_ingest_distilled(&parsed, &session).await
                            }
                            "skills.evolve" => handle_skills_evolve(&parsed, &session).await,
                            "skills.domains_needing_evolution" => {
                                handle_skills_domains_needing_evolution(&parsed, &session).await
                            }
                            "skills.ingest_provisional" => {
                                handle_skills_ingest_provisional(&parsed, &session).await
                            }
                            "skills.gate" => handle_skills_gate(&parsed, &session).await,
                            "skill.meta" => handle_skill_meta(&parsed, &session).await,
                            "skill.export" => handle_skill_export(&parsed, &session).await,
                            "skill.import" => handle_skill_import(&parsed, &session).await,
                            "multi.swarm" => handle_multi_swarm(&parsed, &session).await,
                            "multi.pipeline" => handle_multi_pipeline(&parsed, &session).await,
                            "multi.supervisor" => handle_multi_supervisor(&parsed, &session).await,
                            "multi.map_reduce" => handle_multi_map_reduce(&parsed, &session).await,
                            "multi.vote" => handle_multi_vote(&parsed, &session).await,
                            "multi.tournament" => handle_multi_tournament(&parsed, &session).await,
                            "multi.subtask" => handle_multi_subtask(&parsed, &session).await,
                            "scheduler.create" => handle_scheduler_create(&parsed),
                            "scheduler.run" => handle_scheduler_run(&parsed, &session).await,
                            "scheduler.run_loop" => {
                                handle_scheduler_run_loop(&parsed, &session).await
                            }
                            "scheduler.os_render" => handle_scheduler_os_render(&parsed),
                            "scheduler.os_install" => handle_scheduler_os_install(&parsed),
                            "scheduler.os_uninstall" => handle_scheduler_os_uninstall(&parsed),
                            "scheduler.os_list" => handle_scheduler_os_list(&parsed),
                            "scheduler.os_reconcile" => handle_scheduler_os_reconcile(&parsed),
                            "tasks.schedule" => handle_tasks_schedule(&parsed, &session, &state),
                            "tasks.list" => handle_tasks_list(&parsed),
                            "tasks.unschedule" => {
                                handle_tasks_unschedule(&parsed, &session, &state)
                            }
                            "diagnostics.secret_store_activity" => {
                                handle_secret_store_activity(&session, &state)
                            }
                            // In-app feedback (PR A wave 2). compose_preview
                            // and submit share ONE compose path (PREV-2);
                            // submit is the only spool writer (PRIV-2). Every
                            // arm is gated on the negotiated `feedback.v1`
                            // capability — protocol version alone is not
                            // consent to this surface.
                            "feedback.compose_preview" => {
                                require_feedback_capability(&session)?;
                                crate::feedback::handle_compose_preview(&parsed, &state, &session)
                                    .await
                            }
                            "feedback.submit" => {
                                require_feedback_capability(&session)?;
                                crate::feedback::handle_submit(&parsed, &state, &session).await
                            }
                            "feedback.status" => {
                                require_feedback_capability(&session)?;
                                crate::feedback::handle_status(&parsed, &state).await
                            }
                            "feedback.list" => {
                                require_feedback_capability(&session)?;
                                crate::feedback::handle_list(&parsed, &state).await
                            }
                            "infer" => handle_infer(&parsed, state.clone(), session.clone()).await,
                            "infer.cancel" => handle_infer_cancel(&parsed, &session).await,
                            "infer.deadline" => handle_infer_deadline(&parsed, &session).await,
                            "image.generate" => handle_image_generate(&parsed, &state).await,
                            "video.generate" => handle_video_generate(&parsed, &state).await,
                            "embed" => handle_embed(&parsed, &state).await,
                            "classify" => handle_classify(&parsed, &state).await,
                            "tokenize" => handle_tokenize(&parsed, &state).await,
                            "detokenize" => handle_detokenize(&parsed, &state).await,
                            "rerank" => handle_rerank(&parsed, &state).await,
                            "transcribe" => handle_transcribe(&parsed, &state).await,
                            "synthesize" => handle_synthesize(&parsed, &state).await,
                            "search" => handle_search(&parsed, &state).await,
                            "web_fetch" => handle_web_fetch(&parsed, &state).await,
                            "infer_stream" => handle_infer_stream(&parsed, &session, &state).await,
                            "speech.prepare" => handle_speech_prepare(&state).await,
                            "models.route" => handle_models_route(&parsed, &state).await,
                            "models.stats" => handle_models_stats(&state).await,
                            "outcomes.scoreboard" => handle_outcomes_scoreboard(&state).await,
                            "outcomes.resolve_pending" => {
                                handle_outcomes_resolve_pending(&parsed, &state).await
                            }
                            "events.count" => handle_events_count(&session).await,
                            "events.stats" => handle_events_stats(&session).await,
                            "events.truncate" => handle_events_truncate(&parsed, &session).await,
                            "events.clear" => handle_events_clear(&session).await,
                            "events.query" => handle_events_query(&parsed, &session).await,
                            "events.retention" => handle_events_retention(&parsed, &session).await,
                            "events.cost_by_agent" => handle_events_cost_by_agent(&session).await,
                            "events.chain.enable" => handle_events_chain_enable(&session).await,
                            "events.chain.verify" => handle_events_chain_verify(&session).await,
                            "metrics.summary" => handle_metrics_summary(&session).await,
                            "metrics.alerts" => handle_metrics_alerts(&parsed, &session).await,
                            "nlp.identify_language" => handle_nlp(&parsed, NlpOp::IdentifyLanguage),
                            "nlp.tokenize" => handle_nlp(&parsed, NlpOp::Tokenize),
                            "nlp.extract_entities" => handle_nlp(&parsed, NlpOp::ExtractEntities),
                            // Agent run tracing, U1 — run lifecycle bracket.
                            // `runs.start` mints a run_id and tags the
                            // session's current run BEFORE responding (KTD3);
                            // `runs.complete` records the terminal outcome.
                            // The per-turn recorder (U2) and the read/
                            // subscribe RPCs (U4/U5) build on these.
                            "runs.start" => handle_runs_start(&parsed, &session, &state).await,
                            "runs.resume" => handle_runs_resume(&parsed, &session, &state).await,
                            "runs.complete" => {
                                handle_runs_complete(&parsed, &session, &state).await
                            }
                            "runs.cancel" => handle_runs_cancel(&parsed, &session, &state).await,
                            // Client-narrated turn append (feedback-agent
                            // A2UI/runs plan, U1). WS-only (no FFI method, like
                            // runs.subscribe) — an out-of-pipeline agent whose
                            // work happens inside its own subprocess pushes full
                            // RunTurns it built itself. Authorized to the run's
                            // OWNING agent only (host-token/unbound writers are
                            // rejected as forgery); appends through the shared
                            // `record_run_turns` (index re-stamp, persist, fanout).
                            "runs.record_turns" => {
                                handle_runs_record_turns(&parsed, &session, &state).await
                            }
                            // Live run-trace subscribe/unsubscribe (U4). WS-only
                            // (no FFI method) — CarHost consumes the
                            // `runs.trace.event` notification. Authorization
                            // gated per-run (R16/KTD10).
                            "runs.subscribe" => {
                                handle_runs_subscribe(&parsed, &session, &state).await
                            }
                            "runs.unsubscribe" => {
                                handle_runs_unsubscribe(&parsed, &session, &state).await
                            }
                            // Replay reads (U5). WS-only (no FFI method, like
                            // `runs.subscribe`) — CarHost lists an agent's runs
                            // and fetches a completed run's full trace from the
                            // disk store (works across restart / client_id
                            // churn). Authorization gated per-agent/run (R16).
                            "runs.list" => handle_runs_list(&parsed, &session, &state).await,
                            "runs.get_trace" => {
                                handle_runs_get_trace(&parsed, &session, &state).await
                            }
                            "replan.set_config" => {
                                handle_replan_set_config(&parsed, &session).await
                            }
                            "models.list" => handle_models_list(&state),
                            "models.register" => handle_models_register(&parsed, &state).await,
                            "models.unregister" => handle_models_unregister(&parsed, &state).await,
                            "models.list_unified" => {
                                handle_models_list_unified(&parsed, &state).await
                            }
                            "models.catalog_snapshot" => {
                                handle_models_catalog_snapshot(&session, &state)
                            }
                            "models.resource_policy.get" => {
                                handle_models_resource_policy_get(&parsed, &state)
                            }
                            "models.resource_policy.set" => {
                                handle_models_resource_policy_set(&parsed, &session, &state)
                            }
                            "models.preflight" => handle_models_preflight(&parsed, &state),
                            "models.storage_roots" => {
                                handle_models_storage_roots(&parsed, &session, &state)
                            }
                            "models.remove" => {
                                handle_models_remove(&parsed, &session, &state).await
                            }
                            "models.adopt" => handle_models_adopt(&parsed, &session, &state).await,
                            "models.route_provenance" => {
                                handle_models_route_provenance(&parsed, &state).await
                            }
                            "models.search" => handle_models_search(&parsed, &state).await,
                            "models.recommend" => handle_models_recommend(&parsed, &state),
                            "models.setup_plan" => handle_models_setup_plan(&parsed, &state),
                            "models.upgrades" => handle_models_upgrades(&state),
                            "models.detect_upgrades" => handle_models_detect_upgrades(&state).await,
                            "models.check_upgrade_nudge" => {
                                handle_models_check_upgrade_nudge(&parsed, &state).await
                            }
                            "models.dismiss_upgrade" => {
                                handle_models_dismiss_upgrade(&parsed, &state)
                            }
                            "models.check_concierge" => {
                                handle_models_check_concierge(&parsed, &state).await
                            }
                            "models.dismiss_suggestion" => {
                                handle_models_dismiss_suggestion(&parsed, &state)
                            }
                            // Concierge (Phase C1) — ambient status + labeled
                            // dismissal. WS-only; CarHost's Model Health pane +
                            // friction card consume these.
                            "concierge.status" => handle_concierge_status(&parsed, &state).await,
                            "concierge.dismiss" => handle_concierge_dismiss(&parsed, &state),
                            "concierge.defaults" => handle_concierge_defaults(&state),
                            "concierge.set_default" => {
                                handle_concierge_set_default(&parsed, &state).await
                            }
                            "concierge.clear_default" => {
                                handle_concierge_clear_default(&parsed, &state).await
                            }
                            "concierge.apply" => handle_concierge_apply(&parsed, &state).await,
                            "concierge.rollback" => {
                                handle_concierge_rollback(&parsed, &state).await
                            }
                            "concierge.actions" => handle_concierge_actions(&parsed, &state),
                            "concierge.refresh_catalog" => {
                                handle_concierge_refresh_catalog(&state).await
                            }
                            "concierge.ask" => handle_concierge_ask(&parsed, &state).await,
                            "models.update_prefs_get" => handle_models_update_prefs_get(&state),
                            "models.update_prefs_set" => {
                                handle_models_update_prefs_set(&parsed, &state)
                            }
                            "models.pull" | "models.install" => {
                                handle_models_pull(&parsed, &session, &state).await
                            }
                            "skills.distill" => handle_skills_distill(&parsed, &state).await,
                            "skills.list" => handle_skills_list(&parsed, &session).await,
                            "browser.run" => handle_browser_run(&parsed, &session).await,
                            "browser.close" => handle_browser_close(&session).await,
                            // The browser DRAWER surface (`browser.view.*`).
                            // Separate from `browser.run` above, which is the
                            // per-connection scripted browser and is untouched:
                            // this one watches and drives the ASSISTANT's
                            // browser (or the shared standing session) for a
                            // human at the Command Deck. Host-management client
                            // only — see `crate::browser_view`'s module docs for
                            // why that is stricter than `runs.subscribe`.
                            "browser.view.subscribe" => {
                                crate::browser_view::handle_subscribe(&parsed, &session, &state)
                                    .await
                            }
                            "browser.view.unsubscribe" => {
                                crate::browser_view::handle_unsubscribe(&parsed, &session, &state)
                                    .await
                            }
                            "browser.view.take_control" => {
                                crate::browser_view::handle_take_control(&parsed, &session, &state)
                                    .await
                            }
                            "browser.view.hand_back" => {
                                crate::browser_view::handle_hand_back(&parsed, &session, &state)
                                    .await
                            }
                            "browser.view.navigate" => {
                                crate::browser_view::handle_input(
                                    crate::browser_view::InputOp::Navigate,
                                    &parsed,
                                    &session,
                                    &state,
                                )
                                .await
                            }
                            "browser.view.click" => {
                                crate::browser_view::handle_input(
                                    crate::browser_view::InputOp::Click,
                                    &parsed,
                                    &session,
                                    &state,
                                )
                                .await
                            }
                            "browser.view.type" => {
                                crate::browser_view::handle_input(
                                    crate::browser_view::InputOp::Type,
                                    &parsed,
                                    &session,
                                    &state,
                                )
                                .await
                            }
                            "browser.view.keypress" => {
                                crate::browser_view::handle_input(
                                    crate::browser_view::InputOp::Keypress,
                                    &parsed,
                                    &session,
                                    &state,
                                )
                                .await
                            }
                            "browser.view.scroll" => {
                                crate::browser_view::handle_input(
                                    crate::browser_view::InputOp::Scroll,
                                    &parsed,
                                    &session,
                                    &state,
                                )
                                .await
                            }
                            // Paste carries the TEXT: the clipboard belongs
                            // to the host's OS, and CDP's injected key events
                            // cannot reach one, so a synthesised Cmd+V would
                            // deliver a key event and nothing would arrive.
                            "browser.view.paste" => {
                                crate::browser_view::handle_input(
                                    crate::browser_view::InputOp::Paste,
                                    &parsed,
                                    &session,
                                    &state,
                                )
                                .await
                            }
                            // The nav bar's history buttons. No params of
                            // their own — which page they act on is the active
                            // tab's own history.
                            "browser.view.back" => {
                                crate::browser_view::handle_input(
                                    crate::browser_view::InputOp::Back,
                                    &parsed,
                                    &session,
                                    &state,
                                )
                                .await
                            }
                            "browser.view.forward" => {
                                crate::browser_view::handle_input(
                                    crate::browser_view::InputOp::Forward,
                                    &parsed,
                                    &session,
                                    &state,
                                )
                                .await
                            }
                            "browser.view.reload" => {
                                crate::browser_view::handle_input(
                                    crate::browser_view::InputOp::Reload,
                                    &parsed,
                                    &session,
                                    &state,
                                )
                                .await
                            }
                            "browser.view.tab_open" => {
                                crate::browser_view::handle_input(
                                    crate::browser_view::InputOp::TabOpen,
                                    &parsed,
                                    &session,
                                    &state,
                                )
                                .await
                            }
                            "browser.view.tab_close" => {
                                crate::browser_view::handle_input(
                                    crate::browser_view::InputOp::TabClose,
                                    &parsed,
                                    &session,
                                    &state,
                                )
                                .await
                            }
                            "browser.view.tab_switch" => {
                                crate::browser_view::handle_input(
                                    crate::browser_view::InputOp::TabSwitch,
                                    &parsed,
                                    &session,
                                    &state,
                                )
                                .await
                            }
                            // The AGENT side of the drawer (`browser.producer.*`):
                            // a supervised agent process publishing ITS OWN
                            // browser so `browser.view.*` above can serve it.
                            // Agent sessions only — see `crate::browser_relay`.
                            "browser.producer.register" => {
                                crate::browser_relay::handle_producer_register(
                                    &parsed, &session, &state,
                                )
                                .await
                            }
                            "secret.put" => handle_secret_put(&parsed).await,
                            "secret.get" => handle_secret_get(&parsed, &session, &state).await,
                            "secret.delete" => handle_secret_delete(&parsed).await,
                            "secret.status" => handle_secret_status(&parsed),
                            "secret.available" => Ok(car_ffi_common::secrets::is_available()),
                            "secret.list" => car_ffi_common::secrets::list(),
                            "permissions.status" => handle_perm_status(&parsed),
                            "permissions.request" => handle_perm_request(&parsed),
                            "permissions.explain" => handle_perm_explain(&parsed),
                            "permissions.domains" => Ok(car_ffi_common::permissions::domains()),
                            "accounts.list" => car_ffi_common::accounts::list(),
                            "accounts.open" => {
                                #[derive(serde::Deserialize, Default)]
                                struct OpenParams {
                                    #[serde(default)]
                                    account_id: Option<String>,
                                }
                                let p: OpenParams = serde_json::from_value(parsed.params.clone())
                                    .unwrap_or_default();
                                car_ffi_common::accounts::open_settings(p.account_id.as_deref())
                            }
                            "calendar.list" => car_ffi_common::integrations::calendar_list(),
                            "calendar.events" => handle_calendar_events(&parsed),
                            "calendar.create_event" => handle_calendar_create_event(&parsed),
                            "calendar.update_event" => handle_calendar_update_event(&parsed),
                            "calendar.delete_event" => handle_calendar_delete_event(&parsed),
                            "contacts.containers" => {
                                car_ffi_common::integrations::contacts_containers()
                            }
                            "contacts.find" => handle_contacts_find(&parsed),
                            "mail.accounts" => car_ffi_common::integrations::mail_accounts(),
                            "mail.inbox" => handle_mail_inbox(&parsed),
                            "mail.mailboxes" => handle_mail_mailboxes(&parsed),
                            "mail.messages" => handle_mail_messages(&parsed),
                            "mail.message_body" => handle_mail_message_body(&parsed),
                            "mail.send" => handle_mail_send(&parsed),
                            "messages.services" => {
                                car_ffi_common::integrations::messages_services()
                            }
                            "messages.chats" => handle_messages_chats(&parsed),
                            "messages.read" => handle_messages_read(&parsed),
                            "messages.send" => handle_messages_send(&parsed),
                            "notes.accounts" => car_ffi_common::integrations::notes_accounts(),
                            "notes.find" => handle_notes_find(&parsed),
                            "reminders.lists" => car_ffi_common::integrations::reminders_lists(),
                            "reminders.items" => handle_reminders_items(&parsed),
                            "photos.albums" => car_ffi_common::integrations::photos_albums(),
                            "bookmarks.list" => handle_bookmarks_list(&parsed),
                            "files.locations" => car_ffi_common::integrations::files_locations(),
                            "keychain.status" => car_ffi_common::integrations::keychain_status(),
                            "health.status" => car_ffi_common::health::status(),
                            "health.sleep" => handle_health_sleep(&parsed),
                            "health.workouts" => handle_health_workouts(&parsed),
                            "health.activity" => handle_health_activity(&parsed),
                            "voice.transcribe_stream.start" => {
                                handle_voice_transcribe_stream_start(&parsed, &state, &session)
                                    .await
                            }
                            "voice.transcribe_stream.stop" => {
                                handle_voice_transcribe_stream_stop(&parsed, &state).await
                            }
                            "voice.transcribe_stream.push" => {
                                handle_voice_transcribe_stream_push(&parsed, &state).await
                            }
                            "voice.tts_stream.start" => {
                                handle_voice_tts_stream_start(&parsed, &session).await
                            }
                            "voice.tts_stream.cancel" => {
                                handle_voice_tts_stream_cancel(&parsed).await
                            }
                            "voice.tts_stream.list" => Ok(handle_voice_tts_stream_list()),
                            "voice.sessions.list" => Ok(handle_voice_sessions_list(&state)),
                            "voice.dispatch_turn" => {
                                handle_voice_dispatch_turn(&parsed, &state, &session).await
                            }
                            "voice.cancel_turn" => handle_voice_cancel_turn().await,
                            "voice.prewarm_turn" => handle_voice_prewarm_turn(&state).await,
                            "inference.register_runner" => {
                                handle_inference_register_runner(&session).await
                            }
                            "inference.runner.event" => {
                                handle_inference_runner_event(&parsed).await
                            }
                            "inference.runner.complete" => {
                                handle_inference_runner_complete(&parsed).await
                            }
                            "inference.runner.fail" => handle_inference_runner_fail(&parsed).await,
                            "voice.providers.list" => {
                                // Stateless: enumerates STT/TTS providers compiled into
                                // this build. Runtime readiness (API key, permission,
                                // model download) is reported via per-provider errors.
                                serde_json::from_str::<serde_json::Value>(
                                    &car_voice::list_voice_providers_json(),
                                )
                                .map_err(|e| e.to_string())
                            }
                            "voice.prepare_parakeet" => car_ffi_common::voice::prepare_parakeet()
                                .await
                                .and_then(|j| serde_json::from_str(&j).map_err(|e| e.to_string())),
                            "voice.prepare_diarizer" => car_ffi_common::voice::prepare_diarizer()
                                .await
                                .and_then(|j| serde_json::from_str(&j).map_err(|e| e.to_string())),
                            "voice.enroll_speaker" => handle_enroll_speaker(&parsed).await,
                            "voice.list_enrollments" => car_ffi_common::voice::list_enrollments()
                                .and_then(|j| serde_json::from_str(&j).map_err(|e| e.to_string())),
                            "voice.remove_enrollment" => handle_remove_enrollment(&parsed),
                            "workflow.run" => handle_workflow_run(&parsed, &session).await,
                            "workflow.chain" => handle_workflow_chain(&parsed, &session).await,
                            "workflow.resume" => handle_workflow_resume(&parsed, &session).await,
                            "workflow.list_paused" => handle_workflow_list_paused().await,
                            "builder.build" => {
                                handle_builder_build(&parsed, &state, &session).await
                            }
                            "workflow.verify" => handle_workflow_verify(&parsed),
                            "workflow.build_automation" => {
                                handle_workflow_build_automation(&parsed)
                            }
                            "meeting.start" => {
                                handle_meeting_start(&parsed, &state, &session).await
                            }
                            "meeting.stop" => handle_meeting_stop(&parsed, &state, &session).await,
                            "meeting.list" => handle_meeting_list(&parsed),
                            "meeting.get" => handle_meeting_get(&parsed),
                            "registry.register" => handle_registry_register(&parsed),
                            "registry.heartbeat" => handle_registry_heartbeat(&parsed),
                            "registry.unregister" => handle_registry_unregister(&parsed),
                            "registry.list" => handle_registry_list(&parsed),
                            "registry.reap" => handle_registry_reap(&parsed),
                            "admission.status" => handle_admission_status(&state),
                            "a2a.start" => handle_a2a_start(&parsed, &state, &session).await,
                            "a2a.stop" => handle_a2a_stop(),
                            "a2a.status" => handle_a2a_status(),
                            "a2a.send" => handle_a2a_send(&parsed, &state).await,
                            "a2a.peers.add" => handle_a2a_peers_add(&parsed),
                            "a2a.peers.list" => handle_a2a_peers_list(),
                            "a2a.peers.remove" => handle_a2a_peers_remove(&parsed),
                            "a2ui.apply" => handle_a2ui_apply(&parsed, &state).await,
                            "a2ui.ingest" => handle_a2ui_ingest(&parsed, &state).await,
                            "a2ui.capabilities" => handle_a2ui_capabilities(&state),
                            "a2ui.reap" => handle_a2ui_reap(&state).await,
                            "a2ui.surfaces" => handle_a2ui_surfaces(&state).await,
                            "a2ui.get" => handle_a2ui_get(&parsed, &state).await,
                            "a2ui.action" => handle_a2ui_action(&parsed, &state).await,
                            "a2ui.render_report" => {
                                handle_a2ui_render_report(&parsed, &state).await
                            }
                            "a2ui/subscribe" => handle_a2ui_subscribe(&session, &state).await,
                            "a2ui/unsubscribe" => handle_a2ui_unsubscribe(&session, &state).await,
                            "a2ui/replay" => handle_a2ui_replay(&parsed, &state).await,
                            "automation.run_applescript" => handle_run_applescript(&parsed).await,
                            "automation.run_powershell" => handle_run_powershell(&parsed).await,
                            "automation.shortcuts.list" => handle_list_shortcuts(&parsed).await,
                            "automation.shortcuts.run" => handle_run_shortcut(&parsed).await,
                            "notifications.local" => handle_local_notification(&parsed).await,
                            "vision.ocr" => handle_vision_ocr(&parsed).await,
                            "coder.start" => {
                                crate::coder::rpc::handle_coder_start(&parsed, &state, &session)
                                    .await
                            }
                            "coder.projects.list" => {
                                crate::coder::rpc::handle_coder_projects_list(&state).await
                            }
                            "coder.projects.create" => {
                                crate::coder::rpc::handle_coder_projects_create(&parsed, &state)
                                    .await
                            }
                            "coder.projects.get" => {
                                crate::coder::rpc::handle_coder_projects_get(&parsed, &state).await
                            }
                            "coder.confirm_contract" => {
                                crate::coder::rpc::handle_coder_confirm_contract(&parsed, &state)
                                    .await
                            }
                            "coder.list" => crate::coder::rpc::handle_coder_list(&state).await,
                            "coder.get" => {
                                crate::coder::rpc::handle_coder_get(&parsed, &state).await
                            }
                            "coder.subscribe" => {
                                crate::coder::rpc::handle_coder_subscribe(&parsed, &state, &session)
                                    .await
                            }
                            "coder.unsubscribe" => {
                                crate::coder::rpc::handle_coder_unsubscribe(
                                    &parsed, &state, &session,
                                )
                                .await
                            }
                            "coder.respond" => {
                                crate::coder::rpc::handle_coder_respond(&parsed, &state).await
                            }
                            "coder.watch" => {
                                crate::coder::rpc::handle_coder_watch(&parsed, &state, &session)
                                    .await
                            }
                            "coder.unwatch" => {
                                crate::coder::rpc::handle_coder_unwatch(&state, &session).await
                            }
                            "coder.revise_contract" => {
                                crate::coder::rpc::handle_coder_revise_contract(&parsed, &state)
                                    .await
                            }
                            "coder.approve_merge" => {
                                crate::coder::rpc::handle_coder_approve_merge(&parsed, &state).await
                            }
                            "coder.cancel" => {
                                crate::coder::rpc::handle_coder_cancel(&parsed, &state).await
                            }
                            "coder.discuss.start" => {
                                crate::coder::discuss::handle_discuss_start(
                                    &parsed, &state, &session,
                                )
                                .await
                            }
                            "coder.discuss.send" => {
                                crate::coder::discuss::handle_discuss_send(
                                    &parsed, &state, &session,
                                )
                                .await
                            }
                            "coder.discuss.subscribe" => {
                                crate::coder::discuss::handle_discuss_subscribe(
                                    &parsed, &state, &session,
                                )
                                .await
                            }
                            "coder.discuss.unsubscribe" => {
                                crate::coder::discuss::handle_discuss_unsubscribe(
                                    &parsed, &state, &session,
                                )
                                .await
                            }
                            "coder.discuss.promote" => {
                                crate::coder::discuss::handle_discuss_promote(
                                    &parsed, &state, &session,
                                )
                                .await
                            }
                            "coder.discuss.close" => {
                                crate::coder::discuss::handle_discuss_close(
                                    &parsed, &state, &session,
                                )
                                .await
                            }
                            "coder.discuss.list" => {
                                crate::coder::discuss::handle_discuss_list(&state, &session).await
                            }
                            "declagents.list" => {
                                crate::coder::rpc::handle_declagents_list(&state).await
                            }
                            "declagents.get" => {
                                crate::coder::rpc::handle_declagents_get(&parsed, &state).await
                            }
                            "declagents.remove" => {
                                require_host_lifecycle_authority(&session, &state).await?;
                                crate::coder::rpc::handle_declagents_remove(
                                    &parsed, &state, &session,
                                )
                                .await
                            }
                            "declagents.set_enabled" => {
                                require_host_lifecycle_authority(&session, &state).await?;
                                crate::coder::rpc::handle_declagents_set_enabled(
                                    &parsed, &state, &session,
                                )
                                .await
                            }
                            "declagents.invoke" => {
                                crate::coder::rpc::handle_declagents_invoke(
                                    &parsed, &state, &session,
                                )
                                .await
                            }
                            "declagents.route" => {
                                crate::coder::rpc::handle_declagents_route(
                                    &parsed, &state, &session,
                                )
                                .await
                            }
                            "declagents.route_split" => {
                                crate::coder::rpc::handle_declagents_route_split(
                                    &parsed, &state, &session,
                                )
                                .await
                            }
                            "declagents.routing_stats" => {
                                crate::coder::rpc::handle_declagents_routing_stats(&state).await
                            }
                            "discovery.resolve" => {
                                crate::coder::rpc::handle_discovery_resolve(&parsed, &state).await
                            }
                            "discovery.route_compose" => {
                                crate::coder::rpc::handle_discovery_route_compose(&parsed, &state)
                                    .await
                            }
                            "discovery.report" => {
                                crate::coder::rpc::handle_discovery_report(&parsed, &state).await
                            }
                            "agents.list" => handle_agents_list(&state).await,
                            "agents.health" => handle_agents_health(&state).await,
                            "agents.upsert" => {
                                handle_agents_upsert(&parsed, &state, &session).await
                            }
                            "agents.install" => {
                                handle_agents_install(&parsed, &state, &session).await
                            }
                            "agents.remove" => {
                                handle_agents_remove(&parsed, &state, &session).await
                            }
                            "agents.start" => handle_agents_start(&parsed, &state, &session).await,
                            "agents.stop" => handle_agents_stop(&parsed, &state, &session).await,
                            "agents.restart" => {
                                handle_agents_restart(&parsed, &state, &session).await
                            }
                            "agents.wait" => handle_agents_wait(&parsed, &state, bound_agent).await,
                            "agents.tail_log" => {
                                handle_agents_tail_log(&parsed, &state, bound_agent).await
                            }
                            "agents.list_external" => handle_agents_list_external(&parsed).await,
                            "agents.detect_external" => {
                                handle_agents_detect_external(&parsed).await
                            }
                            "agents.health_external" => {
                                handle_agents_health_external(&parsed).await
                            }
                            "assistant.identity.get" => handle_assistant_identity_get(),
                            "assistant.identity.set" => {
                                handle_assistant_identity_set(&parsed, &session, &state).await
                            }
                            "assistants.invoke" => {
                                handle_assistants_invoke(&parsed, &state, &session).await
                            }
                            "agents.invoke_external" => {
                                handle_agents_invoke_external(&parsed, &state, &session).await
                            }
                            "agents.chat" => handle_agents_chat(&parsed, &state, &session).await,
                            "agents.peers" => {
                                crate::peers::handle_agents_peers(&state, &session).await
                            }
                            "agents.message" => {
                                crate::peers::handle_agents_message(&parsed, &state, &session).await
                            }
                            "agents.message.pending" => {
                                crate::peers::handle_agents_message_pending(&state, &session).await
                            }
                            "agents.message.approve" => {
                                crate::peers::handle_agents_message_approve(
                                    &parsed, &state, &session,
                                )
                                .await
                            }
                            "agents.chat.cancel" => {
                                handle_agents_chat_cancel(
                                    &parsed,
                                    &state,
                                    &session.client_id,
                                    session.is_host.load(std::sync::atomic::Ordering::Acquire),
                                )
                                .await
                            }
                            "agents.chat.approve" => {
                                handle_agents_chat_approve(
                                    &parsed,
                                    &state,
                                    &session.client_id,
                                    session.is_host.load(std::sync::atomic::Ordering::Acquire),
                                )
                                .await
                            }
                            "goal.suggest" => handle_goal_suggest(&parsed, &state).await,
                            "goal.set" => handle_goal_set(&parsed, &state).await,
                            "goal.status" => handle_goal_status(&parsed, &state).await,
                            "goal.clear" => handle_goal_clear(&parsed, &state).await,
                            // Foreman: decompose a coding goal into a footprint-
                            // annotated, scheduled subtask plan (B6). Execution
                            // (foreman.run) farms the plan to external CLIs and gates
                            // the union — added once the run surface lands.
                            "foreman.plan" => handle_foreman_plan(&parsed, &state).await,
                            "foreman.run" => handle_foreman_run(&parsed, &state, &session).await,
                            // fleet.* — what every reachable CAR instance can do,
                            // and whether this one takes farmed-out work.
                            "fleet.inventory" => {
                                crate::fleet::handle_fleet_inventory(&state, &session).await
                            }
                            "fleet.composite" => {
                                crate::fleet::handle_fleet_composite(&parsed, &state, &session)
                                    .await
                            }
                            "fleet.worker.get" => crate::fleet::handle_fleet_worker_get().await,
                            "fleet.worker.set" => {
                                crate::fleet::handle_fleet_worker_set(&parsed, &session).await
                            }
                            // Remote MCP connectors (CAR as MCP client). WS-only
                            // (no FFI surface in Phase 1) — connector lifecycle is
                            // daemon-shared and interactive. See
                            // docs/proposals/remote-mcp-connectors.md.
                            "connectors.add" => handle_connectors_add(&parsed, &state).await,
                            "connectors.add_stdio" => {
                                handle_connectors_add_stdio(&parsed, &state).await
                            }
                            "connectors.authenticate" => {
                                handle_connectors_authenticate(&parsed, &state).await
                            }
                            "connectors.complete_authentication" => {
                                handle_connectors_complete_authentication(&parsed, &state).await
                            }
                            "connectors.list" => handle_connectors_list(&state).await,
                            "connectors.tools" => handle_connectors_tools(&parsed, &state).await,
                            "connectors.enable_tools" => {
                                handle_connectors_enable_tools(&parsed, &state).await
                            }
                            "connectors.disable_tools" => {
                                handle_connectors_disable_tools(&parsed, &state).await
                            }
                            "connectors.refresh" => {
                                handle_connectors_refresh(&parsed, &state).await
                            }
                            "connectors.remove" => handle_connectors_remove(&parsed, &state).await,
                            // A2A v1.0 (PascalCase) + v0.3 (slash form) — both
                            // alias to the same in-core dispatcher per
                            // Parslee-ai/car-releases#28. Embedders that need a
                            // custom AgentCardSource / TaskStore plug them in
                            // via ServerStateConfig::with_a2a_card_source /
                            // with_a2a_store before any handler runs.
                            "message/send"
                            | "SendMessage"
                            | "message/stream"
                            | "SendStreamingMessage"
                            | "tasks/get"
                            | "GetTask"
                            | "tasks/list"
                            | "ListTasks"
                            | "tasks/cancel"
                            | "CancelTask"
                            | "tasks/resubscribe"
                            | "SubscribeToTask"
                            | "tasks/pushNotificationConfig/set"
                            | "CreateTaskPushNotificationConfig"
                            | "tasks/pushNotificationConfig/get"
                            | "GetTaskPushNotificationConfig"
                            | "tasks/pushNotificationConfig/list"
                            | "ListTaskPushNotificationConfigs"
                            | "tasks/pushNotificationConfig/delete"
                            | "DeleteTaskPushNotificationConfig"
                            | "agent/getAuthenticatedExtendedCard"
                            | "GetExtendedAgentCard" => {
                                handle_a2a_dispatch(method_owned.as_str(), &parsed, &state).await
                            }
                            _ => Err(format!("unknown method: {}", method_owned)),
                        }
                    };

                    // Per-request deadline so a wedged handler can't hang the
                    // client forever. None = exempt (unbounded streams/subs/loops).
                    // On timeout the handler future is dropped. That DOES now
                    // fire the tools.cancel host-abort and release the `pending`
                    // entry for any in-flight tool callback: the cleanup hangs
                    // off a `Drop` guard (`PendingToolCall` in session.rs), so
                    // it survives the future being dropped rather than needing
                    // code to run after the await (car#264).
                    // `parsed.params` rides along because `proposal.submit`'s
                    // deadline is derived from the submitted proposal's own
                    // action budgets, not from the method name alone (#265).
                    let result = dispatch_with_server_deadline(
                        method_owned.as_str(),
                        &parsed.params,
                        dispatch,
                    )
                    .await;

                    if method_owned == "session.auth"
                        && result.is_ok()
                        && credential_event_is_eligible(
                            &session,
                            credential_transport_auth_required,
                            credential_host_role_required,
                        )
                    {
                        let _ = credential_activation_tx_task.send(true);
                        let mut ready = credential_ready_rx_task;
                        while !*ready.borrow_and_update() {
                            if ready.changed().await.is_err() {
                                break;
                            }
                        }
                    }

                    let resp = json_rpc_response_for_handler_result(parsed.id, result);
                    let _ = send_response(&session.channel, resp).await;
                });
            }
        } else if msg.is_binary() {
            // CAR binary frame transport — see `car_ffi_common::voice::binary`
            // for the canonical header definition. 26-byte fixed header
            // followed by an opaque payload. Inbound type 0x01 carries
            // 16-bit signed LE PCM into a `pcm_push` session; other
            // types (0x02 TTS chunk, 0x03 final marker, 0x04 error)
            // are server-emitted and rejected here.
            let bytes = msg.into_data();
            let parsed = match car_ffi_common::voice::binary::parse_frame(&bytes) {
                Ok(p) => p,
                Err(e) => {
                    tracing::warn!("binary frame from {} rejected: {}", client_id, e);
                    continue;
                }
            };
            match parsed.frame_type {
                car_ffi_common::voice::binary::FRAME_TYPE_INBOUND_PCM => {
                    let registry = state.voice_sessions.clone();
                    let payload_owned = parsed.payload.to_vec();
                    let session_id_owned = parsed.session_id_hex.clone();
                    conn_tasks.spawn(async move {
                        if let Err(e) = car_ffi_common::voice::transcribe_stream_push(
                            &session_id_owned,
                            &payload_owned,
                            registry,
                        )
                        .await
                        {
                            tracing::warn!(
                                "binary PCM push to session {} failed: {}",
                                session_id_owned,
                                e
                            );
                        }
                    });
                }
                other => {
                    tracing::debug!(
                        "binary frame type {:#04x} from {} not accepted server-side",
                        other,
                        client_id
                    );
                }
            }
        } else if msg.is_close() {
            info!("Client {} disconnected", client_id);
            break;
        }
    }

    // car#209: abort every in-flight handler for this connection
    // *first* — they each hold an `Arc<ClientSession>` → `Arc<WsChannel>`
    // clone; until they're gone the split sink (and the inbound socket
    // FD) can't drop, even after the registries below are cleared.
    conn_tasks.abort_all();
    // Inference backend wrappers outlive their response waiter after a
    // controlled terminal. Abort every retained active/orphan task when the
    // owning socket disconnects so no provider or delegated runner detaches.
    session.inference_control.abort_all();

    session.host.unsubscribe(&client_id).await;
    // Drop this connection's supervisor registration too. Intents it left
    // parked are deliberately NOT released here — they run out their timeout
    // and fail closed, so a supervisor cannot convert a pending deny into an
    // allow by dropping the socket.
    state.supervision.unsubscribe(&client_id).await;
    // Auto-cancel this session's pending approvals so the queue stays
    // in sync with what's actually decidable — covers graceful
    // unregister+close, hard crash (TCP reset), and ping timeout in
    // one place. System-level gate approvals (client_id None) are not
    // touched. car-releases#48.
    session.host.reap_session_approvals(&client_id).await;
    state.a2ui_subscribers.lock().await.remove(&client_id);

    // Fix for MULTI-4 / WS-3: drop the session from the registry and
    // drain any pending tool callbacks. Without this, every connection
    // we ever accepted keeps an `Arc<ClientSession>` alive in
    // `state.sessions`, and outstanding `oneshot::Sender`s in
    // `session.channel.pending` outlive the closed connection until
    // their per-call timeout (the action budget, or `DEFAULT_TOOL_TIMEOUT_MS`
    // — no longer a hardcoded 60s, see car#259). Dropping the senders here causes any
    // awaiting `recv()` in `WsToolExecutor::execute` to return
    // `RecvError` immediately, which the existing error-handler path
    // already maps to "callback channel closed" — same shape as the
    // timeout path, just faster.
    let _removed = state.remove_session(&client_id).await;
    {
        let mut pending = session.channel.pending.lock().await;
        pending.clear();
    }

    Ok(())
}

async fn send_response(
    channel: &WsChannel,
    resp: JsonRpcResponse,
) -> Result<(), Box<dyn std::error::Error>> {
    use futures::SinkExt;
    let json = serde_json::to_string(&resp)?;
    channel
        .write
        .lock()
        .await
        .send(Message::Text(json.into()))
        .await?;
    Ok(())
}

// --- Request handlers ---

async fn handle_host_subscribe(
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    session
        .host
        .subscribe(&session.client_id, session.channel.clone())
        .await;
    // Capture the ordering boundary BEFORE reading browser state. If a live
    // sign-in event races this snapshot, it receives a larger sequence and a
    // client that already applied it can reject this older response.
    let event_sequence = session.host.event_sequence();
    let snapshot = serde_json::to_value(HostSnapshot {
        subscribed: true,
        agents: session.host.agents().await,
        devices: session.host.devices().await,
        approvals: session.host.approvals().await,
        events: session.host.events(50).await,
        pending_signins: state.browser_views.pending_signins().await,
        event_sequence,
        identity: Some(daemon_identity(state)),
    })
    .map_err(|e| e.to_string())?;
    Ok(snapshot)
}

/// `supervision.subscribe` — register this connection as a supervisor.
///
/// `{ filter?: { tools?, sessions?, min_reversibility? } }` →
/// `{ subscribed, decision_timeout_ms, supervisors }`.
///
/// Re-subscribing replaces the filter, so a supervisor narrows or widens its
/// view without a disconnect. The connection's own channel is the delivery
/// path, exactly as `host.subscribe` works.
async fn handle_supervision_subscribe(
    request: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let filter: crate::supervision::SupervisionFilter = match request.params.get("filter") {
        Some(Value::Null) | None => Default::default(),
        Some(v) => serde_json::from_value(v.clone())
            .map_err(|e| format!("invalid supervision filter: {e}"))?,
    };
    state
        .supervision
        .subscribe(&session.client_id, filter, session.channel.clone())
        .await;
    Ok(serde_json::json!({
        "subscribed": true,
        "decision_timeout_ms": state.supervision.timeout().as_millis() as u64,
        "supervisors": state.supervision.subscriber_count().await,
    }))
}

/// `supervision.unsubscribe` — stop supervising. `{}` → `{ subscribed: false,
/// was_subscribed }`.
async fn handle_supervision_unsubscribe(
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let was = state.supervision.unsubscribe(&session.client_id).await;
    Ok(serde_json::json!({ "subscribed": false, "was_subscribed": was }))
}

/// `supervision.pending` — every intent currently parked on a verdict.
/// `{}` → `{ intents: [...] }`.
///
/// This is the batching half of the design: one model call can cover every
/// parked intent, which is what makes supervision affordable at all
/// (Shepherd Appendix E — batched and trimmed, not a cheap meta-model).
async fn handle_supervision_pending(state: &Arc<ServerState>) -> Result<Value, String> {
    Ok(serde_json::json!({ "intents": state.supervision.pending().await }))
}

/// `supervision.decide` — answer one intent.
/// `{ intent_id, decision: { kind: "allow" | "deny" | "escalate", reason? } }`
/// → `{ decided: true }`.
///
/// Errors when the intent is unknown — already decided, already timed out, or
/// never existed. That is deliberate: a supervisor that believes it denied
/// something needs to hear when the denial did not land.
async fn handle_supervision_decide(
    request: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let intent_id = request
        .params
        .get("intent_id")
        .and_then(|v| v.as_str())
        .ok_or("supervision.decide requires 'intent_id'")?;
    let decision_value = request
        .params
        .get("decision")
        .ok_or("supervision.decide requires 'decision'")?;
    let decision: crate::supervision::SupervisionDecision =
        serde_json::from_value(decision_value.clone())
            .map_err(|e| format!("invalid supervision decision: {e}"))?;
    state.supervision.decide(intent_id, decision).await?;
    Ok(serde_json::json!({ "decided": true }))
}

/// Snapshot the daemon-identity facts for a fresh subscriber.
/// Cheap: non-acquiring reads on `OnceLock`s + a single
/// `to_string_lossy` on the manifest path. Critically uses
/// [`ServerState::supervisor_if_installed`] — not the lazy-init
/// `supervisor()` — so a Heisenberg subscribe can't *cause* the
/// daemon to acquire the manifest lock just by asking whether it
/// owns one.
fn daemon_identity(state: &Arc<ServerState>) -> car_proto::HostIdentity {
    // Observer takes precedence: when both supervisor and observer
    // markers are set (currently unreachable through the standalone
    // binary, but an embedder could install both racily), the
    // observer marker is the authoritative role since the
    // supervisor handle is only installed when this daemon owns
    // the lock.
    let (manifest_path, manifest_role) = if let Some(p) = state.observer_manifest_path() {
        (
            Some(p.to_string_lossy().into_owned()),
            car_proto::HostManifestRole::Observer,
        )
    } else if let Some(s) = state.supervisor_if_installed() {
        (
            Some(s.manifest_path().to_string_lossy().into_owned()),
            car_proto::HostManifestRole::Owner,
        )
    } else {
        (None, car_proto::HostManifestRole::None)
    };
    car_proto::HostIdentity {
        version: env!("CARGO_PKG_VERSION").to_string(),
        pid: std::process::id(),
        manifest_path,
        manifest_role,
        parslee: state
            .parslee_session
            .get()
            .map(|session| session.identity.clone()),
    }
}

/// Return the Parslee cloud credential for an authenticated CAR
/// connection. Managed agents already receive `CAR_AUTH_TOKEN` and
/// authenticate to the local daemon with `session.auth`; this method is
/// their supported bridge from local CAR auth to the user's Parslee
/// backend auth.
///
/// The bearer token is intentionally not injected into every managed
/// child process environment. Agents ask for it only when they need it,
/// through the same local auth gate that protects the rest of the
/// daemon.
async fn handle_parslee_auth(state: &ServerState) -> Result<Value, String> {
    let (session, api_base) = crate::parslee_auth::load_or_refresh_with_authority()
        .await?
        .ok_or_else(|| "Parslee account not authenticated; run `car auth login`".to_string())?;
    activate_parslee_session(state, session.clone(), api_base);
    Ok(serde_json::json!({
        "authenticated": true,
        "token_type": "Bearer",
        "access_token": session.access_token,
        "authorization_header": format!("Bearer {}", session.access_token),
        "identity": session.identity,
    }))
}

// --- auth.* : GUI-driven Parslee sign-in (CAR Host.app).
// Shares one implementation with `car auth login` via the car-auth
// crate. The trusted in-process GUI holds the PKCE verifier + state;
// the daemon serializes process-global operations and persists only
// an attempt-bound completion proof beside the credentials so a lost
// reply can be reconciled without replaying the one-time code.
// --- auth.* : host-gated Parslee login management (car#661) ---
//
// Same trust root as `openrouter.*` (car#650) and `messaging.*`. These methods
// own the daemon's Parslee identity: `logout` clears the active login's tokens,
// `switch_org`/`switch_account` silently repoint which identity subsequent
// inference runs and bills against, and `remove_account` drops a stored login.
// They took only the request params, so they could not check the caller's role
// and did not — any authenticated local connection (a registered supervised
// agent, or any process that read the auth token from `GET /auth-token`) could
// sign the user out of every Parslee-routed model with one call.
//
// The reads are gated too: `status`/`accounts` enumerate which identities exist
// and which is active; `snapshot`/`completion_status` expose authentication and
// attempt state.
//
// Gating does NOT cost the CLI anything, which is the thing worth checking
// before copying this pattern: `car auth login`/`logout`/`orgs`/`switch-org`/
// `accounts` never touch this surface — they call `car_auth::` in-process
// (main.rs: `exchange_code`/`store_tokens`/`clear_tokens`). The only WS consumer
// is CarHost.app's `ParsleeAccount`, which drives `HostEventsClient` and already
// presents `session.auth { host_token }`.
//
// DEGRADED-MODE CAVEAT (inherited, not specific to this surface):
// `require_approval_authority` is a no-op when no host token is configured
// (pure-dev / `--no-auth`), where the connection is the authority. Identical to
// `permission.*`, `messaging.*`, and `openrouter.*`.

async fn dispatch_daemon_owned_auth(
    method: &str,
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, HandlerFailure> {
    match method {
        "auth.authority_hint" => serde_json::to_value(car_auth::credential_authority_hint())
            .map_err(|error| HandlerFailure::Dispatch(error.to_string())),
        "auth.start" => handle_auth_start(req)
            .await
            .map_err(|error| classified_auth_failure(method, error)),
        "auth.complete" => accept_auth_completion(req, state)
            .await
            .map_err(|error| classified_auth_failure(method, error)),
        "auth.completion_status" => handle_auth_completion_status(req, state)
            .await
            .map_err(|error| classified_auth_failure(method, error)),
        "auth.snapshot" => handle_auth_snapshot()
            .await
            .map_err(HandlerFailure::from_dispatch),
        "auth.status" => handle_auth_status(req, state)
            .await
            .map_err(HandlerFailure::from_dispatch),
        "auth.switch_org" => handle_auth_switch_org(req)
            .await
            .map_err(HandlerFailure::from_dispatch),
        "auth.accounts" => handle_auth_accounts(req)
            .await
            .map_err(HandlerFailure::from_dispatch),
        "auth.switch_account" => handle_auth_switch_account(req)
            .await
            .map_err(HandlerFailure::from_dispatch),
        "auth.remove_account" => handle_auth_remove_account(req)
            .await
            .map_err(HandlerFailure::from_dispatch),
        "auth.logout" => handle_auth_logout()
            .await
            .map_err(HandlerFailure::from_dispatch),
        _ => Err(HandlerFailure::Dispatch(format!(
            "unknown daemon-owned auth method: {method}"
        ))),
    }
}

async fn handle_auth_start(req: &JsonRpcMessage) -> Result<Value, car_auth::AuthOperationError> {
    // Choosing the browser endpoint must never inspect existing credentials.
    // The durable attempt reservation below is a separate state mutation.
    let environment_api_base = std::env::var(car_auth::PARSLEE_API_BASE_KEY).ok();
    let api_base = select_auth_start_api_base(&req.params, environment_api_base.as_deref());
    let client_id = str_or(&req.params, "client_id", "parslee-car");
    let redirect_uri =
        require_str(&req.params, "redirect_uri").map_err(car_auth::AuthOperationError::Terminal)?;
    let provider = opt_str(&req.params, "provider");
    // `prompt=select_account` (sent by the add-account path) forces the account
    // chooser so a second Parslee login can be added alongside the current one.
    let prompt = opt_str(&req.params, "prompt");
    let state = car_auth::new_state();
    let attempt_id = uuid::Uuid::new_v4().simple().to_string();
    let verifier = car_auth::pkce_verifier();
    let challenge = car_auth::pkce_challenge(&verifier);
    let url = car_auth::authorize_url(
        &api_base,
        client_id,
        redirect_uri,
        &state,
        &challenge,
        provider,
        prompt,
    )
    .map_err(car_auth::AuthOperationError::Terminal)?;
    // The reservation is the durable ordering point. A later auth.start,
    // logout, or identity switch fences this attempt before auth.complete can
    // touch the one-time authorization code.
    let lease = car_auth::reserve_login_attempt_classified(&attempt_id).await?;
    Ok(serde_json::json!({
        "authorize_url": url,
        "state": state,
        "verifier": verifier,
        "attempt_id": attempt_id,
        "expires_at_unix_ms": lease.attempt_expires_at_unix_ms,
    }))
}

fn select_auth_start_api_base(params: &Value, environment_api_base: Option<&str>) -> String {
    opt_str(params, "api_base")
        .map(str::trim)
        .filter(|value| !value.is_empty())
        .map(str::to_string)
        .or_else(|| {
            environment_api_base
                .map(str::trim)
                .filter(|value| !value.is_empty())
                .map(str::to_string)
        })
        .unwrap_or_else(|| car_auth::DEFAULT_API_BASE.to_string())
        .trim_end_matches('/')
        .to_string()
}

fn auth_completion_value(record: &car_auth::AuthCompletionRecord) -> Value {
    let session = record
        .session
        .as_deref()
        .and_then(|raw| serde_json::from_str::<Value>(raw).ok());
    serde_json::json!({
        "state": "complete",
        "attempt_id": record.attempt_id,
        "generation": record.generation,
        "account_id": record.account_id,
        "session": session,
    })
}

#[derive(Clone)]
struct AuthCompletionRequest {
    api_base: String,
    client_id: String,
    redirect_uri: String,
    code: String,
    verifier: String,
    attempt_id: String,
}

fn parse_auth_completion_request(req: &JsonRpcMessage) -> Result<AuthCompletionRequest, String> {
    Ok(AuthCompletionRequest {
        api_base: car_auth::api_base(opt_str(&req.params, "api_base")),
        client_id: str_or(&req.params, "client_id", "parslee-car").to_string(),
        redirect_uri: require_str(&req.params, "redirect_uri")?.to_string(),
        code: require_str(&req.params, "code")?.to_string(),
        verifier: require_str(&req.params, "verifier")?.to_string(),
        attempt_id: require_str(&req.params, "attempt_id")?.to_string(),
    })
}

async fn accept_auth_completion(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, car_auth::AuthOperationError> {
    let request =
        parse_auth_completion_request(req).map_err(car_auth::AuthOperationError::Terminal)?;
    let attempt_id = request.attempt_id.clone();
    let task_attempt_id = attempt_id.clone();
    let lease =
        car_auth::claim_login_attempt_classified(&attempt_id, &state.auth_completion_owner_id)
            .await?;
    state
        .spawn_durable_task(format!("auth.complete:{attempt_id}"), async move {
            if let Err(error) = complete_auth_completion(request, lease).await {
                tracing::warn!(attempt_id = %task_attempt_id, error = %error, "Parslee login completion failed");
            }
        })
        .await;
    Ok(serde_json::json!({
        "state": "accepted",
        "attempt_id": attempt_id,
    }))
}

async fn complete_auth_completion(
    request: AuthCompletionRequest,
    lease: car_auth::LoginAttemptLease,
) -> Result<Value, String> {
    // The direct RPC response is produced only after this lease was durably
    // claimed and this daemon-owned redemption task was spawned. A truthful
    // `accepted` receipt therefore always has a redeeming proof to reconcile.
    let worker_lease = lease.clone();
    let result = match tokio::spawn(complete_claimed_auth_completion(request, worker_lease)).await {
        Ok(result) => result,
        Err(error) => Err(format!(
            "Parslee login worker stopped unexpectedly: {error}"
        )),
    };
    if result.is_err() {
        match car_auth::fail_login_attempt(
            &lease,
            car_auth::AuthAttemptFailure::completion_failed(),
        )
        .await
        {
            Ok(true) => {}
            Ok(false) => {
                tracing::debug!(
                    attempt_id = %lease.attempt_id,
                    "stale auth worker exit could not replace a newer attempt"
                );
            }
            Err(error) => {
                tracing::warn!(
                    attempt_id = %lease.attempt_id,
                    error = %error,
                    "failed to persist terminal auth worker lifecycle"
                );
            }
        }
    }
    result
}

async fn complete_claimed_auth_completion(
    request: AuthCompletionRequest,
    lease: car_auth::LoginAttemptLease,
) -> Result<Value, String> {
    let (token, completion_session) =
        auth_completion_network_with_deadline(car_auth::AUTH_COMPLETION_NETWORK_DEADLINE, async {
            let token = car_auth::exchange_code(
                &request.api_base,
                &request.client_id,
                &request.redirect_uri,
                &request.code,
                &request.verifier,
            )
            .await?;
            let session = fetch_completion_session(&request.api_base, &token.access_token).await?;
            Ok((token, session))
        })
        .await?;

    // Identity is known and all network work is finished. This lease-checked
    // local publication deliberately sits outside the cancellable network cap.
    let record =
        car_auth::commit_login(&request.api_base, &token, &completion_session, Some(lease)).await?;

    Ok(auth_completion_value(&record))
}

async fn auth_completion_network_with_deadline<T, F>(
    deadline: std::time::Duration,
    operation: F,
) -> Result<T, String>
where
    F: std::future::Future<Output = Result<T, String>>,
{
    tokio::time::timeout(deadline, operation)
        .await
        .map_err(|_| {
            format!(
                "Parslee login network phase timed out after {}s; no credentials were saved",
                deadline.as_secs()
            )
        })?
}

/// A successful token exchange consumes the authorization code, but the session
/// read is a safe bearer GET and occurs before any credential persistence. Give
/// one transient session failure a bounded retry without ever re-exchanging the
/// code or publishing an unattributed token set.
async fn fetch_completion_session(api_base: &str, access_token: &str) -> Result<String, String> {
    match car_auth::fetch_status_with_access(api_base, access_token).await {
        Ok(session) => Ok(session),
        Err(first_error) => {
            tokio::time::sleep(std::time::Duration::from_millis(200)).await;
            car_auth::fetch_status_with_access(api_base, access_token)
                .await
                .map_err(|second_error| {
                    format!(
                        "OAuth authorization code was consumed, but CAR could not validate the signed-in account after two bounded session checks. No credentials were saved; check connectivity and sign in again. First check: {first_error}; second check: {second_error}"
                    )
                })
        }
    }
}

/// Read the result of one exact browser attempt from the already-published V2
/// authority. It never refreshes, calls the network, or migrates legacy slots.
/// A later identity mutation advances the durable generation and supersedes the
/// proof.
async fn handle_auth_completion_status(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, car_auth::AuthOperationError> {
    let attempt_id =
        require_str(&req.params, "attempt_id").map_err(car_auth::AuthOperationError::Terminal)?;
    let mut value = serde_json::to_value(
        car_auth::auth_completion_status_classified(attempt_id, &state.auth_completion_owner_id)
            .await?,
    )
    .map_err(|error| {
        car_auth::AuthOperationError::Terminal(format!("serialize auth completion status: {error}"))
    })?;
    if let Some(raw_session) = value.get("session").and_then(Value::as_str) {
        let decoded = serde_json::from_str::<Value>(raw_session).unwrap_or(Value::Null);
        value["session"] = decoded;
    }
    Ok(value)
}

/// Local-only, non-refreshing pre-browser baseline. The first V2 read may
/// migrate attributable legacy state; ambiguous legacy state fails closed.
async fn handle_auth_snapshot() -> Result<Value, String> {
    serde_json::to_value(car_auth::local_auth_snapshot().await?).map_err(|e| e.to_string())
}

async fn handle_auth_status(req: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let mode = if req
        .params
        .get("retry_keychain_access")
        .and_then(Value::as_bool)
        == Some(true)
    {
        car_auth::CredentialReadMode::Retry
    } else {
        car_auth::CredentialReadMode::Use
    };
    let Some(mut credential) = car_auth::resolve_credential(mode)
        .await
        .map_err(|error| error.to_string())?
    else {
        return Ok(serde_json::json!({ "authenticated": false }));
    };

    // The endpoint and bearer are one coordinator-resolved authoritative
    // bundle. No request parameter can redirect this session check.
    let session_json =
        match car_auth::fetch_status_with_access(&credential.api_base, &credential.access_token)
            .await
        {
            Ok(session) => session,
            Err(error) if error.contains("HTTP 401") => {
                let Some(refreshed) = car_auth::refresh_credential()
                    .await
                    .map_err(|refresh_error| refresh_error.to_string())?
                else {
                    return Err(error);
                };
                let session = car_auth::fetch_status_with_access(
                    &refreshed.api_base,
                    &refreshed.access_token,
                )
                .await?;
                credential = refreshed;
                session
            }
            Err(error) => return Err(error),
        };
    if let Ok(session) =
        crate::parslee_auth::session_from_status(credential.access_token, &session_json)
    {
        activate_parslee_session(state, session, credential.api_base);
    }
    let session: Value = serde_json::from_str(&session_json).unwrap_or(Value::Null);
    Ok(serde_json::json!({ "authenticated": true, "session": session }))
}

fn activate_parslee_session(
    state: &ServerState,
    session: crate::parslee_auth::ParsleeSession,
    api_base: String,
) {
    let email = session
        .identity
        .email
        .clone()
        .unwrap_or_else(|| "<unknown>".to_string());
    let org = session
        .identity
        .active_organization
        .clone()
        .unwrap_or_else(|| "<none>".to_string());
    let access_token = session.access_token.clone();
    if state.install_parslee_session(session).is_err() {
        return;
    }

    info!(
        email = %email,
        active_org = %org,
        "Parslee account auth activated for this CAR daemon"
    );
    let Some(runtime_url) = state.mobile_registration_url.get().cloned() else {
        return;
    };
    let token = state.auth_token.get().cloned();
    tokio::spawn(async move {
        let registration =
            crate::mobile_runtime::MobileRuntimeRegistration::new(runtime_url, token);
        match crate::mobile_runtime::register(&api_base, &access_token, &registration).await {
            Ok(()) => info!("registered this CAR machine for Parslee mobile discovery"),
            Err(error) => tracing::warn!(
                error = %error,
                "failed to register this CAR machine for Parslee mobile discovery; \
                 local Parslee Core runtime remains available"
            ),
        }
    });
}

async fn handle_auth_logout() -> Result<Value, String> {
    car_auth::logout().await?;
    Ok(serde_json::json!({ "ok": true }))
}

// --- openrouter.* : host-gated OAuth connection management (car#650) ---
//
// The OpenRouter OAuth credential is deliberately daemon-private: the generic
// secret surface fail-closes on it (`secret.put`/`delete` reject the reserved
// slot), so `openrouter.disconnect` is the ONLY path that can delete it. That
// made it the one unguarded door in an otherwise closed design — any
// authenticated local connection (a supervised agent, or any process that
// fetched the auth token from `GET /auth-token`) could log the user out of
// OpenRouter, or cancel the host's in-progress connect.
//
// All four are gated on the same trust root as every other config-mutation
// surface (`require_approval_authority`), including the read: `status` carries
// credential-presence and pending-flow metadata for whichever principal owns
// the connection, which is not another client's business.
//
// DEGRADED-MODE CAVEAT (inherited, not specific to this surface):
// `require_approval_authority` is a no-op when no host token is configured
// (pure-dev / `--no-auth`) — the connection governs itself, the developer being
// the authority. Identical to `permission.*` and `messaging.*`; not diverged
// from here.

// --- assistant.identity.* : the name the flagship agent answers to (car#1013) ---
//
// One record (`~/.car/identity.json`, via `car_identity`) feeds the system
// prompt, the voice wake gate, and every host's addressing copy. Before this,
// the same idea was four disagreeing string literals in three languages, and
// none of them was settable.
//
// The READ is deliberately ungated, unlike `openrouter.status` next door. A
// name is not a credential — it is what every connected surface has to render
// to address the assistant at all, and iPhone/Android hosts reach the daemon
// without approval authority. It also ships in the `server.handshake` reply, so
// gating the RPC would protect nothing while breaking mobile.
//
// The WRITE is gated on the same trust root as every other config mutation
// (`require_approval_authority`). A rename repoints the voice wake word: an
// ungated write would let any authenticated local connection make the
// assistant stop answering to the name its user knows.
//
// DEGRADED-MODE CAVEAT (inherited): `require_approval_authority` is a no-op
// when no host token is configured (pure-dev / `--no-auth`). Same as
// `permission.*`, `messaging.*`, and `openrouter.*`.

/// `assistant.identity.get` → `{ name, spellings, aliases, user_name, brand }`.
///
/// A malformed record is an ERROR here, not a silent fall back to the default
/// name — this is the surface a user checks when the assistant stopped
/// answering to the name they set, and "everything is fine, it's called
/// Parslee" is the least useful possible answer.
fn handle_assistant_identity_get() -> Result<Value, String> {
    let identity = car_identity::IdentityStore::from_home().load()?;
    Ok(assistant_identity_wire(&identity))
}

/// `assistant.identity.set` `{ name?, spellings?, user_name? }` → the new record.
///
/// Read-modify-write: every field is optional, so a host that only knows about
/// the name cannot wipe spellings a voice-settings pane wrote, and vice versa.
/// Broadcasts `host.event { kind: "assistant.identity.changed" }` so a live
/// rename reaches open sessions without a reconnect.
async fn handle_assistant_identity_set(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;

    let store = car_identity::IdentityStore::from_home();
    let mut identity = store.load()?;

    // `set_name` drops spellings that belonged to the OLD name; an explicit
    // `spellings` below then sets the new one's. Without that, renaming Jarvis
    // to Friday would leave it waking on "jervis".
    if let Some(name) = req.params.get("name").and_then(Value::as_str) {
        identity.set_name(name)?;
    }
    if let Some(Value::Array(items)) = req.params.get("spellings") {
        identity.spellings = car_identity::validate_spellings(
            items
                .iter()
                .filter_map(|v| v.as_str().map(str::to_string))
                .collect(),
        )?;
    }
    match req.params.get("user_name") {
        Some(Value::Null) => identity = identity.with_user_name(None)?,
        Some(Value::String(user)) => {
            identity = identity.with_user_name(Some(user.clone()))?;
        }
        _ => {}
    }
    identity.touch();
    store.save(&identity)?;

    let wire = assistant_identity_wire(&identity);
    session
        .host
        .record_event(
            "assistant.identity.changed",
            None,
            format!("the assistant now answers to {}", identity.name),
            wire.clone(),
        )
        .await;
    Ok(wire)
}

/// The wire shape shared by `assistant.identity.*` and `server.handshake`.
///
/// `aliases` is derived, not stored: hosts match against it locally (their wake
/// matchers must work before the daemon answers), and deriving it here is what
/// keeps Swift, Kotlin, and Rust from drifting into three different lists —
/// which is the exact failure this whole change exists to fix.
fn assistant_identity_wire(identity: &car_identity::AssistantIdentity) -> Value {
    serde_json::json!({
        "name": identity.name,
        "spellings": identity.spellings,
        "aliases": identity.aliases(),
        "user_name": identity.user_name,
        "brand": car_identity::BRAND_NAME,
        "updated_at_unix": identity.updated_at_unix,
    })
}

fn handle_openrouter_status(
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    serde_json::to_value(crate::openrouter_auth::status()).map_err(|e| e.to_string())
}

async fn handle_openrouter_auth_start(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    let authorization_base_url = opt_str(&req.params, "authorization_base_url");
    let exchange_url = opt_str(&req.params, "exchange_url");
    let timeout_seconds = req.params.get("timeout_seconds").and_then(Value::as_u64);
    let started =
        crate::openrouter_auth::start(authorization_base_url, exchange_url, timeout_seconds)
            .await?;
    serde_json::to_value(started).map_err(|e| e.to_string())
}

fn handle_openrouter_auth_cancel(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    let status = crate::openrouter_auth::cancel(opt_str(&req.params, "flow_id"));
    serde_json::to_value(status).map_err(|e| e.to_string())
}

async fn handle_openrouter_disconnect(
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    serde_json::to_value(crate::openrouter_auth::disconnect().await?).map_err(|e| e.to_string())
}

/// List every stored Parslee login (`active` marks the current one). Migrates a
/// pre-multi-login session into the registry on first call.
async fn handle_auth_accounts(req: &JsonRpcMessage) -> Result<Value, String> {
    let api_base = opt_str(&req.params, "api_base");
    let accounts = car_auth::list_accounts(api_base).await?;
    Ok(serde_json::json!({ "accounts": accounts }))
}

/// Switch which stored login is active (swaps the keychain token slots), then
/// returns the refreshed session for the newly-active login.
async fn handle_auth_switch_account(req: &JsonRpcMessage) -> Result<Value, String> {
    let account_id = req
        .params
        .get("account_id")
        .and_then(|v| v.as_str())
        .ok_or("invalid params: account_id is required")?;
    let api_base = opt_str(&req.params, "api_base");
    car_auth::switch_account(account_id).await?;
    // The swapped-in token may be near expiry; refresh before reporting.
    let _ = car_auth::access_token_refreshing().await;
    match car_auth::fetch_status(api_base).await? {
        Some(session_json) => {
            let session: Value = serde_json::from_str(&session_json).unwrap_or(Value::Null);
            Ok(serde_json::json!({ "authenticated": true, "session": session }))
        }
        None => Ok(serde_json::json!({ "authenticated": false })),
    }
}

/// Remove a stored login. If it was active, another remaining login becomes
/// active (or the session is cleared when none remain). Returns the new list.
async fn handle_auth_remove_account(req: &JsonRpcMessage) -> Result<Value, String> {
    let account_id = req
        .params
        .get("account_id")
        .and_then(|v| v.as_str())
        .ok_or("invalid params: account_id is required")?;
    let accounts = car_auth::remove_account(account_id).await?;
    Ok(serde_json::json!({ "ok": true, "accounts": accounts }))
}

/// Switch the signed-in account's active organization. Silent — mints a fresh
/// token scoped to `organization_id` via the refresh grant (the backend
/// validates membership), so inference immediately follows the new org.
/// Returns the refreshed session so the caller can render the new active org.
async fn handle_auth_switch_org(req: &JsonRpcMessage) -> Result<Value, String> {
    let org_id = req
        .params
        .get("organization_id")
        .and_then(|v| v.as_str())
        .ok_or("invalid params: organization_id is required")?;
    let api_base = opt_str(&req.params, "api_base");
    car_auth::switch_org(api_base, org_id).await?;
    match car_auth::fetch_status(api_base).await? {
        Some(session_json) => {
            let session: Value = serde_json::from_str(&session_json).unwrap_or(Value::Null);
            Ok(serde_json::json!({ "authenticated": true, "session": session }))
        }
        None => Ok(serde_json::json!({ "authenticated": false })),
    }
}

async fn handle_host_agents(
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    // Base: agents that explicitly registered into HostState (callback clients
    // via `host.register_agent`, multi-agent runners via `WsAgentRunner`).
    let mut agents = session.host.agents().await;

    // Merge: registry-supervised agents that ADVERTISE capabilities (e.g.
    // `car-assistant` with `["chat"]`). Those attach via `session.auth
    // { agent_id }`, which never registers into HostState, so their
    // `AgentSpec.capabilities` — present in `agents.list` — were invisible to
    // `host.agents` (issue #483). We read them from the supervisor at request
    // time rather than registering on attach: it's self-correcting (reflects
    // live supervisor status, can't leak a stale record across a disconnect the
    // attach path doesn't clean up). Scoped to capability-bearing agents so the
    // existing `host.agents` contents are unchanged for the common case. An
    // explicit HostState registration for the same id wins (skip on dup).
    if let Ok(supervisor) = state.supervisor() {
        use car_registry::supervisor::AgentStatus;
        let have: std::collections::HashSet<String> = agents.iter().map(|a| a.id.clone()).collect();
        for m in supervisor.list().await {
            if m.spec.capabilities.is_empty() || have.contains(&m.spec.id) {
                continue;
            }
            let status = match m.status {
                AgentStatus::Running => car_proto::HostAgentStatus::Running,
                AgentStatus::Starting => car_proto::HostAgentStatus::Idle,
                AgentStatus::Backoff | AgentStatus::Errored => car_proto::HostAgentStatus::Errored,
                AgentStatus::Stopped => car_proto::HostAgentStatus::Stopped,
            };
            agents.push(car_proto::HostAgent {
                id: m.spec.id.clone(),
                name: m.spec.name.clone(),
                kind: "supervised".to_string(),
                capabilities: m.spec.capabilities.clone(),
                project: None,
                session_id: None,
                status,
                current_task: None,
                pid: m.pid,
                display: Default::default(),
                updated_at: chrono::Utc::now(),
                metadata: Value::Null,
            });
        }
    }

    serde_json::to_value(agents).map_err(|e| e.to_string())
}

async fn handle_host_events(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let limit = req
        .params
        .get("limit")
        .and_then(|v| v.as_u64())
        .unwrap_or(100) as usize;
    serde_json::to_value(session.host.events(limit).await).map_err(|e| e.to_string())
}

async fn handle_host_approvals(session: &crate::session::ClientSession) -> Result<Value, String> {
    serde_json::to_value(session.host.approvals().await).map_err(|e| e.to_string())
}

async fn handle_a2ui_apply(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    #[derive(Deserialize)]
    struct Params {
        #[serde(default)]
        envelope: Option<car_a2ui::A2uiEnvelope>,
        #[serde(default)]
        message: Option<car_a2ui::A2uiEnvelope>,
    }

    let envelope = if req.params.get("createSurface").is_some()
        || req.params.get("updateComponents").is_some()
        || req.params.get("updateDataModel").is_some()
        || req.params.get("deleteSurface").is_some()
    {
        serde_json::from_value::<car_a2ui::A2uiEnvelope>(req.params.clone())
            .map_err(|e| e.to_string())?
    } else {
        match serde_json::from_value::<Params>(req.params.clone()) {
            Ok(params) => params
                .envelope
                .or(params.message)
                .ok_or_else(|| "`a2ui.apply` requires an A2UI envelope".to_string())?,
            Err(_) => serde_json::from_value::<car_a2ui::A2uiEnvelope>(req.params.clone())
                .map_err(|e| e.to_string())?,
        }
    };

    apply_a2ui_envelope(state, envelope, None, None).await
}

async fn handle_a2ui_ingest(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    #[derive(Deserialize)]
    #[serde(rename_all = "camelCase")]
    struct Params {
        #[serde(default)]
        endpoint: Option<String>,
        #[serde(default)]
        a2a_endpoint: Option<String>,
        #[serde(default)]
        owner: Option<car_a2ui::A2uiSurfaceOwner>,
        #[serde(default)]
        route_auth: Option<A2aRouteAuth>,
        #[serde(default)]
        allow_untrusted_endpoint: bool,
    }

    let params = serde_json::from_value::<Params>(req.params.clone()).unwrap_or(Params {
        endpoint: None,
        a2a_endpoint: None,
        owner: None,
        route_auth: None,
        allow_untrusted_endpoint: false,
    });
    let payload = req.params.get("payload").unwrap_or(&req.params);
    state
        .a2ui
        .validate_payload(payload)
        .map_err(|e| e.to_string())?;
    let envelopes = car_a2ui::envelopes_from_value(payload).map_err(|e| e.to_string())?;
    if envelopes.is_empty() {
        return Err("no A2UI envelopes found in payload".into());
    }
    let endpoint = params.endpoint.or(params.a2a_endpoint);
    let endpoint = trusted_route_endpoint(endpoint, params.allow_untrusted_endpoint);
    let owner = params
        .owner
        .or_else(|| car_a2ui::owner_from_value(payload))
        .map(|owner| match endpoint.clone() {
            Some(endpoint) => owner.with_endpoint(Some(endpoint)),
            None => owner,
        });

    let mut results = Vec::new();
    for envelope in envelopes {
        let value =
            apply_a2ui_envelope(state, envelope, owner.clone(), params.route_auth.clone()).await?;
        results.push(value);
    }
    Ok(serde_json::json!({ "applied": results }))
}

async fn apply_a2ui_envelope(
    state: &Arc<ServerState>,
    envelope: car_a2ui::A2uiEnvelope,
    owner: Option<car_a2ui::A2uiSurfaceOwner>,
    route_auth: Option<A2aRouteAuth>,
) -> Result<Value, String> {
    let result = state
        .a2ui
        .apply_with_owner(envelope, owner)
        .await
        .map_err(|e| e.to_string())?;
    update_a2ui_route_auth(state, &result, route_auth).await;
    let kind = if result.deleted {
        "a2ui.surface_deleted"
    } else {
        "a2ui.surface_updated"
    };
    let message = if result.deleted {
        format!("A2UI surface {} deleted", result.surface_id)
    } else {
        format!("A2UI surface {} updated", result.surface_id)
    };
    let payload = serde_json::to_value(&result).map_err(|e| e.to_string())?;
    state
        .host
        .record_event(kind, None, message, payload.clone())
        .await;
    // Push the envelope result to every WS subscriber as an
    // `a2ui.event` notification — Parslee-ai/car-releases#29. Late
    // joiners catch up via `a2ui/replay` (or `a2ui.surfaces`).
    broadcast_a2ui_event(state, kind, &payload).await;
    serde_json::to_value(result).map_err(|e| e.to_string())
}

async fn broadcast_a2ui_event(state: &Arc<ServerState>, kind: &str, result: &Value) {
    use futures::SinkExt;
    use tokio_tungstenite::tungstenite::Message;
    let subscribers: Vec<Arc<crate::session::WsChannel>> = state
        .a2ui_subscribers
        .lock()
        .await
        .values()
        .cloned()
        .collect();
    if subscribers.is_empty() {
        return;
    }
    let Ok(json) = serde_json::to_string(&serde_json::json!({
        "jsonrpc": "2.0",
        "method": "a2ui.event",
        "params": {
            "kind": kind,
            "result": result,
        },
    })) else {
        return;
    };
    for channel in subscribers {
        let _ = channel
            .write
            .lock()
            .await
            .send(Message::Text(json.clone().into()))
            .await;
    }
}

async fn update_a2ui_route_auth(
    state: &Arc<ServerState>,
    result: &car_a2ui::A2uiApplyResult,
    route_auth: Option<A2aRouteAuth>,
) {
    let mut auth = state.a2ui_route_auth.lock().await;
    if result.deleted {
        auth.remove(&result.surface_id);
        return;
    }

    let has_route_endpoint = result
        .surface
        .as_ref()
        .and_then(|surface| surface.owner.as_ref())
        .and_then(|owner| owner.endpoint.as_ref())
        .is_some();
    match (has_route_endpoint, route_auth) {
        (true, Some(route_auth)) => {
            auth.insert(result.surface_id.clone(), route_auth);
        }
        _ => {
            auth.remove(&result.surface_id);
        }
    }
}

fn handle_a2ui_capabilities(state: &Arc<ServerState>) -> Result<Value, String> {
    serde_json::to_value(state.a2ui.capabilities()).map_err(|e| e.to_string())
}

async fn handle_a2ui_reap(state: &Arc<ServerState>) -> Result<Value, String> {
    let removed = state.a2ui.reap_expired(chrono::Utc::now()).await;
    if !removed.is_empty() {
        let mut auth = state.a2ui_route_auth.lock().await;
        for surface_id in &removed {
            auth.remove(surface_id);
        }
    }
    Ok(serde_json::json!({ "removed": removed }))
}

async fn handle_a2ui_surfaces(state: &Arc<ServerState>) -> Result<Value, String> {
    serde_json::to_value(state.a2ui.list().await).map_err(|e| e.to_string())
}

async fn handle_a2ui_get(req: &JsonRpcMessage, state: &Arc<ServerState>) -> Result<Value, String> {
    let surface_id = req
        .params
        .get("surface_id")
        .or_else(|| req.params.get("surfaceId"))
        .and_then(Value::as_str)
        .ok_or_else(|| "`a2ui.get` requires surface_id".to_string())?;
    serde_json::to_value(state.a2ui.get(surface_id).await).map_err(|e| e.to_string())
}

/// `a2ui/subscribe` — opt this WS connection into `a2ui.event`
/// notifications. Subscribers receive every `apply_a2ui_envelope`
/// result for as long as they're connected; the cleanup hook in
/// `run_dispatch` removes them on disconnect. Closes
/// Parslee-ai/car-releases#29.
async fn handle_a2ui_subscribe(
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    state
        .a2ui_subscribers
        .lock()
        .await
        .insert(session.client_id.clone(), session.channel.clone());
    Ok(serde_json::json!({ "subscribed": true }))
}

/// `a2ui/unsubscribe` — opt out of `a2ui.event` notifications.
/// Idempotent: returns `{ subscribed: false }` regardless of prior
/// state.
async fn handle_a2ui_unsubscribe(
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    state
        .a2ui_subscribers
        .lock()
        .await
        .remove(&session.client_id);
    Ok(serde_json::json!({ "subscribed": false }))
}

/// `a2ui/replay` — fetch the current state of one surface. Intended
/// for late joiners and reconnect: a client calls `subscribe`, then
/// `replay` once per surface it's tracking, and from then on
/// notifications keep it in sync. Equivalent to `a2ui.get` on the
/// surface store; lives in the subscribe namespace for
/// discoverability.
async fn handle_a2ui_replay(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let surface_id = req
        .params
        .get("surface_id")
        .or_else(|| req.params.get("surfaceId"))
        .and_then(Value::as_str)
        .ok_or_else(|| "`a2ui/replay` requires surface_id".to_string())?;
    serde_json::to_value(state.a2ui.get(surface_id).await).map_err(|e| e.to_string())
}

async fn handle_a2ui_action(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let action: car_a2ui::ClientAction =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let owner = state.a2ui.owner(&action.surface_id).await;

    // Deliver the interaction to A2UI subscribers on the same channel that
    // carries surface updates — Parslee-ai/car-releases#58. The owning agent
    // listens for `a2ui.event` (that's how it gets `surface_updated`); before
    // this it saw nothing on click, so its surfaces were display-only.
    // Broadcast BEFORE the A2A route below: the local notification must not be
    // gated behind a (possibly slow) outbound A2A round-trip, and `route` is
    // deliberately excluded so an A2A endpoint URL/response isn't fanned out to
    // unrelated subscribers — it stays in the `host.event` record and the RPC
    // return for the privileged consumers that already see it.
    let action_result = serde_json::json!({
        "surfaceId": action.surface_id,
        "action": action,
        "owner": owner,
    });
    broadcast_a2ui_event(state, "a2ui.action", &action_result).await;

    let route = route_a2ui_action(state, &action, owner.clone()).await;
    let payload = serde_json::json!({
        "action": action,
        "owner": owner,
        "route": route,
    });
    let event = state
        .host
        .record_event(
            "a2ui.action",
            None,
            format!(
                "A2UI action {} from {}",
                action.name, action.source_component_id
            ),
            payload,
        )
        .await;
    Ok(serde_json::json!({
        "event": event,
        "route": route,
    }))
}

/// `a2ui.render_report` — renderer-emitted telemetry envelope
/// (Parslee-ai/car#180). Fire-and-forget; we record an event in
/// the host log (so dev tools and the conversation log see it) and
/// broadcast as `a2ui.event { kind: "a2ui.render_report", result }`
/// to every WS subscriber. The improvement agent reads the report
/// and decides whether to issue a follow-up `patchComponents`.
async fn handle_a2ui_render_report(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    // Parse into the typed struct to enforce the schema; we
    // re-serialize for the event/broadcast payload so downstream
    // consumers don't have to defensively re-validate.
    let report: car_a2ui::RenderReport =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let payload = serde_json::to_value(&report).map_err(|e| e.to_string())?;
    let kind = "a2ui.render_report";
    let message = format!("A2UI render report for surface {}", report.surface_id);
    let event = state
        .host
        .record_event(kind, None, message, payload.clone())
        .await;
    broadcast_a2ui_event(state, kind, &payload).await;

    // Hand the report to the in-process UI-improvement agent. The
    // agent is sync but cheap; we await the surface lookup before
    // calling it so the strategies see the same surface state the
    // renderer saw at report-emit time. Best-effort: surface lookup
    // misses (the surface might have been deleted between
    // report-emit and report-receive) are logged and skipped, never
    // surfaced as JSON-RPC errors — render_report is fire-and-forget.
    if let Some(surface) = state.a2ui.get(&report.surface_id).await {
        // Iteration budget — runaway-loop backstop. try_consume
        // claims the slot atomically; if the surface is already at
        // the cap, we short-circuit before consulting the agent.
        // The slot stays consumed only if the patch actually
        // applies — failure paths refund.
        if !state.ui_agent_budget.try_consume(&report.surface_id) {
            tracing::warn!(
                surface_id = %report.surface_id,
                count = state.ui_agent_budget.count(&report.surface_id),
                max = state.ui_agent_budget.max(),
                "ui-agent iteration budget exhausted; skipping agent invocation"
            );
            return Ok(serde_json::json!({ "event": event }));
        }
        // From here on, every non-applied branch must `refund` the
        // slot we just claimed. Only the successful-apply branch
        // keeps it consumed.
        match state.ui_agent.on_render_report(&report, &surface) {
            car_ui_agent::Decision::Patch {
                envelope,
                strategy_id,
                patch_hash,
                elapsed_ns,
            } => {
                // Runtime-side convergence monitor — neo's deferred
                // ask. The agent's no-double-patch guard catches
                // same-sequence repeats; this catches A→B→A across
                // sequences by tracking recent patch hashes per
                // surface. When a proposal would repeat one in the
                // window, drop it; the loop waits for the next
                // signature change.
                if !state
                    .ui_agent_oscillation
                    .check_and_record(&report.surface_id, patch_hash)
                {
                    tracing::warn!(
                        surface_id = %report.surface_id,
                        strategy = %strategy_id,
                        patch_hash,
                        "ui-agent oscillation detected; suppressing patch"
                    );
                    // Suppressed patch never applied → release the
                    // budget slot we claimed above.
                    state.ui_agent_budget.refund(&report.surface_id);
                    return Ok(serde_json::json!({ "event": event }));
                }
                let a2ui_envelope = car_a2ui::A2uiEnvelope {
                    patch_components: Some(envelope),
                    ..Default::default()
                };
                if let Err(e) = apply_a2ui_envelope(state, a2ui_envelope, None, None).await {
                    tracing::warn!(
                        surface_id = %report.surface_id,
                        strategy = %strategy_id,
                        patch_hash,
                        elapsed_ns,
                        error = %e,
                        "ui-agent patch apply failed",
                    );
                    // Apply failed → release the budget slot.
                    state.ui_agent_budget.refund(&report.surface_id);
                } else {
                    tracing::debug!(
                        surface_id = %report.surface_id,
                        strategy = %strategy_id,
                        patch_hash,
                        elapsed_ns,
                        iteration = state.ui_agent_budget.count(&report.surface_id),
                        "ui-agent patch applied",
                    );
                    // Memgine trace: one Conversation node per
                    // successful patch, tagged "ui-agent/<surface>".
                    // Spreading activation can surface these on
                    // future renders of related surfaces. Spawned
                    // off the render-report hot path — ingest walks
                    // the graph for spreading activation and can
                    // take real time; we don't want two surfaces
                    // churning patches to serialize through the
                    // memgine mutex behind the WS handler.
                    if let Some(memgine) = state.shared_memgine.clone() {
                        let speaker = format!("ui-agent/{}", report.surface_id);
                        let text = format!("strategy applied: {}", strategy_id);
                        tokio::spawn(async move {
                            let mut guard = memgine.lock().await;
                            guard.ingest_conversation(&speaker, &text, chrono::Utc::now());
                        });
                    }
                }
            }
            car_ui_agent::Decision::StableNoChange => {
                // No patch this round → release the slot.
                state.ui_agent_budget.refund(&report.surface_id);
            }
            car_ui_agent::Decision::HardStop { reason } => {
                state.ui_agent_budget.refund(&report.surface_id);
                // Renderer painted unknown components — contract
                // violation between server and renderer. Per
                // types.rs docs: "loud failure" + "MUST pause."
                // `error!` not `warn!` so it surfaces in production
                // logs at the right severity.
                tracing::error!(
                    surface_id = %report.surface_id,
                    reason = %reason,
                    "ui-agent hard-stopped improvement loop",
                );
            }
        }
    } else {
        tracing::debug!(
            surface_id = %report.surface_id,
            "ui-agent skipped — surface not found in store",
        );
    }

    Ok(serde_json::json!({ "event": event }))
}

async fn route_a2ui_action(
    state: &Arc<ServerState>,
    action: &car_a2ui::ClientAction,
    owner: Option<car_a2ui::A2uiSurfaceOwner>,
) -> Value {
    let Some(owner) = owner else {
        return serde_json::json!({ "delivered": false, "reason": "surface has no owner" });
    };
    if owner.kind != "a2a" {
        return serde_json::json!({ "delivered": false, "reason": "unsupported owner kind", "owner": owner });
    }
    let Some(endpoint) = owner.endpoint.clone() else {
        return serde_json::json!({
            "delivered": false,
            "reason": "surface owner has no endpoint",
            "owner": owner
        });
    };

    let message = car_a2a::Message {
        message_id: format!("a2ui-action-{}", uuid::Uuid::new_v4().simple()),
        role: car_a2a::MessageRole::User,
        parts: vec![car_a2a::Part::Data(car_a2a::types::DataPart {
            data: serde_json::json!({
                "a2uiAction": action,
            }),
            metadata: Default::default(),
        })],
        task_id: owner.task_id.clone(),
        context_id: owner.context_id.clone(),
        metadata: Default::default(),
    };

    let auth = state
        .a2ui_route_auth
        .lock()
        .await
        .get(&action.surface_id)
        .cloned()
        .map(client_auth_from_route_auth)
        .unwrap_or(car_a2a::ClientAuth::None);

    match car_a2a::A2aClient::new(endpoint.clone())
        .with_auth(auth)
        .send_message(message, false)
        .await
    {
        Ok(result) => serde_json::json!({
            "delivered": true,
            "owner": owner,
            "endpoint": endpoint,
            "result": result,
        }),
        Err(error) => serde_json::json!({
            "delivered": false,
            "owner": owner,
            "endpoint": endpoint,
            "error": error.to_string(),
        }),
    }
}

fn client_auth_from_route_auth(auth: A2aRouteAuth) -> car_a2a::ClientAuth {
    match auth {
        A2aRouteAuth::None => car_a2a::ClientAuth::None,
        A2aRouteAuth::Bearer { token } => car_a2a::ClientAuth::Bearer(token),
        A2aRouteAuth::Header { name, value } => car_a2a::ClientAuth::Header { name, value },
    }
}

fn trusted_route_endpoint(endpoint: Option<String>, allow_untrusted: bool) -> Option<String> {
    let endpoint = endpoint?;
    if allow_untrusted || is_loopback_http_endpoint(&endpoint) {
        Some(endpoint)
    } else {
        None
    }
}

fn is_loopback_http_endpoint(endpoint: &str) -> bool {
    endpoint == "http://localhost"
        || endpoint.starts_with("http://localhost:")
        || endpoint.starts_with("http://localhost/")
        || endpoint == "http://127.0.0.1"
        || endpoint.starts_with("http://127.0.0.1:")
        || endpoint.starts_with("http://127.0.0.1/")
        || endpoint == "http://[::1]"
        || endpoint.starts_with("http://[::1]:")
        || endpoint.starts_with("http://[::1]/")
}

async fn handle_host_register_agent(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let request: RegisterHostAgentRequest =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    serde_json::to_value(
        session
            .host
            .register_agent(&session.client_id, request)
            .await?,
    )
    .map_err(|e| e.to_string())
}

async fn handle_host_unregister_agent(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let agent_id = req
        .params
        .get("agent_id")
        .and_then(|v| v.as_str())
        .ok_or("missing agent_id")?;
    session
        .host
        .unregister_agent(&session.client_id, agent_id)
        .await?;
    Ok(serde_json::json!({"ok": true}))
}

async fn handle_host_set_status(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let request: SetHostAgentStatusRequest =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    serde_json::to_value(session.host.set_status(&session.client_id, request).await?)
        .map_err(|e| e.to_string())
}

async fn handle_host_register_device(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let request: RegisterHostDeviceRequest =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    serde_json::to_value(
        session
            .host
            .register_device(&session.client_id, request)
            .await?,
    )
    .map_err(|e| e.to_string())
}

async fn handle_host_update_device(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let request: UpdateHostDeviceRequest =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    serde_json::to_value(
        session
            .host
            .update_device(&session.client_id, request)
            .await?,
    )
    .map_err(|e| e.to_string())
}

async fn handle_host_devices(session: &crate::session::ClientSession) -> Result<Value, String> {
    serde_json::to_value(session.host.devices().await).map_err(|e| e.to_string())
}

async fn handle_mobile_runtime(state: &Arc<ServerState>) -> Result<Value, String> {
    let url = state
        .mobile_runtime_url
        .get()
        .cloned()
        .ok_or_else(|| "mobile Parslee Core connection is not configured".to_string())?;
    let token = state.auth_token.get().cloned();
    Ok(serde_json::json!({
        "name": "Parslee Core",
        "source": "car",
        "url": url,
        "token": token,
    }))
}

async fn handle_host_notify(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let kind = req
        .params
        .get("kind")
        .and_then(|v| v.as_str())
        .unwrap_or("host.notification");
    let agent_id = req
        .params
        .get("agent_id")
        .and_then(|v| v.as_str())
        .map(str::to_string);
    let message = req
        .params
        .get("message")
        .and_then(|v| v.as_str())
        .unwrap_or("");
    let payload = req.params.get("payload").cloned().unwrap_or(Value::Null);
    serde_json::to_value(
        session
            .host
            .record_event(kind, agent_id, message, payload)
            .await,
    )
    .map_err(|e| e.to_string())
}

async fn handle_host_request_approval(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let mut request: CreateHostApprovalRequest =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    // Stamp the requester from the session's AUTHENTICATED agent binding rather
    // than trusting the caller's claim — the same stance
    // `handle_permission_decision` takes for `reviewer` ("an audit log whose
    // 'who approved' is forgeable by the approver undercuts §5.2.5"). The
    // binding is not self-declared: `session.auth` validates `agent_id` against
    // the per-agent token the supervisor minted before setting it.
    //
    // Without this the row's `agent_id` was whatever the requester typed, so it
    // was neither an audit record nor usable as the requester half of the
    // requester-vs-resolver comparison in `car_server_types::host::Resolver`.
    request.agent_id = stamped_requester(
        authenticated_bound_agent_id(session).await,
        request.agent_id.take(),
    );
    if let Some(agent_id) = &request.agent_id {
        // Best-effort. If the caller doesn't own this agent the
        // ACL added 2026-05 will refuse the status update — that
        // is the correct semantics; we still want the approval row
        // itself to land so the UI can render the request.
        let _ = session
            .host
            .set_status(
                &session.client_id,
                SetHostAgentStatusRequest {
                    agent_id: agent_id.clone(),
                    status: HostAgentStatus::WaitingForApproval,
                    current_task: None,
                    message: Some("Waiting for approval".to_string()),
                    payload: Value::Null,
                },
            )
            .await;
    }
    // `system_level: true` opts the approval out of per-session
    // ownership. The host-side ACL then allows any authenticated
    // session (typically CarHost or `car-host approve`) to resolve.
    // Agents requesting user approval should always set this — the
    // session-owned mode is only correct when the requesting session
    // is also the resolving session, which approval-via-UI never is.
    let owner_client_id = if request.system_level {
        None
    } else {
        Some(session.client_id.as_str())
    };
    serde_json::to_value(
        session
            .host
            .create_approval(owner_client_id, request)
            .await?,
    )
    .map_err(|e| e.to_string())
}

async fn handle_host_resolve_approval(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let request: ResolveHostApprovalRequest =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    // The agent identity only counts when the session is authenticated AND
    // bound to one — an unauthenticated claim must not launder itself into an
    // identity the self-resolution check would then trust.
    let bound_agent = authenticated_bound_agent_id(session).await;
    let resolver =
        car_server_types::host::Resolver::agent_session(&session.client_id, bound_agent.as_deref());
    serde_json::to_value(session.host.resolve_approval(resolver, request).await?)
        .map_err(|e| e.to_string())
}

/// Method-not-found-class denial for a method absent from a supervised-agent
/// token's scope. The stable message prefix is the named authorization error;
/// callers can distinguish it from the ordinary `unknown method: ...` response
/// while receiving the same non-disclosure-oriented JSON-RPC class.
const AGENT_METHOD_NOT_ALLOWED_ERROR_CODE: i32 = -32601;
const AGENT_METHOD_NOT_ALLOWED_MESSAGE_PREFIX: &str =
    "agent_method_not_allowed: supervised agent token does not allow daemon method ";

/// Transport-establishment calls are necessarily implicit: the daemon cannot
/// know a token's scope until `session.auth` succeeds, and a client must be able
/// to negotiate the protocol before invoking its first scoped application
/// method. Every other request/notification is checked at the dispatch boundary.
fn agent_method_scope_allows(session: &crate::session::ClientSession, method: &str) -> bool {
    if matches!(method, "session.auth" | "server.handshake")
        || session.is_host.load(std::sync::atomic::Ordering::Acquire)
    {
        return true;
    }
    match session.agent_method_allowlist.read() {
        Ok(scope) => scope
            .as_ref()
            .is_none_or(|methods| methods.contains(method)),
        // Poisoning means a prior scope write panicked. Failing closed is the
        // only safe interpretation for a bound credential.
        Err(_) => false,
    }
}

/// `session.auth` — present the per-launch token to unlock the
/// connection. When `state.auth_token` is unset, this method is a
/// no-op success (auth is disabled). When set, the supplied token
/// must equal it (constant-time comparison) — a successful auth
/// flips `session.authenticated` to `true` so subsequent methods
/// pass the gate. Wrong token returns an error AND leaves the
/// session unauthenticated; the dispatcher loop's gate then closes
/// the connection on the next non-auth method.
///
/// Closes Parslee-ai/car-releases#32.
async fn handle_session_auth(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    // C-4: optional `tenant_id` binds the connection to one tenant
    // namespace. Parsed + validated up front, bound only on auth
    // success. Once bound, tenant-scoped handlers use this identity
    // and reject a conflicting per-request `tenant_id`.
    let tenant_binding = match req.params.get("tenant_id").and_then(Value::as_str) {
        Some(t) if !t.is_empty() => {
            validate_tenant_id(t)?;
            Some(t.to_string())
        }
        _ => None,
    };

    // car-releases#79: an optional host-declared memory namespace. A SEPARATE
    // axis from `agent_id` — one agent may span namespaces, and two hosts may
    // share a namespace without sharing an identity — so it binds its own
    // engine from its own registry. Absent, the session keeps the daemon's
    // shared graph, which is what makes MCP-ingested facts visible over WS.
    //
    // Read BEFORE the host-token branch: that branch returns early, and a host
    // client is exactly the caller that wants per-project memory.
    let memory_namespace = req
        .params
        .get("memory_namespace")
        .and_then(Value::as_str)
        .filter(|s| !s.trim().is_empty())
        .map(str::to_string);

    // #254: optional `host_token` elevates the connection to the
    // host-management role. It is a *distinct* credential from the
    // daemon `token` — only readable from the `0600` host-token file,
    // never served over `GET /auth-token` — so a generic authenticated
    // client (or another local user who scraped the auth token via the
    // HTTP endpoint) cannot self-elevate to host and read other agents'
    // run traces. Validated first, before the `token` requirement,
    // because presenting a valid host token both authenticates and
    // elevates the session (a host client sends only `host_token`).
    if let Some(host_supplied) = req.params.get("host_token").and_then(Value::as_str) {
        let expected = state.host_token.get().ok_or_else(|| {
            "host auth unavailable: this daemon has no host token (started with --no-auth?)"
                .to_string()
        })?;
        if !constant_time_eq(host_supplied.as_bytes(), expected.as_bytes()) {
            return Err("auth failed: host token mismatch".to_string());
        }
        session
            .authenticated
            .store(true, std::sync::atomic::Ordering::Release);
        session
            .is_host
            .store(true, std::sync::atomic::Ordering::Release);
        // A host just appeared. Supervised agent processes cache this answer
        // — they have no read of the daemon's session set — and it decides
        // whether `browser_await_signin` points at the drawer or tells the
        // user to open the CAR app. Push the transition rather than leaving
        // them to find out at their next registration.
        state.browser_views.broadcast_host_connected(true).await;
        *session.tenant.lock().await = tenant_binding;
        if let Some(ns) = memory_namespace.as_deref() {
            bind_memory_namespace(state, session, ns).await?;
        }
        return Ok(serde_json::json!({
            "ok": true,
            "auth_enabled": true,
            "role": "host",
            "memory_namespace": memory_namespace,
        }));
    }

    let supplied = req
        .params
        .get("token")
        .and_then(Value::as_str)
        .ok_or_else(|| "session.auth requires { token: string }".to_string())?;
    // #169: optional `agent_id` binds the WS connection to a
    // supervised lifecycle agent. When present, the supplied token
    // must equal the per-agent token the supervisor minted at upsert
    // (NOT the daemon-wide auth token). When absent, fall back to
    // the daemon-wide token — preserves the legacy unbound-token
    // path for browser/host/CLI clients.
    let agent_id = req
        .params
        .get("agent_id")
        .and_then(Value::as_str)
        .map(str::to_string);

    if let Some(id) = agent_id {
        let supervisor = state.supervisor()?;
        let binding = supervisor
            .authenticate_agent_token(&id, supplied)
            .await
            .map_err(|error| format!("auth failed for agent_id `{id}`: {error}"))?
            .ok_or_else(|| {
                format!("auth failed: agent_id `{id}` is not supervised, or token mismatch")
            })?;
        // Bind the token's method scope before publishing the agent identity.
        // On an auth-enabled daemon the read-loop auth gate also serializes
        // this handshake; the ordering closes the dominant auth-disabled
        // pipelining window in the same way the identity-first ordering below
        // closes the sandbox-bind window.
        *session
            .agent_method_allowlist
            .write()
            .map_err(|_| "auth failed: agent method allowlist lock poisoned".to_string())? =
            binding
                .method_allowlist
                .clone()
                .map(|methods| methods.into_iter().collect());
        // Commit the bound agent identity FIRST, before the attached-agents
        // lock and the (disk-I/O) memgine load below (Parslee-ai/car#480 review).
        // Frames on one connection are dispatched concurrently, so on an
        // auth-DISABLED daemon a pipelined `session.bindSandbox` could otherwise
        // race this handler and observe `agent_id == None` during that I/O
        // window, escaping its supervised-agent gate. (On an auth-token daemon —
        // the deployment that cares about confinement — the read-loop auth gate
        // already serializes the handshake, so the gate is sound by
        // construction; this ordering closes the dominant auth-disabled window
        // too.)
        *session.agent_id.lock().await = Some(id.clone());
        // Single-claim: only one connection at a time per
        // agent_id. A second claim is rejected so the daemon-side
        // per-agent state stays unambiguous.
        {
            let mut attached = state.attached_agents.lock().await;
            if let Some(prior) = attached.get(&id) {
                if prior != &session.client_id {
                    // Supersede a stale claim rather than reject it. The
                    // supervisor runs a single instance per `agent_id`, and this
                    // connection just passed `validate_agent_token`, so a fresh
                    // valid attach is authoritative — it's the live process.
                    //
                    // Why this matters (Parslee-ai/car Windows bring-up): when a
                    // supervised agent is hard-killed and respawned, the dead
                    // process's socket can linger half-open (no FIN on a
                    // TerminateProcess), so the disconnect teardown that frees
                    // this claim (session.rs) hasn't run yet. The old
                    // reject-on-conflict then failed EVERY respawn with
                    // "already attached", and the agent flapped forever
                    // (running→errored→backoff), so no chat turn could route.
                    // Last-valid-attach-wins is exactly what the teardown code's
                    // own comment intends ("supervisor-respawned replacement can
                    // take the slot"); this makes it robust to delayed teardown.
                    tracing::warn!(
                        agent_id = %id,
                        prior_client = %prior,
                        new_client = %session.client_id,
                        "superseding stale agent attach claim (respawn took over)"
                    );
                }
            }
            attached.insert(id.clone(), session.client_id.clone());
        }
        // #170: attach the daemon-owned persistent memgine for
        // this agent. Lazy-loaded on first connection per id from
        // `~/.car/memory/agents/<id>.jsonl`; retained across
        // disconnect so the next session sees the same state.
        let agent_eng = get_or_load_agent_memgine(state, &id).await?;
        // An explicit namespace wins for the memory scope: it is the more
        // specific request, and it is what a single agent working across two
        // projects needs. The agent binding still governs identity, tokens and
        // the attach claim above — only the graph differs.
        let bound = match memory_namespace.as_deref() {
            Some(ns) => {
                // Record the namespace here too — this path binds the graph
                // directly rather than through bind_memory_namespace, because
                // it falls back to the agent engine when no namespace is given.
                *session.memory_namespace.lock().await = Some(ns.to_string());
                get_or_load_namespace_memgine(state, ns).await?
            }
            None => agent_eng,
        };
        *session.bound_memgine.lock().await = Some(bound);
        session
            .authenticated
            .store(true, std::sync::atomic::Ordering::Release);
        *session.tenant.lock().await = tenant_binding;
        let mut response = serde_json::json!({
            "ok": true,
            "auth_enabled": true,
            "agent_id": id,
        });
        if let Some(methods) = binding.method_allowlist {
            response["method_allowlist"] = serde_json::json!(methods);
        }
        return Ok(response);
    }

    let expected = match state.auth_token.get() {
        Some(t) => t,
        None => {
            // Auth disabled — accept any token politely so callers
            // that always include a session.auth handshake (e.g. the
            // FFI proxy) don't fail when the daemon happens to be
            // unauthed. Mark the session authenticated anyway so the
            // gate is a no-op below.
            if let Some(ns) = memory_namespace.as_deref() {
                bind_memory_namespace(state, session, ns).await?;
            }
            session
                .authenticated
                .store(true, std::sync::atomic::Ordering::Release);
            *session.tenant.lock().await = tenant_binding;
            return Ok(serde_json::json!({
                "ok": true,
                "auth_enabled": false,
                "memory_namespace": memory_namespace,
            }));
        }
    };
    if !constant_time_eq(supplied.as_bytes(), expected.as_bytes()) {
        return Err("auth failed: token mismatch".to_string());
    }
    if let Some(ns) = memory_namespace.as_deref() {
        bind_memory_namespace(state, session, ns).await?;
    }
    session
        .authenticated
        .store(true, std::sync::atomic::Ordering::Release);
    *session.tenant.lock().await = tenant_binding;
    Ok(serde_json::json!({
        "ok": true,
        "auth_enabled": true,
        "memory_namespace": memory_namespace,
        "parslee": state.parslee_session.get().map(|session| session.identity.clone()),
    }))
}

/// Length-checked constant-time byte comparison. Returns false when
/// lengths differ (so length itself is the only timing leak — fine
/// for our 43-char fixed-length tokens).
fn constant_time_eq(a: &[u8], b: &[u8]) -> bool {
    if a.len() != b.len() {
        return false;
    }
    let mut diff: u8 = 0;
    for (x, y) in a.iter().zip(b.iter()) {
        diff |= x ^ y;
    }
    diff == 0
}

/// Block dispatch of `method` until the user resolves the approval
/// raised on [`HostState`].
///
/// Called from the dispatcher loop only when
/// [`crate::session::ApprovalGate::requires_approval`] returns true.
/// `Ok(())` means the user picked "approve"; `Err(reason)` is sent
/// to the caller as JSON-RPC error code `-32003` with the supplied
/// reason. On timeout, the approval row stays in `Pending` so the
/// UI keeps a record of the unanswered request.
async fn gate_high_risk_method(
    method: &str,
    params: &Value,
    state: &Arc<ServerState>,
) -> Result<(), String> {
    let timeout = state.approval_gate.timeout;
    let req = CreateHostApprovalRequest {
        agent_id: None,
        action: format!("ws.method:{method}"),
        details: serde_json::json!({
            "method": method,
            // Truncate params for the UI — full payload is recoverable
            // via the request-time host event log if needed. The cap
            // keeps a malicious caller from drowning the UI in JSON.
            "params_preview": preview_params(params, 2_000),
        }),
        options: vec!["approve".to_string(), "deny".to_string()],
        // The high-risk-method gate is already system-level (it
        // passes None as the owner via request_and_wait_approval's
        // internal call). This field is informational here.
        system_level: true,
    };
    match state
        .host
        .request_and_wait_approval(req, "approve", timeout)
        .await
    {
        Ok(crate::host::ApprovalOutcome::Approved) => Ok(()),
        Ok(crate::host::ApprovalOutcome::Denied) => Err(format!(
            "{method} denied by user (approval gate, audit 2026-05). \
             To call this method without an interactive prompt, start \
             car-server with --no-approvals on a trusted machine."
        )),
        Ok(crate::host::ApprovalOutcome::TimedOut) => Err(format!(
            "{method} approval timed out after {}s with no resolution. \
             The approval is still visible in `host.approvals` for \
             forensics; resubmit the request to retry.",
            timeout.as_secs()
        )),
        Err(e) => Err(format!("approval gate error: {e}")),
    }
}

fn preview_params(value: &Value, max_chars: usize) -> Value {
    let s = value.to_string();
    if s.len() <= max_chars {
        value.clone()
    } else {
        Value::String(format!("{}… (truncated)", &s[..max_chars]))
    }
}

async fn handle_session_init(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let _lifecycle_guard = session.run_lifecycle_guard.lock().await;
    let init: SessionInitRequest =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;

    for tool in &init.tools {
        register_callback_definition(session, tool).await?;
    }

    let mut policy_count = 0;
    {
        let mut policies = session.runtime.policies.write().await;
        for policy_def in &init.policies {
            if let Some(check) = build_policy_check(policy_def) {
                match blanket_denied_tool(policy_def) {
                    Some(tool) => policies.register_tool_deny(&policy_def.name, &tool, check, ""),
                    None => policies.register(&policy_def.name, check, ""),
                }
                policy_count += 1;
            }
        }
    }

    serde_json::to_value(SessionInitResponse {
        session_id: session.client_id.clone(),
        tools_registered: init.tools.len(),
        policies_registered: policy_count,
    })
    .map_err(|e| e.to_string())
}

/// Clear the fail-stop latch on this exact WebSocket session.
///
/// The latch belongs to the connection, so only a host-authenticated client
/// on that same connection can clear it. Ordinary clients recover by
/// reconnecting, which creates a fresh session as required by the non-durable
/// contract.
async fn handle_session_clear_halt(
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    if !session.is_host.load(Ordering::Acquire) {
        return Err("session.clear_halt requires the host-management role".to_string());
    }
    let cleared = session.halted.swap(false, Ordering::AcqRel);
    Ok(serde_json::json!({ "cleared": cleared, "halted": false }))
}

/// `session.bindSubstrate { connector: "<slug>" }` — bind THIS session's
/// runtime to the execution substrate of an already-connected MCP
/// connector (`docs/execution-substrate.md` phase 3). After binding, the
/// session's commodity built-ins (`read_file`/`write_file`/`edit_file`/
/// `list_dir`/`find_files`/`grep_files`) execute on the connector's
/// environment instead of the WS client/host, so they co-locate with the
/// session's `mcp_{slug}_*` tools.
///
/// Opt-in and per-session: a session that never calls this keeps the
/// historic host/client composition. Returns
/// `{ "bound": true, "substrate": "<name>" }` on success.
async fn handle_session_bind_substrate(
    req: &JsonRpcMessage,
    session: &Arc<crate::session::ClientSession>,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let connector = req
        .params
        .get("connector")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `connector` (MCP connector slug)".to_string())?;

    let name = state
        .bind_substrate_to_connector(session, connector)
        .await?;
    Ok(serde_json::json!({ "bound": true, "substrate": name }))
}

/// `session.bindSandbox { working_dir, image?, network?, memory?, cpus?,
/// pids_limit?, persistent?, command_timeout_secs? }` — bind this session's
/// runtime to a Docker-sandboxed execution environment (D1). The session's
/// commodity built-ins (shell / read_file / write_file / list_dir /
/// grep_files) then run INSIDE a hardened container mounted on
/// `working_dir` (default-secure: no network unless `network` is set,
/// memory/pids/cpu caps, dropped capabilities — D2/D3).
///
/// Preflights Docker + the image FIRST and returns the preflight's
/// actionable error when the host can't run containers (no daemon, image
/// unpullable) — an explicit, typed refusal, never a silent fallback to
/// unsandboxed local execution (D3: substituting the host for the sandbox
/// behind the caller's back would be a security downgrade).
async fn handle_session_bind_sandbox(
    req: &JsonRpcMessage,
    session: &Arc<crate::session::ClientSession>,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    // `session.bindSandbox` mounts an arbitrary host `working_dir` read-write
    // into a container the caller drives via shell. Bound agents are denied
    // (Parslee-ai/car#480); host/CLI clients are unaffected.
    //
    // **Advisory, not a confinement boundary — do not build authorization on
    // it.** This used to say that letting a supervised agent bind-mount any
    // host dir "would turn the daemon into a confinement escape". It would not.
    // A supervised agent runs as the launching user with no sandbox, so it can
    // already read `~/.ssh` directly; the isolation car-pr-review has is
    // app-level (CAR declines to hand it credentials), not an OS boundary. And
    // the check is escapable on its own terms: an agent controls its own
    // environment, so it can unset `CAR_AGENT_ID` and reconnect unbound
    // (car#1297).
    //
    // Kept anyway, because it costs nothing and makes the confined path the
    // easy one. What it must not do is imply a guarantee it cannot make. The
    // per-gate audit is in docs/proposals/agent-binding-trust-boundary.md;
    // `host_token` is what a real boundary looks like in this codebase.
    if let Some(agent_id) = session.agent_id.lock().await.clone() {
        return Err(format!(
            "session.bindSandbox is not available to supervised agents \
             (agent '{agent_id}'): it would let a confined agent bind-mount any \
             host directory into a container it controls. See Parslee-ai/car#480."
        ));
    }

    let working_dir = req
        .params
        .get("working_dir")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `working_dir`".to_string())?;
    let wd = std::path::Path::new(working_dir);
    if !wd.is_dir() {
        return Err(format!("working_dir '{working_dir}' is not a directory"));
    }

    let mut config = car_sandbox::SandboxConfig {
        working_dir: wd.to_path_buf(),
        ..Default::default()
    };
    if let Some(image) = opt_str(&req.params, "image") {
        config.image = image.to_string();
    }
    // Egress stays OFF unless explicitly requested (D2).
    if let Some(net) = opt_str(&req.params, "network") {
        config.network = Some(net.to_string());
    }
    if let Some(mem) = opt_str(&req.params, "memory") {
        config.memory = Some(mem.to_string());
    }
    if let Some(cpus) = opt_str(&req.params, "cpus") {
        config.cpus = Some(cpus.to_string());
    }
    if let Some(pids) = req.params.get("pids_limit").and_then(|v| v.as_u64()) {
        config.pids_limit = Some(pids);
    }
    // NOTE: no `persistent` param — SandboxConfig::persistent is not yet
    // wired in the executor (the container is always cached per executor),
    // and advertising a no-op knob is worse than not offering it (review Q1).
    if let Some(t) = req
        .params
        .get("command_timeout_secs")
        .and_then(|v| v.as_u64())
    {
        if t == 0 {
            return Err("command_timeout_secs must be >= 1".to_string());
        }
        config.command_timeout_secs = t;
    }

    // D3: preflight before binding — a host without Docker gets the
    // preflight's own actionable message (install/start Docker, pull the
    // image), not a broken half-bound session.
    let pf = car_sandbox::preflight(&config.image).await;
    if !pf.is_ok() {
        return Err(format!("sandbox preflight failed: {}", pf.message()));
    }

    let executor = std::sync::Arc::new(car_sandbox::SandboxExecutor::new(config));
    let substrate: std::sync::Arc<dyn car_engine::Substrate> = executor;
    let name = substrate.name().to_string();

    // Same three-step swap as bind_substrate_to_connector (see its note on
    // why the non-atomic swap is benign: a WS connection handles its
    // JSON-RPC sequentially and bind is a control call issued before tool
    // work): bind the substrate, re-register the substrate-backed
    // built-ins, then shadow the substrate-owned tool names so they fall
    // through to the sandbox while everything else keeps the WS callback
    // path.
    session.runtime.set_substrate(substrate).await;
    session.runtime.register_agent_basics().await;
    // Compose EXACTLY like bind_substrate_to_connector: connector
    // (mcp_{slug}_*) routes first, then the WS client callback, with the
    // substrate-owned built-in names shadowed to the sandbox. Wrapping the
    // bare WS executor here severed every connector tool on the session —
    // still registered and advertised to the model, but dispatched to a WS
    // client that has never heard of them (review C1).
    let ws_executor = std::sync::Arc::new(crate::session::WsToolExecutor::new(
        session.channel.clone(),
        session.negotiated_capabilities.clone(),
        session.halted.clone(),
    ));
    let composed: std::sync::Arc<dyn car_engine::ToolExecutor> =
        std::sync::Arc::new(state.mcp_executor.share_with_fallback(ws_executor));
    let shadowed: std::sync::Arc<dyn car_engine::ToolExecutor> =
        std::sync::Arc::new(crate::session::SubstrateShadowExecutor::new(composed));
    session.runtime.set_executor(shadowed).await;

    Ok(serde_json::json!({ "bound": true, "substrate": name }))
}

/// The tool a policy definition forbids **outright**, if it forbids one.
///
/// `deny_tool` is the only wire rule kind whose totality is decidable from the
/// kind alone, which is the same line `PolicyEngine::blanket_denied_tools`
/// draws. `deny_connector` is also a blanket refusal but of an `mcp_{slug}_*`
/// PREFIX rather than a named tool, which that surface cannot express. It stays
/// enforcement-only, and nothing is lost by that: connector rules live on the
/// daemon's session runtime, which never assembles a model-facing tool list
/// (the model is in the client there), and disabling a connector already calls
/// `Runtime::unregister_tool` on each of its tools — removing them from the
/// registry outright, which is strictly stronger than declining to advertise
/// them. A prefix read-back here would have no caller.
fn blanket_denied_tool(def: &PolicyDefinition) -> Option<String> {
    (def.rule.as_str() == "deny_tool").then(|| def.target.clone())
}

fn build_policy_check(def: &PolicyDefinition) -> Option<car_policy::PolicyCheck> {
    match def.rule.as_str() {
        "deny_tool" => {
            let target = def.target.clone();
            Some(Box::new(
                move |action: &car_ir::Action, _: &car_state::StateStore| {
                    if action.tool.as_deref() == Some(&target) {
                        Some(format!("tool '{}' denied", target))
                    } else {
                        None
                    }
                },
            ))
        }
        // Deny every tool from a remote MCP connector by slug. Connector
        // tools are named `mcp_{slug}_{tool}` (car-connectors), so a
        // single rule governs the whole connector — the policy-level
        // counterpart to per-tool enablement.
        "deny_connector" => {
            let slug = def.target.clone();
            let prefix = format!("mcp_{slug}_");
            Some(Box::new(
                move |action: &car_ir::Action, _: &car_state::StateStore| match action
                    .tool
                    .as_deref()
                {
                    Some(tool) if tool.starts_with(&prefix) => {
                        Some(format!("connector '{}' denied", slug))
                    }
                    _ => None,
                },
            ))
        }
        "require_state" => {
            let key = def.key.clone();
            let value = def.value.clone();
            Some(Box::new(
                move |_: &car_ir::Action, state: &car_state::StateStore| {
                    if state.get(&key).as_ref() != Some(&value) {
                        Some(format!("state['{}'] must be {:?}", key, value))
                    } else {
                        None
                    }
                },
            ))
        }
        "deny_tool_param" => {
            let target = def.target.clone();
            let param = def.key.clone();
            let pattern = def.pattern.clone();
            Some(Box::new(
                move |action: &car_ir::Action, _: &car_state::StateStore| {
                    if action.tool.as_deref() != Some(&target) {
                        return None;
                    }
                    if let Some(val) = action.parameters.get(&param) {
                        let s = val.as_str().unwrap_or(&val.to_string()).to_string();
                        if s.contains(&pattern) {
                            return Some(format!("param '{}' matches '{}'", param, pattern));
                        }
                    }
                    None
                },
            ))
        }
        _ => None,
    }
}

async fn handle_tools_register(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let _lifecycle_guard = session.run_lifecycle_guard.lock().await;
    let tools: Vec<ToolDefinition> =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    for tool in &tools {
        register_callback_definition(session, tool).await?;
    }
    Ok(Value::from(tools.len()))
}

/// Bridge a wire-protocol `ToolDefinition` to the engine's
/// schema-aware registration. Carries the caller-settable ToolSchema fields
/// (description, parameters, returns, idempotency, caching, rate limit) through
/// to the validator, while assigning `source = user_defined` server-side. An
/// empty `parameters` object is
/// the legacy schemaless registration — the validator no-ops for
/// those, so pre-v0.5.x callers see no change.
fn callback_standing_authority_eligible(def: &ToolDefinition) -> bool {
    // Standing authority is intentionally limited to the one callback CAR
    // currently needs for Daily Continuity. A denylist is unsafe here: an
    // equivalent generic executor can always be renamed (for example `curl`
    // or `fetch`) or hide its authority behind a new parameter name.
    if def.name != "newsroom.publish"
        || def.idempotent
        || def.cache_ttl_secs.is_some()
        || def.rate_limit.is_some()
    {
        return false;
    }
    def.parameters
        == serde_json::json!({
            "type": "object",
            "properties": {
                "edition_id": {
                    "type": "string",
                    "minLength": 1
                }
            },
            "required": ["edition_id"],
            "additionalProperties": false
        })
}

async fn register_callback_definition(
    session: &crate::session::ClientSession,
    def: &ToolDefinition,
) -> Result<(), String> {
    if session.runtime.registry.get(&def.name).await.is_some() {
        return Err(format!(
            "tool '{}' is server-owned and cannot be shadowed by tools.register",
            def.name
        ));
    }
    let digest = car_proto::canonical_sha256(def)?;
    {
        let mut callbacks = session.callback_tool_schema_digests.write().await;
        if callback_standing_authority_eligible(def) {
            callbacks.insert(def.name.clone(), digest);
        } else {
            callbacks.remove(&def.name);
        }
    }
    session
        .runtime
        .register_tool_schema(car_ir::ToolSchema {
            name: def.name.clone(),
            source: car_ir::ToolSourceKind::UserDefined,
            description: def.description.clone(),
            parameters: def.parameters.clone(),
            returns: def.returns.clone(),
            idempotent: def.idempotent,
            cache_ttl_secs: def.cache_ttl_secs,
            rate_limit: def.rate_limit.as_ref().map(|rl| car_ir::ToolRateLimit {
                max_calls: rl.max_calls,
                interval_secs: rl.interval_secs,
            }),
        })
        .await;
    Ok(())
}

/// `tools.list` — the toolset actually in effect on this connection. No params.
///
/// Counterpart to `tools.register`, which had none: a client could add tools to
/// its session runtime but had no way to ask what was registered, so a governed
/// or read-only deployment could not prove "only X and Y are callable here"
/// (Parslee-ai/car#892). The enumerate already existed on the engine
/// (`Runtime::tool_schemas`) — it was simply never exposed to daemon clients.
/// Exactly the gap `policy.list` closed for `policy.register` in
/// Parslee-ai/car#623; this is the other half of the same pair.
///
/// Returns `{ tools: [ToolSchema, ...], count }`. Each entry is the **full**
/// schema — `name`, runtime-assigned `source`, `description`, `parameters`,
/// and (when set) `returns`, `idempotent`, `cache_ttl_secs`, `rate_limit` — not
/// just the name, because
/// what a tool accepts is part of the effective surface being proven. Optional
/// fields are omitted when unset, per `car_ir::ToolSchema`'s own serialization.
///
/// **The array is sorted by tool name.** The underlying store is a `HashMap`,
/// so unsorted output would reorder between two calls that registered nothing
/// in between — an audit surface whose order changes on its own cannot be
/// diffed and is therefore not usable as proof.
///
/// Scope is the connection: every WebSocket client gets its own
/// `car_engine::Runtime`, so this reports what is in force on *this* session,
/// not a daemon-wide set. It is also not the assistant's set — `car do` /
/// `agents.chat` build their own `Runtime`, so a client that lists here and
/// then drives the assistant is not looking at the toolset that will execute
/// there.
///
/// Note that "in force" is a superset of "what the client registered", which is
/// most of why enumerating is worth doing. A fresh session already carries the
/// `messaging.send` built-in — `create_session` attaches an outbound message
/// sink, and `Runtime::with_message_sink` registers the matching schema in the
/// same step so the model is never shown a tool the runtime cannot execute. The
/// commodity stdlib is *not* included until the session asks for it; both
/// `session.bindSubstrate` and `session.bindSandbox` call
/// `register_agent_basics`, so either one adds it.
async fn handle_tools_list(session: &crate::session::ClientSession) -> Result<Value, String> {
    let mut schemas = session.runtime.tool_schemas().await;
    schemas.sort_by(|a, b| a.name.cmp(&b.name));
    let count = schemas.len();
    let tools = schemas
        .iter()
        .map(serde_json::to_value)
        .collect::<std::result::Result<Vec<Value>, _>>()
        .map_err(|e| format!("serialize tool schema: {e}"))?;
    Ok(serde_json::json!({ "tools": tools, "count": count }))
}

/// `tools.unregister` — remove one tool from this session's runtime.
/// `{ name }`.
///
/// The removal half of Parslee-ai/car#892: with only `tools.register` on the
/// wire, a tool added to a session could not be taken back for the life of the
/// connection, so narrowing an over-broad registration meant reconnecting and
/// rebuilding the session's state. `Runtime::unregister_tool` already dropped
/// the tool from **both** the canonical registry and the legacy schema map —
/// the model stops seeing it and the validator stops accepting it — but nothing
/// called it from the dispatcher.
///
/// Returns `{ unregistered, removed }`, where `removed` is `1` if the tool was
/// present and `0` if it was not. A `0` is reported rather than raised, so a
/// client cleaning up can call this unconditionally without first listing —
/// the same contract `policy.unregister` settled on (Parslee-ai/car#623).
async fn handle_tools_unregister(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let _lifecycle_guard = session.run_lifecycle_guard.lock().await;
    let name = req
        .params
        .get("name")
        .and_then(|v| v.as_str())
        .ok_or("missing 'name'")?;
    let removed = session.runtime.unregister_tool(name).await;
    session
        .callback_tool_schema_digests
        .write()
        .await
        .remove(name);
    Ok(serde_json::json!({
        "unregistered": name,
        "removed": u32::from(removed),
    }))
}

// ---- Detached tool dispatch (streaming/long-running, EPIC C / C2) ----
//
// A ToolCall action with `invocation_mode: "streaming" | "long_running"`
// is *started*, not awaited: its output is `{tool_handle, status:
// "running"}` and the DAG proceeds. These methods drive the handle
// against the session runtime's `ToolHandleRegistry`.

/// `tools.poll { handle }` — drain the chunks buffered since the last
/// poll plus the invocation's current status (and, once terminal, its
/// final result/error). Returns `null` for an unknown or already
/// fully-consumed handle — absence, not an error (a terminal handle is
/// removed after its final state has been observed once with an empty
/// buffer, per the `car_engine::tool_handles` contract).
async fn handle_tools_poll(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let handle = req
        .params
        .get("handle")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `handle`".to_string())?;
    match session.runtime.tool_poll(handle).await {
        Some(res) => serde_json::to_value(&res).map_err(|e| e.to_string()),
        None => Ok(Value::Null),
    }
}

/// `tools.cancel { handle }` — request cooperative cancellation of a
/// detached invocation. Returns `{ cancelled: bool }` — `false` for an
/// unknown handle. Distinct from the server → client `tools.cancel`
/// *notification* (car#264, emitted when a `tools.execute` callback is
/// reaped): same method name, opposite direction.
async fn handle_tools_cancel(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let handle = req
        .params
        .get("handle")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `handle`".to_string())?;
    let cancelled = session.runtime.tool_cancel(handle).await;
    Ok(serde_json::json!({ "cancelled": cancelled }))
}

/// `tools.stream.subscribe {}` — forward every [`car_ir::ToolStreamEvent`]
/// from this session runtime's fanout to the connection as a
/// `tools.stream.event` JSON-RPC notification `{ handle, chunk }`.
/// Idempotent per connection (a second subscribe is a no-op — one
/// forwarder task per session). The forwarder holds only the broadcast
/// receiver + the WS channel: it exits when the socket is gone (write
/// failure/timeout, same bounded-write policy as the run-trace drain
/// task) or the broadcast closes; on lag it skips the missed events and
/// keeps forwarding — missed chunks remain drainable via `tools.poll`,
/// which reads the buffer, not the broadcast.
async fn handle_tools_stream_subscribe(
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    use std::sync::atomic::Ordering;
    if session
        .tool_stream_subscribed
        .compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst)
        .is_err()
    {
        // Already forwarding to this connection.
        return Ok(serde_json::json!({ "subscribed": true }));
    }
    let mut rx = session.runtime.subscribe_tool_events();
    let channel = session.channel.clone();
    // Q2 (linus review): the forwarder can exit on a 10s write TIMEOUT
    // while the connection later recovers — the flag must reset when
    // the task exits so a re-subscribe spawns a fresh forwarder instead
    // of no-op'ing while events silently never flow again.
    let subscribed = session.tool_stream_subscribed.clone();
    tokio::spawn(async move {
        use futures::SinkExt;
        struct ResetOnExit(std::sync::Arc<std::sync::atomic::AtomicBool>);
        impl Drop for ResetOnExit {
            fn drop(&mut self) {
                self.0.store(false, std::sync::atomic::Ordering::SeqCst);
            }
        }
        let _reset_on_exit = ResetOnExit(subscribed);
        loop {
            match rx.recv().await {
                Ok(ev) => {
                    let Ok(json) = serde_json::to_string(&serde_json::json!({
                        "jsonrpc": "2.0",
                        "method": "tools.stream.event",
                        "params": { "handle": ev.handle.id, "chunk": ev.chunk },
                    })) else {
                        continue;
                    };
                    // Bounded write: a wedged socket must not park this
                    // task on a full TCP buffer forever. Any write
                    // failure/timeout means the connection is unusable —
                    // stop forwarding (chunks stay pollable).
                    let mut guard = channel.write.lock().await;
                    let send = tokio::time::timeout(
                        std::time::Duration::from_secs(10),
                        guard.send(Message::Text(json.into())),
                    )
                    .await;
                    drop(guard);
                    match send {
                        Ok(Ok(())) => {}
                        _ => break,
                    }
                }
                // Lagged subscriber: the bounded broadcast dropped its
                // oldest events. Not fatal — resume from the current
                // position; the gap is recoverable via tools.poll.
                Err(tokio::sync::broadcast::error::RecvError::Lagged(_)) => continue,
                Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
            }
        }
    });
    Ok(serde_json::json!({ "subscribed": true }))
}

// ---- Remote MCP connectors (CAR as MCP client) ----------------------
//
// All connector state is process-wide on `ServerState` (shared
// McpToolExecutor + ConnectorManager), so these handlers take `&state`
// rather than the per-session runtime. Each ensures the persisted
// connectors are loaded before acting (idempotent after the first call
// / boot-time load).

/// `connectors.add { name, url, headers? }` — register a remote MCP
/// server, connect, and discover its tools. `headers` is an optional
/// map of secret auth-header name → value, stored in the keychain (not
/// the manifest). No tools are enabled by the add itself; the response
/// reports the discovered count.
async fn handle_connectors_add(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    state.ensure_connectors_loaded().await;
    let name = req
        .params
        .get("name")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `name`".to_string())?;
    let url = req
        .params
        .get("url")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `url`".to_string())?;
    let headers: Vec<(String, String)> = req
        .params
        .get("headers")
        .and_then(|v| v.as_object())
        .map(|m| {
            m.iter()
                .filter_map(|(k, v)| v.as_str().map(|s| (k.clone(), s.to_string())))
                .collect()
        })
        .unwrap_or_default();

    let status = state
        .connectors()
        .add(name, url, headers)
        .await
        .map_err(|e| e.to_string())?;
    serde_json::to_value(status).map_err(|e| e.to_string())
}

/// `connectors.add_stdio { name, command, args?, env? }` — register a
/// local stdio MCP server (subprocess transport), connect, and discover
/// its tools. No tools are enabled by the add itself.
async fn handle_connectors_add_stdio(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    state.ensure_connectors_loaded().await;
    let name = req
        .params
        .get("name")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `name`".to_string())?;
    let command = req
        .params
        .get("command")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `command`".to_string())?;
    let args: Vec<String> = req
        .params
        .get("args")
        .and_then(|v| v.as_array())
        .map(|a| {
            a.iter()
                .filter_map(|v| v.as_str().map(str::to_string))
                .collect()
        })
        .unwrap_or_default();
    let env: std::collections::BTreeMap<String, String> = req
        .params
        .get("env")
        .and_then(|v| v.as_object())
        .map(|m| {
            m.iter()
                .filter_map(|(k, v)| v.as_str().map(|s| (k.clone(), s.to_string())))
                .collect()
        })
        .unwrap_or_default();

    let status = state
        .connectors()
        .add_stdio(name, command, args, env)
        .await
        .map_err(|e| e.to_string())?;
    serde_json::to_value(status).map_err(|e| e.to_string())
}

/// `connectors.authenticate { name, url, redirect_uri }` — begin an
/// OAuth 2.1 flow for a remote MCP server. Runs discovery + dynamic
/// client registration + PKCE, returns `{ authorize_url, state }`. The
/// GUI opens `authorize_url` (with its own `redirect_uri` callback),
/// captures the `code`, and calls `connectors.complete_authentication`.
async fn handle_connectors_authenticate(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    state.ensure_connectors_loaded().await;
    let name = req
        .params
        .get("name")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `name`".to_string())?;
    let url = req
        .params
        .get("url")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `url`".to_string())?;
    let redirect_uri = req
        .params
        .get("redirect_uri")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `redirect_uri`".to_string())?;

    let (authorize_url, oauth_state) = state
        .connectors()
        .authenticate(name, url, redirect_uri)
        .await
        .map_err(|e| e.to_string())?;
    Ok(serde_json::json!({ "authorize_url": authorize_url, "state": oauth_state }))
}

/// `connectors.complete_authentication { state, code }` — finish the
/// OAuth flow started by `connectors.authenticate`: exchange the code,
/// store tokens in the keychain, connect, and discover tools.
async fn handle_connectors_complete_authentication(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    state.ensure_connectors_loaded().await;
    let oauth_state = req
        .params
        .get("state")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `state`".to_string())?;
    let code = req
        .params
        .get("code")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `code`".to_string())?;

    let status = state
        .connectors()
        .complete_authentication(oauth_state, code)
        .await
        .map_err(|e| e.to_string())?;
    serde_json::to_value(status).map_err(|e| e.to_string())
}

/// `connectors.list` — all configured connectors with status.
async fn handle_connectors_list(state: &Arc<ServerState>) -> Result<Value, String> {
    state.ensure_connectors_loaded().await;
    let list = state.connectors().list().await;
    serde_json::to_value(list).map_err(|e| e.to_string())
}

/// `connectors.tools { slug }` — discovered tools for a connector,
/// flagged by whether each is enabled.
async fn handle_connectors_tools(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    state.ensure_connectors_loaded().await;
    let slug = req
        .params
        .get("slug")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `slug`".to_string())?;
    let tools = state
        .connectors()
        .tools(slug)
        .await
        .map_err(|e| e.to_string())?;
    serde_json::to_value(tools).map_err(|e| e.to_string())
}

/// `connectors.enable_tools { slug, tools: [..] }` — enable a set of
/// (bare, server-side) tool names. Routes them, registers their
/// schemas into every open session's runtime, and persists the choice.
async fn handle_connectors_enable_tools(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    state.ensure_connectors_loaded().await;
    let slug = req
        .params
        .get("slug")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `slug`".to_string())?;
    let tools: Vec<String> = req
        .params
        .get("tools")
        .and_then(|v| v.as_array())
        .map(|a| {
            a.iter()
                .filter_map(|v| v.as_str().map(str::to_string))
                .collect()
        })
        .ok_or_else(|| "missing `tools` array".to_string())?;

    let entries = state
        .connectors()
        .enable_tools(slug, &tools)
        .await
        .map_err(|e| e.to_string())?;
    let enabled = entries.len();
    state.register_connector_entries(&entries).await;
    Ok(serde_json::json!({ "enabled": enabled }))
}

/// `connectors.refresh { slug }` — re-run `tools/list` and re-register
/// any still-enabled tools.
async fn handle_connectors_refresh(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    state.ensure_connectors_loaded().await;
    let slug = req
        .params
        .get("slug")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `slug`".to_string())?;
    let tools = state
        .connectors()
        .refresh(slug)
        .await
        .map_err(|e| e.to_string())?;
    // Re-seed enabled entries into live sessions in case the refresh
    // re-discovered a previously-enabled tool.
    let entries = state.connectors().enabled_tool_entries().await;
    state.register_connector_entries(&entries).await;
    serde_json::to_value(tools).map_err(|e| e.to_string())
}

/// `connectors.remove { slug }` — disconnect, drop routes, delete
/// keychain secrets, and remove from the manifest.
async fn handle_connectors_remove(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    state.ensure_connectors_loaded().await;
    let slug = req
        .params
        .get("slug")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `slug`".to_string())?;
    let canonicals = state
        .connectors()
        .remove(slug)
        .await
        .map_err(|e| e.to_string())?;
    state.unregister_connector_tools(&canonicals).await;
    Ok(serde_json::json!({ "removed": slug }))
}

async fn run_store_blocking<T, F>(context: &'static str, operation: F) -> Result<T, String>
where
    T: Send + 'static,
    F: FnOnce() -> Result<T, String> + Send + 'static,
{
    tokio::task::spawn_blocking(operation)
        .await
        .map_err(|error| format!("{context} blocking task failed: {error}"))?
}

/// Run a trust-bearing trace read off the Tokio worker, then publish any
/// discovered corruption into the live run registry before returning the
/// typed wire error. Filesystem scanning/marker persistence never holds the
/// global run lock; the short quarantine step runs only after it completes.
async fn strict_run_trace_read_blocking<T, F>(
    context: &'static str,
    state: &Arc<ServerState>,
    run_id: String,
    operation: F,
) -> Result<T, String>
where
    T: Send + 'static,
    F: FnOnce() -> std::io::Result<T> + Send + 'static,
{
    let result = tokio::task::spawn_blocking(operation)
        .await
        .map_err(|error| format!("{context} blocking task failed: {error}"))?;
    match result {
        Ok(value) => Ok(value),
        Err(error) if crate::run_store::is_trace_corruption_error(&error) => Err(state
            .quarantine_run_trace_from_read(&run_id, error.to_string())
            .await),
        Err(error) => Err(run_trace_read_error(&run_id, error)),
    }
}

/// Run one proposal durability boundary without pinning a Tokio worker.
///
/// The owned lifecycle guard moves into the blocking task and is returned only
/// after the fsync/rename operation finishes. If the JSON-RPC handler is
/// cancelled while awaiting, the task still owns the guard until durability is
/// settled, so an exact retry cannot race an in-flight marker/outbox commit.
async fn run_lifecycle_durability_blocking<T, F>(
    guard: &mut Option<tokio::sync::OwnedMutexGuard<()>>,
    context: &'static str,
    operation: F,
) -> Result<T, String>
where
    T: Send + 'static,
    F: FnOnce() -> Result<T, String> + Send + 'static,
{
    let owned = guard
        .take()
        .expect("proposal durability requires the owned lifecycle guard");
    match tokio::task::spawn_blocking(move || {
        let result = operation();
        (owned, result)
    })
    .await
    {
        Ok((owned, result)) => {
            *guard = Some(owned);
            result
        }
        Err(error) => Err(format!("{context} blocking task failed: {error}")),
    }
}

/// `connectors.disable_tools { slug, tools: [..] }` — disable a set of
/// (bare, server-side) tool names: drop their routes and unregister
/// their schemas from every open session's runtime.
async fn handle_connectors_disable_tools(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    state.ensure_connectors_loaded().await;
    let slug = req
        .params
        .get("slug")
        .and_then(|v| v.as_str())
        .ok_or_else(|| "missing `slug`".to_string())?;
    let tools: Vec<String> = req
        .params
        .get("tools")
        .and_then(|v| v.as_array())
        .map(|a| {
            a.iter()
                .filter_map(|v| v.as_str().map(str::to_string))
                .collect()
        })
        .ok_or_else(|| "missing `tools` array".to_string())?;

    let canonicals = state
        .connectors()
        .disable_tools(slug, &tools)
        .await
        .map_err(|e| e.to_string())?;
    let disabled = canonicals.len();
    state.unregister_connector_tools(&canonicals).await;
    Ok(serde_json::json!({ "disabled": disabled }))
}

async fn handle_proposal_submit(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let submit: ProposalSubmitRequest =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let original_submission = req
        .params
        .get("proposal")
        .cloned()
        .ok_or_else(|| "proposal.submit is missing `proposal`".to_string())?;
    // Fail before binding a policy session or executing any action when two
    // proposal-local actions would share an ambiguous journal/DAG join key, or
    // when the exact submitted Proposal cannot carry the mandatory RFC 8785
    // identity used by proposal_received. Runtime entry points repeat both
    // guards; this boundary preserves an invalid-proposal JSON-RPC error.
    car_engine::validate_proposal_action_ids(&submit.proposal)
        .map_err(|error| format!("invalid proposal: {error}"))?;
    let submitted_proposal_digest = canonical_sha256(&submit.proposal)?;
    let submitted_proposal_value =
        serde_json::to_value(&submit.proposal).map_err(|e| e.to_string())?;
    // `session_id` is sibling to `proposal` in the params object —
    // not part of `ProposalSubmitRequest` (kept proto-compatible). When
    // present, executes the proposal under the named session so any
    // session-scoped policies layer on top of global ones.
    // See docs/proposals/per-session-policy-scoping.md.
    let session_id = match req.params.get("session_id") {
        None | Some(Value::Null) => None,
        Some(Value::String(value)) if !value.is_empty() => Some(value.clone()),
        Some(_) => return Err("invalid `session_id`: expected a non-empty string".to_string()),
    };

    // Decode every execution context before acquiring/binding live lifecycle
    // state. A malformed scope must be a side-effect-free request error, not a
    // half-open proposal policy binding. CAR currently has no runtime entry
    // point that enforces both a policy session and a tenant scope; accepting
    // both while silently dropping either constraint would be an authorization
    // bypass, so the wire fails closed until a combined entry point exists.
    let scope: Option<car_engine::RuntimeScope> = match req.params.get("scope") {
        Some(v) if !v.is_null() => {
            Some(serde_json::from_value(v.clone()).map_err(|e| format!("invalid scope: {e}"))?)
        }
        _ => None,
    };
    if session_id.is_some() && scope.is_some() {
        return Err(
            "proposal.submit cannot combine `session_id` and `scope`: CAR cannot yet enforce both contexts"
                .to_string(),
        );
    }

    // One authenticated run bracket is one ordered journal producer. The
    // dispatcher otherwise runs frames concurrently, so serialize proposal
    // lifecycle with runs.start/runs.complete/disconnect before reading the
    // current run and keep the guard through the terminal proposal event.
    let mut run_guard = Some(session.run_lifecycle_guard.clone().lock_owned().await);
    let current_run = session.current_run_id.lock().await.clone();

    // The global retry-owner check is one content-addressed file read. Run it
    // on blocking capacity so the async worker never performs filesystem I/O.
    // Keeping the lifecycle guard preserves request ordering while replacing
    // the old unbounded receipt/run-directory scan with one exact lookup.
    let receipt_owner = {
        let run_store = state.run_store.clone();
        let requested_policy_session_id = session_id.clone();
        let original_submission = original_submission.clone();
        tokio::task::spawn_blocking(move || {
            run_store.completed_proposal_retry_owner(
                requested_policy_session_id.as_deref(),
                &original_submission,
            )
        })
        .await
        .map_err(|error| format!("completed proposal response owner lookup failed: {error}"))?
        .map_err(|error| format!("completed proposal response registry is unreadable: {error}"))?
    };
    if let Some((receipt_run, receipt_client)) = receipt_owner.as_ref() {
        let owner_matches = if current_run.as_deref() == Some(receipt_run.as_str()) {
            state
                .run_owner_binding(receipt_run)
                .await
                .is_some_and(|(durable, active)| {
                    durable == *receipt_client && active == session.client_id
                })
        } else {
            false
        };
        if !owner_matches {
            return Err(format!(
                "{} completed proposal response belongs to run `{receipt_run}` / durable client `{receipt_client}`; this socket is not the active authenticated owner",
                car_proto::RUN_OWNERSHIP_CONFLICT_MESSAGE_PREFIX
            ));
        }
    }
    if let Some(run_id) = current_run.as_deref() {
        let (durable_client, active_client) = state
            .run_owner_binding(run_id)
            .await
            .ok_or_else(|| format!("active run `{run_id}` is absent from CAR's run registry"))?;
        let (owner_client, terminal, start_committed, completion_pending, trace_corruption) = state
            .run_lifecycle_state_with_corruption(run_id)
            .await
            .ok_or_else(|| format!("active run `{run_id}` is absent from CAR's run registry"))?;
        if let Some(error) = trace_corruption {
            return Err(error);
        }
        if terminal
            || !start_committed
            || completion_pending
            || owner_client != session.client_id
            || active_client != session.client_id
        {
            return Err(format!(
                "active run is not writable for run_id `{run_id}` / client_id `{}`",
                session.client_id
            ));
        }
        session.require_run_journal_binding(run_id).await?;

        let (completed, resumed_policy_rotation) = {
            let run_store = state.run_store.clone();
            let run_id = run_id.to_string();
            let client_id = durable_client.clone();
            let requested_policy_session_id = session_id.clone();
            let original_submission = original_submission.clone();
            run_store_blocking("completed proposal response lookup", move || {
                let exact = run_store
                    .completed_proposal(
                        &run_id,
                        &client_id,
                        requested_policy_session_id.as_deref(),
                        &original_submission,
                    )
                    .map_err(|error| {
                        proposal_durability_quarantine(&run_id, "completed response", &error)
                    })?;
                let resumed_owner = client_id != active_client;
                if exact.is_some() || !resumed_owner {
                    return Ok((exact, resumed_owner));
                }
                run_store
                    .completed_proposal_for_resumed_owner(&run_id, &client_id, &original_submission)
                    .map(|receipt| (receipt, true))
                    .map_err(|error| {
                        proposal_durability_quarantine(
                            &run_id,
                            "resumed completed response",
                            &error,
                        )
                    })
            })
            .await?
        };
        if let Some(receipt) = completed {
            if resumed_policy_rotation {
                let original_policy = &receipt.finalization.requested_policy_session_id;
                let authenticated_original_policy = &receipt.finalization.policy_session_id;
                let replacement_policy_is_live = match session_id.as_deref() {
                    Some(policy_session_id) => {
                        session.runtime.session_exists(policy_session_id).await
                    }
                    None => false,
                };
                match (original_policy, authenticated_original_policy, &session_id) {
                    (None, None, None) => {}
                    (Some(requested), Some(authenticated), Some(_))
                        if requested == authenticated && replacement_policy_is_live => {}
                    _ => {
                        return Err(
                            "resumed proposal recovery requires the original authenticated policy provenance and a live replacement policy session"
                                .to_string(),
                        );
                    }
                }
            }
            let run_store = state.run_store.clone();
            let (value, cleanup_error) = run_lifecycle_durability_blocking(
                &mut run_guard,
                "completed proposal guard cleanup",
                move || {
                    let cleanup_error = run_store
                        .cleanup_completed_proposal_guards(&receipt)
                        .err()
                        .map(|error| error.to_string());
                    let value = run_store
                        .completed_proposal_response_value(&receipt)
                        .map_err(|error| {
                            format!("completed proposal response serialization failed: {error}")
                        })?;
                    Ok((value, cleanup_error))
                },
            )
            .await?;
            if let Some(error) = cleanup_error {
                tracing::warn!(run_id, %error, "completed proposal response remains recoverable while guard cleanup is pending");
            }
            return Ok(value);
        }

        let pending = {
            let run_store = state.run_store.clone();
            let run_id = run_id.to_string();
            run_store_blocking("pending proposal lookup", move || {
                run_store.pending_proposal(&run_id).map_err(|error| {
                    proposal_durability_quarantine(&run_id, "finalization", &error)
                })
            })
            .await?
        };
        if let Some(pending) = pending {
            if pending.client_id != durable_client
                || pending.original_submission != original_submission
                || pending.requested_policy_session_id.as_deref() != session_id.as_deref()
            {
                return Err(format!(
                    "proposal finalization pending for run_id `{run_id}`; only an exact retry of original submission `{}` may reconcile it",
                    pending.original_proposal_id
                ));
            }
            return finish_pending_proposal(
                session,
                state,
                &pending,
                &durable_client,
                &mut run_guard,
            )
            .await;
        }
        let marker = {
            let run_store = state.run_store.clone();
            let run_id = run_id.to_string();
            run_store_blocking("proposal execution marker lookup", move || {
                run_store
                    .execution_marker(&run_id)
                    .map_err(|error| proposal_durability_quarantine(&run_id, "execution", &error))
            })
            .await?
        };
        if let Some(marker) = marker {
            return Err(format!(
                "proposal execution outcome unknown for run_id `{run_id}` / original submission `{}`; CAR will not redispatch automatically",
                marker.original_proposal_id
            ));
        }
        if durable_client != session.client_id {
            return Err(format!(
                "resumed run `{run_id}` accepts only an exact recovery submission; CAR will not dispatch new actions"
            ));
        }
    }

    // Only a CAR-minted live policy session is authenticated enough to stamp
    // into the journal. An arbitrary request label is never copied. The
    // runtime preserves its existing unknown-session rejection semantics.
    let authenticated_policy_session = match session_id.as_deref() {
        Some(policy_session_id) if session.runtime.session_exists(policy_session_id).await => {
            Some(policy_session_id.to_string())
        }
        _ => None,
    };
    let execution_marker =
        current_run
            .as_deref()
            .map(|run_id| crate::run_store::ProposalExecutionMarker {
                run_id: run_id.to_string(),
                client_id: session.client_id.clone(),
                requested_policy_session_id: session_id.clone(),
                policy_session_id: authenticated_policy_session.clone(),
                original_proposal_id: submit.proposal.id.clone(),
                original_submission: original_submission.clone(),
                original_proposal: submitted_proposal_value.clone(),
                proposal_digest: submitted_proposal_digest.clone(),
            });
    let retry_rollback =
        execution_marker
            .as_ref()
            .map(|marker| crate::run_store::ProposalRetryRollback {
                run_id: marker.run_id.clone(),
                client_id: marker.client_id.clone(),
                requested_policy_session_id: marker.requested_policy_session_id.clone(),
                original_submission: original_submission.clone(),
            });
    if let (Some(marker), Some(rollback)) = (execution_marker.as_ref(), retry_rollback.as_ref()) {
        let run_store = state.run_store.clone();
        let marker = marker.clone();
        let rollback = rollback.clone();
        let expected_run_id = marker.run_id.clone();
        let reservation = run_lifecycle_durability_blocking(
            &mut run_guard,
            "proposal pre-execution reservation durability",
            move || {
                run_store
                    .claim_proposal_id(
                        &marker.run_id,
                        &marker.client_id,
                        &marker.original_proposal_id,
                        &marker.original_submission,
                    )
                    .map_err(|error| {
                        format!("proposal id could not be durably claimed: {error}")
                    })?;
                run_store
                    .write_proposal_retry_rollback(&rollback)
                    .map_err(|error| {
                        format!("proposal retry rollback could not be durably prepared: {error}")
                    })?;
                run_store
                    .reserve_proposal_retry_owner(
                        &marker.run_id,
                        &marker.client_id,
                        marker.requested_policy_session_id.as_deref(),
                        &marker.original_submission,
                    )
                    .map_err(|error| {
                        format!("proposal retry reservation could not be durably prepared: {error}")
                    })
            },
        )
        .await?;
        if let crate::run_store::ProposalRetryReservation::Existing {
            run_id: reserved_run,
            client_id: reserved_client,
        } = reservation
        {
            if reserved_run != expected_run_id || reserved_client != session.client_id {
                let run_store = state.run_store.clone();
                let rollback = retry_rollback
                    .as_ref()
                    .expect("active reservation has rollback authority")
                    .clone();
                run_lifecycle_durability_blocking(
                    &mut run_guard,
                    "losing proposal retry rollback cleanup",
                    move || {
                        run_store
                            .clear_proposal_retry_rollback(&rollback)
                            .map_err(|error| {
                                format!("losing retry rollback cleanup failed: {error}")
                            })
                    },
                )
                .await?;
                return Err(format!(
                    "{} proposal retry tuple belongs to run `{reserved_run}` / client `{reserved_client}`; concurrent submission cannot dispatch it",
                    car_proto::RUN_OWNERSHIP_CONFLICT_MESSAGE_PREFIX
                ));
            }
        }
    }
    if let Some(marker) = execution_marker.as_ref() {
        let run_store = state.run_store.clone();
        let durable_marker = marker.clone();
        let write_result = run_lifecycle_durability_blocking(
            &mut run_guard,
            "proposal execution marker durability",
            move || {
                run_store
                    .write_execution_marker(&durable_marker)
                    .map_err(|error| {
                        format!("proposal execution could not be durably prepared: {error}")
                    })
            },
        )
        .await;
        if let Err(error) = write_result {
            rollback_pre_execution_guards(state, &mut run_guard, marker, &original_submission)
                .await
                .map_err(|rollback| format!("{error}; exact guard rollback failed: {rollback}"))?;
            return Err(error);
        }
    }
    if current_run.is_some() {
        if let Some(policy_session_id) = authenticated_policy_session.as_deref() {
            if let Err(error) = session
                .runtime
                .event_log_handle()
                .lock()
                .await
                .bind_policy_session(policy_session_id)
            {
                if let Some(marker) = execution_marker.as_ref() {
                    rollback_pre_execution_guards(
                        state,
                        &mut run_guard,
                        marker,
                        &original_submission,
                    )
                    .await
                    .map_err(|rollback| {
                        format!("{error}; exact guard rollback failed: {rollback}")
                    })?;
                }
                return Err(error);
            }
        }
    }

    if let Some(rollback) = retry_rollback.as_ref() {
        let run_store = state.run_store.clone();
        let rollback = rollback.clone();
        let clear_result = run_lifecycle_durability_blocking(
            &mut run_guard,
            "proposal retry rollback intent cleanup",
            move || {
                run_store
                    .clear_proposal_retry_rollback(&rollback)
                    .map_err(|error| format!("proposal retry rollback cleanup failed: {error}"))
            },
        )
        .await;
        if let Err(error) = clear_result {
            if let Some(policy_session_id) = authenticated_policy_session.as_deref() {
                session
                    .runtime
                    .event_log_handle()
                    .lock()
                    .await
                    .clear_policy_session(policy_session_id)
                    .map_err(|unbind| {
                        format!("{error}; policy rollback failed before dispatch: {unbind}")
                    })?;
            }
            if let Some(marker) = execution_marker.as_ref() {
                rollback_pre_execution_guards(state, &mut run_guard, marker, &original_submission)
                    .await
                    .map_err(|rollback| {
                        format!("{error}; exact guard rollback failed: {rollback}")
                    })?;
            }
            return Err(error);
        }
    }

    let proposal_event_start = if current_run.is_some() {
        Some(session.runtime.event_log_handle().lock().await.len())
    } else {
        None
    };

    let result = match (session_id.as_deref(), scope) {
        (Some(sid), None) => {
            if current_run.is_some() {
                session
                    .runtime
                    .execute_with_session_and_stable_replan_id(&submit.proposal, sid)
                    .await
            } else {
                session
                    .runtime
                    .execute_with_session(&submit.proposal, sid)
                    .await
            }
        }
        (None, Some(s)) => {
            if current_run.is_some() {
                session
                    .runtime
                    .execute_scoped_with_stable_replan_id(&submit.proposal, &s)
                    .await
            } else {
                session.runtime.execute_scoped(&submit.proposal, &s).await
            }
        }
        (None, None) => {
            if current_run.is_some() {
                session
                    .runtime
                    .execute_with_stable_replan_id(&submit.proposal)
                    .await
            } else {
                session.runtime.execute(&submit.proposal).await
            }
        }
        (Some(_), Some(_)) => unreachable!("combined execution context rejected before binding"),
    };

    // The engine has already applied terminal semantics here: retry stopped,
    // the proposal aborted, and transactional state rolled back. Latch the
    // daemon-only session scope before any optional run-finalization work so a
    // terminal callback cannot be followed by another admitted proposal even
    // if durable finalization reports an error to this caller.
    if result.results.iter().any(|action| action.terminal) {
        session.halted.store(true, Ordering::Release);
    }

    if current_run.is_some() {
        let proposal_result_value = serde_json::to_value(&result).map_err(|e| e.to_string())?;
        let result_digest = canonical_sha256(&proposal_result_value)?;
        let final_proposal = result
            .final_proposal
            .clone()
            .ok_or_else(|| "active v3 runtime result is missing final_proposal".to_string())?;
        let event_start = proposal_event_start
            .expect("active run captured its proposal event boundary before dispatch");
        let accepted_proposal_preimages = {
            let log = session.runtime.event_log_handle();
            let log = log.lock().await;
            collect_accepted_proposal_preimages(
                &submit.proposal,
                &result,
                &log.events()[event_start..],
            )?
        };
        let run_id = current_run
            .as_deref()
            .expect("current run checked before proposal finalization");
        let pending = crate::run_store::PendingProposalFinalization {
            run_id: run_id.to_string(),
            client_id: session.client_id.clone(),
            requested_policy_session_id: session_id,
            policy_session_id: authenticated_policy_session.clone(),
            original_proposal_id: result.original_proposal_id.clone(),
            final_proposal_id: result.proposal_id.clone(),
            original_submission,
            original_proposal: submit.proposal.clone(),
            final_proposal,
            accepted_proposal_preimages,
            proposal_result: result.clone(),
            result_digest,
        };
        let run_store = state.run_store.clone();
        let durable_pending = pending.clone();
        run_lifecycle_durability_blocking(
            &mut run_guard,
            "proposal finalization outbox durability",
            move || {
                run_store
                    .write_pending_proposal(&durable_pending)
                    .map_err(|error| {
                        format!("proposal finalization could not be durably prepared: {error}")
                    })
            },
        )
        .await?;
        return finish_pending_proposal(
            session,
            state,
            &pending,
            &session.client_id,
            &mut run_guard,
        )
        .await;
    }

    serde_json::to_value(result).map_err(|e| e.to_string())
}

async fn rollback_pre_execution_guards(
    state: &Arc<ServerState>,
    run_guard: &mut Option<tokio::sync::OwnedMutexGuard<()>>,
    marker: &crate::run_store::ProposalExecutionMarker,
    original_submission: &Value,
) -> Result<(), String> {
    let run_store = state.run_store.clone();
    let marker = marker.clone();
    let submission = original_submission.clone();
    let rollback = crate::run_store::ProposalRetryRollback {
        run_id: marker.run_id.clone(),
        client_id: marker.client_id.clone(),
        requested_policy_session_id: marker.requested_policy_session_id.clone(),
        original_submission: submission.clone(),
    };
    run_lifecycle_durability_blocking(
        run_guard,
        "proposal pre-execution guard rollback",
        move || {
            run_store
                .clear_execution_marker(&marker)
                .map_err(|error| format!("execution marker rollback failed: {error}"))?;
            run_store
                .release_proposal_retry_owner(
                    &marker.run_id,
                    &marker.client_id,
                    marker.requested_policy_session_id.as_deref(),
                    &submission,
                )
                .map_err(|error| format!("retry owner rollback failed: {error}"))?;
            run_store
                .clear_proposal_retry_rollback(&rollback)
                .map_err(|error| format!("retry rollback intent cleanup failed: {error}"))
        },
    )
    .await
}

async fn finish_pending_proposal(
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
    pending: &crate::run_store::PendingProposalFinalization,
    durable_client_id: &str,
    run_guard: &mut Option<tokio::sync::OwnedMutexGuard<()>>,
) -> Result<Value, String> {
    let (started, _marker) = {
        let run_store = state.run_store.clone();
        let pending = pending.clone();
        run_store_blocking("proposal finalization provenance lookup", move || {
            run_store.pending_provenance(&pending).map_err(|error| {
                format!("proposal finalization provenance validation failed: {error}")
            })
        })
        .await?
    };
    let durable_client = started
        .client_id
        .as_deref()
        .ok_or_else(|| "durable RunStarted is missing its client identity".to_string())?;
    let active_owner = state
        .run_owner_binding(&pending.run_id)
        .await
        .ok_or_else(|| {
            format!(
                "active run `{}` is absent from CAR's run registry",
                pending.run_id
            )
        })?;
    if durable_client != durable_client_id
        || active_owner.0 != durable_client_id
        || active_owner.1 != session.client_id
    {
        return Err(
            "proposal finalization owner does not match the authenticated run binding".into(),
        );
    }
    session.require_run_journal_binding(&pending.run_id).await?;
    let event_log = session.runtime.event_log_handle();
    let mut log = event_log.lock().await;
    let active_policy = log
        .active_run_binding()
        .and_then(|(_, _, policy_session_id)| policy_session_id.map(str::to_string));
    match (
        active_policy.as_deref(),
        pending.policy_session_id.as_deref(),
    ) {
        (Some(active), Some(expected)) if active == expected => {}
        (None, Some(expected)) => log.bind_policy_session(expected)?,
        (None, None) => {}
        _ => {
            return Err(
                "proposal finalization policy identity does not match the active journal binding"
                    .into(),
            );
        }
    }
    state.ensure_proposal_run_turns(pending).await?;
    match log
        .append_critical_async(
            car_eventlog::EventKind::ProposalCompleted,
            None,
            Some(&pending.final_proposal_id),
            pending.event_data(),
            PROPOSAL_TERMINAL_ACKNOWLEDGEMENT_TIMEOUT,
        )
        .await
    {
        Ok(_) => {}
        Err(car_eventlog::CriticalAppendError::DurabilityUnknown { reason }) => {
            return Err(format!(
                "proposal finalization durability is unknown; retry the exact proposal.submit safely: {reason}"
            ));
        }
        Err(car_eventlog::CriticalAppendError::Rejected { reason }) => {
            return Err(format!(
                "proposal finalization critical journal append rejected: {reason}"
            ));
        }
    }
    if let Some(policy_session_id) = pending.policy_session_id.as_deref() {
        log.clear_policy_session(policy_session_id)?;
    }
    drop(log);
    let run_store = state.run_store.clone();
    let pending = pending.clone();
    let pending_run_id = pending.run_id.clone();
    let (value, cleanup_error) = run_lifecycle_durability_blocking(
        run_guard,
        "completed proposal response durability",
        move || {
            let receipt = run_store
                .write_completed_proposal(&pending)
                .map_err(|error| {
                    format!("completed proposal response persistence failed: {error}")
                })?;
            let cleanup_error = run_store
                .cleanup_completed_proposal_guards(&receipt)
                .err()
                .map(|error| error.to_string());
            let value = run_store
                .completed_proposal_response_value(&receipt)
                .map_err(|error| {
                    format!("completed proposal response serialization failed: {error}")
                })?;
            Ok((value, cleanup_error))
        },
    )
    .await?;
    if let Some(error) = cleanup_error {
        tracing::warn!(run_id = %pending_run_id, %error, "completed proposal response is durable; guard cleanup remains pending");
    }
    Ok(value)
}

fn collect_accepted_proposal_preimages(
    original: &car_ir::ActionProposal,
    result: &car_ir::ProposalResult,
    proposal_events: &[car_eventlog::Event],
) -> Result<Vec<crate::run_store::AcceptedProposalPreimage>, String> {
    let mut accepted = Vec::new();
    for lineage in &result.replan_lineage {
        if lineage.status != car_ir::ProposalLineageStatus::Accepted {
            continue;
        }
        if lineage.generation == 0 {
            accepted.push(crate::run_store::AcceptedProposalPreimage {
                generation: 0,
                proposal: original.clone(),
            });
            continue;
        }
        let matches: Vec<_> = proposal_events
            .iter()
            .filter(|event| {
                event.kind == car_eventlog::EventKind::ReplanProposalReceived
                    && event.proposal_id.as_deref() == Some(result.original_proposal_id.as_str())
                    && event.data.get("attempt").and_then(Value::as_u64)
                        == Some(u64::from(lineage.generation))
                    && event.data.get("proposal_id").and_then(Value::as_str)
                        == Some(lineage.proposal_id.as_str())
                    && event.data.get("proposal_digest").and_then(Value::as_str)
                        == lineage.proposal_digest.as_deref()
            })
            .collect();
        if matches.len() != 1 {
            return Err(format!(
                "accepted replan generation {} has {} exact proposal preimage events",
                lineage.generation,
                matches.len()
            ));
        }
        let proposal = matches[0].data.get("proposal").cloned().ok_or_else(|| {
            format!(
                "accepted replan generation {} is missing its proposal preimage",
                lineage.generation
            )
        })?;
        accepted.push(crate::run_store::AcceptedProposalPreimage {
            generation: lineage.generation,
            proposal: serde_json::from_value(proposal).map_err(|error| {
                format!(
                    "accepted replan generation {} has invalid proposal preimage: {error}",
                    lineage.generation
                )
            })?,
        });
    }
    Ok(accepted)
}

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

    #[test]
    fn accepted_replan_uses_exact_authenticated_event_preimage() {
        let timestamp = chrono::Utc::now();
        let original: car_ir::ActionProposal = serde_json::from_value(serde_json::json!({
            "id": "original",
            "source": "caller",
            "actions": [],
            "timestamp": timestamp,
            "context": {}
        }))
        .unwrap();
        let final_proposal: car_ir::ActionProposal = serde_json::from_value(serde_json::json!({
            "id": "accepted-replan",
            "source": "replanner",
            "actions": [],
            "timestamp": timestamp,
            "context": {"generation": 1}
        }))
        .unwrap();
        let original_digest = canonical_sha256(&original).unwrap();
        let final_digest = canonical_sha256(&final_proposal).unwrap();
        let result = car_ir::ProposalResult {
            proposal_id: final_proposal.id.clone(),
            original_proposal_id: original.id.clone(),
            final_proposal: Some(final_proposal.clone()),
            accepted_proposal_preimages: vec![],
            replan_lineage: vec![
                car_ir::ProposalLineageEntry {
                    generation: 0,
                    proposal_id: original.id.clone(),
                    proposal_digest: Some(original_digest),
                    status: car_ir::ProposalLineageStatus::Accepted,
                    rejection_reason: None,
                },
                car_ir::ProposalLineageEntry {
                    generation: 1,
                    proposal_id: final_proposal.id.clone(),
                    proposal_digest: Some(final_digest.clone()),
                    status: car_ir::ProposalLineageStatus::Accepted,
                    rejection_reason: None,
                },
            ],
            results: vec![],
            cost: car_ir::CostSummary::default(),
        };
        let event = car_eventlog::Event {
            kind: car_eventlog::EventKind::ReplanProposalReceived,
            run_id: Some("run".to_string()),
            client_id: Some("client".to_string()),
            policy_session_id: None,
            action_id: None,
            proposal_id: Some(original.id.clone()),
            data: HashMap::from([
                ("attempt".to_string(), Value::from(1)),
                (
                    "proposal_id".to_string(),
                    Value::from(final_proposal.id.clone()),
                ),
                ("proposal_digest".to_string(), Value::from(final_digest)),
                (
                    "proposal".to_string(),
                    serde_json::to_value(&final_proposal).unwrap(),
                ),
            ]),
            timestamp,
            prev_hash: None,
            hash: None,
        };

        let accepted = collect_accepted_proposal_preimages(&original, &result, &[event]).unwrap();
        assert_eq!(accepted.len(), 2);
        assert_eq!(accepted[0].generation, 0);
        assert_eq!(accepted[0].proposal, original);
        assert_eq!(accepted[1].generation, 1);
        assert_eq!(accepted[1].proposal, final_proposal);
    }
}

/// Lowercase SHA-256 of RFC 8785/JCS. Proposal terminal events use the exact
/// serialized `ProposalResult`; run terminal identity uses the exact
/// `RunTermination` via `session::run_completion_digest`.
fn canonical_sha256<T: serde::Serialize + ?Sized>(value: &T) -> Result<String, String> {
    let canonical = car_inference::catalog_identity::canonical_json(value)?;
    Ok(format!("{:x}", Sha256::digest(canonical.as_bytes())))
}

fn proposal_durability_quarantine(
    run_id: &str,
    state_kind: &str,
    error: &std::io::Error,
) -> String {
    format!(
        "proposal {state_kind} durability state is unreadable for run_id `{run_id}`; outcome unknown and CAR will not redispatch, complete, replace, or fabricate a terminal: {error}"
    )
}

/// Keep proposal-terminal journal uncertainty inside the handler deadline.
/// This matches the run lifecycle acknowledgement policy in `session.rs`.
const PROPOSAL_TERMINAL_ACKNOWLEDGEMENT_TIMEOUT: std::time::Duration =
    std::time::Duration::from_secs(5);

async fn handle_session_policy_open(
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let id = session.runtime.open_session().await;
    Ok(serde_json::json!({ "session_id": id }))
}

async fn handle_session_policy_close(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let sid = req
        .params
        .get("session_id")
        .and_then(|v| v.as_str())
        .ok_or("missing 'session_id'")?;
    let closed = session.runtime.close_session(sid).await;
    Ok(serde_json::json!({ "closed": closed }))
}

/// `policy.register` — register one policy against this WebSocket
/// session's runtime. Mirrors the `PolicyDefinition` shape used by
/// `session.init`. When `session_id` is present, the policy is scoped
/// to the named in-runtime session opened via `session.policy.open`;
/// otherwise it is global.
async fn handle_policy_register(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let def: PolicyDefinition = serde_json::from_value(req.params.clone())
        .map_err(|e| format!("invalid policy params: {e}"))?;
    let session_id = req
        .params
        .get("session_id")
        .and_then(|v| v.as_str())
        .map(str::to_string);
    let check = build_policy_check(&def)
        .ok_or_else(|| format!("unsupported policy rule '{}'", def.rule))?;
    let denies_tool = blanket_denied_tool(&def);
    match session_id {
        Some(sid) => {
            let registered = match &denies_tool {
                Some(tool) => {
                    session
                        .runtime
                        .register_tool_deny_in_session(&sid, &def.name, tool, check, "")
                        .await
                }
                None => {
                    session
                        .runtime
                        .register_policy_in_session(&sid, &def.name, check, "")
                        .await
                }
            };
            registered.map(
                |_| serde_json::json!({ "registered": def.name, "scope": { "session_id": sid } }),
            )
        }
        None => {
            let mut policies = session.runtime.policies.write().await;
            match &denies_tool {
                Some(tool) => policies.register_tool_deny(&def.name, tool, check, ""),
                None => policies.register(&def.name, check, ""),
            }
            Ok(serde_json::json!({ "registered": def.name, "scope": "global" }))
        }
    }
}

/// `policy.unregister` — remove a policy by name. `{ name, session_id? }`.
///
/// Counterpart to `policy.register`, which had none: a global policy, once
/// registered over the wire, could only be cleared by restarting the daemon, so
/// a mistyped or over-broad rule stayed in force and took every other piece of
/// in-memory state with it when you finally bounced the process
/// (Parslee-ai/car#623). Session-scoped policies could already be dropped
/// wholesale by closing the session; this removes one by name.
///
/// Returns `{ unregistered, removed, scope }`. `removed: 0` means nothing
/// matched — reported rather than treated as an error, so a client cleaning up
/// can call this unconditionally.
async fn handle_policy_unregister(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let name = req
        .params
        .get("name")
        .and_then(|v| v.as_str())
        .ok_or("missing 'name'")?;
    let session_id = req.params.get("session_id").and_then(|v| v.as_str());
    let removed = session
        .runtime
        .unregister_policy(name, session_id)
        .await
        .map_err(|e| e.to_string())?;
    Ok(serde_json::json!({
        "unregistered": name,
        "removed": removed,
        "scope": session_id.map(|s| serde_json::json!({ "session_id": s }))
            .unwrap_or_else(|| Value::String("global".to_string())),
    }))
}

/// `policy.list` — what is currently in force. `{ session_id? }`.
///
/// Without this a client could register a policy but never ask what was
/// enforced, so an action rejection could not be explained beyond its own
/// message (Parslee-ai/car#623).
async fn handle_policy_list(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let session_id = req.params.get("session_id").and_then(|v| v.as_str());
    let policies = session
        .runtime
        .list_policies(session_id)
        .await
        .map_err(|e| e.to_string())?;
    Ok(serde_json::json!({
        "policies": policies
            .into_iter()
            .map(|(name, description)| serde_json::json!({
                "name": name,
                "description": description,
            }))
            .collect::<Vec<_>>(),
        "scope": session_id.map(|s| serde_json::json!({ "session_id": s }))
            .unwrap_or_else(|| Value::String("global".to_string())),
    }))
}

async fn handle_verify(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let vr: VerifyRequest =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    // Verify against the full registered schemas so tool_call
    // parameters are checked for type mismatches + missing required
    // fields, not just tool existence (register_tool_schema's
    // documented contract; car-releases#56). The read guard is held
    // across the synchronous verify call.
    let tools_guard = session.runtime.tools.read().await;
    let result = car_verify::verify_with_schemas(
        &vr.proposal,
        Some(&vr.initial_state),
        Some(&tools_guard),
        30,
    );
    drop(tools_guard);
    let evidence = serde_json::to_value(&result.evidence).unwrap_or(Value::Null);
    serde_json::to_value(VerifyResponse {
        valid: result.valid,
        issues: result
            .issues
            .iter()
            .map(|i| VerifyIssueProto {
                action_id: i.action_id.clone(),
                severity: i.severity.clone(),
                message: i.message.clone(),
                tier: i.tier.as_str().to_string(),
            })
            .collect(),
        simulated_state: result.simulated_state,
        execution_levels: result.execution_levels,
        conflicts: result.conflicts,
        evidence,
    })
    .map_err(|e| e.to_string())
}

/// Default recency window for trajectory-derived success rates, in days.
///
/// A success rate is a claim about how a tool behaves *now*. Unbounded history
/// makes it progressively less responsive to the recent change an operator is
/// usually trying to see, and keeps an outage that was fixed months ago
/// depressing the rate forever.
const MONTE_CARLO_RATE_WINDOW_DAYS: u32 = 30;

/// Params for `verify.monte_carlo`.
///
/// `tool_success_rates` is optional. When omitted, rates are derived from the
/// daemon's trajectory store over the last `rate_window_days` — the point of
/// wiring that store into every session's `Runtime`. An explicitly supplied map
/// always wins: a caller modelling a hypothetical ("what if this tool were 99%
/// reliable?") must be able to override observed history, and per-tool entries
/// merge over the derived ones rather than replacing the whole map.
#[derive(Debug, Deserialize)]
struct MonteCarloParams {
    proposal: car_ir::ActionProposal,
    #[serde(default)]
    initial_state: HashMap<String, Value>,
    #[serde(default)]
    tool_success_rates: HashMap<String, f64>,
    #[serde(default)]
    goal: Option<car_verify::GoalCondition>,
    #[serde(default)]
    config: car_verify::MonteCarloConfig,
    /// Recency window for derived rates. Defaults to
    /// [`MONTE_CARLO_RATE_WINDOW_DAYS`]. Set `0` to skip derivation entirely
    /// and use only what the caller passed.
    #[serde(default)]
    rate_window_days: Option<u32>,
}

async fn handle_verify_monte_carlo(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let p: MonteCarloParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;

    let window = p.rate_window_days.unwrap_or(MONTE_CARLO_RATE_WINDOW_DAYS);
    let derived = if window > 0 {
        session.runtime.tool_feedback(window)
    } else {
        None
    };

    // Caller-supplied entries win per tool, so a hypothetical can override one
    // tool's observed rate without discarding the evidence for the others.
    let mut rates = derived
        .as_ref()
        .map(|f| f.tool_success_rates.clone())
        .unwrap_or_default();
    let overridden: Vec<String> = p
        .tool_success_rates
        .keys()
        .filter(|t| rates.contains_key(*t))
        .cloned()
        .collect();
    rates.extend(p.tool_success_rates.iter().map(|(k, v)| (k.clone(), *v)));

    let result = car_verify::simulate_monte_carlo(
        &p.proposal,
        Some(&p.initial_state),
        &rates,
        p.goal.as_ref(),
        &p.config,
    );

    // Where every rate actually came from. A probability with no provenance is
    // not actionable — the caller cannot tell 0.9-from-500-observations from
    // 0.9-because-nothing-was-recorded, and those warrant very different
    // confidence in the verdict.
    let counts = derived
        .as_ref()
        .map(|f| f.tool_dispatch_counts.clone())
        .unwrap_or_default();
    let mut tools: Vec<Value> = p
        .proposal
        .actions
        .iter()
        .filter(|a| a.action_type == car_ir::ActionType::ToolCall)
        .filter_map(|a| a.tool.clone())
        .collect::<std::collections::BTreeSet<_>>()
        .into_iter()
        .map(|tool| {
            let caller_set = p.tool_success_rates.contains_key(&tool);
            let observed = counts.get(&tool).copied();
            let source = if caller_set {
                "caller"
            } else if observed.is_some() {
                "trajectories"
            } else {
                "default"
            };
            serde_json::json!({
                "tool": tool,
                "rate": rates.get(&tool).copied()
                    .unwrap_or(p.config.default_success_rate),
                "source": source,
                "succeeded": observed.map(|(s, _)| s),
                "dispatched": observed.map(|(_, d)| d),
            })
        })
        .collect();
    tools.sort_by(|a, b| a["tool"].as_str().cmp(&b["tool"].as_str()));

    let mut out = serde_json::to_value(&result).map_err(|e| e.to_string())?;
    if let Some(obj) = out.as_object_mut() {
        obj.insert(
            "rate_provenance".to_string(),
            serde_json::json!({
                "window_days": window,
                "trajectories_available": derived.is_some(),
                "overridden_by_caller": overridden,
                "tools": tools,
            }),
        );
    }
    Ok(out)
}

// --- sync.* / lease.* : multi-device sync + execution lease (B6) ---
//
// Thin param-parsers over the daemon-held `SyncSubsystem` (one per daemon = one
// device). Each locks the subsystem's tokio mutex and calls a `&mut self`
// method; the sync mechanics, fold, fence, and lease coordination all live in
// `crate::sync`. See `docs/proposals/multi-device-sync.md` §B6.

async fn handle_sync_status(state: &ServerState) -> Result<Value, String> {
    let sub = state.sync_subsystem()?;
    let mut s = sub.lock().await;
    s.status()
}

/// `sync.knowledge` — the read side of the assistant's synced memory. Returns
/// the folded knowledge facts (`{subject, body}`, ascending by hlc). With
/// `pump: true` it pumps-then-reads under ONE lock acquisition, so recall sees a
/// fresh pull with no interleave window; the pump is best-effort (a relay hiccup
/// still returns the already-folded facts). Read-only otherwise.
async fn handle_sync_knowledge(req: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let pump = req
        .params
        .get("pump")
        .and_then(Value::as_bool)
        .unwrap_or(false);
    // Personal knowledge first; release its guard before touching the org one.
    let personal = {
        let sub = state.sync_subsystem()?;
        let mut s = sub.lock().await;
        if pump {
            let _ = s.pump();
        }
        s.knowledge()
    };
    // Merge the shared org subsystem's knowledge when opted in (8b): personal ∪ org.
    // With org-scope OFF, `org_subsystem()` is None → personal-only, byte-identical.
    let org = match state.org_subsystem() {
        Some(org_sub) => {
            let mut s = org_sub.lock().await;
            if pump {
                let _ = s.pump();
            }
            Some(s.knowledge())
        }
        None => None,
    };
    Ok(serde_json::json!({ "facts": merge_knowledge(personal, org) }))
}

/// Merge personal knowledge with the opted-in org knowledge (personal ∪ org).
/// `None` org → personal unchanged (the org-scope-off invariant). Pure, so it is
/// unit-testable without a daemon.
///
/// ORDER IS LOAD-BEARING (linus): each scope's `knowledge()` is ascending by
/// `(hlc, op_id)`, but the two are NOT globally HLC-ordered, and the recall
/// reducer (`car-cli reduce_newest_per_subject`) is POSITIONAL last-wins — it
/// keeps the LAST occurrence per subject, trusting ascending order. So this
/// concatenates ORG FIRST, PERSONAL LAST: within a scope newest still wins, and
/// for a subject present in BOTH scopes the personal entry lands last → PERSONAL
/// wins. That is deliberate — it matches the recall path's Option-B policy
/// ("a peer's newer edit to a locally-held subject is intentionally NOT applied";
/// personal/local is authoritative). Do NOT flip to personal-first (that would
/// silently make a staler org fact shadow a newer personal one).
fn merge_knowledge(personal: Vec<Value>, org: Option<Vec<Value>>) -> Vec<Value> {
    match org {
        Some(mut org) => {
            org.extend(personal);
            org
        }
        None => personal,
    }
}

async fn handle_sync_append(req: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let surface_str = req
        .params
        .get("surface")
        .and_then(Value::as_str)
        .ok_or("missing 'surface'")?;
    let surface = crate::sync::parse_surface(surface_str)?;
    let payload = req.params.get("payload").cloned().unwrap_or(Value::Null);
    let scope = crate::sync::parse_scope(&req.params);
    let sub = state.subsystem_for_scope(&scope)?;
    let mut s = sub.lock().await;
    s.append(scope, surface, payload)
}

async fn handle_sync_record_turn(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let conversation_id = req
        .params
        .get("conversation_id")
        .and_then(Value::as_str)
        .unwrap_or("");
    let role = req
        .params
        .get("role")
        .and_then(Value::as_str)
        .unwrap_or("user");
    let content = req
        .params
        .get("content")
        .and_then(Value::as_str)
        .unwrap_or("");
    let tool_calls = req
        .params
        .get("tool_calls")
        .and_then(Value::as_array)
        .cloned()
        .unwrap_or_default();
    let tool_use_id = req.params.get("tool_use_id").and_then(Value::as_str);
    let timestamp = req
        .params
        .get("timestamp")
        .and_then(Value::as_u64)
        .unwrap_or(0);
    let scope = crate::sync::parse_scope(&req.params);
    let sub = state.subsystem_for_scope(&scope)?;
    let mut s = sub.lock().await;
    s.record_turn(
        scope,
        conversation_id,
        role,
        content,
        tool_calls,
        tool_use_id,
        timestamp,
    )
}

async fn handle_sync_record_intent(
    req: &JsonRpcMessage,
    state: &ServerState,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let agent_id = req
        .params
        .get("agent_id")
        .and_then(Value::as_str)
        .ok_or("missing 'agent_id'")?;
    require_sync_agent_or_host(session, state, "sync.record_intent", agent_id).await?;
    record_sync_intent(req, state, agent_id).await
}

async fn record_sync_intent(
    req: &JsonRpcMessage,
    state: &ServerState,
    agent_id: &str,
) -> Result<Value, String> {
    let run_id = req
        .params
        .get("run_id")
        .and_then(Value::as_str)
        .ok_or("missing 'run_id'")?;
    let epoch = req
        .params
        .get("epoch")
        .and_then(Value::as_u64)
        .ok_or("missing 'epoch'")?;
    let status_str = req
        .params
        .get("status")
        .and_then(Value::as_str)
        .ok_or("missing 'status'")?;
    let status = crate::sync::parse_intent_status(status_str)?;
    let intent = car_sync::Intent::new(agent_id, run_id, epoch, status);
    let scope = crate::sync::parse_scope(&req.params);
    let sub = state.subsystem_for_scope(&scope)?;
    let mut s = sub.lock().await;
    s.record_intent(scope, &intent)
}

async fn handle_sync_pump(state: &ServerState) -> Result<Value, String> {
    // Pump the personal subsystem first and RELEASE its guard before touching the
    // org one — never hold both `tokio::Mutex` subsystem guards across an await
    // (deadlock vector). A personal-pump failure is fatal, as before.
    let user_result = {
        let sub = state.sync_subsystem()?;
        let mut s = sub.lock().await;
        s.pump()?
    };
    // Then the shared org subsystem, if opted in (8a). Its leases are independent
    // of the personal scope, so there is no cross-scope ordering requirement. An
    // org-pump failure must NOT suppress the personal-pump result — surface both.
    let Some(org_sub) = state.org_subsystem() else {
        return Ok(user_result);
    };
    let org_result = {
        let mut s = org_sub.lock().await;
        s.pump()
    };
    match org_result {
        Ok(org) => Ok(serde_json::json!({ "user": user_result, "org": org })),
        Err(e) => Ok(serde_json::json!({ "user": user_result, "org_error": e })),
    }
}

async fn handle_sync_checkpoint(state: &ServerState) -> Result<Value, String> {
    let sub = state.sync_subsystem()?;
    let mut s = sub.lock().await;
    s.checkpoint()
}

async fn handle_sync_rebase(state: &ServerState) -> Result<Value, String> {
    let sub = state.sync_subsystem()?;
    let mut s = sub.lock().await;
    s.rebase()
}

async fn handle_sync_transcript(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let conversation_id = req
        .params
        .get("conversation_id")
        .and_then(Value::as_str)
        .unwrap_or("");
    let sub = state.sync_subsystem()?;
    let s = sub.lock().await;
    Ok(s.transcript(conversation_id))
}

async fn handle_sync_resume(req: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let conversation_id = req
        .params
        .get("conversation_id")
        .and_then(Value::as_str)
        .unwrap_or("");
    let sub = state.sync_subsystem()?;
    let s = sub.lock().await;
    s.resume(conversation_id)
}

async fn handle_sync_assistant_checkpoint_put(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let raw = req
        .params
        .get("checkpoint")
        .cloned()
        .ok_or("missing 'checkpoint'")?;
    let checkpoint =
        serde_json::from_value(raw).map_err(|e| format!("invalid assistant checkpoint: {e}"))?;
    let sub = state.sync_subsystem()?;
    let mut s = sub.lock().await;
    s.assistant_checkpoint_put(checkpoint)
}

async fn handle_sync_assistant_checkpoint_get(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let session_id = req
        .params
        .get("session_id")
        .and_then(Value::as_str)
        .ok_or("missing 'session_id'")?;
    let sub = state.sync_subsystem()?;
    let s = sub.lock().await;
    serde_json::to_value(s.assistant_checkpoint_get(session_id)?)
        .map_err(|e| format!("serialize assistant checkpoint: {e}"))
}

async fn handle_sync_assistant_action_put(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let raw = req
        .params
        .get("record")
        .cloned()
        .ok_or("missing 'record'")?;
    let record = serde_json::from_value(raw)
        .map_err(|e| format!("invalid supervised action record: {e}"))?;
    let sub = state.sync_subsystem()?;
    let mut s = sub.lock().await;
    s.assistant_action_put(record)
}

async fn handle_sync_assistant_action_get(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let action_id = req
        .params
        .get("action_id")
        .and_then(Value::as_str)
        .ok_or("missing 'action_id'")?;
    let sub = state.sync_subsystem()?;
    let s = sub.lock().await;
    serde_json::to_value(s.assistant_action_get(action_id)?)
        .map_err(|e| format!("serialize supervised action record: {e}"))
}

async fn handle_sync_fence_check(
    req: &JsonRpcMessage,
    state: &ServerState,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let agent_id = req
        .params
        .get("agent_id")
        .and_then(Value::as_str)
        .ok_or("missing 'agent_id'")?;
    require_sync_agent_or_host(session, state, "sync.fence_check", agent_id).await?;
    check_sync_fence(req, state, agent_id).await
}

async fn check_sync_fence(
    req: &JsonRpcMessage,
    state: &ServerState,
    agent_id: &str,
) -> Result<Value, String> {
    let run_id = req
        .params
        .get("run_id")
        .and_then(Value::as_str)
        .ok_or("missing 'run_id'")?;
    let epoch = req
        .params
        .get("epoch")
        .and_then(Value::as_u64)
        .ok_or("missing 'epoch'")?;
    let sub = state.sync_subsystem()?;
    let mut s = sub.lock().await;
    s.fence_check(agent_id, run_id, epoch)
}

async fn handle_lease_acquire(
    req: &JsonRpcMessage,
    state: &ServerState,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let agent_id = req
        .params
        .get("agent_id")
        .and_then(Value::as_str)
        .ok_or("missing 'agent_id'")?;
    require_sync_agent_or_host(session, state, "lease.acquire", agent_id).await?;
    acquire_lease(req, state, agent_id).await
}

async fn acquire_lease(
    req: &JsonRpcMessage,
    state: &ServerState,
    agent_id: &str,
) -> Result<Value, String> {
    let ttl_ms = req
        .params
        .get("ttl_ms")
        .and_then(Value::as_u64)
        .unwrap_or(30_000);
    let sub = state.sync_subsystem()?;
    let mut s = sub.lock().await;
    s.lease_acquire(agent_id, ttl_ms)
}

async fn handle_lease_renew(
    req: &JsonRpcMessage,
    state: &ServerState,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let agent_id = req
        .params
        .get("agent_id")
        .and_then(Value::as_str)
        .ok_or("missing 'agent_id'")?;
    require_sync_agent_or_host(session, state, "lease.renew", agent_id).await?;
    renew_lease(req, state, agent_id).await
}

async fn renew_lease(
    req: &JsonRpcMessage,
    state: &ServerState,
    agent_id: &str,
) -> Result<Value, String> {
    let epoch = req
        .params
        .get("epoch")
        .and_then(Value::as_u64)
        .ok_or("missing 'epoch'")?;
    let ttl_ms = req
        .params
        .get("ttl_ms")
        .and_then(Value::as_u64)
        .unwrap_or(30_000);
    let sub = state.sync_subsystem()?;
    let mut s = sub.lock().await;
    s.lease_renew(agent_id, epoch, ttl_ms)
}

async fn handle_lease_release(
    req: &JsonRpcMessage,
    state: &ServerState,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let agent_id = req
        .params
        .get("agent_id")
        .and_then(Value::as_str)
        .ok_or("missing 'agent_id'")?;
    require_sync_agent_or_host(session, state, "lease.release", agent_id).await?;
    release_lease(req, state, agent_id).await
}

async fn release_lease(
    req: &JsonRpcMessage,
    state: &ServerState,
    agent_id: &str,
) -> Result<Value, String> {
    let epoch = req
        .params
        .get("epoch")
        .and_then(Value::as_u64)
        .ok_or("missing 'epoch'")?;
    let sub = state.sync_subsystem()?;
    let mut s = sub.lock().await;
    s.lease_release(agent_id, epoch)
}

async fn handle_lease_status(
    req: &JsonRpcMessage,
    state: &ServerState,
    bound_agent: Option<&str>,
) -> Result<Value, String> {
    let agent_id = req
        .params
        .get("agent_id")
        .and_then(Value::as_str)
        .ok_or("missing 'agent_id'")?;
    // Reading a lease is the same identity parameter as taking one, and the
    // answer names the holder and its fencing epoch — everything needed to
    // decide when to try stealing it.
    require_own_agent(bound_agent, "lease.status", agent_id)?;
    let sub = state.sync_subsystem()?;
    let mut s = sub.lock().await;
    s.lease_status(agent_id)
}

/// Host-only, aggregate process-lifetime secret-store activity. The public
/// value is intentionally the exact five-counter struct from `car-secrets`:
/// no service, key, path, value, identity, or credential state is available to
/// serialize here.
fn handle_secret_store_activity(
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    serde_json::to_value(car_secrets::secret_store_activity()).map_err(|error| error.to_string())
}

// --- permission.* : per-session permission-tier gate (survey §3.4.3/§5.2.5) ---

// The canonical value lives in the leaf `car-proto` crate so the lightweight
// daemon client can consume it without creating car-server-core →
// car-ffi-common → car-daemon-client → car-server-core. Re-exporting it beside
// the authority gate makes this the daemon's public authorization contract.
pub use car_proto::HOST_MANAGEMENT_METHODS;

/// Authority gate for the *mutating* permission methods (set_tier, approve,
/// reject). When the daemon runs under a host token (the CarHost regime,
/// where there is a distinguished human-management client), only that host
/// connection may change a session's tier or record approvals — a
/// registered agent connection must not self-elevate or self-approve, which
/// would make the §5.2.5 gate theater (neo review #3). In pure-dev /
/// embedder mode (no host token configured) the connection governs its own
/// session, the developer being the authority.
fn require_approval_authority(
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<(), String> {
    if state.host_token.get().is_some()
        && !session.is_host.load(std::sync::atomic::Ordering::Acquire)
    {
        return Err("this operation requires the host-management role".into());
    }
    Ok(())
}

/// Refuse a bound session acting on an agent that is not itself.
///
/// Whether a caller-supplied agent id is one this session may act as.
/// The bound identity WINS over the parameter — the rule `runs.start` already
/// applies to trace attribution (FIX 5). A session that authenticated as an
/// agent is authoritative about who it is, so an id naming a *different* agent
/// is a forgery attempt and is rejected loudly rather than honored. A matching
/// id is redundant and fine.
///
/// An UNBOUND session passes this identity-only helper. It remains appropriate
/// for `agents.wait`/`tail_log` and the lease/sync surfaces, where an unbound
/// operator may act on an explicit id. Mutating lifecycle methods use the
/// stronger host-aware helpers below: start/stop/restart admit self or host,
/// while upsert/install/remove require host authority.
///
/// Takes the RESOLVED bound id rather than the session: it is the whole input
/// the rule needs, and a `ClientSession` cannot be built outside a live
/// connection, so this keeps every caller exercisable.
///
/// Naming the id back is safe here, unlike [`authorize_run_access`]'s FIX 3 —
/// the caller supplied it, and the refusal happens before any lookup, so it
/// reveals nothing about whether that agent exists.
fn require_own_agent(bound: Option<&str>, method: &str, target: &str) -> Result<(), String> {
    match bound {
        Some(b) if b != target => Err(format!(
            "{method} `{target}` does not match this session's bound agent: a supervised \
             agent may only act on itself"
        )),
        _ => Ok(()),
    }
}

/// Start, stop, or restart is available to the bound agent itself and to the
/// host authority. An unbound daemon-token client is accepted only in
/// dev/embedder mode, where no host token exists and `require_approval_authority`
/// deliberately treats the developer as the authority.
async fn require_own_agent_or_host(
    session: &crate::session::ClientSession,
    state: &ServerState,
    method: &str,
    target: &str,
) -> Result<(), String> {
    if session.is_host.load(Ordering::Acquire) {
        return Ok(());
    }
    let bound = session.agent_id.lock().await.clone();
    match bound.as_deref() {
        Some(_) => require_own_agent(bound.as_deref(), method, target),
        None if state.host_token.get().is_some() => {
            Err("this operation requires the host-management role".into())
        }
        None => Ok(()),
    }
}

/// Authorize a lease/sync mutation under the connection's actual identity.
/// The identity and host rules intentionally match agent lifecycle mutations.
async fn require_sync_agent_or_host(
    session: &crate::session::ClientSession,
    state: &ServerState,
    method: &str,
    target: &str,
) -> Result<(), String> {
    require_own_agent_or_host(session, state, method, target).await
}

/// Agent-definition and removal methods belong to host authority. Preserve
/// auth-disabled development mode for unbound callers, but never let a bound
/// supervised agent inherit that degraded-mode authority.
pub(crate) async fn require_host_lifecycle_authority(
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<(), String> {
    require_approval_authority(session, state)?;
    if session.agent_id.lock().await.is_some() && !session.is_host.load(Ordering::Acquire) {
        return Err("this operation requires the host-management role".into());
    }
    Ok(())
}

/// Stronger boundary for daemon-wide agent policy. Even in auth-disabled
/// embedder mode, an authenticated lifecycle agent may not mutate or inspect
/// host-only exact grants for itself. Development clients remain compatible;
/// they are unbound and continue to govern their own daemon when no host token
/// is configured.
/// Gate for `agent_permissions.*`: approval authority, and not a bound agent.
///
/// **The second half is escapable and the first half is conditional — read both
/// before trusting this.** An agent controls its own environment, so it can
/// unset `CAR_AGENT_ID` and reconnect unbound (car#1297). What stops it there is
/// [`require_approval_authority`], which only bites when a host token exists:
/// on an ordinary desktop install CarHost holds one, `is_host` fails for the
/// agent, and the gate holds — `host_token` is a separate `0600` file never
/// served over `GET /auth-token`.
///
/// On a daemon with NO host token — headless, CI, `car-server` started directly
/// — approval authority passes for every authenticated client, and unbinding is
/// sufficient to reach this surface. That is tracked separately; see the
/// per-gate audit in `docs/proposals/agent-binding-trust-boundary.md`.
async fn require_agent_permissions_authority(
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<(), String> {
    require_approval_authority(session, state)?;
    if session.agent_id.lock().await.is_some() {
        return Err("this operation requires the host-management role".into());
    }
    Ok(())
}

/// Resolve and freeze the callback identity currently attached to `agent_id`.
/// The returned lifecycle guard stays held through the policy write, so a
/// concurrent `tools.register` / `tools.unregister` / proposal cannot change
/// the schema between observation and persistence.
async fn live_agent_callback_registration(
    state: &ServerState,
    agent_id: &str,
    tool: &str,
) -> Result<
    (
        Arc<crate::session::ClientSession>,
        tokio::sync::OwnedMutexGuard<()>,
        String,
    ),
    String,
> {
    let client_id = state
        .attached_agents
        .lock()
        .await
        .get(agent_id)
        .cloned()
        .ok_or_else(|| format!("agent '{agent_id}' is not attached"))?;
    let target = state
        .sessions
        .lock()
        .await
        .get(&client_id)
        .cloned()
        .ok_or_else(|| format!("attached agent '{agent_id}' has no live session"))?;
    let guard = target.run_lifecycle_guard.clone().lock_owned().await;

    let still_attached = state
        .attached_agents
        .lock()
        .await
        .get(agent_id)
        .is_some_and(|current| current == &target.client_id);
    let bound_agent = target.agent_id.lock().await.clone();
    if !still_attached
        || !target
            .authenticated
            .load(std::sync::atomic::Ordering::Acquire)
        || bound_agent.as_deref() != Some(agent_id)
    {
        return Err(format!(
            "agent '{agent_id}' callback session changed while authorizing tool '{tool}'"
        ));
    }
    if target.runtime.registry.get(tool).await.is_some() {
        return Err(format!(
            "tool '{tool}' is server-owned and is ineligible for agent standing authority"
        ));
    }
    let digest = target
        .callback_tool_schema_digests
        .read()
        .await
        .get(tool)
        .cloned()
        .ok_or_else(|| {
            format!(
                "tool '{tool}' has no eligible exact reverse-callback registration for agent '{agent_id}'"
            )
        })?;
    Ok((target, guard, digest))
}

async fn handle_agent_permission_set_tool(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let (agent_id, tool) = crate::agent_permissions::exact_tool_params(&req.params)?;
    let mode = crate::agent_permissions::requested_tool_mode(&req.params)?;
    if mode == car_policy::ApprovalMode::AlwaysAllow {
        let (_target, _guard, digest) =
            live_agent_callback_registration(state, agent_id, tool).await?;
        crate::agent_permissions::handle_set_tool(req, Some(digest))
    } else {
        crate::agent_permissions::handle_set_tool(req, None)
    }
}

async fn handle_agent_permission_evaluate_tool(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let (agent_id, tool) = crate::agent_permissions::exact_tool_params(&req.params)?;
    let mut value = crate::agent_permissions::handle_evaluate_tool(req)?;
    let has_override = value
        .get("has_tool_override")
        .and_then(Value::as_bool)
        .unwrap_or(false);
    let mode = value.get("mode").and_then(Value::as_str);
    let stored_digest = value.get("schema_digest").and_then(Value::as_str);
    let live_digest = if mode == Some("always_allow") && has_override {
        live_agent_callback_registration(state, agent_id, tool)
            .await
            .ok()
            .map(|(_target, _guard, digest)| digest)
    } else {
        None
    };
    let schema_bound = stored_digest.is_some();
    let active = if mode == Some("always_allow") {
        stored_digest
            .zip(live_digest.as_deref())
            .is_some_and(|(stored, live)| stored == live)
    } else {
        has_override
    };
    let object = value
        .as_object_mut()
        .ok_or_else(|| "agent permission evaluation returned a non-object".to_string())?;
    object.insert("active".into(), active.into());
    object.insert("schema_bound".into(), schema_bound.into());
    object.insert("schema_digest_present".into(), schema_bound.into());
    Ok(value)
}

/// The authenticated principal for this connection, stamped into approval
/// audit records server-side so the "who decided" field can't be forged by
/// the caller (neo review #5c). Prefers the bound agent identity, else the
/// connection id.
/// Public wrapper over [`session_principal`] for the peer-messaging module.
///
/// Exposed rather than duplicated: the whole value of the principal is that
/// exactly one place derives it, server-side, from the bound agent identity.
pub async fn session_principal_for_peers(session: &crate::session::ClientSession) -> String {
    session_principal(session).await
}

async fn session_principal(session: &crate::session::ClientSession) -> String {
    if let Some(agent) = session.agent_id.lock().await.clone() {
        format!("agent:{agent}")
    } else {
        format!("conn:{}", session.client_id)
    }
}

/// Return the session's current granted standing tier.
async fn handle_permission_get_tier(
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let tier = session.permission_gate.read().await.granted_tier();
    Ok(serde_json::json!({ "granted_tier": tier.as_str() }))
}

/// Set the session's granted standing tier. Params: `{ tier }`.
async fn handle_permission_set_tier(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    let tier_str = req
        .params
        .get("tier")
        .and_then(|v| v.as_str())
        .ok_or("missing 'tier'")?;
    let tier = car_policy::PermissionTier::from_str_opt(tier_str)
        .ok_or_else(|| format!("invalid tier '{tier_str}'"))?;
    session.permission_gate.write().await.set_granted_tier(tier);
    Ok(serde_json::json!({ "granted_tier": tier.as_str() }))
}

// --- iMessage approval-transport config surface (`messaging.*`) ---
//
// The host/local-auth-gated config channel for the iMessage approval
// transport (Unit 3). These handlers are the ONLY allowlist/config-mutation
// path in the system. Every one of them rejects a caller that is not
// `session.is_host` and is not presenting the per-launch local auth token —
// the SAME trust root (`require_approval_authority`) that guards all config
// mutation today (permission-tier / approval changes). An inbound iMessage
// carries neither credential, so there is no inbound→config edge anywhere.
//
// DEGRADED-MODE CAVEAT (inherited platform behavior, NOT specific to this
// surface): `require_approval_authority` is a no-op when NO host token is
// configured (pure-dev / `--no-auth` / a failed boot token-write) — in that
// regime the connection governs its own session, the developer being the
// authority, so these `messaging.*` methods become callable by any local
// connection. This is identical to how `permission.*` (set_tier/approve/reject)
// already behaves and is the deliberate platform gate pattern; we do NOT
// diverge from it here. The core anti-injection invariant still holds
// regardless: an inbound iMessage carries no WS session at all, so even in the
// fail-open regime it can never reach these setters — the degraded mode only
// relaxes WHICH local connections are trusted, never opens an inbound→config
// edge.
//
// The store is constructed per-call from the CAR state root (the same pattern
// `models.register` uses for its per-call `models.json`), keeping these
// handlers state-free and side-effect-local.

/// Build the durable messaging config store rooted at the daemon's state root.
/// `from_home` resolves it through `car_home` — `CAR_HOME` when set, otherwise
/// `~/.car` from `HOME`/`USERPROFILE`.
fn messaging_store() -> crate::messaging_config::MessagingConfigStore {
    crate::messaging_config::MessagingConfigStore::from_home()
}

/// Resolve the optional `channel` string from a request's params to a
/// [`ChannelId`]. **Absent ⇒ iMessage** (back-compat for the #403 surface and
/// the bindings, which have no `channel` field). An unrecognized channel string
/// is an error rather than a silent default (fail-closed on a typo). Reads the
/// top-level `channel` field directly so it works for both the `set` request
/// (which has a typed field) and the param-light `get`/`pairing` methods.
fn messaging_channel_from_params(
    params: &Value,
) -> Result<crate::messaging_config::ChannelId, String> {
    match params.get("channel") {
        None | Some(Value::Null) => Ok(crate::messaging_config::ChannelId::IMessage),
        Some(Value::String(s)) => crate::messaging_config::ChannelId::from_str_opt(s)
            .ok_or_else(|| format!("unknown messaging channel '{s}'")),
        Some(other) => Err(format!("messaging channel must be a string, got {other}")),
    }
}

/// Project a `MessagingConfig` load into the wire view for `channel` (without
/// leaking the active pairing code — that is `messaging.pairing.status` only).
///
/// Per-channel since Unit 2; an absent `channel` in the request defaults to
/// iMessage so the existing 4 methods and their bindings keep working unchanged.
fn messaging_config_view(
    store: &crate::messaging_config::MessagingConfigStore,
    channel: crate::messaging_config::ChannelId,
) -> Result<car_proto::MessagingConfigView, String> {
    let cfg = store.load()?.channel(channel);
    Ok(car_proto::MessagingConfigView {
        channel: channel.as_str().to_string(),
        enabled: cfg.enabled,
        allowlisted_handles: cfg.allowlisted_handles,
        pairing_active: cfg.active_pairing_code.is_some(),
    })
}

/// `messaging.config.get` — return the current transport config view for the
/// (optional) channel (default iMessage). Host/local-auth gated (a read of the
/// trust state is host-only).
async fn handle_messaging_config_get(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    let channel = messaging_channel_from_params(&req.params)?;
    let view = messaging_config_view(&messaging_store(), channel)?;
    serde_json::to_value(view).map_err(|e| e.to_string())
}

/// `messaging.config.set` — mutate the transport config (enabled flag and
/// allowlist) for the (optional) channel (default iMessage). Host/local-auth
/// gated; this is the ONLY allowlist/config mutation path. Params:
/// `MessagingConfigSetRequest`.
async fn handle_messaging_config_set(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    let set: car_proto::MessagingConfigSetRequest = serde_json::from_value(req.params.clone())
        .map_err(|e| format!("invalid messaging.config.set params: {e}"))?;
    // Resolve the channel through the shared `messaging_channel_from_params`
    // (used by all four messaging handlers) rather than `set.channel`: the
    // resolver is the single place that maps absent ⇒ iMessage AND rejects an
    // unknown/non-string `channel` with a clear error. `set.channel` stays a
    // documented part of the request shape (it is what the absent-⇒-iMessage
    // default is named after) but is not re-parsed here.
    let channel = messaging_channel_from_params(&req.params)?;
    let store = messaging_store();
    // Slack token provisioning (MC-9 + MC-6). The `require_approval_authority`
    // host-gate above has ALREADY fired (provisioning is host-only — an inbound
    // message carries no WS session, so it can never reach here). When BOTH
    // `bot_token` + `app_token` are present on the SLACK channel, write the
    // bearer values to the OS keychain via `provision_slack_tokens` and persist
    // ONLY the returned keychain key-REFERENCES into the config — the bearer
    // values never touch `messaging.json` and never echo back in the view.
    // Both-or-neither: a single token present (or the wrong channel) is ignored
    // here so the normal enable/allowlist set stays back-compatible.
    if let (Some(bot), Some(app)) = (set.bot_token.as_deref(), set.app_token.as_deref()) {
        if channel == crate::messaging_config::ChannelId::Slack {
            let secrets = car_secrets::SecretStore::new();
            let refs = crate::slack_adapter::provision_slack_tokens(&secrets, bot, app)
                .map_err(|e| format!("provision slack tokens: {e}"))?;
            store.set_slack_token_ref_for(
                channel,
                crate::messaging_config::SlackTokenRef {
                    bot_token_key: refs.bot_token_key,
                    app_token_key: refs.app_token_key,
                },
            )?;
        }
    }
    // Slack post-channel id (S1). CONFIG, not a secret: the host-gated call
    // persists it INTO `messaging.json` (never the keychain) so the boot path
    // can construct the adapter with the channel to post into. Slack channel
    // only; a non-empty value is required (an empty string would post to
    // `channel:""` → `channel_not_found`).
    if let Some(slack_channel) = set.slack_channel.as_deref() {
        if channel == crate::messaging_config::ChannelId::Slack && !slack_channel.is_empty() {
            store.set_slack_channel_id_for(channel, slack_channel)?;
        }
    }
    if let Some(enabled) = set.enabled {
        // U1: detect an OFF→ON transition so we can spawn the channel's watcher
        // immediately (no daemon/app restart). Read the prior flag BEFORE the
        // mutation; only an actual off→on edge triggers the spawn (an on→on
        // re-set is a no-op via the supervisor's idempotency guard anyway).
        let was_enabled = store.is_enabled_for(channel).unwrap_or(false);
        store.set_enabled_for(channel, enabled)?;
        if enabled && !was_enabled {
            if let Some(sup) = state.channel_supervisor.get() {
                // Spawn the watcher now. A spawn error (e.g. Slack runtime-enable,
                // which is unsupported in this build because its outbound prompt
                // driver is the boot-time FanoutCoordinator) does NOT hard-500 the
                // whole call: config is config, so the enabled flag stays
                // persisted (the user asked to enable it), but the supervisor
                // rolls back its live-set reservation so the channel is NOT marked
                // watcher_running. `messaging.status` then honestly reports
                // `watcher_running:false` — never claiming a channel is live when
                // its outbound cannot fire. The failure is logged, not swallowed
                // silently, and surfaced via `messaging.status` rather than as a
                // transport error on this config write.
                if let Err(e) = sup.ensure_spawned(channel) {
                    tracing::warn!(
                        channel = channel.as_str(),
                        error = %e,
                        "channel enabled in config but its runtime watcher could not start; \
                         messaging.status will report watcher_running:false"
                    );
                }
            }
        }
    }
    if let Some(handles) = set.allowlisted_handles {
        store.set_allowlist_for(channel, handles)?;
    }
    for handle in &set.add_handles {
        store.add_handle_for(channel, handle)?;
    }
    for handle in &set.remove_handles {
        store.remove_handle_for(channel, handle)?;
    }
    let view = messaging_config_view(&store, channel)?;
    serde_json::to_value(view).map_err(|e| e.to_string())
}

/// `messaging.pairing.start` — mint a fresh high-entropy pairing code for the
/// (optional) channel (default iMessage), persist it as that channel's active
/// code, and return it for display ONLY in the local UI. Host/local-auth gated.
/// Rotates any prior active code on that channel.
async fn handle_messaging_pairing_start(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    let channel = messaging_channel_from_params(&req.params)?;
    let store = messaging_store();
    let code = store.mint_pairing_code_for(channel)?;
    let view = messaging_config_view(&store, channel)?;
    let resp = car_proto::MessagingPairingStartResponse {
        pairing_code: code,
        config: view,
    };
    serde_json::to_value(resp).map_err(|e| e.to_string())
}

/// `messaging.pairing.status` — report whether a pairing is in flight on the
/// (optional) channel (default iMessage) and (host/local-auth gated only)
/// re-surface the active code so the local UI can re-display it after a reload.
/// Never exposed over any inbound channel.
async fn handle_messaging_pairing_status(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    let channel = messaging_channel_from_params(&req.params)?;
    let code = messaging_store().active_pairing_code_for(channel)?;
    let resp = car_proto::MessagingPairingStatusResponse {
        pairing_active: code.is_some(),
        pairing_code: code,
    };
    serde_json::to_value(resp).map_err(|e| e.to_string())
}

/// Daemon-side Full Disk Access probe for `messaging.status` (U2, R-B). The
/// daemon is the chat.db reader, so this reflects the DAEMON's access — not the
/// host app's. iMessage probes the real Messages library; other channels carry
/// no chat.db dependency and are always "readable". On non-macOS there is no
/// chat.db, so iMessage is reported readable too (the channel reads nothing
/// there anyway, gated by `cfg(target_os = "macos")` in the adapter).
#[allow(unused_variables)]
fn messaging_fda_readable(channel: crate::messaging_config::ChannelId) -> bool {
    match channel {
        crate::messaging_config::ChannelId::IMessage => {
            #[cfg(target_os = "macos")]
            {
                car_ffi_common::integrations::messages_fda_readable()
            }
            #[cfg(not(target_os = "macos"))]
            {
                true
            }
        }
        crate::messaging_config::ChannelId::Slack => true,
    }
}

/// `messaging.status` — return the real runtime liveness of the (optional)
/// channel (default iMessage) so the host UI can render a SINGLE readiness state
/// (U2). Host/local-auth gated EXACTLY like the other `messaging.*` methods — an
/// inbound message carries no host credential, so it can never call this.
///
/// `enabled` + `paired` come from the config store; `watcher_running` from the
/// runtime channel supervisor's live set (U1); `fda_readable` from a daemon-side
/// probe (R-B); `last_send_*` / `last_error` from the supervisor's per-channel
/// liveness (written by the send path, U3). When the supervisor is not installed
/// (an embedder that never booted the channel pollers), `watcher_running` is
/// `false` and the liveness fields are empty.
async fn handle_messaging_status(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    let channel = messaging_channel_from_params(&req.params)?;
    let store = messaging_store();
    let enabled = store.is_enabled_for(channel).unwrap_or(false);
    let paired = !store.allowlist_for(channel).unwrap_or_default().is_empty();

    let (watcher_running, liveness) = match state.channel_supervisor.get() {
        Some(sup) => (sup.is_spawned(channel), sup.liveness_snapshot(channel)),
        None => (false, crate::channel_supervisor::ChannelLiveness::default()),
    };

    let view = car_proto::MessagingStatusView {
        channel: channel.as_str().to_string(),
        enabled,
        paired,
        watcher_running,
        fda_readable: messaging_fda_readable(channel),
        last_send_at_ms: liveness.last_send_at_ms,
        last_send_ok: liveness.last_send_ok,
        last_error: liveness.last_error,
    };
    serde_json::to_value(view).map_err(|e| e.to_string())
}

/// `messaging.test_send` — send a fixed, clearly-labeled self-test message to
/// the paired handle of the (optional) channel (default iMessage) and return a
/// synchronous `{ ok, error }` (U4). Host/local-auth gated EXACTLY like the
/// other `messaging.*` methods. The self-test mints NO approval/pairing mapping
/// and resolves nothing — it is purely a "does my Mac actually text my phone"
/// probe whose outcome is recorded into liveness (so a pass genuinely proves
/// Automation works and a failure surfaces identically to a real send).
///
/// Reuses the SAME `RealMessageSender` + liveness sink the boot/runtime adapters
/// use, so the test result and `messaging.status`'s `last_send_*` agree. Slack
/// is not yet wired here (the pane this serves is iMessage-only in v1); a Slack
/// test_send returns a clear "not supported on this channel yet" error.
async fn handle_messaging_test_send(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    let channel = messaging_channel_from_params(&req.params)?;

    let result = match channel {
        crate::messaging_config::ChannelId::IMessage => {
            // Build a one-shot orchestrator over the SAME shared liveness the
            // status method reads, so a test send updates "last delivered".
            let liveness = state.channel_supervisor.get().map(|sup| sup.liveness());
            // The CAR state root, so a relocated daemon's test send writes its
            // liveness alongside the rest of its state rather than the primary's.
            let base_dir = car_home::root_or_relative();
            let orch = match liveness {
                Some(liveness) => {
                    crate::messaging_orchestrator::MessagingOrchestrator::with_liveness(
                        state.host.clone(),
                        messaging_store(),
                        std::sync::Arc::new(crate::messaging_orchestrator::RealMessageSender),
                        base_dir,
                        liveness,
                    )
                }
                None => crate::messaging_orchestrator::MessagingOrchestrator::new(
                    state.host.clone(),
                    messaging_store(),
                    std::sync::Arc::new(crate::messaging_orchestrator::RealMessageSender),
                    base_dir,
                ),
            };
            orch.send_test().await
        }
        crate::messaging_config::ChannelId::Slack => {
            Err("Test send is not supported on the Slack channel yet.".to_string())
        }
    };

    let resp = match result {
        Ok(()) => car_proto::MessagingTestSendResponse {
            ok: true,
            error: None,
        },
        Err(e) => car_proto::MessagingTestSendResponse {
            ok: false,
            error: Some(e),
        },
    };
    serde_json::to_value(resp).map_err(|e| e.to_string())
}

/// Parse a proposal from `params.proposal`.
fn proposal_from_params(req: &JsonRpcMessage) -> Result<car_ir::ActionProposal, String> {
    let p = req.params.get("proposal").ok_or("missing 'proposal'")?;
    serde_json::from_value(p.clone()).map_err(|e| format!("invalid proposal: {e}"))
}

/// Classify each action in a proposal on both authorization-adjacent axes.
/// Params: `{ proposal }`. Returns `{ classifications: [{ action_id, tool,
/// required_tier, reversibility, missing_compensation }],
/// declared_rollback_contract }`. The envelope is what distinguishes this from
/// the FFI `permission_classify`, which returns the row array bare and
/// therefore carries no batch-level roll-up.
///
/// `required_tier` answers *who may authorize this*; `reversibility`
/// (`car_policy::classify_reversibility`) answers the independent question
/// *can this be undone*. They used to be one field, and collapsed they cannot
/// distinguish a `git push` from a charged card — both land on `full_access`.
/// The tier comes from the **session's** classifier (which may carry custom
/// rules); the reversibility classifier is stateless and has no such hook yet.
///
/// `missing_compensation` flags the one incoherent IR combination —
/// `reversibility: "compensable"` declared with no `compensation` — and reads
/// the action's *declared* field, so it stays `false` for proposals that never
/// opted into the axis.
///
/// `declared_rollback_contract` is `ActionProposal::rollback_contract()`: the
/// least recoverable contract any action **declares**, because a plan is only
/// as recoverable as its worst step and partial execution is a real outcome.
/// It is named for what it reads and is deliberately *not* a roll-up of the
/// `reversibility` column beside it — that column is the classifier's
/// independent guess from tool names, this one is what the author committed
/// to. For a proposal that never set the field it reads `"irreversible"`,
/// which is the serde default and exactly what the runtime should believe
/// about an unclassified plan.
///
/// Nothing here gates on the second axis — it is classified and reported, not
/// enforced. See `docs/proposals/shepherd-substrate-adoption.md`.
async fn handle_permission_classify(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let proposal = proposal_from_params(req)?;
    let gate = session.permission_gate.read().await;
    let rows: Vec<Value> = proposal
        .actions
        .iter()
        // Same row shape as the FFI `permission_classify`, from one
        // definition — but built against the SESSION's classifier, which may
        // carry custom rules a fresh `RiskClassifier` would not have.
        .map(|a| car_ffi_common::permgate::classification_row(gate.classifier(), a))
        .collect();
    Ok(serde_json::json!({
        "classifications": rows,
        "declared_rollback_contract": proposal.rollback_contract().as_str(),
    }))
}

/// Evaluate each action against the session's gate (consulting its durable
/// ledger). Params: `{ proposal }`. Returns `[{ action_id, fingerprint,
/// decision, reversibility, ... }]`.
///
/// `reversibility` is on every row, `allow` included, and is orthogonal to
/// `decision`: the gate's verdict says whether the action may run, not whether
/// it could be taken back afterwards. An approval UI that shows both can tell
/// the operator which of two identically-escalated actions is the one there is
/// no undoing.
async fn handle_permission_evaluate(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    let proposal = proposal_from_params(req)?;
    let ceiling = resolve_skill_ceiling(req, session).await;
    let agent_id = authenticated_bound_agent_id(session).await;
    let policy = crate::agent_permissions::load_policy();
    let callback_tools = crate::permission_gate::eligible_callback_tool_digests(
        &session.callback_tool_schema_digests,
        &session.runtime.registry,
    )
    .await;
    let gate = session.permission_gate.read().await;
    // Prior decisions come from the SHARED daemon ledger (C1) — an approval
    // recorded on another connection must be honoured here.
    let ledger = state.approval_ledger.read().await;
    let rows = evaluate_actions(
        &gate,
        &policy,
        agent_id.as_deref(),
        &callback_tools,
        &proposal,
        ceiling,
        &ledger,
    );
    let mut resp = serde_json::json!({ "decisions": rows });
    if let Some(c) = ceiling {
        resp.as_object_mut()
            .unwrap()
            .insert("skill_ceiling".into(), serde_json::json!(c.as_str()));
    }
    Ok(resp)
}

/// Like evaluate but returns only the actions that need a human decision —
/// the work queue for an approval UI. Rows carry `reversibility` for the same
/// reason they do there, and it matters most here: this queue is where a human
/// decides, and "can this be undone?" is the question they are actually
/// weighing.
async fn handle_permission_pending(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    let proposal = proposal_from_params(req)?;
    let ceiling = resolve_skill_ceiling(req, session).await;
    let agent_id = authenticated_bound_agent_id(session).await;
    let policy = crate::agent_permissions::load_policy();
    let callback_tools = crate::permission_gate::eligible_callback_tool_digests(
        &session.callback_tool_schema_digests,
        &session.runtime.registry,
    )
    .await;
    let gate = session.permission_gate.read().await;
    let ledger = state.approval_ledger.read().await;
    let pending: Vec<Value> = evaluate_actions(
        &gate,
        &policy,
        agent_id.as_deref(),
        &callback_tools,
        &proposal,
        ceiling,
        &ledger,
    )
    .into_iter()
    .filter(|r| r.get("decision").and_then(|v| v.as_str()) == Some("needs_approval"))
    .collect();
    Ok(serde_json::json!({ "pending": pending }))
}

/// Resolve the optional skill-deployment ceiling for a permission evaluation: if
/// the request names a `skill`, look up its persisted `deployment_tier` (the
/// ceiling the skill-trust gate stamped at load time) so the action-level gate
/// caps standing authority at it. `None` when no skill is named, the skill is
/// absent, or it carries no governed tier — leaving evaluation unchanged.
async fn resolve_skill_ceiling(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Option<car_policy::PermissionTier> {
    let skill = req.params.get("skill").and_then(|v| v.as_str())?;
    let engine = session.memgine.lock().await;
    engine.skill_meta(skill).and_then(|m| m.deployment_tier)
}

fn evaluate_actions(
    gate: &car_policy::PermissionGate,
    policy: &car_policy::AgentPermissionPolicy,
    agent_id: Option<&str>,
    callback_tools: &HashMap<String, String>,
    proposal: &car_ir::ActionProposal,
    ceiling: Option<car_policy::PermissionTier>,
    ledger: &car_policy::ApprovalLedger,
) -> Vec<Value> {
    proposal
        .actions
        .iter()
        .map(|a| {
            // Both axes from one flatten of the parameters (Parslee-ai/car#856)
            // — this runs per action over a whole batch.
            let evaluation = crate::permission_gate::evaluate_action(
                gate,
                policy,
                agent_id,
                a,
                a.tool
                    .as_deref()
                    .and_then(|tool| callback_tools.get(tool))
                    .map(String::as_str),
                ceiling,
                ledger,
            );
            let mut obj = serde_json::to_value(&evaluation.axes.decision).unwrap_or(Value::Null);
            if let Some(map) = obj.as_object_mut() {
                map.insert("action_id".into(), serde_json::json!(a.id));
                map.insert(
                    "fingerprint".into(),
                    serde_json::json!(car_policy::action_fingerprint(a)),
                );
                if let Some(source) = evaluation.authorization_source {
                    map.insert("authorization_source".into(), source.into());
                }
                if let Some(digest) = evaluation.schema_digest {
                    map.insert("authorization_schema_digest".into(), digest.into());
                }
            }
            // The second axis rides on every row, `allow` included — an action
            // the gate waved through still has a rollback contract, and that is
            // the row an incident review reads first. Shared with the NAPI/PyO3
            // projection so the two cannot drift (project convention #2).
            car_ffi_common::permgate::stamp_reversibility(&mut obj, evaluation.axes.reversibility);
            obj
        })
        .collect()
}

/// Which agent id a newly created approval should be attributed to.
///
/// A session **bound to an agent** is that agent, full stop: its binding was
/// proven against the supervisor-minted per-agent token, so a claim to be some
/// other agent is a forgery and is discarded. A session with no binding is a
/// host client — CarHost, `car-host approve`, the CLI — and those legitimately
/// raise approvals on an agent's behalf, so their claim is kept.
///
/// Pure so the rule is testable without a live session.
fn stamped_requester(bound: Option<String>, claimed: Option<String>) -> Option<String> {
    bound.or(claimed)
}

async fn authenticated_bound_agent_id(session: &crate::session::ClientSession) -> Option<String> {
    if !session
        .authenticated
        .load(std::sync::atomic::Ordering::Acquire)
    {
        return None;
    }
    session.agent_id.lock().await.clone()
}

/// Record a durable human-in-the-loop decision. Params either
/// `{ fingerprint, required_tier, reviewer, reason, evidence? }` (from a
/// prior `permission.evaluate`) or `{ action, reviewer, reason, evidence? }`.
/// Also audited to the session event log as `ApprovalRecorded`.
async fn handle_permission_decision(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
    approve: bool,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    // The reviewer is the server-stamped principal, NOT a caller string —
    // an audit log whose "who approved" is forgeable by the approver
    // undercuts §5.2.5 (neo review #5c). The caller's free-text note is
    // kept as the reason.
    let reviewer = session_principal(session).await;
    let reason = req
        .params
        .get("reason")
        .and_then(|v| v.as_str())
        .unwrap_or("");
    let evidence = req
        .params
        .get("evidence")
        .and_then(|v| v.as_str())
        .map(str::to_string);

    // Decisions land on the SHARED daemon ledger (kernel review C1): the
    // approver is typically a host connection while the runner that surfaced
    // the fingerprint is another — a per-session ledger would strand the
    // decision where the runner never reads it. The session gate contributes
    // only its classifier (for the action-shaped variant).
    let decision = if approve {
        car_policy::ApprovalDecision::Approved
    } else {
        car_policy::ApprovalDecision::Rejected
    };
    let record = if let Some(action_val) = req.params.get("action") {
        let action: car_ir::Action = serde_json::from_value(action_val.clone())
            .map_err(|e| format!("invalid action: {e}"))?;
        let rec = {
            let gate = session.permission_gate.read().await;
            gate.decision_record(&action, decision, &reviewer, reason, evidence)
        };
        state
            .approval_ledger
            .write()
            .await
            .record(rec.clone())
            // Journal write failure = decision NOT durable; propagate instead
            // of emitting a false ApprovalRecorded audit event (review A7).
            .map_err(|e| format!("failed to persist approval decision: {e}"))?;
        rec
    } else {
        let fingerprint = req
            .params
            .get("fingerprint")
            .and_then(|v| v.as_str())
            .ok_or("missing 'fingerprint' (or 'action')")?;
        let required_tier = req
            .params
            .get("required_tier")
            .and_then(|v| v.as_str())
            .and_then(car_policy::PermissionTier::from_str_opt)
            .unwrap_or(car_policy::PermissionTier::FullAccess);
        state
            .approval_ledger
            .write()
            .await
            .record_decision(
                fingerprint,
                required_tier,
                decision,
                &reviewer,
                reason,
                evidence,
            )
            .map_err(|e| format!("failed to persist approval decision: {e}"))?
    };

    // Audit the durable transition (§5.2.5) to the session event log — at
    // parity with car-engine's TierPermissionHandler emission (required_tier
    // + evidence; approval derived from the stored decision, not the request).
    let mut data = std::collections::HashMap::new();
    data.insert(
        "fingerprint".to_string(),
        Value::from(record.fingerprint.clone()),
    );
    data.insert(
        "approval".to_string(),
        Value::from(match record.decision {
            car_policy::ApprovalDecision::Approved => "approved",
            car_policy::ApprovalDecision::Rejected => "rejected",
        }),
    );
    data.insert(
        "required_tier".to_string(),
        Value::from(record.required_tier.as_str()),
    );
    data.insert("reviewer".to_string(), Value::from(record.reviewer.clone()));
    data.insert("reason".to_string(), Value::from(record.reason.clone()));
    if let Some(ev) = &record.evidence {
        data.insert("evidence".to_string(), Value::from(ev.clone()));
    }
    session.runtime.log.lock().await.append(
        car_eventlog::EventKind::ApprovalRecorded,
        None,
        None,
        data,
    );

    serde_json::to_value(&record).map_err(|e| e.to_string())
}

/// Validate a tenant id (linus review C-4). `:` is the namespace
/// separator in `tenant:<id>:<key>`, so an id containing it nests
/// inside (or envelops) another tenant's namespace — `"acme:sub"`
/// would read acme's keys and be captured by acme's scoped
/// snapshot/restore/reap. Reject at the boundary.
fn validate_tenant_id(id: &str) -> Result<(), String> {
    if id.contains(':') {
        return Err(format!(
            "invalid tenant_id '{id}': ':' is reserved as the namespace separator"
        ));
    }
    Ok(())
}

/// Resolve the tenant identity for a tenant-scoped handler
/// (Parslee-ai/car#187 phase 3-E, hardened per linus review C-4).
///
/// The session's bound tenant (from `session.auth { tenant_id }`) is
/// authoritative: when bound, a per-request `tenant_id` may restate it
/// but a mismatch is an error — request params are caller-controlled
/// and must not hop namespaces. An unbound session keeps the legacy
/// per-request behavior (validated). Absent/empty → unscoped.
async fn effective_tenant(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Option<String>, String> {
    let param = req
        .params
        .get("tenant_id")
        .and_then(|v| v.as_str())
        .filter(|s| !s.is_empty())
        .map(str::to_string);
    if let Some(p) = &param {
        validate_tenant_id(p)?;
    }
    let bound = session.tenant.lock().await.clone();
    match (bound, param) {
        (Some(b), Some(p)) if b != p => Err(format!(
            "tenant_id '{p}' conflicts with this session's bound tenant '{b}'"
        )),
        (Some(b), _) => Ok(Some(b)),
        (None, p) => Ok(p),
    }
}

/// Refuse unscoped access to a tenant-namespaced key (linus review
/// C-4): without this, `state.get {key: "tenant:acme:secret"}` with no
/// `tenant_id` read (and `state.set` wrote) straight through another
/// tenant's namespace — enforcement existed only on `keys`/`snapshot`.
fn reject_unscoped_tenant_key(tenant: &Option<String>, key: &str) -> Result<(), String> {
    if tenant.is_none() && key.starts_with("tenant:") {
        return Err(format!(
            "unscoped access to tenant-namespaced key '{key}' is not permitted; \
             authenticate with the owning tenant_id"
        ));
    }
    Ok(())
}

fn handle_capabilities_list(bound_agent: Option<&str>, is_host: bool) -> Value {
    let caller_role = if is_host {
        "host"
    } else if bound_agent.is_some() {
        "agent"
    } else {
        "operator"
    };
    let methods: Vec<Value> = crate::generated_rpc_capabilities::RPC_CAPABILITIES
        .iter()
        .filter(|(_, role)| match *role {
            // Ungated methods are callable by every authenticated client.
            "operator" => true,
            // Owner methods authorize the concrete resource at call time.
            "owner" => is_host || bound_agent.is_some(),
            "agent" => bound_agent.is_some(),
            "host" => is_host,
            _ => false,
        })
        .map(|(method, role)| serde_json::json!({"method": method, "role": role}))
        .collect();
    serde_json::json!({
        "caller_role": caller_role,
        "count": methods.len(),
        "methods": methods,
    })
}

#[cfg(test)]
mod capability_discovery_tests {
    use super::handle_capabilities_list;

    #[test]
    fn agent_discovery_excludes_host_methods_and_preserves_roles() {
        let result = handle_capabilities_list(Some("agent-a"), false);
        let methods = result["methods"].as_array().expect("method rows");
        assert_eq!(result["caller_role"], "agent");
        assert!(methods
            .iter()
            .any(|row| row["method"] == "capabilities.list"));
        assert!(methods.iter().any(|row| row["role"] == "agent"));
        assert!(methods.iter().any(|row| row["role"] == "owner"));
        assert!(methods.iter().any(|row| row["role"] == "operator"));
        assert!(!methods.iter().any(|row| row["role"] == "host"));
    }

    #[test]
    fn unbound_discovery_contains_only_ungated_methods() {
        let result = handle_capabilities_list(None, false);
        let methods = result["methods"].as_array().expect("method rows");
        assert_eq!(result["caller_role"], "operator");
        assert!(methods.iter().all(|row| row["role"] == "operator"));
    }
}

async fn handle_state_get(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let key = require_str(&req.params, "key")?;
    let tenant = effective_tenant(req, session).await?;
    reject_unscoped_tenant_key(&tenant, key)?;
    Ok(session
        .runtime
        .state
        .scoped(tenant.as_deref())
        .get(key)
        .unwrap_or(Value::Null))
}

async fn handle_state_set(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let key = require_str(&req.params, "key")?;
    let value = req.params.get("value").cloned().unwrap_or(Value::Null);
    let tenant = effective_tenant(req, session).await?;
    reject_unscoped_tenant_key(&tenant, key)?;
    session
        .runtime
        .state
        .scoped(tenant.as_deref())
        .set(key, value, "client");
    Ok(Value::from("ok"))
}

/// `state.exists` — true if the key is set in this session's state
/// store, false otherwise. Cheaper than `state.get` + null-check on
/// the client side because it doesn't serialize the value.
async fn handle_state_exists(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let key = require_str(&req.params, "key")?;
    let tenant = effective_tenant(req, session).await?;
    reject_unscoped_tenant_key(&tenant, key)?;
    Ok(Value::Bool(
        session.runtime.state.scoped(tenant.as_deref()).exists(key),
    ))
}

/// `state.keys` — list every key currently set in this session's
/// state store. Returns a JSON array of strings.
async fn handle_state_keys(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let tenant = effective_tenant(req, session).await?;
    Ok(Value::Array(
        session
            .runtime
            .state
            .scoped(tenant.as_deref())
            .keys()
            .into_iter()
            .map(Value::String)
            .collect(),
    ))
}

/// `state.snapshot` — return the entire session state store as a
/// JSON object (`{ key: value, ... }`). Equivalent to iterating
/// `state.keys` + `state.get` but in a single round-trip; for
/// inspectors/dashboards.
///
/// Tenant-scoped variant: when `tenant_id` is set, only that
/// tenant's keys are returned (prefix stripped on the way out).
/// `state.snapshot` with no `tenant_id` returns only unscoped
/// keys; consistent with `state.keys`'s filter behaviour and the
/// strict-isolation contract from phase 3-B.
async fn handle_state_snapshot(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let tenant = effective_tenant(req, session).await?;
    // One locked snapshot, not keys()-then-get(): each of those calls
    // acquires the state lock separately, so a concurrent mutation batch
    // could commit between two get()s and the response would mix old and
    // new values of a single callback's key set (Parslee-ai/car#1140).
    let map: serde_json::Map<String, Value> = session
        .runtime
        .state
        .scoped(tenant.as_deref())
        .snapshot_stripped()
        .into_iter()
        .collect();
    Ok(Value::Object(map))
}

// --- Per-agent persistent memgine (#170) ---

/// `~/.car/memory/agents/<id>.json` — the per-agent snapshot file.
/// Mirrors the existing `memory.persist` shape (flat JSON array of
/// fact objects) so the same loader path works.
fn agent_memgine_snapshot_path(agent_id: &str) -> Result<std::path::PathBuf, String> {
    let base = car_ffi_common::memory_path::ensure_base()
        .map_err(|e| format!("memory base unavailable: {e}"))?;
    let dir = base.join("agents");
    std::fs::create_dir_all(&dir).map_err(|e| format!("create agents dir: {e}"))?;
    Ok(dir.join(format!("{agent_id}.json")))
}

/// Acquire (or lazy-create + load from disk) the daemon-owned
/// persistent memgine for `agent_id`. First call per id reads
/// `~/.car/memory/agents/<id>.json` if it exists; subsequent calls
/// share the in-memory engine across sessions. Caller stores the
/// returned `Arc` on `ClientSession.bound_memgine` so memory.*
/// handlers route through it via [`ClientSession::effective_memgine`](crate::session::ClientSession::effective_memgine).
/// Resolve the [`car_memgine::MemgineConfig`] the daemon seeds its engines with:
/// discover the `.car/` project from the **project anchor** and apply its
/// `config.toml` overrides (e.g. utility-aware retrieval). The anchor is
/// `$CAR_PROJECT_DIR` when set, else the process cwd.
///
/// The env var is load-bearing for the shipped macOS path: the
/// `launchd`/CarHost-supervised `car-server` inherits the app bundle (or `/`)
/// as cwd, which has no `.car/` ancestor — so cwd-only discovery would silently
/// no-op there. A host that wants project tuning points `CAR_PROJECT_DIR` at the
/// workspace. With neither anchor resolvable, returns the default config
/// (utility retrieval off) — a safe no-op, never a panic.
pub fn seed_memgine_config() -> car_memgine::MemgineConfig {
    let anchor = std::env::var_os("CAR_PROJECT_DIR")
        .map(std::path::PathBuf::from)
        .or_else(|| std::env::current_dir().ok());
    match anchor {
        Some(dir) => {
            car_memgine::project::resolve_config(&dir, car_memgine::MemgineConfig::default())
        }
        None => car_memgine::MemgineConfig::default(),
    }
}

/// Read the operator's **trusted skill-signer keyring** from the `.car/`
/// project's `config.toml` (`trusted_skill_signers`), discovered from the same
/// anchor as [`seed_memgine_config`]: `$CAR_PROJECT_DIR` when set, else the
/// process cwd. Absent key, absent file, or no project → an empty keyring.
///
/// This is the operator half of skill-trust governance (arXiv 2602.12430
/// "Agent Skills"; `docs/proposals/skill-trust-governance.md`). It decides
/// whether a bundle's ed25519 signature confers `signer_trusted` on the
/// resulting `SkillProvenance`.
///
/// Be precise about what an empty keyring costs, because it is narrower than
/// it sounds: `signer_trusted` separates **only** `Official` from `Verified`
/// in [`car_policy::skill_trust::classify_trust`]. A signed + scanned pack
/// with an empty keyring lands `Verified` → `sandbox_edit`, not `Community`
/// — that tier requires `scanned && !signed`, so a signed pack can never
/// reach it. What the keyring withholds is `Official`/`full_access`, nothing
/// else. An unscanned pack is `Untrusted` → denied regardless of signature,
/// and `scanned` is caller-supplied on every path, so a self-signed manifest
/// declared scanned still reaches `sandbox_edit` here.
///
/// The keyring comes ONLY from operator config, never from the JSON-RPC
/// request. A caller that could name its own trusted key ids would be
/// self-certifying: it would sign a pack, declare its own key trusted, and
/// take the `manifest` path straight to `Official`. Note this constrains the
/// `manifest` path only — `skill.adopt_pack` also accepts a caller-assembled
/// `provenance` at face value (see [`resolve_adopt_provenance`]).
pub fn seed_trusted_skill_signers() -> Vec<String> {
    let Some(anchor) = std::env::var_os("CAR_PROJECT_DIR")
        .map(std::path::PathBuf::from)
        .or_else(|| std::env::current_dir().ok())
    else {
        return Vec::new();
    };
    let Some(car_dir) = car_memgine::project::discover_project(&anchor) else {
        return Vec::new();
    };
    car_memgine::project::load_config_overrides(&car_dir)
        .and_then(|o| o.trusted_skill_signers)
        .unwrap_or_default()
}

/// Snapshot path for a host-declared memory namespace.
///
/// Deliberately NOT `agents/`: a namespace is a different axis from an agent
/// id (Parslee-ai/car-releases#79), so one agent may work across several
/// namespaces and two hosts may share a namespace without sharing an identity.
/// Colliding the two directories would also let a namespace masquerade as a
/// supervised agent's snapshot.
///
/// Encoded — not sanitized — because a namespace is arbitrary host-supplied
/// text that becomes a filename, and the mapping from namespace to filename
/// must be **injective**. An `agent_id` is safe by construction (`session.auth`
/// rejects one the supervisor does not know); nothing validates a namespace, so
/// `../../…` here would escape the memory base.
///
/// The old mapping replaced `/ \ : NUL` with `_` and trimmed `.`/whitespace,
/// which is lossy: `proj/x`, `proj:x`, `proj\x`, `proj_x` and `proj_x ` all
/// landed on `proj_x.json`. The in-memory registry is keyed on the raw
/// namespace, so nothing looked wrong while the daemon ran — but the loader
/// reads whatever sits at the path with no namespace check, so on the next
/// snapshot LOAD (daemon restart, or `memory.load`) whichever namespace
/// resolved second inherited the first one's persisted graph. That is
/// cross-project memory leakage through a filename (#891).
///
/// The mapping here is a lowercase percent-encoding of the namespace's UTF-8
/// bytes: `a`-`z`, `0`-`9`, `-`, `_` and `.` pass through, every other byte
/// becomes `%` plus two lowercase hex digits (`/` → `%2f`, `:` → `%3a`,
/// ` ` → `%20`), and `%` itself becomes `%25`. Because `%` is always escaped,
/// every `%` in the output starts an escape, so distinct namespaces cannot
/// produce the same filename. Uppercase letters and uppercase hex are escaped
/// rather than passed through **because APFS is case-insensitive by default**:
/// letting `A` through would let `Proj` and `proj` collide again on the very
/// platform CarHost ships on.
///
/// Nothing is trimmed — trimming is lossy — and nothing needs to be: `/` is
/// escaped, so `.` and `..` are ordinary filenames here and no traversal is
/// possible.
fn namespace_memgine_snapshot_path(namespace: &str) -> Result<std::path::PathBuf, String> {
    if namespace.is_empty() {
        return Err("memory_namespace must contain at least one usable character".into());
    }
    const HEX: &[u8; 16] = b"0123456789abcdef";
    let mut encoded = String::with_capacity(namespace.len());
    for &b in namespace.as_bytes() {
        match b {
            b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' => encoded.push(b as char),
            _ => {
                encoded.push('%');
                encoded.push(HEX[(b >> 4) as usize] as char);
                encoded.push(HEX[(b & 0x0f) as usize] as char);
            }
        }
    }
    let file_name = format!("{encoded}.json");
    // Encoding can triple the length, so a namespace well under any filesystem
    // limit can still encode past one. Fail with the namespace named rather
    // than letting the OS return an opaque ENAMETOOLONG on the first write.
    if file_name.len() > 255 {
        return Err(format!(
            "memory_namespace is too long: {:?} encodes to a {}-byte filename \
             (limit 255)",
            namespace,
            file_name.len()
        ));
    }
    let base = car_ffi_common::memory_path::ensure_base()
        .map_err(|e| format!("memory base unavailable: {e}"))?;
    let dir = base.join("memory-namespaces");
    std::fs::create_dir_all(&dir).map_err(|e| format!("create namespaces dir: {e}"))?;
    Ok(dir.join(file_name))
}

/// Acquire (or lazy-create + load) the daemon-owned memgine for a namespace.
///
/// Mirrors [`get_or_load_agent_memgine`]; the registries are separate so the
/// two axes cannot collide.
async fn get_or_load_namespace_memgine(
    state: &Arc<ServerState>,
    namespace: &str,
) -> Result<Arc<tokio::sync::Mutex<car_memgine::MemgineEngine>>, String> {
    {
        let map = state.namespace_memgines.lock().await;
        if let Some(eng) = map.get(namespace) {
            return Ok(eng.clone());
        }
    }
    let engine = Arc::new(tokio::sync::Mutex::new(car_memgine::MemgineEngine::new(
        Some(seed_memgine_config()),
    )));
    let path = namespace_memgine_snapshot_path(namespace)?;
    if path.exists() {
        // Same on-disk shape as the per-agent snapshot: a flat array of facts.
        let content = std::fs::read_to_string(&path)
            .map_err(|e| format!("read {}: {}", path.display(), e))?;
        let facts: Vec<Value> = serde_json::from_str(&content).unwrap_or_default();
        let mut g = engine.lock().await;
        for (loaded, fact) in facts.iter().enumerate() {
            ingest_snapshot_fact(&mut g, fact, format!("loaded-{loaded}"));
        }
    }
    let mut map = state.namespace_memgines.lock().await;
    Ok(map.entry(namespace.to_string()).or_insert(engine).clone())
}

/// Bind a session to a namespace graph AND record which namespace it is.
///
/// These two must happen together. Binding without recording is what made
/// namespace memory non-durable (car-releases#82): the daemon knew which graph
/// the session used but not what to call it, so nothing could write it back to
/// disk. Keeping them in one helper means a future bind site cannot do half of
/// it — there were four call sites, and a fifth would have been easy to get
/// wrong.
async fn bind_memory_namespace(
    state: &Arc<ServerState>,
    session: &crate::session::ClientSession,
    namespace: &str,
) -> Result<(), String> {
    let eng = get_or_load_namespace_memgine(state, namespace).await?;
    *session.bound_memgine.lock().await = Some(eng);
    *session.memory_namespace.lock().await = Some(namespace.to_string());
    Ok(())
}

/// Write a namespace's graph to
/// `~/.car/memory/memory-namespaces/<encoded-ns>.json` (see
/// [`namespace_memgine_snapshot_path`] for the encoding).
///
/// Mirrors [`persist_agent_memgine`] exactly, including its lock discipline:
/// the shared memgine lock is released BEFORE serialize+write, and the write
/// runs on the blocking pool. Holding it across a blocking write would
/// serialize every namespace's memory ops and one stuck write would wedge them
/// all.
///
/// The on-disk shape is the flat fact array `get_or_load_namespace_memgine`
/// already reads — that loader existed from the start, reading a file nothing
/// ever wrote.
async fn persist_namespace_memgine(
    namespace: &str,
    engine: &Arc<tokio::sync::Mutex<car_memgine::MemgineEngine>>,
) -> Result<(), String> {
    let path = namespace_memgine_snapshot_path(namespace)?;
    let g = engine.lock().await;
    let facts = memory_snapshot_facts(&g);
    drop(g);
    let path_owned = path.clone();
    tokio::task::spawn_blocking(move || -> Result<(), String> {
        let json = serde_json::to_string(&facts).map_err(|e| e.to_string())?;
        atomic_write_sync(&path_owned, json.as_bytes())
            .map_err(|e| format!("write {}: {}", path_owned.display(), e))
    })
    .await
    .map_err(|e| format!("persist_namespace_memgine join: {e}"))?
}

/// One flat JSON row per persisted graph node, in the shape the snapshot
/// loaders (`get_or_load_namespace_memgine`, `get_or_load_agent_memgine`,
/// `handle_memory_load`) read back.
///
/// The row format is deliberately lossy and always has been: non-Fact kinds
/// collapse onto the three flat labels (`constraint`/`pattern`/`outcome`) and
/// reload as plain Fact nodes (a Conversation's `outcome` row becomes a
/// non-constraint Fact; Skill/Conclusion/FactSuperseded rows fall into the
/// `_` arm), while Identity/Environment nodes are not written at all. Only
/// Fact rows round-trip `fact_id`/`tags`/`source` verbatim — the metadata
/// preservation the docs promise holds for facts, not for the whole graph.
fn memory_snapshot_facts(engine: &car_memgine::MemgineEngine) -> Vec<Value> {
    engine
        .graph
        .inner
        .node_indices()
        .filter_map(|nix| {
            let node = engine.graph.inner.node_weight(nix)?;
            if !node.is_valid() {
                return None;
            }
            if node.kind == car_memgine::MemKind::Identity
                || node.kind == car_memgine::MemKind::Environment
            {
                return None;
            }
            Some(serde_json::json!({
                "fact_id": node.fact_id,
                "subject": node.key,
                "body": node.value,
                "kind": match node.kind {
                    car_memgine::MemKind::Fact if node.is_constraint => "constraint",
                    car_memgine::MemKind::Fact => "pattern",
                    car_memgine::MemKind::Conversation => "outcome",
                    _ => "pattern",
                },
                "confidence": 0.5,
                "content_type": node.content_type.as_label(),
                "tags": node.metadata.tags,
                "source": node
                    .metadata
                    .provenance
                    .first()
                    .map(|entry| entry.source.as_str())
                    .unwrap_or(""),
            }))
        })
        .collect()
}

fn ingest_snapshot_fact(
    engine: &mut car_memgine::MemgineEngine,
    fact: &Value,
    fallback_id: String,
) {
    let subject = fact.get("subject").and_then(Value::as_str).unwrap_or("");
    let body = fact.get("body").and_then(Value::as_str).unwrap_or("");
    let kind = fact
        .get("kind")
        .and_then(Value::as_str)
        .unwrap_or("pattern");
    let fact_id = fact
        .get("fact_id")
        .and_then(Value::as_str)
        .unwrap_or(&fallback_id);
    let tags = fact
        .get("tags")
        .cloned()
        .and_then(|value| serde_json::from_value::<Vec<String>>(value).ok())
        .unwrap_or_default();
    let source = fact
        .get("source")
        .and_then(Value::as_str)
        .unwrap_or_default();
    let nix = engine.ingest_fact(
        fact_id,
        subject,
        body,
        "user",
        "peer",
        chrono::Utc::now(),
        "global",
        None,
        vec![],
        kind == "constraint",
    );
    if let Some(node) = engine.graph.inner.node_weight_mut(nix) {
        node.metadata.tags = tags;
        if !source.is_empty() {
            node.metadata.provenance = vec![car_memgine::Provenance {
                source: source.to_string(),
                ..Default::default()
            }];
        }
    }
}

async fn get_or_load_agent_memgine(
    state: &Arc<ServerState>,
    agent_id: &str,
) -> Result<Arc<tokio::sync::Mutex<car_memgine::MemgineEngine>>, String> {
    {
        let map = state.agent_memgines.lock().await;
        if let Some(eng) = map.get(agent_id) {
            return Ok(eng.clone());
        }
    }
    // Build a fresh engine and try to load from disk. Seed its config from the
    // `.car/` project (like the daemon's shared engine) so a bound agent's
    // retrieval honors the same team-shared tuning (e.g. utility-aware
    // retrieval) — otherwise the knob could never reach the per-agent engine
    // (#170 bound_memgine path).
    let engine = Arc::new(tokio::sync::Mutex::new(car_memgine::MemgineEngine::new(
        Some(seed_memgine_config()),
    )));
    let path = agent_memgine_snapshot_path(agent_id)?;
    if path.exists() {
        let content = std::fs::read_to_string(&path)
            .map_err(|e| format!("read {}: {}", path.display(), e))?;
        let facts: Vec<Value> = serde_json::from_str(&content).unwrap_or_default();
        let mut g = engine.lock().await;
        for (loaded, fact) in facts.iter().enumerate() {
            ingest_snapshot_fact(&mut g, fact, format!("loaded-{loaded}"));
        }
    }
    let mut map = state.agent_memgines.lock().await;
    let stored = map.entry(agent_id.to_string()).or_insert(engine).clone();
    Ok(stored)
}

/// Crash- and concurrency-safe write: serialize to a UNIQUE temp in the same
/// directory, then atomically rename over the target. A crash mid-write or a
/// concurrent writer to the same (client-chosen) path can no longer leave a
/// partial or interleaved file — `rename(2)` is atomic on the same filesystem,
/// and the per-call temp name (pid + monotonic seq) means two writers never
/// collide on the temp. Synchronous — call inside spawn_blocking.
fn atomic_write_sync(path: &std::path::Path, bytes: &[u8]) -> std::io::Result<()> {
    use std::sync::atomic::{AtomicU64, Ordering};
    static SEQ: AtomicU64 = AtomicU64::new(0);
    let seq = SEQ.fetch_add(1, Ordering::Relaxed);
    let mut tmp_os = path.as_os_str().to_owned();
    tmp_os.push(format!(".tmp.{}.{}", std::process::id(), seq));
    let tmp = std::path::PathBuf::from(tmp_os);
    std::fs::write(&tmp, bytes)?;
    std::fs::rename(&tmp, path)
}

/// Snapshot the agent's memgine to its disk file. Same on-wire shape
/// as `memory.persist` so manual snapshots and the daemon-owned
/// persistence stay interoperable.
async fn persist_agent_memgine(
    agent_id: &str,
    engine: &Arc<tokio::sync::Mutex<car_memgine::MemgineEngine>>,
) -> Result<(), String> {
    let path = agent_memgine_snapshot_path(agent_id)?;
    let g = engine.lock().await;
    let facts = memory_snapshot_facts(&g);
    // Release the SHARED memgine lock before serialize+write, then do that work
    // on the blocking pool: holding the lock across a blocking write serializes
    // every agent's memory ops and a slow/stuck write would wedge them all
    // (the incident). spawn_blocking also keeps the write off the tokio worker
    // (no thread-pinning) and lets the per-request deadline preempt at the await.
    drop(g);
    let path_owned = path.clone();
    tokio::task::spawn_blocking(move || -> Result<(), String> {
        let json = serde_json::to_string(&facts).map_err(|e| e.to_string())?;
        atomic_write_sync(&path_owned, json.as_bytes())
            .map_err(|e| format!("write {}: {}", path_owned.display(), e))
    })
    .await
    .map_err(|e| format!("persist_agent_memgine join: {e}"))?
}

// --- Memory handlers ---

/// `memory.fact_count` — return `valid_fact_count()` of the
/// session's memgine. Used by FFI bindings to mirror their
/// embedded `fact_count()` accessor without round-tripping a full
/// query. No params.
async fn handle_memory_fact_count(
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let engine_arc = session.effective_memgine().await;
    let engine = engine_arc.lock().await;
    Ok(Value::from(engine.valid_fact_count()))
}

/// Parse a `CommitAuthority` from its wire label.
///
/// Matched exhaustively against the enum's own `as_str` labels rather than
/// hand-written strings, so a new authority variant cannot silently become
/// unparseable here (project convention #2).
fn parse_commit_authority(s: &str) -> Result<car_verify::CommitAuthority, String> {
    use car_verify::CommitAuthority as A;
    for candidate in [
        A::Execution,
        A::Review,
        A::Coordination,
        A::Scheduling,
        A::SystemConfig,
    ] {
        if candidate.as_str() == s {
            return Ok(candidate);
        }
    }
    Err(format!(
        "unknown commit authority `{s}` (expected one of: execution, review, coordination, scheduling, system_config)"
    ))
}

/// `memory.set_admission_table` — install or clear the durable-state
/// admission rules for this session's memgine.
///
/// Params: `{ table: OwnershipTable | null }`. `null` (or an absent `table`)
/// clears the rules, turning the gate **off** — which is the default and what
/// every deployment gets until this is called. Off is not the same as an empty
/// table: an empty table is fail-closed and refuses every externally-authored
/// fact, which is the core's documented behaviour.
async fn handle_memory_set_admission_table(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let table: Option<car_verify::OwnershipTable> = match req.params.get("table") {
        None | Some(Value::Null) => None,
        Some(v) => {
            Some(serde_json::from_value(v.clone()).map_err(|e| format!("invalid table: {e}"))?)
        }
    };

    // Name the surfaces whose rule imposes no real constraint, so an operator
    // installing a table that only looks governed hears about it now rather
    // than discovering it after something unreviewed became durable.
    let ungated: Vec<&'static str> = table
        .as_ref()
        .map(|t| t.ungated_surfaces().iter().map(|s| s.as_str()).collect())
        .unwrap_or_default();
    let enabled = table.is_some();

    let engine_arc = session.effective_memgine().await;
    engine_arc.lock().await.set_admission_table(table);

    Ok(serde_json::json!({
        "enabled": enabled,
        "ungated_surfaces": ungated,
    }))
}

/// `memory.admission_table` — read back the installed rules.
///
/// Returns `{ enabled, table, ungated_surfaces }`. `enabled: false` with a null
/// `table` means the gate is off.
async fn handle_memory_admission_table(
    _req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let engine_arc = session.effective_memgine().await;
    let engine = engine_arc.lock().await;
    let table = engine.admission_table();
    Ok(serde_json::json!({
        "enabled": table.is_some(),
        "table": table,
        "ungated_surfaces": table
            .map(|t| t.ungated_surfaces().iter().map(|s| s.as_str()).collect::<Vec<_>>())
            .unwrap_or_default(),
    }))
}

async fn handle_memory_add_fact(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let subject = req
        .params
        .get("subject")
        .and_then(|v| v.as_str())
        .ok_or("missing subject")?;
    let body = req
        .params
        .get("body")
        .and_then(|v| v.as_str())
        .ok_or("missing body")?;
    let kind = req
        .params
        .get("kind")
        .and_then(|v| v.as_str())
        .unwrap_or("pattern");
    let tags = match req.params.get("tags") {
        Some(value) => serde_json::from_value::<Vec<String>>(value.clone())
            .map_err(|_| "tags must be an array of strings".to_string())?,
        None => vec![],
    };
    let source = match req.params.get("source") {
        Some(Value::String(value)) => value.clone(),
        Some(_) => return Err("source must be a string".to_string()),
        None => "user".to_string(),
    };
    // Route through `effective_memgine` so connections bound to a
    // lifecycle agent (#169) write into the daemon-owned per-agent
    // memgine instead of the per-WS ephemeral one (#170).
    // Durable-state admission (car#1031 core, wired here). This is the
    // externally-authored write path — a peer hands us a subject and body — so
    // it goes through `try_ingest_fact` rather than the raw ingest the engine
    // uses for its own derived facts.
    //
    // `produced_by` is fixed to `Execution` and is deliberately NOT
    // caller-settable: a peer calling this surface *is* the execution path,
    // and letting it name its own producer would let it satisfy any rule by
    // declaring itself whatever the rule expects.
    //
    // `committed_by` IS caller-supplied, and the limitation is worth stating
    // plainly rather than implying more than is true: this surface does not yet
    // authenticate the claim. So with a table configured, the gate enforces
    // **evidence** (a caller cannot conjure a passing verifier verdict) and
    // structure, but not committer **identity**. Binding the committer to the
    // authenticated session is follow-up work; until then treat this half as
    // bookkeeping, not a security boundary.
    let committed_by = req
        .params
        .get("committed_by")
        .and_then(|v| v.as_str())
        .map(parse_commit_authority)
        .transpose()?;
    let verdicts: Vec<car_verify::VerifierVerdict> = match req.params.get("verdicts") {
        Some(v) => {
            serde_json::from_value(v.clone()).map_err(|e| format!("invalid verdicts: {e}"))?
        }
        None => Vec::new(),
    };

    let engine_arc = session.effective_memgine().await;
    let count = {
        let mut engine = engine_arc.lock().await;
        // A caller-supplied id is identity, not a hint. A duplicate errors —
        // except when it re-states the fact already stored under it (same
        // subject and body): that is the at-least-once retry / daemon-reload
        // replay case, which resolves to the existing fact instead of failing
        // or silently duplicating. Same id, different content is a genuine
        // collision and still errors.
        let fid = match req.params.get("fact_id") {
            Some(Value::String(value)) if !value.is_empty() => {
                let fid = value.clone();
                if let Some((_, existing)) = engine.graph.get_by_fact_id(&fid) {
                    if existing.key == subject && existing.value == body {
                        return Ok(Value::from(engine.valid_fact_count()));
                    }
                    return Err(format!("fact_id `{fid}` already exists"));
                }
                fid
            }
            Some(Value::String(_)) => return Err("fact_id must not be empty".to_string()),
            Some(_) => return Err("fact_id must be a string".to_string()),
            // Auto-minted `ws-<count>` ids must dodge collisions too: a caller
            // may legally pass a literal `ws-7`, and deletions or a reload can
            // shrink the count past it. Bump past any id already in the graph
            // rather than letting ingest_fact silently rewrite to `ws-7-2`.
            None => {
                let mut n = engine.valid_fact_count();
                loop {
                    let candidate = format!("ws-{n}");
                    if engine.graph.get_by_fact_id(&candidate).is_none() {
                        break candidate;
                    }
                    n += 1;
                }
            }
        };
        let nix = engine
            .try_ingest_fact(
                &fid,
                subject,
                body,
                "user",
                "peer",
                chrono::Utc::now(),
                "global",
                None,
                vec![],
                kind == "constraint",
                car_verify::CommitAuthority::Execution,
                committed_by,
                verdicts,
            )
            .map_err(|decision| {
                // Surface the refusal reasons rather than a bare "denied" —
                // the caller needs to know which half it failed.
                format!(
                    "memory admission refused for `{}`: {}",
                    decision.id,
                    serde_json::to_string(&decision.refusals)
                        .unwrap_or_else(|_| "<unserialisable>".into())
                )
            })?;
        if let Some(node) = engine.graph.inner.node_weight_mut(nix) {
            node.metadata.tags = tags;
            node.metadata.provenance = vec![car_memgine::Provenance {
                source,
                ..Default::default()
            }];
        }
        engine.valid_fact_count()
    };
    // Persist after every add when the session is bound to a durable graph —
    // a supervised agent OR a memory namespace. This went through the agent
    // branch only, which is why namespace facts were never written (#82).
    persist_bound_agent_memory(session, &engine_arc, "memory.add_fact").await;
    Ok(Value::from(count))
}

/// Flush the session's bound graph after a mutation.
///
/// Covers BOTH durable axes. It used to handle only `agent_id`, so a
/// namespace-bound session accumulated facts that were never written anywhere
/// and vanished on daemon restart (car-releases#82) — CarHost restarts on every
/// Sparkle update, so that was routine data loss, not an edge case.
///
/// A session binds at most one of the two: `session.auth` picks the namespace
/// graph over the agent graph when both are supplied, and `memory_namespace`
/// is recorded on exactly the paths that make that choice. Persisting whichever
/// is set therefore writes the graph the session is actually using.
async fn persist_bound_agent_memory(
    session: &crate::session::ClientSession,
    engine_arc: &Arc<Mutex<car_memgine::MemgineEngine>>,
    op: &str,
) {
    if let Some(ns) = session.memory_namespace.lock().await.clone() {
        if let Err(e) = persist_namespace_memgine(&ns, engine_arc).await {
            tracing::warn!(memory_namespace = %ns, error = %e, op = %op,
                "namespace memgine persist failed; in-memory state is canonical");
        }
        return;
    }
    if let Some(id) = session.agent_id.lock().await.clone() {
        if let Err(e) = persist_agent_memgine(&id, engine_arc).await {
            tracing::warn!(agent_id = %id, error = %e, op = %op,
                "agent memgine persist failed; in-memory state is canonical");
        }
    }
}

#[derive(Debug, Deserialize)]
struct MemoryUpdateStatusParams {
    body: String,
    #[serde(default)]
    tenant_id: Option<String>,
}

async fn handle_memory_update_status(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let params: MemoryUpdateStatusParams = typed_params(&req.params)?;
    let engine_arc = session.effective_memgine().await;
    let status = {
        let mut engine = engine_arc.lock().await;
        engine.update_proactive_status(params.body, params.tenant_id)
    };
    serde_json::to_value(status).map_err(|e| e.to_string())
}

async fn handle_memory_maintain(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let params: car_memgine::ProactiveMaintenanceRequest = typed_params(&req.params)?;
    let events = {
        let log = session.runtime.log.lock().await;
        log.events().to_vec()
    };
    let engine_arc = session.effective_memgine().await;
    let report = {
        let mut engine = engine_arc.lock().await;
        engine.maintain_proactive_memory_from_events(&events, &params)
    };
    if !report.saved.is_empty() {
        persist_bound_agent_memory(session, &engine_arc, "memory.maintain").await;
    }
    {
        let mut log = session.runtime.log.lock().await;
        log.append(
            car_eventlog::EventKind::ProactiveMemoryMaintained,
            None,
            None,
            proactive_maintenance_event_data(&report),
        );
    }
    serde_json::to_value(report).map_err(|e| e.to_string())
}

async fn handle_memory_save_knowledge(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let save: car_memgine::ProactiveMemorySave = typed_params(&req.params)?;
    let engine_arc = session.effective_memgine().await;
    let saved = {
        let mut engine = engine_arc.lock().await;
        engine.save_proactive_knowledge(save)
    };
    persist_bound_agent_memory(session, &engine_arc, "memory.save_knowledge").await;
    serde_json::to_value(saved).map_err(|e| e.to_string())
}

async fn handle_memory_save_procedural(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let save: car_memgine::ProactiveMemorySave = typed_params(&req.params)?;
    let engine_arc = session.effective_memgine().await;
    let saved = {
        let mut engine = engine_arc.lock().await;
        engine.save_proactive_procedural(save)
    };
    persist_bound_agent_memory(session, &engine_arc, "memory.save_procedural").await;
    serde_json::to_value(saved).map_err(|e| e.to_string())
}

#[derive(Debug, Deserialize)]
struct MemoryDeleteParams {
    id: String,
}

async fn handle_memory_delete(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let params: MemoryDeleteParams = typed_params(&req.params)?;
    let engine_arc = session.effective_memgine().await;
    let deleted = {
        let mut engine = engine_arc.lock().await;
        engine.delete_proactive_memory(&params.id)
    };
    if deleted.deleted
        && !matches!(
            deleted.kind,
            Some(car_memgine::ProactiveMemoryEntryKind::Status)
        )
    {
        persist_bound_agent_memory(session, &engine_arc, "memory.delete").await;
    }
    serde_json::to_value(deleted).map_err(|e| e.to_string())
}

async fn handle_memory_query(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let query = req
        .params
        .get("query")
        .and_then(|v| v.as_str())
        .ok_or("missing query")?;
    let k = req.params.get("k").and_then(|v| v.as_u64()).unwrap_or(5) as usize;
    let engine_arc = session.effective_memgine().await;
    let engine = engine_arc.lock().await;
    let seeds = engine.graph.find_seeds(query, 5);
    // FFI parity with NAPI `query_facts` — both use Personalized PageRank so
    // transport choice doesn't shift ranking semantics. The bindings proxy this
    // result directly, including caller-authored identity and provenance.
    let hits = if !seeds.is_empty() {
        engine.graph.retrieve_ppr(&seeds, None, 0.5, k)
    } else {
        vec![]
    };
    let results: Vec<Value> = hits
        .iter()
        .filter_map(|hit| {
            let node = engine.graph.inner.node_weight(hit.node_ix)?;
            Some(serde_json::json!({
                "fact_id": node.fact_id,
                "subject": node.key,
                "body": node.value,
                "kind": format!("{:?}", node.kind).to_lowercase(),
                "confidence": hit.activation,
                "tags": node.metadata.tags,
                "source": node
                    .metadata
                    .provenance
                    .first()
                    .map(|entry| entry.source.as_str())
                    .unwrap_or(""),
            }))
        })
        .collect();
    serde_json::to_value(results).map_err(|e| e.to_string())
}

/// `memory.intervene` — proactive memory control-loop hook. Returns either a
/// concise transient reminder grounded in the graph, or an explicit silence
/// decision when no memory is strong enough to interrupt the next action.
async fn handle_memory_intervene(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let request: car_memgine::ProactiveMemoryRequest = typed_params(&req.params)?;
    let engine_arc = session.effective_memgine().await;
    let decision = {
        let mut engine = engine_arc.lock().await;
        engine.proactive_intervention(&request)
    };
    {
        let mut log = session.runtime.log.lock().await;
        log.append(
            car_eventlog::EventKind::ProactiveMemoryIntervention,
            None,
            None,
            proactive_intervention_event_data(&decision),
        );
    }
    serde_json::to_value(decision).map_err(|e| e.to_string())
}

/// `memory.evaluate` — offline calibration hook for proactive memory. Runs
/// labeled next-action cases against the current memory graph and compares the
/// selective selector against always-inject, passive-retrieval, and no-memory
/// baselines.
async fn handle_memory_evaluate(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let request: car_memgine::ProactiveEvaluationRequest = typed_params(&req.params)?;
    let engine_arc = session.effective_memgine().await;
    let engine = engine_arc.lock().await;
    let report = engine.evaluate_proactive_memory(&request);
    serde_json::to_value(report).map_err(|e| e.to_string())
}

async fn maybe_apply_proactive_memory(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    req: &mut car_inference::GenerateRequest,
) -> Result<(), String> {
    let tier = session.permission_gate.read().await.granted_tier();
    let mut request = match proactive_memory_activation(&msg.params, req, tier)? {
        ProactiveMemoryActivation::Disabled => return Ok(()),
        ProactiveMemoryActivation::Default => car_memgine::ProactiveMemoryRequest::default(),
        ProactiveMemoryActivation::Request(request) => request,
    };

    if request.query.trim().is_empty() {
        request.query = msg
            .params
            .get("context_query")
            .and_then(|v| v.as_str())
            .filter(|s| !s.trim().is_empty())
            .unwrap_or(&req.prompt)
            .to_string();
    }
    if request.recent.is_empty() && !req.prompt.trim().is_empty() {
        request.recent.push(req.prompt.clone());
    }
    let events = {
        let log = session.runtime.log.lock().await;
        log.events().to_vec()
    };
    let engine_arc = session.effective_memgine().await;
    let maintenance = {
        let mut engine = engine_arc.lock().await;
        engine.maintain_proactive_memory_from_events(
            &events,
            &car_memgine::ProactiveMaintenanceRequest {
                max_recent: 32,
                tenant_id: request.tenant_id.clone(),
            },
        )
    };
    if !maintenance.saved.is_empty() {
        persist_bound_agent_memory(session, &engine_arc, "memory_intervention.maintain").await;
    }
    {
        let mut log = session.runtime.log.lock().await;
        log.append(
            car_eventlog::EventKind::ProactiveMemoryMaintained,
            None,
            None,
            proactive_maintenance_event_data(&maintenance),
        );
    }
    let mut derived_trigger = maintenance.trigger;
    if tier == car_policy::PermissionTier::FullAccess
        || req.intent.as_ref().is_some_and(|intent| intent.high_stakes)
    {
        derived_trigger.high_risk_action = true;
    }
    request.trigger.merge(derived_trigger);

    let decision = {
        let mut engine = engine_arc.lock().await;
        engine.proactive_intervention(&request)
    };
    {
        let mut log = session.runtime.log.lock().await;
        log.append(
            car_eventlog::EventKind::ProactiveMemoryIntervention,
            None,
            None,
            proactive_intervention_event_data(&decision),
        );
    }
    if let car_memgine::ProactiveMemoryDecision::Inject { reminder, .. } = decision {
        append_context_block(req, "Proactive Memory", &reminder);
    }
    Ok(())
}

enum ProactiveMemoryActivation {
    Disabled,
    Default,
    Request(car_memgine::ProactiveMemoryRequest),
}

fn proactive_memory_activation(
    params: &Value,
    req: &car_inference::GenerateRequest,
    tier: car_policy::PermissionTier,
) -> Result<ProactiveMemoryActivation, String> {
    match params.get("memory_intervention") {
        Some(raw) if raw.as_bool() == Some(false) || raw.is_null() => {
            Ok(ProactiveMemoryActivation::Disabled)
        }
        Some(raw) if raw.as_bool() == Some(true) => Ok(ProactiveMemoryActivation::Default),
        Some(raw) => serde_json::from_value(raw.clone())
            .map(ProactiveMemoryActivation::Request)
            .map_err(|e| format!("invalid memory_intervention: {e}")),
        None if should_auto_apply_proactive_memory(req, tier) => {
            Ok(ProactiveMemoryActivation::Default)
        }
        None => Ok(ProactiveMemoryActivation::Disabled),
    }
}

fn should_auto_apply_proactive_memory(
    req: &car_inference::GenerateRequest,
    tier: car_policy::PermissionTier,
) -> bool {
    if tier == car_policy::PermissionTier::FullAccess {
        return true;
    }
    if req.tools.as_ref().is_some_and(|tools| !tools.is_empty()) {
        return true;
    }
    let Some(intent) = req.intent.as_ref() else {
        return false;
    };
    if intent.high_stakes {
        return true;
    }
    matches!(
        intent.task,
        Some(car_inference::TaskHint::Code | car_inference::TaskHint::Reasoning)
    )
}

fn proactive_maintenance_event_data(
    report: &car_memgine::ProactiveMaintenanceReport,
) -> HashMap<String, Value> {
    let mut data = proactive_trigger_event_data(&report.trigger);
    data.insert(
        "saved_count".to_string(),
        Value::from(report.saved.len() as u64),
    );
    data.insert(
        "skipped_existing".to_string(),
        Value::from(report.skipped_existing as u64),
    );
    data.insert(
        "status_updated".to_string(),
        Value::from(report.status.is_some()),
    );
    data
}

fn proactive_intervention_event_data(
    decision: &car_memgine::ProactiveMemoryDecision,
) -> HashMap<String, Value> {
    let mut data = HashMap::new();
    match decision {
        car_memgine::ProactiveMemoryDecision::Inject {
            selected,
            candidates,
            bank,
            ..
        } => {
            data.insert("decision".to_string(), Value::from("inject"));
            data.insert("selected_id".to_string(), Value::from(selected.id.clone()));
            data.insert(
                "selected_kind".to_string(),
                Value::from(format!("{:?}", selected.kind).to_ascii_lowercase()),
            );
            data.insert(
                "candidate_count".to_string(),
                Value::from(candidates.len() as u64),
            );
            data.insert(
                "bank_knowledge".to_string(),
                Value::from(bank.knowledge as u64),
            );
            data.insert(
                "bank_procedural".to_string(),
                Value::from(bank.procedural as u64),
            );
            data.insert(
                "bank_open_subgoals".to_string(),
                Value::from(bank.open_subgoals as u64),
            );
        }
        car_memgine::ProactiveMemoryDecision::Silent {
            reason,
            candidates,
            bank,
        } => {
            data.insert("decision".to_string(), Value::from("silent"));
            data.insert("reason".to_string(), Value::from(reason.clone()));
            data.insert(
                "candidate_count".to_string(),
                Value::from(candidates.len() as u64),
            );
            data.insert(
                "bank_knowledge".to_string(),
                Value::from(bank.knowledge as u64),
            );
            data.insert(
                "bank_procedural".to_string(),
                Value::from(bank.procedural as u64),
            );
            data.insert(
                "bank_open_subgoals".to_string(),
                Value::from(bank.open_subgoals as u64),
            );
        }
    }
    data
}

fn proactive_trigger_event_data(
    trigger: &car_memgine::ProactiveMemoryTrigger,
) -> HashMap<String, Value> {
    HashMap::from([
        (
            "repeated_failures".to_string(),
            Value::from(trigger.repeated_failures as u64),
        ),
        ("tool_error".to_string(), Value::from(trigger.tool_error)),
        (
            "explicit_uncertainty".to_string(),
            Value::from(trigger.explicit_uncertainty),
        ),
        (
            "high_risk_action".to_string(),
            Value::from(trigger.high_risk_action),
        ),
        (
            "context_shift".to_string(),
            Value::from(trigger.context_shift),
        ),
    ])
}

fn append_context_block(req: &mut car_inference::GenerateRequest, title: &str, body: &str) {
    let block = format!("## {title}\n{body}");
    req.context = Some(match req.context.take() {
        Some(existing) if !existing.trim().is_empty() => format!("{existing}\n\n{block}"),
        _ => block,
    });
}

#[cfg(test)]
mod proactive_memory_activation_tests {
    use super::{proactive_memory_activation, ProactiveMemoryActivation};
    use car_inference::{GenerateRequest, IntentHint, TaskHint};
    use car_policy::PermissionTier;
    use serde_json::json;

    fn req() -> GenerateRequest {
        GenerateRequest {
            prompt: "finish the task".to_string(),
            ..Default::default()
        }
    }

    fn is_disabled(activation: ProactiveMemoryActivation) -> bool {
        matches!(activation, ProactiveMemoryActivation::Disabled)
    }

    fn is_default(activation: ProactiveMemoryActivation) -> bool {
        matches!(activation, ProactiveMemoryActivation::Default)
    }

    #[test]
    fn explicit_false_disables_even_when_auto_eligible() {
        let mut req = req();
        req.tools = Some(vec![json!({"name": "edit_file"})]);
        let activation = proactive_memory_activation(
            &json!({"memory_intervention": false}),
            &req,
            PermissionTier::FullAccess,
        )
        .unwrap();
        assert!(is_disabled(activation));
    }

    #[test]
    fn explicit_true_uses_default_request() {
        let activation = proactive_memory_activation(
            &json!({"memory_intervention": true}),
            &req(),
            PermissionTier::ReadOnly,
        )
        .unwrap();
        assert!(is_default(activation));
    }

    #[test]
    fn explicit_object_is_preserved() {
        let activation = proactive_memory_activation(
            &json!({
                "memory_intervention": {
                    "query": "pricing rollout",
                    "tenant_id": "tenant-a"
                }
            }),
            &req(),
            PermissionTier::ReadOnly,
        )
        .unwrap();
        let ProactiveMemoryActivation::Request(request) = activation else {
            panic!("expected explicit request");
        };
        assert_eq!(request.query, "pricing rollout");
        assert_eq!(request.tenant_id.as_deref(), Some("tenant-a"));
    }

    #[test]
    fn ordinary_chat_is_not_auto_enabled() {
        let mut req = req();
        req.intent = Some(IntentHint {
            task: Some(TaskHint::Chat),
            ..Default::default()
        });
        let activation =
            proactive_memory_activation(&json!({}), &req, PermissionTier::ReadOnly).unwrap();
        assert!(is_disabled(activation));
    }

    #[test]
    fn tool_code_reasoning_and_high_stakes_requests_auto_enable() {
        let mut tool_req = req();
        tool_req.tools = Some(vec![json!({"name": "shell"})]);
        assert!(is_default(
            proactive_memory_activation(&json!({}), &tool_req, PermissionTier::ReadOnly).unwrap()
        ));

        let mut code_req = req();
        code_req.intent = Some(IntentHint {
            task: Some(TaskHint::Code),
            ..Default::default()
        });
        assert!(is_default(
            proactive_memory_activation(&json!({}), &code_req, PermissionTier::ReadOnly).unwrap()
        ));

        let mut reasoning_req = req();
        reasoning_req.intent = Some(IntentHint {
            task: Some(TaskHint::Reasoning),
            ..Default::default()
        });
        assert!(is_default(
            proactive_memory_activation(&json!({}), &reasoning_req, PermissionTier::ReadOnly)
                .unwrap()
        ));

        assert!(is_default(
            proactive_memory_activation(&json!({}), &req(), PermissionTier::FullAccess).unwrap()
        ));
    }
}

async fn handle_memory_build_context(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let query = req
        .params
        .get("query")
        .and_then(|v| v.as_str())
        .unwrap_or("");
    // FFI parity with NAPI `build_context(query, model_context_window)`.
    // When supplied, sizes the assembly budget against the model's window
    // instead of the fixed 8K default.
    let model_context_window = req
        .params
        .get("model_context_window")
        .and_then(|v| v.as_u64())
        .map(|w| w as usize);
    // `effective_memgine`: context assembly must read the graph the session's
    // facts actually went into. Reading the ephemeral graph while a namespace
    // was bound meant every namespace fact was stored, isolated, queryable —
    // and invisible to the model, which is the only consumer that matters.
    let engine_arc = session.effective_memgine().await;
    let mut engine = engine_arc.lock().await;
    Ok(Value::from(
        engine.build_context_for_model(query, model_context_window),
    ))
}

/// `memory.build_context_fast` — Fast-mode context assembly for
/// latency-sensitive paths (voice, real-time). Skips embedding flush,
/// skill lookup, PPR-based scoring, inline repairs, known-unknowns
/// extraction. Keeps identity, constraints, facts (creation order),
/// conversation, environment.
async fn handle_memory_build_context_fast(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let query = req
        .params
        .get("query")
        .and_then(|v| v.as_str())
        .unwrap_or("");
    let model_context_window = req
        .params
        .get("model_context_window")
        .and_then(|v| v.as_u64())
        .map(|w| w as usize);
    // Same binding fix as build_context above (#82).
    let engine_arc = session.effective_memgine().await;
    let mut engine = engine_arc.lock().await;
    Ok(Value::from(engine.build_context_with_options(
        query,
        model_context_window,
        car_memgine::ContextMode::Fast,
        None,
    )))
}

/// `memory.persist` — write the session's memgine to a JSON file
/// at `path`. Mirrors NAPI `persist_memory` (car-ffi-napi/src/lib.rs:797)
/// so daemon-mode clients can drive checkpoint/restore symmetrically
/// with embedded mode. Returns the number of facts written.
///
/// Filesystem caveat: `path` is interpreted on the daemon's filesystem,
/// not the caller's. Since the 2026-05 audit, `path` is also
/// sandboxed under `~/.car/memory/` via
/// [`car_ffi_common::memory_path::resolve`] — relative paths land
/// under the base, absolute paths must already be under the base,
/// `..` segments are rejected, symlinks pointing out are rejected.
/// Pre-2026-05 the path was passed straight to `std::fs::write` and
/// became an arbitrary file-write primitive. The base64-blob escape
/// hatch tracked in `Parslee-ai/car-releases#31` will plug into the
/// same resolver when it lands.
struct ProtocolHandshakeError {
    code: i32,
    message: String,
}

/// Negotiate this connection's daemon JSON-RPC protocol.
///
/// Protocol v3 is exact-version only. Capability negotiation follows transport
/// authentication and rejects any unsupported mandatory capability. The
/// negotiated version and capabilities are stored on
/// `ClientSession`, never `ServerState`, so a transport reconnect cannot inherit
/// another socket's compatibility proof. Repeating the same handshake is
/// intentionally idempotent.
fn handle_server_handshake(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, ProtocolHandshakeError> {
    let client_protocol = req
        .params
        .get("protocol_version")
        .and_then(Value::as_u64)
        .ok_or_else(|| ProtocolHandshakeError {
            code: car_proto::PROTOCOL_VERSION_MISMATCH_ERROR_CODE,
            message: format!(
                "{} `server.handshake` requires an unsigned numeric \
                 `protocol_version`; this daemon requires v{}",
                car_proto::PROTOCOL_VERSION_MISMATCH_MESSAGE_PREFIX,
                car_proto::PROTOCOL_VERSION,
            ),
        })?;

    if client_protocol != u64::from(car_proto::PROTOCOL_VERSION) {
        return Err(ProtocolHandshakeError {
            code: car_proto::PROTOCOL_VERSION_MISMATCH_ERROR_CODE,
            message: format!(
                "{} client requested v{}, but this daemon requires v{}; \
                 update/restart CarHost and car-server so their wire protocols match",
                car_proto::PROTOCOL_VERSION_MISMATCH_MESSAGE_PREFIX,
                client_protocol,
                car_proto::PROTOCOL_VERSION,
            ),
        });
    }

    fn string_array(params: &Value, field: &str) -> Result<Vec<String>, ProtocolHandshakeError> {
        let Some(value) = params.get(field) else {
            return Ok(Vec::new());
        };
        let values = value.as_array().ok_or_else(|| ProtocolHandshakeError {
            code: car_proto::PROTOCOL_CAPABILITY_MISMATCH_ERROR_CODE,
            message: format!(
                "{} `{field}` must be an array of capability strings",
                car_proto::PROTOCOL_CAPABILITY_MISMATCH_MESSAGE_PREFIX,
            ),
        })?;
        values
            .iter()
            .map(|value| {
                value
                    .as_str()
                    .filter(|capability| !capability.trim().is_empty())
                    .map(str::to_string)
                    .ok_or_else(|| ProtocolHandshakeError {
                        code: car_proto::PROTOCOL_CAPABILITY_MISMATCH_ERROR_CODE,
                        message: format!(
                            "{} `{field}` entries must be non-empty strings",
                            car_proto::PROTOCOL_CAPABILITY_MISMATCH_MESSAGE_PREFIX,
                        ),
                    })
            })
            .collect()
    }

    let required_capabilities = string_array(&req.params, "required_capabilities")?;
    let optional_capabilities = string_array(&req.params, "optional_capabilities")?;
    let negotiated_capabilities =
        car_proto::negotiate_capabilities(&required_capabilities, &optional_capabilities).map_err(
            |missing| ProtocolHandshakeError {
                code: car_proto::PROTOCOL_CAPABILITY_MISMATCH_ERROR_CODE,
                message: format!(
            "{} unsupported mandatory capabilities: {}; update/restart CarHost and car-server",
            car_proto::PROTOCOL_CAPABILITY_MISMATCH_MESSAGE_PREFIX,
            missing.join(", "),
        ),
            },
        )?;

    session.negotiated_protocol_version.store(
        car_proto::PROTOCOL_VERSION,
        std::sync::atomic::Ordering::Release,
    );
    *session
        .negotiated_capabilities
        .write()
        .expect("negotiated capability lock poisoned") =
        negotiated_capabilities.iter().cloned().collect();

    // The assistant's identity rides on the handshake every host already
    // performs, so a host knows what to call the assistant before it renders a
    // single label. `load_or_default` deliberately keeps a damaged optional
    // identity record from locking every host out of the daemon; the dedicated
    // identity RPC remains the surface that reports that read error.
    let identity = car_identity::IdentityStore::from_home().load_or_default();

    // Echo the client's own build version back. The Rust clients have always
    // sent it and this daemon always threw it away, so the only place a
    // `car-runtime` package's version ever appeared was inside the skew
    // warning's prose — and `car --version` answers for the bundled CLI, a
    // different component (Parslee-ai/car#1050). Echoing makes it a readable
    // field on the handshake every client already performs. Additive, so no
    // PROTOCOL_VERSION bump.
    //
    // `unknown` is the honest answer, not a placeholder to read past: the
    // native CarHost clients (macOS, iOS, Android) and the dashboard send no
    // `client_version`, so they land here. Do not treat this log line or field
    // as identifying every connect — only the ones that report.
    //
    // Truncated because it is client-controlled and otherwise unbounded. A
    // semver plus pre-release metadata fits well inside this; anything longer
    // is not a version, and it should not reach the log or the reply at full
    // length.
    const MAX_CLIENT_VERSION: usize = 64;
    let reported = req
        .params
        .get("client_version")
        .and_then(Value::as_str)
        .unwrap_or("unknown");
    let client_version = match reported.char_indices().nth(MAX_CLIENT_VERSION) {
        Some((cut, _)) => &reported[..cut],
        None => reported,
    };
    tracing::debug!(
        target: "car_server_core::handler",
        client_version,
        server_version = env!("CARGO_PKG_VERSION"),
        "server.handshake negotiated"
    );

    Ok(serde_json::json!({
        "protocol_version": car_proto::PROTOCOL_VERSION,
        "server_version": env!("CARGO_PKG_VERSION"),
        "client_protocol_version": client_protocol,
        "client_version": client_version,
        "negotiated_capabilities": negotiated_capabilities,
        "assistant_name": identity.name,
        "assistant_aliases": identity.aliases(),
        "assistant_brand": car_identity::BRAND_NAME,
    }))
}

async fn handle_memory_persist(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let path = req
        .params
        .get("path")
        .and_then(|v| v.as_str())
        .ok_or("missing path")?;
    let resolved = car_ffi_common::memory_path::resolve(path)
        .map_err(|e| format!("memory.persist rejected path {path:?}: {e}"))?;
    // `effective_memgine`, not the ephemeral `memgine`: with a namespace or an
    // agent bound, reading the ephemeral graph serialized an EMPTY array and
    // reported 0 records while the real facts sat in the bound graph
    // (car-releases#82). A durability call that reports success having written
    // nothing is worse than one that fails.
    let engine_arc = session.effective_memgine().await;
    let engine = engine_arc.lock().await;
    let facts = memory_snapshot_facts(&engine);
    let count = facts.len();
    // Release the shared memgine lock, then serialize+write on the blocking pool
    // (see persist_agent_memgine): never hold the lock across blocking I/O, keep
    // the write off the tokio worker, and let the deadline preempt at the await.
    drop(engine);
    let resolved_owned = resolved.clone();
    tokio::task::spawn_blocking(move || -> Result<(), String> {
        let json = serde_json::to_string(&facts).map_err(|e| e.to_string())?;
        atomic_write_sync(&resolved_owned, json.as_bytes())
            .map_err(|e| format!("failed to write {}: {}", resolved_owned.display(), e))
    })
    .await
    .map_err(|e| format!("memory.persist join: {e}"))??;
    Ok(Value::from(count as u64))
}

/// `memory.load` — replace the session's memgine with facts from the
/// JSON file at `path`. Mirrors NAPI `load_memory`
/// (car-ffi-napi/src/lib.rs:121). Same `~/.car/memory/` sandboxing
/// as `memory.persist` since the 2026-05 audit — relative paths
/// land under the base, anything that escapes is rejected.
async fn handle_memory_load(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let path = req
        .params
        .get("path")
        .and_then(|v| v.as_str())
        .ok_or("missing path")?;
    let resolved = car_ffi_common::memory_path::resolve(path)
        .map_err(|e| format!("memory.load rejected path {path:?}: {e}"))?;
    let content = std::fs::read_to_string(&resolved)
        .map_err(|e| format!("failed to read {}: {}", resolved.display(), e))?;
    let facts: Vec<Value> =
        serde_json::from_str(&content).map_err(|e| format!("invalid JSON: {}", e))?;
    // Symmetric with memory.persist above. This one was worse than a no-op:
    // `reset()` cleared the EPHEMERAL graph and loaded into it, so a
    // namespace-bound caller restoring a snapshot silently left the bound
    // graph untouched and believed it had been restored.
    let engine_arc = session.effective_memgine().await;
    let mut engine = engine_arc.lock().await;
    engine.reset();
    let mut count: u32 = 0;
    for fact in &facts {
        ingest_snapshot_fact(&mut engine, fact, format!("loaded-{count}"));
        count += 1;
    }
    Ok(Value::from(count))
}

// --- Skill handlers ---

async fn handle_skill_ingest(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let name = req
        .params
        .get("name")
        .and_then(|v| v.as_str())
        .ok_or("missing name")?;
    let code = req
        .params
        .get("code")
        .and_then(|v| v.as_str())
        .ok_or("missing code")?;
    let platform = req
        .params
        .get("platform")
        .and_then(|v| v.as_str())
        .unwrap_or("unknown");
    let persona = req
        .params
        .get("persona")
        .and_then(|v| v.as_str())
        .unwrap_or("");
    let url_pattern = req
        .params
        .get("url_pattern")
        .and_then(|v| v.as_str())
        .unwrap_or("");
    let description = req
        .params
        .get("description")
        .and_then(|v| v.as_str())
        .unwrap_or("");
    let supersedes = opt_str(&req.params, "supersedes");
    let keywords: Vec<String> = req
        .params
        .get("task_keywords")
        .and_then(|v| v.as_array())
        .map(|arr| {
            arr.iter()
                .filter_map(|v| v.as_str().map(String::from))
                .collect()
        })
        .unwrap_or_default();

    let trigger = car_memgine::SkillTrigger {
        persona: persona.into(),
        url_pattern: url_pattern.into(),
        task_keywords: keywords,
        structured: None,
    };
    let mut engine = session.memgine.lock().await;
    let node = engine.ingest_skill(
        name,
        code,
        platform,
        trigger,
        description,
        supersedes,
        vec![],
        vec![],
    );
    Ok(Value::from(node.index() as u64))
}

async fn handle_skill_find(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let persona = req
        .params
        .get("persona")
        .and_then(|v| v.as_str())
        .unwrap_or("");
    let url = str_or(&req.params, "url", "");
    let task = req
        .params
        .get("task")
        .and_then(|v| v.as_str())
        .unwrap_or("");
    let max = req
        .params
        .get("max_results")
        .and_then(|v| v.as_u64())
        .unwrap_or(1) as usize;
    // Tenant-scoped matching (linus review C-3): a bound/param tenant
    // sees only its own skills; an unscoped caller sees only unscoped
    // skills. Strict isolation over the WS boundary, consistent with
    // state.keys/state.snapshot — the legacy see-everything find_skill
    // remains available to in-process embedders only.
    let tenant = effective_tenant(req, session).await?;
    let engine = session.memgine.lock().await;
    let results = engine.find_skill_scoped(persona, url, task, max, tenant.as_deref());
    let json: Vec<Value> = results
        .iter()
        .map(|(m, s)| {
            serde_json::json!({
                "name": m.name, "code": m.code, "platform": m.platform,
                "description": m.description, "stats": m.stats, "match_score": s,
            })
        })
        .collect();
    serde_json::to_value(json).map_err(|e| e.to_string())
}

async fn handle_skill_report(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let name = req
        .params
        .get("skill_name")
        .and_then(|v| v.as_str())
        .ok_or("missing skill_name")?;
    let outcome_str = req
        .params
        .get("outcome")
        .and_then(|v| v.as_str())
        .ok_or("missing outcome")?;
    let outcome = match outcome_str {
        "success" => car_memgine::SkillOutcome::Success,
        _ => car_memgine::SkillOutcome::Fail,
    };
    // Tenant-exact resolution (linus review): one tenant's outcome
    // reports must not degrade another tenant's same-named skill.
    let tenant = effective_tenant(req, session).await?;
    let mut engine = session.memgine.lock().await;
    let stats = engine
        .report_outcome_scoped(name, outcome, tenant.as_deref())
        .ok_or(format!("skill '{}' not found", name))?;
    serde_json::to_value(stats).map_err(|e| e.to_string())
}

/// Gate a skill's deployment capability against its provenance, folding the
/// named skill's **live** track record into the decision (arXiv 2602.12430
/// "Agent Skills"; `docs/proposals/skill-trust-governance.md`). The host
/// supplies the static `provenance` (signature/scan/source — typically built
/// from a `car-bundle` manifest via `assess_signature_trust`) and the
/// `requested_tier`; the engine overrides the lifecycle counts with the skill's
/// real `success_count`/`fail_count`, so a skill failing in the field is denied
/// despite an official signature. Returns the `SkillDeploymentDecision` JSON.
async fn handle_skill_gate_deployment(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let name = req
        .params
        .get("skill_name")
        .and_then(|v| v.as_str())
        .ok_or("missing skill_name")?;
    let provenance: car_policy::skill_trust::SkillProvenance = serde_json::from_value(
        req.params
            .get("provenance")
            .cloned()
            .unwrap_or_else(|| serde_json::json!({})),
    )
    .map_err(|e| format!("invalid provenance: {e}"))?;
    let tier_str = req
        .params
        .get("requested_tier")
        .and_then(|v| v.as_str())
        .ok_or("missing requested_tier")?;
    let requested =
        car_policy::permission::PermissionTier::from_str_opt(tier_str).ok_or_else(|| {
            format!(
                "invalid requested_tier '{tier_str}' \
                 (expected read_only|sandbox_edit|full_access)"
            )
        })?;
    let engine = session.memgine.lock().await;
    let decision = engine.gate_skill_deployment(name, provenance, requested);
    serde_json::to_value(decision).map_err(|e| e.to_string())
}

/// Enforce a skill's deployment at load time against the session's durable
/// `ApprovalLedger` — the HITL bridge (arXiv 2602.12430 "Agent Skills" Slice 4;
/// `docs/proposals/skill-trust-governance.md`). Gates the skill (folding its
/// live track record), then resolves the verdict against standing operator
/// decisions: `Allow`/`Downgrade` deploy autonomously (a downgrade is the gate's
/// own safe mitigation), a `Deny` is overridden if an operator previously
/// approved it, blocked if rejected, or surfaced as a `pending_approval` the host
/// routes through the existing `permission.approve`/`permission.reject` flow by
/// the returned `fingerprint`. Returns `{ decision, enforcement, pending_approval? }`.
async fn handle_skill_enforce_deployment(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    let name = req
        .params
        .get("skill_name")
        .and_then(|v| v.as_str())
        .ok_or("missing skill_name")?;
    let provenance: car_policy::skill_trust::SkillProvenance = serde_json::from_value(
        req.params
            .get("provenance")
            .cloned()
            .unwrap_or_else(|| serde_json::json!({})),
    )
    .map_err(|e| format!("invalid provenance: {e}"))?;
    let tier_str = req
        .params
        .get("requested_tier")
        .and_then(|v| v.as_str())
        .ok_or("missing requested_tier")?;
    let requested =
        car_policy::permission::PermissionTier::from_str_opt(tier_str).ok_or_else(|| {
            format!(
                "invalid requested_tier '{tier_str}' \
                 (expected read_only|sandbox_edit|full_access)"
            )
        })?;

    // Gate first (folds the skill's live success/fail record into the verdict).
    let decision = {
        let engine = session.memgine.lock().await;
        engine.gate_skill_deployment(name, provenance, requested)
    };
    // Then enforce against the daemon's SHARED durable HITL ledger — the same
    // ledger `permission.*` records decisions to, from ANY connection (C1).
    let enforcement = {
        let ledger = state.approval_ledger.read().await;
        car_policy::skill_trust::enforce_deployment(&decision, name, requested, &ledger)
    };

    // Extract the pending fingerprint before the values are moved into the
    // response (so the host can resolve it via permission.approve/reject).
    let pending_json = enforcement.pending.as_ref().map(|p| {
        serde_json::json!({
            "fingerprint": p.fingerprint,
            "skill_name": p.skill_name,
            "requested_tier": requested.as_str(),
        })
    });
    let mut resp = serde_json::json!({ "decision": decision, "enforcement": enforcement });
    if let Some(pj) = pending_json {
        resp.as_object_mut()
            .unwrap()
            .insert("pending_approval".into(), pj);
    }
    Ok(resp)
}

/// Ingest a skill **through the deployment gate** (arXiv 2602.12430 "Agent
/// Skills" — the loader integration). Gates the skill's provenance against the
/// requested capability, enforces the verdict against the session's durable
/// `ApprovalLedger`, and **only adds the skill to the graph when deployment is
/// permitted** — stamping the granted ceiling onto the skill so later execution
/// honours it. A denied skill is not ingested; an unseen deny surfaces a
/// `pending_approval` resolved through `permission.approve`/`permission.reject`.
/// Same flat skill fields as `skill.ingest`, plus `provenance?` and
/// `requested_tier`. Returns `{ ingested, node?, decision, enforcement,
/// pending_approval? }`.
async fn handle_skill_ingest_governed(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    let name = req
        .params
        .get("name")
        .and_then(|v| v.as_str())
        .ok_or("missing name")?;
    let code = req
        .params
        .get("code")
        .and_then(|v| v.as_str())
        .ok_or("missing code")?;
    let platform = req
        .params
        .get("platform")
        .and_then(|v| v.as_str())
        .unwrap_or("unknown");
    let persona = req
        .params
        .get("persona")
        .and_then(|v| v.as_str())
        .unwrap_or("");
    let url_pattern = req
        .params
        .get("url_pattern")
        .and_then(|v| v.as_str())
        .unwrap_or("");
    let description = req
        .params
        .get("description")
        .and_then(|v| v.as_str())
        .unwrap_or("");
    let supersedes = opt_str(&req.params, "supersedes");
    let keywords: Vec<String> = req
        .params
        .get("task_keywords")
        .and_then(|v| v.as_array())
        .map(|arr| {
            arr.iter()
                .filter_map(|v| v.as_str().map(String::from))
                .collect()
        })
        .unwrap_or_default();
    let trigger = car_memgine::SkillTrigger {
        persona: persona.into(),
        url_pattern: url_pattern.into(),
        task_keywords: keywords,
        structured: None,
    };

    let provenance: car_policy::skill_trust::SkillProvenance = serde_json::from_value(
        req.params
            .get("provenance")
            .cloned()
            .unwrap_or_else(|| serde_json::json!({})),
    )
    .map_err(|e| format!("invalid provenance: {e}"))?;
    let tier_str = req
        .params
        .get("requested_tier")
        .and_then(|v| v.as_str())
        .ok_or("missing requested_tier")?;
    let requested =
        car_policy::permission::PermissionTier::from_str_opt(tier_str).ok_or_else(|| {
            format!(
                "invalid requested_tier '{tier_str}' \
                 (expected read_only|sandbox_edit|full_access)"
            )
        })?;

    // Gate + enforce against the daemon's SHARED durable ledger (C1),
    // ingesting only on a deploy verdict. Holding the ledger read-lock across
    // the engine ingest is safe: no handler holds the engine and
    // approval-ledger locks in the opposite order, so there is no inversion
    // to deadlock against.
    let ledger = state.approval_ledger.read().await;
    let out = {
        let mut engine = session.memgine.lock().await;
        engine.ingest_skill_governed(
            name,
            code,
            platform,
            trigger,
            description,
            supersedes,
            vec![],
            vec![],
            provenance,
            requested,
            &ledger,
        )
    };
    drop(ledger);

    let pending_json = out.enforcement.pending.as_ref().map(|p| {
        serde_json::json!({
            "fingerprint": p.fingerprint,
            "skill_name": p.skill_name,
            "requested_tier": requested.as_str(),
        })
    });
    let mut resp = serde_json::json!({
        "ingested": out.ingested.is_some(),
        "node": out.ingested.map(|n| n.index()),
        "decision": out.decision,
        "enforcement": out.enforcement,
    });
    if let Some(pj) = pending_json {
        resp.as_object_mut()
            .unwrap()
            .insert("pending_approval".into(), pj);
    }
    Ok(resp)
}

/// Resolve the [`car_policy::skill_trust::SkillProvenance`] a `skill.adopt_pack`
/// call is governed under, from the three mutually-exclusive shapes a caller may
/// send. Pure (no I/O, no locks) so the precedence is unit-testable:
///
/// 1. `manifest` — the signed `car-bundle` manifest the pack shipped in. The
///    **derived** path: `signed`/`signer_trusted` are computed from it against
///    the operator's `trusted` keyring; the caller cannot assert either flag.
/// 2. `provenance` — a caller-assembled `SkillProvenance`, taken at **face
///    value**: nothing here clamps or cross-checks it, so any caller that can
///    reach this method can assert any tier, up to `official` + `full_access`.
///    It is a trusted-caller escape hatch for hosts carrying their own
///    attestation, inherited verbatim from `skill.ingest_governed`, and it is
///    why the operator-keyring rule constrains the `manifest` path only.
/// 3. Neither — unsigned and untrusted, with only the scan/source hints the
///    caller passed. The conservative default: the gate sees no signature.
///
/// Sending both `manifest` and `provenance` is an **error**, not a precedence
/// question. Silently preferring one would drop a security-relevant input the
/// caller believed was in force.
fn resolve_adopt_provenance(
    params: &Value,
    trusted: &[String],
) -> Result<car_policy::skill_trust::SkillProvenance, String> {
    let scanned = params
        .get("scanned")
        .and_then(|v| v.as_bool())
        .unwrap_or(false);
    let vulnerabilities = params
        .get("vulnerabilities")
        .and_then(|v| v.as_u64())
        .unwrap_or(0);
    let source_str = params
        .get("source")
        .and_then(|v| v.as_str())
        .unwrap_or("unknown");
    let source: car_policy::skill_trust::SkillSource =
        serde_json::from_value(Value::String(source_str.to_string())).map_err(|_| {
            format!(
                "invalid source '{source_str}' \
                 (expected official|first_party|community|unknown)"
            )
        })?;

    let manifest_val = params.get("manifest");
    let provenance_val = params.get("provenance");
    if manifest_val.is_some() && provenance_val.is_some() {
        return Err(
            "pass either 'manifest' (signature derived from the bundle) or \
                    'provenance' (caller-assembled), not both"
                .into(),
        );
    }

    if let Some(mv) = manifest_val {
        let manifest: car_registry::manifest::AgentManifest =
            serde_json::from_value(mv.clone()).map_err(|e| format!("invalid manifest: {e}"))?;
        return Ok(car_memgine::MemgineEngine::skill_provenance_from_bundle(
            &manifest,
            trusted,
            scanned,
            vulnerabilities,
            source,
        ));
    }

    if let Some(pv) = provenance_val {
        return serde_json::from_value(pv.clone()).map_err(|e| format!("invalid provenance: {e}"));
    }

    Ok(car_policy::skill_trust::SkillProvenance {
        scanned,
        vulnerabilities,
        source,
        ..Default::default()
    })
}

/// Adopt an installed **skill pack** through the skill-trust deployment gate —
/// the daemon call-site for governed pack adoption (arXiv 2602.12430 "Agent
/// Skills"; `Parslee-ai/car` `docs/proposals/skill-trust-governance.md`).
/// Until this method existed, `ApprovedSkillPack::materialize_into_memgine_governed`
/// was reachable only by an in-process Rust consumer supplying its own ledger,
/// so a daemon host could not adopt a pack under governance at all.
///
/// Governance is **unconditional**: there is no ungoverned mode on this method.
/// Every skill in the pack is ingested through the gate under one provenance
/// (packs are signed and scanned as a unit) and one `requested_tier`, and a
/// `Deny` skill never enters the graph.
///
/// **Adoption is per-skill, so a pack can adopt partially.** The verdict is
/// computed per skill (the approval fingerprint is a function of skill name +
/// requested tier), so the skills that deploy land in `loaded` while the rest
/// surface in `pending`/`refused`; the host resolves those and re-adopts the
/// same pack. All-or-nothing would let one unresolved skill block the pack.
///
/// Provenance comes from the bundle `manifest`, whose signature is verified
/// against the operator's `.car/config.toml` `trusted_skill_signers` keyring
/// ([`seed_trusted_skill_signers`] — never from the request), or from a
/// caller-assembled `provenance`, defaulting conservatively to
/// unsigned/unscanned when neither is sent. Only the `manifest` path derives
/// its signature flags; a `provenance` object is taken at face value, so a
/// caller that can reach this method can assert any trust tier (the
/// `skill.ingest_governed` contract, unchanged here) — see
/// [`resolve_adopt_provenance`].
///
/// Params: `pack` (an `ApprovedSkillPack`), `requested_tier?` (default
/// `read_only`), and either `manifest?` or `provenance?`, plus optional
/// `scanned?`/`vulnerabilities?`/`source?`. Returns `{ loaded, pending, refused,
/// requested_tier, provenance, trusted_signers }`; an unseen deny surfaces in
/// `pending` with a `fingerprint` the host resolves via
/// `permission.approve`/`permission.reject` and then re-adopts.
async fn handle_skill_adopt_pack(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    let pack_val = req.params.get("pack").ok_or("missing 'pack' parameter")?;
    let pack: car_memgine::ApprovedSkillPack =
        serde_json::from_value(pack_val.clone()).map_err(|e| format!("invalid pack: {e}"))?;
    let tier_str = req
        .params
        .get("requested_tier")
        .and_then(|v| v.as_str())
        .unwrap_or("read_only");
    let requested =
        car_policy::permission::PermissionTier::from_str_opt(tier_str).ok_or_else(|| {
            format!(
                "invalid requested_tier '{tier_str}' \
                 (expected read_only|sandbox_edit|full_access)"
            )
        })?;

    // The keyring is operator config, never request input — see
    // `seed_trusted_skill_signers`.
    let trusted = seed_trusted_skill_signers();
    let provenance = resolve_adopt_provenance(&req.params, &trusted)?;

    // Gate + enforce against the daemon's SHARED durable ledger (C1). Holding
    // the ledger read-lock across the engine materialization is safe: no
    // handler holds the engine and approval-ledger locks in the opposite
    // order, so there is no inversion to deadlock against.
    let ledger = state.approval_ledger.read().await;
    let out = {
        let mut engine = session.memgine.lock().await;
        pack.materialize_into_memgine_governed(&mut engine, &provenance, requested, &ledger)
    };
    drop(ledger);

    let pending: Vec<Value> = out
        .pending
        .iter()
        .map(|(skill_id, fingerprint)| {
            serde_json::json!({ "skill_id": skill_id, "fingerprint": fingerprint })
        })
        .collect();
    let refused: Vec<Value> = out
        .refused
        .iter()
        .map(|(skill_id, reason)| serde_json::json!({ "skill_id": skill_id, "reason": reason }))
        .collect();

    Ok(serde_json::json!({
        "loaded": out.loaded,
        "pending": pending,
        "refused": refused,
        "requested_tier": requested.as_str(),
        "provenance": provenance,
        // The COUNT, deliberately — never the key ids. It answers the one
        // question an operator debugging a downgrade has ("your keyring is
        // empty, that is why a signed pack stopped at Verified") without
        // echoing configured identifiers back over the wire to whoever asked.
        "trusted_signers": trusted.len(),
    }))
}

// ---------------------------------------------------------------------------
// Multi-agent coordination handlers
//
// The WsAgentRunner sends a `multi.run_agent` JSON-RPC request to the client.
// The client runs the model loop and responds with AgentOutput JSON.
// ---------------------------------------------------------------------------

/// AgentRunner backed by WebSocket callback to the client.
struct WsAgentRunner {
    channel: Arc<WsChannel>,
    host: Arc<crate::host::HostState>,
    client_id: String,
}

#[async_trait::async_trait]
impl car_multi::AgentRunner for WsAgentRunner {
    async fn run(
        &self,
        spec: &car_multi::AgentSpec,
        task: &str,
        _runtime: &car_engine::Runtime,
        _mailbox: &car_multi::Mailbox,
    ) -> std::result::Result<car_multi::AgentOutput, car_multi::MultiError> {
        use futures::SinkExt;

        let request_id = self.channel.next_request_id();
        let agent_id = agent_id_for_run(&self.client_id, &spec.name, &request_id);
        let agent = self
            .host
            .register_agent(
                &self.client_id,
                RegisterHostAgentRequest {
                    id: Some(agent_id.clone()),
                    name: spec.name.clone(),
                    kind: "callback".to_string(),
                    capabilities: spec.tools.clone(),
                    project: spec
                        .metadata
                        .get("project")
                        .and_then(|v| v.as_str())
                        .map(str::to_string),
                    pid: None,
                    display: serde_json::from_value(
                        spec.metadata
                            .get("display")
                            .cloned()
                            .unwrap_or(serde_json::Value::Null),
                    )
                    .unwrap_or_default(),
                    metadata: serde_json::to_value(&spec.metadata).unwrap_or(Value::Null),
                },
            )
            .await
            .map_err(|e| car_multi::MultiError::AgentFailed(spec.name.clone(), e))?;
        let _ = self
            .host
            .set_status(
                &self.client_id,
                SetHostAgentStatusRequest {
                    agent_id: agent.id.clone(),
                    status: HostAgentStatus::Running,
                    current_task: Some(task.to_string()),
                    message: Some(format!("{} started", spec.name)),
                    payload: serde_json::json!({ "task": task }),
                },
            )
            .await;

        let rpc_request = serde_json::json!({
            "jsonrpc": "2.0",
            "method": "multi.run_agent",
            "params": {
                "spec": spec,
                "task": task,
            },
            "id": request_id,
        });

        // Create oneshot channel for the response
        let (tx, rx) = tokio::sync::oneshot::channel();
        self.channel
            .pending
            .lock()
            .await
            .insert(request_id.clone(), tx);

        let msg = Message::Text(
            serde_json::to_string(&rpc_request)
                .map_err(|e| car_multi::MultiError::AgentFailed(spec.name.clone(), e.to_string()))?
                .into(),
        );
        if let Err(e) = self.channel.write.lock().await.send(msg).await {
            let _ = self
                .host
                .set_status(
                    &self.client_id,
                    SetHostAgentStatusRequest {
                        agent_id: agent_id.clone(),
                        status: HostAgentStatus::Errored,
                        current_task: None,
                        message: Some(format!("{} failed to start", spec.name)),
                        payload: serde_json::json!({ "error": e.to_string() }),
                    },
                )
                .await;
            return Err(car_multi::MultiError::AgentFailed(
                spec.name.clone(),
                format!("ws send error: {}", e),
            ));
        }

        // Wait for client response (5 min timeout for model loops)
        let response = match tokio::time::timeout(std::time::Duration::from_secs(300), rx).await {
            Ok(Ok(response)) => response,
            Ok(Err(_)) => {
                let _ = self
                    .host
                    .set_status(
                        &self.client_id,
                        SetHostAgentStatusRequest {
                            agent_id: agent_id.clone(),
                            status: HostAgentStatus::Errored,
                            current_task: None,
                            message: Some(format!("{} callback channel closed", spec.name)),
                            payload: Value::Null,
                        },
                    )
                    .await;
                return Err(car_multi::MultiError::AgentFailed(
                    spec.name.clone(),
                    "agent callback channel closed".into(),
                ));
            }
            Err(_) => {
                let _ = self
                    .host
                    .set_status(
                        &self.client_id,
                        SetHostAgentStatusRequest {
                            agent_id: agent_id.clone(),
                            status: HostAgentStatus::Errored,
                            current_task: None,
                            message: Some(format!("{} timed out", spec.name)),
                            payload: Value::Null,
                        },
                    )
                    .await;
                return Err(car_multi::MultiError::AgentFailed(
                    spec.name.clone(),
                    "agent callback timed out (300s)".into(),
                ));
            }
        };

        if let Some(err) = response.error {
            let _ = self
                .host
                .set_status(
                    &self.client_id,
                    SetHostAgentStatusRequest {
                        agent_id: agent_id.clone(),
                        status: HostAgentStatus::Errored,
                        current_task: None,
                        message: Some(format!("{} errored", spec.name)),
                        payload: serde_json::json!({ "error": err }),
                    },
                )
                .await;
            return Err(car_multi::MultiError::AgentFailed(spec.name.clone(), err));
        }

        let output_value = response.output.unwrap_or(Value::Null);
        let output: car_multi::AgentOutput = serde_json::from_value(output_value).map_err(|e| {
            car_multi::MultiError::AgentFailed(
                spec.name.clone(),
                format!("invalid AgentOutput: {}", e),
            )
        })?;
        let status = if output.error.is_some() {
            HostAgentStatus::Errored
        } else {
            HostAgentStatus::Completed
        };
        let message = if output.error.is_some() {
            format!("{} errored", spec.name)
        } else {
            format!("{} completed", spec.name)
        };
        let _ = self
            .host
            .set_status(
                &self.client_id,
                SetHostAgentStatusRequest {
                    agent_id,
                    status,
                    current_task: None,
                    message: Some(message),
                    payload: serde_json::to_value(&output).unwrap_or(Value::Null),
                },
            )
            .await;

        Ok(output)
    }
}

fn agent_id_for_run(client_id: &str, name: &str, request_id: &str) -> String {
    let safe_name: String = name
        .chars()
        .map(|c| {
            if c.is_ascii_alphanumeric() || c == '-' || c == '_' {
                c
            } else {
                '-'
            }
        })
        .collect();
    format!("{}:{}:{}", client_id, safe_name, request_id)
}

/// Build a [`car_multi::SharedInfra`], attaching a coordination budget when the
/// request carries a `budget` object (a `car_multi::BudgetLimits`, e.g.
/// `{"max_total_tokens": 200000, "max_agents": 12}`). Omitted fields are
/// unbounded; absent `budget` means no limits.
fn multi_infra_with_budget(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<car_multi::SharedInfra, String> {
    // Concurrency-anomaly gating (A5) is on for the daemon coordination path:
    // an isolated parallel swarm's cross-agent commit barrier is gated (stale
    // generation rejects the offending commit, reorder is serialized). The
    // infra SHARES the session runtime's state/log/policies (linus review
    // C-6): a fresh per-request store made `parent_keys_before` empty, so a
    // swarm write over a pre-existing session key could never be classified
    // as the read-modify-write that makes it a lost-update hazard — the
    // stale-generation check was structurally dead. Sharing also lands the
    // gate's audit events in the session log, matching the foreman path.
    let infra = car_multi::SharedInfra::with_shared(
        std::sync::Arc::clone(&session.runtime.state),
        std::sync::Arc::clone(&session.runtime.log),
        std::sync::Arc::clone(&session.runtime.policies),
    )
    .with_concurrency_gating();
    match req.params.get("budget") {
        None | Some(Value::Null) => Ok(infra),
        Some(v) => {
            let limits: car_multi::BudgetLimits =
                serde_json::from_value(v.clone()).map_err(|e| format!("invalid budget: {}", e))?;
            Ok(infra.with_budget(limits))
        }
    }
}

async fn handle_multi_swarm(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let mode_str = req
        .params
        .get("mode")
        .and_then(|v| v.as_str())
        .ok_or("missing 'mode'")?;
    let agents_val = req.params.get("agents").ok_or("missing 'agents'")?;
    let task = req
        .params
        .get("task")
        .and_then(|v| v.as_str())
        .ok_or("missing 'task'")?;

    let swarm_mode: car_multi::SwarmMode = serde_json::from_str(&format!("\"{}\"", mode_str))
        .map_err(|e| format!("invalid mode '{}': {}", mode_str, e))?;
    let agent_specs: Vec<car_multi::AgentSpec> =
        serde_json::from_value(agents_val.clone()).map_err(|e| format!("invalid agents: {}", e))?;
    let synth: Option<car_multi::AgentSpec> = req
        .params
        .get("synthesizer")
        .map(|v| serde_json::from_value(v.clone()))
        .transpose()
        .map_err(|e| format!("invalid synthesizer: {}", e))?;

    let runner: Arc<dyn car_multi::AgentRunner> = Arc::new(WsAgentRunner {
        channel: session.channel.clone(),
        host: session.host.clone(),
        client_id: session.client_id.clone(),
    });
    let infra = multi_infra_with_budget(req, session)?;

    let mut swarm = car_multi::Swarm::new(agent_specs, swarm_mode);
    if let Some(s) = synth {
        swarm = swarm.with_synthesizer(s);
    }

    let result = swarm
        .run(task, &runner, &infra)
        .await
        .map_err(|e| format!("swarm error: {}", e))?;
    serde_json::to_value(result).map_err(|e| e.to_string())
}

async fn handle_multi_pipeline(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let stages_val = req.params.get("stages").ok_or("missing 'stages'")?;
    let task = req
        .params
        .get("task")
        .and_then(|v| v.as_str())
        .ok_or("missing 'task'")?;

    let stage_specs: Vec<car_multi::AgentSpec> =
        serde_json::from_value(stages_val.clone()).map_err(|e| format!("invalid stages: {}", e))?;

    let runner: Arc<dyn car_multi::AgentRunner> = Arc::new(WsAgentRunner {
        channel: session.channel.clone(),
        host: session.host.clone(),
        client_id: session.client_id.clone(),
    });
    let infra = multi_infra_with_budget(req, session)?;

    let result = car_multi::Pipeline::new(stage_specs)
        .run(task, &runner, &infra)
        .await
        .map_err(|e| format!("pipeline error: {}", e))?;
    serde_json::to_value(result).map_err(|e| e.to_string())
}

async fn handle_multi_supervisor(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let workers_val = req.params.get("workers").ok_or("missing 'workers'")?;
    let supervisor_val = req.params.get("supervisor").ok_or("missing 'supervisor'")?;
    let task = req
        .params
        .get("task")
        .and_then(|v| v.as_str())
        .ok_or("missing 'task'")?;
    let max_rounds = req
        .params
        .get("max_rounds")
        .and_then(|v| v.as_u64())
        .unwrap_or(3) as u32;

    let worker_specs: Vec<car_multi::AgentSpec> = serde_json::from_value(workers_val.clone())
        .map_err(|e| format!("invalid workers: {}", e))?;
    let supervisor_spec: car_multi::AgentSpec = serde_json::from_value(supervisor_val.clone())
        .map_err(|e| format!("invalid supervisor: {}", e))?;

    let runner: Arc<dyn car_multi::AgentRunner> = Arc::new(WsAgentRunner {
        channel: session.channel.clone(),
        host: session.host.clone(),
        client_id: session.client_id.clone(),
    });
    let infra = multi_infra_with_budget(req, session)?;

    let result = car_multi::Supervisor::new(worker_specs, supervisor_spec)
        .with_max_rounds(max_rounds)
        .run(task, &runner, &infra)
        .await
        .map_err(|e| format!("supervisor error: {}", e))?;
    serde_json::to_value(result).map_err(|e| e.to_string())
}

async fn handle_multi_map_reduce(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let mapper_val = req.params.get("mapper").ok_or("missing 'mapper'")?;
    let reducer_val = req.params.get("reducer").ok_or("missing 'reducer'")?;
    let task = req
        .params
        .get("task")
        .and_then(|v| v.as_str())
        .ok_or("missing 'task'")?;
    let items_val = req.params.get("items").ok_or("missing 'items'")?;

    let mapper_spec: car_multi::AgentSpec =
        serde_json::from_value(mapper_val.clone()).map_err(|e| format!("invalid mapper: {}", e))?;
    let reducer_spec: car_multi::AgentSpec = serde_json::from_value(reducer_val.clone())
        .map_err(|e| format!("invalid reducer: {}", e))?;
    let items: Vec<String> =
        serde_json::from_value(items_val.clone()).map_err(|e| format!("invalid items: {}", e))?;

    let runner: Arc<dyn car_multi::AgentRunner> = Arc::new(WsAgentRunner {
        channel: session.channel.clone(),
        host: session.host.clone(),
        client_id: session.client_id.clone(),
    });
    let infra = multi_infra_with_budget(req, session)?;

    let result = car_multi::MapReduce::new(mapper_spec, reducer_spec)
        .run(task, &items, &runner, &infra)
        .await
        .map_err(|e| format!("map_reduce error: {}", e))?;
    serde_json::to_value(result).map_err(|e| e.to_string())
}

async fn handle_multi_vote(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let agents_val = req.params.get("agents").ok_or("missing 'agents'")?;
    let task = req
        .params
        .get("task")
        .and_then(|v| v.as_str())
        .ok_or("missing 'task'")?;

    let agent_specs: Vec<car_multi::AgentSpec> =
        serde_json::from_value(agents_val.clone()).map_err(|e| format!("invalid agents: {}", e))?;
    let synth: Option<car_multi::AgentSpec> = req
        .params
        .get("synthesizer")
        .map(|v| serde_json::from_value(v.clone()))
        .transpose()
        .map_err(|e| format!("invalid synthesizer: {}", e))?;

    let runner: Arc<dyn car_multi::AgentRunner> = Arc::new(WsAgentRunner {
        channel: session.channel.clone(),
        host: session.host.clone(),
        client_id: session.client_id.clone(),
    });
    let infra = multi_infra_with_budget(req, session)?;

    let mut vote = car_multi::Vote::new(agent_specs);
    if let Some(s) = synth {
        vote = vote.with_synthesizer(s);
    }

    let result = vote
        .run(task, &runner, &infra)
        .await
        .map_err(|e| format!("vote error: {}", e))?;
    serde_json::to_value(result).map_err(|e| e.to_string())
}

async fn handle_multi_tournament(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let competitors_val = req
        .params
        .get("competitors")
        .ok_or("missing 'competitors'")?;
    let judge_val = req.params.get("judge").ok_or("missing 'judge'")?;
    let task = req
        .params
        .get("task")
        .and_then(|v| v.as_str())
        .ok_or("missing 'task'")?;

    let competitors: Vec<car_multi::AgentSpec> = serde_json::from_value(competitors_val.clone())
        .map_err(|e| format!("invalid competitors: {}", e))?;
    let judge: car_multi::AgentSpec =
        serde_json::from_value(judge_val.clone()).map_err(|e| format!("invalid judge: {}", e))?;

    let runner: Arc<dyn car_multi::AgentRunner> = Arc::new(WsAgentRunner {
        channel: session.channel.clone(),
        host: session.host.clone(),
        client_id: session.client_id.clone(),
    });
    let infra = multi_infra_with_budget(req, session)?;

    let result = car_multi::Tournament::new(competitors, judge)
        .run(task, &runner, &infra)
        .await
        .map_err(|e| format!("tournament error: {}", e))?;
    serde_json::to_value(result).map_err(|e| e.to_string())
}

async fn handle_multi_subtask(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let main_val = req.params.get("main").ok_or("missing 'main'")?;
    let task = req
        .params
        .get("task")
        .and_then(|v| v.as_str())
        .ok_or("missing 'task'")?;

    let main_spec: car_multi::AgentSpec =
        serde_json::from_value(main_val.clone()).map_err(|e| format!("invalid main: {}", e))?;

    let runner: Arc<dyn car_multi::AgentRunner> = Arc::new(WsAgentRunner {
        channel: session.channel.clone(),
        host: session.host.clone(),
        client_id: session.client_id.clone(),
    });
    let infra = multi_infra_with_budget(req, session)?;

    let result = car_multi::SpawnSubtask::new(main_spec)
        .run(task, &runner, &infra)
        .await
        .map_err(|e| format!("spawn_subtask error: {}", e))?;
    serde_json::to_value(result).map_err(|e| e.to_string())
}

// ---------------------------------------------------------------------------
// Scheduler handlers
// ---------------------------------------------------------------------------

fn handle_scheduler_create(req: &JsonRpcMessage) -> Result<Value, String> {
    let name = req
        .params
        .get("name")
        .and_then(|v| v.as_str())
        .ok_or("scheduler.create requires 'name'")?;
    let prompt = req
        .params
        .get("prompt")
        .and_then(|v| v.as_str())
        .ok_or("scheduler.create requires 'prompt'")?;

    let mut task = car_scheduler::Task::new(name, prompt);

    if let Some(t) = opt_str(&req.params, "trigger") {
        let trigger = match t {
            "once" => car_scheduler::TaskTrigger::Once,
            "cron" => car_scheduler::TaskTrigger::Cron,
            "interval" => car_scheduler::TaskTrigger::Interval,
            "file_watch" => car_scheduler::TaskTrigger::FileWatch,
            _ => car_scheduler::TaskTrigger::Manual,
        };
        let schedule = req
            .params
            .get("schedule")
            .and_then(|v| v.as_str())
            .unwrap_or("");
        task = task.with_trigger(trigger, schedule);
    }

    if let Some(sp) = opt_str(&req.params, "system_prompt") {
        task = task.with_system_prompt(sp);
    }

    serde_json::to_value(&task).map_err(|e| e.to_string())
}

/// Common param extraction for the OS-schedule handlers: `{ task, program, args? }`.
fn os_schedule_params(req: &JsonRpcMessage) -> Result<(String, String, String), String> {
    let task = req
        .params
        .get("task")
        .ok_or("requires 'task'")
        .and_then(|v| serde_json::to_string(v).map_err(|_| "invalid 'task'"))?;
    let program = req
        .params
        .get("program")
        .and_then(|v| v.as_str())
        .ok_or("requires 'program' (the binary the OS runs to execute the task)")?
        .to_string();
    let args = req
        .params
        .get("args")
        .cloned()
        .unwrap_or_else(|| Value::Array(vec![]));
    let args_json = serde_json::to_string(&args).map_err(|e| e.to_string())?;
    Ok((task, program, args_json))
}

/// Preview the durable OS-level schedule a task would install (no I/O).
fn handle_scheduler_os_render(req: &JsonRpcMessage) -> Result<Value, String> {
    let (task, program, args) = os_schedule_params(req)?;
    let json = car_ffi_common::scheduler::render_os_schedule(&task, &program, &args)?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

/// Install a durable OS-level schedule (launchd/cron) for a task so it fires
/// even when the daemon is down.
fn handle_scheduler_os_install(req: &JsonRpcMessage) -> Result<Value, String> {
    let (task, program, args) = os_schedule_params(req)?;
    let json = car_ffi_common::scheduler::install_os_schedule(&task, &program, &args)?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

/// `tasks.schedule` — schedule a deterministic command on a cadence, hiding the
/// OS backend (#72). Params: `{ name, program, args?, cadence: { interval_secs? |
/// cron? }, durable?, working_dir?, env?, timeout_secs? }`.
///
/// **Host-gated**: scheduling a command is persistent, unsandboxed code
/// execution, so it requires host-management authority (a no-op in tokenless
/// dev/embedder mode). A registered agent connection can't self-schedule a
/// command — same trust root as `permission.set_tier` / `messaging.config.*`.
fn handle_tasks_schedule(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    let spec = serde_json::to_string(&req.params).map_err(|e| e.to_string())?;
    let json = car_ffi_common::scheduler::schedule_task(&spec)?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

/// `tasks.list` — list deterministic (command) scheduled tasks + their backend.
fn handle_tasks_list(_req: &JsonRpcMessage) -> Result<Value, String> {
    let json = car_ffi_common::scheduler::list_scheduled_tasks()?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

/// `tasks.unschedule` — remove a task's OS schedule + delete it from the store.
/// Params: `{ id }` (bare id or full label). Host-gated (same authority as
/// `tasks.schedule`).
fn handle_tasks_unschedule(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    let id = req
        .params
        .get("id")
        .and_then(|v| v.as_str())
        .ok_or("tasks.unschedule requires 'id'")?;
    let json = car_ffi_common::scheduler::unschedule_task(id)?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

/// Remove a task's OS-level schedule. Params: `{ label }` (full label or bare id).
fn handle_scheduler_os_uninstall(req: &JsonRpcMessage) -> Result<Value, String> {
    let label = req
        .params
        .get("label")
        .and_then(|v| v.as_str())
        .ok_or("scheduler.os_uninstall requires 'label' (full label or task id)")?;
    let json = car_ffi_common::scheduler::uninstall_os_schedule(label)?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

/// List CAR-managed OS-level schedule labels installed on this host.
fn handle_scheduler_os_list(_req: &JsonRpcMessage) -> Result<Value, String> {
    let json = car_ffi_common::scheduler::list_os_schedules()?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

/// Reap orphaned OS-level schedules whose backing task was deleted or made
/// non-schedulable. Returns `{ removed, kept, errors }`.
fn handle_scheduler_os_reconcile(_req: &JsonRpcMessage) -> Result<Value, String> {
    let json = car_ffi_common::scheduler::reconcile_os_schedules()?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

/// Reap orphaned OS-level schedules at daemon boot — best-effort, mirrors
/// [`recover_workflow_checkpoints`]. A schedule whose task was deleted while the
/// daemon was down keeps firing a no-op command until this runs.
pub fn reconcile_os_schedules_at_boot() {
    match car_ffi_common::scheduler::reconcile_os_schedules() {
        Ok(json) => match serde_json::from_str::<Value>(&json) {
            Ok(report) => {
                let removed = report
                    .get("removed")
                    .and_then(Value::as_array)
                    .map_or(0, Vec::len);
                let errors = report
                    .get("errors")
                    .and_then(Value::as_array)
                    .map_or(0, Vec::len);
                if removed > 0 || errors > 0 {
                    tracing::info!(removed, errors, "reaped orphaned OS schedules at boot");
                }
            }
            Err(e) => {
                tracing::warn!(error = %e, "OS-schedule reconcile returned unparseable report")
            }
        },
        Err(e) => tracing::warn!(error = %e, "OS-schedule reconcile failed at boot"),
    }
}

/// Reap CAR Docker sandbox containers orphaned by a prior daemon crash/SIGKILL
/// (Parslee-ai/car#479). `SandboxExecutor`'s `Drop` handles normal teardown, but
/// a hard kill leaves the `sleep infinity` container running forever. Sandboxes
/// are created per `session.bindSandbox` (never at boot), so any container
/// carrying the CAR ownership label is by definition orphaned. Best-effort:
/// a host without Docker is a silent no-op.
pub async fn reap_orphaned_sandboxes_at_boot() {
    let reaped = car_sandbox::reap_orphaned_sandboxes().await;
    if reaped > 0 {
        tracing::info!(reaped, "reaped orphaned CAR sandbox containers at boot");
    }
}

/// Seed a client-supplied task with any prior execution history persisted under
/// the given TaskStore. The WS `scheduler.run` / `scheduler.run_loop` surface is
/// otherwise stateless — a client deserializes a `Task` and posts it each call,
/// so `task.executions` arrives empty and the deterministic occurrence guard in
/// [`car_scheduler::Executor::run_occurrence`] never sees the prior run. Loading
/// the stored task by id and copying its `executions` (plus the run bookkeeping
/// the guard reads alongside them) restores statefulness across the JSON-RPC
/// boundary, so a replayed Interval/Once/Cron occurrence dedups. Manual triggers
/// carry no occurrence id and are intentionally never deduped — seeding is a
/// no-op for them.
fn seed_task_from_store(task: &mut car_scheduler::Task, store: &car_scheduler::TaskStore) {
    if let Some(prior) = store.load(&task.id) {
        // Anchor the occurrence slot on the persisted creation time and copy the
        // prior execution history so the admission guard can recognize a replay.
        task.created_at = prior.created_at;
        task.executions = prior.executions;
        task.run_count = prior.run_count;
        task.last_run_at = prior.last_run_at;
    }
}

/// Run a single task occurrence statefully against a TaskStore, persisting the
/// mutated task so the next call sees this run. Shared by the WS handler and the
/// dedup tests.
async fn run_scheduler_task_once(
    task: &mut car_scheduler::Task,
    runner: Arc<dyn car_multi::AgentRunner>,
    store: &car_scheduler::TaskStore,
) -> car_scheduler::TaskExecution {
    seed_task_from_store(task, store);
    let executor = car_scheduler::Executor::new(runner);
    let execution = executor.run_once(task).await;
    let _ = store.save(task);
    execution
}

/// Run a task loop statefully against a TaskStore, persisting the mutated task
/// afterward. Shared by the WS handler and the dedup tests.
async fn run_scheduler_task_loop(
    task: &mut car_scheduler::Task,
    max_iterations: Option<u32>,
    runner: Arc<dyn car_multi::AgentRunner>,
    store: &car_scheduler::TaskStore,
) -> Vec<car_scheduler::TaskExecution> {
    seed_task_from_store(task, store);
    let executor = car_scheduler::Executor::new(runner);
    let (_cancel_tx, cancel_rx) = tokio::sync::watch::channel(false);
    let executions = executor.run_loop(task, max_iterations, cancel_rx).await;
    let _ = store.save(task);
    executions
}

async fn handle_scheduler_run(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let task_val = req
        .params
        .get("task")
        .ok_or("scheduler.run requires 'task'")?;
    let mut task: car_scheduler::Task =
        serde_json::from_value(task_val.clone()).map_err(|e| format!("invalid task: {}", e))?;

    let runner: Arc<dyn car_multi::AgentRunner> = Arc::new(WsAgentRunner {
        channel: session.channel.clone(),
        host: session.host.clone(),
        client_id: session.client_id.clone(),
    });
    let store = car_scheduler::TaskStore::new(&car_scheduler::TaskStore::default_path());
    let execution = run_scheduler_task_once(&mut task, runner, &store).await;

    serde_json::to_value(&execution).map_err(|e| e.to_string())
}

async fn handle_scheduler_run_loop(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let task_val = req
        .params
        .get("task")
        .ok_or("scheduler.run_loop requires 'task'")?;
    let mut task: car_scheduler::Task =
        serde_json::from_value(task_val.clone()).map_err(|e| format!("invalid task: {}", e))?;
    let max_iterations = req
        .params
        .get("max_iterations")
        .and_then(|v| v.as_u64())
        .map(|v| v as u32);

    let runner: Arc<dyn car_multi::AgentRunner> = Arc::new(WsAgentRunner {
        channel: session.channel.clone(),
        host: session.host.clone(),
        client_id: session.client_id.clone(),
    });
    let store = car_scheduler::TaskStore::new(&car_scheduler::TaskStore::default_path());
    let executions = run_scheduler_task_loop(&mut task, max_iterations, runner, &store).await;

    serde_json::to_value(&executions).map_err(|e| e.to_string())
}

// ---------------------------------------------------------------------------
// Inference handlers
// ---------------------------------------------------------------------------

pub(crate) fn get_inference_engine(state: &ServerState) -> &Arc<car_inference::InferenceEngine> {
    state.inference.get_or_init(|| {
        let engine = Arc::new(car_inference::InferenceEngine::new(
            car_inference::InferenceConfig::default(),
        ));
        // Isolate on-device (MLX/Candle) generation in a worker subprocess so a
        // native Metal/MLX abort on a heavy local inference can't take down the
        // shared daemon (car-releases#74). The engine's on-device branch routes
        // through this offloader when installed; a worker crash fails one RPC
        // and respawns rather than killing the daemon. Skipped inside a worker
        // process (it runs generation for real) and opt-out via
        // CAR_NO_INFERENCE_WORKER=1 for debugging the in-process path.
        let worker_disabled = std::env::var_os("CAR_NO_INFERENCE_WORKER").is_some();
        if !car_inference::is_offload_worker() && !worker_disabled {
            match crate::inference_worker::WorkerOffload::new() {
                Ok(offload) => {
                    car_inference::set_local_offload(Some(std::sync::Arc::new(offload)));
                    info!("on-device inference isolated in a worker subprocess (car-releases#74)");
                }
                Err(e) => tracing::warn!(
                    error = %e,
                    "could not install the inference worker offloader; on-device \
                     generation will run in-process (a native MLX abort could crash the daemon)"
                ),
            }
        }
        // Phase E2: keep the model catalog current automatically. OPT-IN via
        // `CAR_MODEL_DISCOVERY=1` (off by default — it makes an outbound
        // provider call to `/v1/models` on a timer, which not every operator
        // wants). When enabled, run provider model discovery on first engine
        // init then re-run daily, caching newly-released chat/reasoning models
        // (e.g. a new gpt-5.x) as Community entries that load at the next
        // daemon start — so the router picks them up without a release.
        // Best-effort: no key / no provider is a no-op.
        let discovery_enabled = std::env::var("CAR_MODEL_DISCOVERY")
            .map(|v| v == "1" || v.eq_ignore_ascii_case("true"))
            .unwrap_or(false);
        if discovery_enabled {
            // `get_or_init` can run outside a tokio runtime (a sync or
            // non-async first caller); `tokio::spawn` panics there. Only spawn
            // when a runtime is actually present, otherwise log and skip.
            match tokio::runtime::Handle::try_current() {
                Ok(handle) => {
                    let disco = Arc::clone(&engine);
                    handle.spawn(async move {
                        loop {
                            match disco.discover_models().await {
                                Ok(n) => info!("model discovery: {n} discovered models cached"),
                                Err(e) => tracing::debug!("model discovery skipped: {e}"),
                            }
                            tokio::time::sleep(std::time::Duration::from_secs(24 * 3600)).await;
                        }
                    });
                }
                Err(_) => tracing::debug!(
                    "model discovery enabled (CAR_MODEL_DISCOVERY) but no tokio runtime at \
                     engine init — skipping the background task"
                ),
            }
        }
        engine
    })
}

/// `foreman.plan` — decompose a coding `goal` into a footprint-annotated,
/// scheduled subtask plan. The planner's repair loop runs against the daemon's
/// inference engine. Returns a [`car_multi::PlanReport`] (the SCHEDULER surface;
/// the gate verdict is a separate surface produced by `foreman.run`).
async fn handle_foreman_plan(msg: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let goal = msg
        .params
        .get("goal")
        .and_then(|v| v.as_str())
        .ok_or("missing 'goal'")?
        .to_string();
    let repo = msg
        .params
        .get("repo")
        .and_then(|v| v.as_str())
        .map(std::path::PathBuf::from)
        .or_else(|| std::env::current_dir().ok())
        .ok_or("no 'repo' and cwd is unavailable")?;
    let max_attempts = msg
        .params
        .get("max_attempts")
        .and_then(|v| v.as_u64())
        .unwrap_or(3) as u32;

    let engine = std::sync::Arc::clone(get_inference_engine(state));
    let result = car_multi::decompose(&repo, &goal, max_attempts, move |prompt| {
        let engine = std::sync::Arc::clone(&engine);
        async move {
            engine
                .generate(car_inference::GenerateRequest {
                    prompt,
                    ..Default::default()
                })
                .await
                .map_err(|e| e.to_string())
        }
    })
    .await;

    serde_json::to_value(car_multi::PlanReport::from(&result))
        .map_err(|e| format!("serialize plan: {e}"))
}

/// `foreman.run` — plan a coding `goal`, farm the independent subtasks to an
/// external coding CLI in isolated git worktrees, gate each worktree and the
/// integrated union. Returns `{ plan, ran, run? }`. **Spends real agent quota.**
async fn handle_foreman_run(
    msg: &JsonRpcMessage,
    state: &ServerState,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let goal = msg
        .params
        .get("goal")
        .and_then(|v| v.as_str())
        .ok_or("missing 'goal'")?
        .to_string();
    let repo = msg
        .params
        .get("repo")
        .and_then(|v| v.as_str())
        .map(std::path::PathBuf::from)
        .or_else(|| std::env::current_dir().ok())
        .ok_or("no 'repo' and cwd is unavailable")?;
    let max_attempts = msg
        .params
        .get("max_attempts")
        .and_then(|v| v.as_u64())
        .unwrap_or(3) as u32;
    let adapter = msg
        .params
        .get("adapter")
        .and_then(|v| v.as_str())
        .unwrap_or("claude-code")
        .to_string();
    let str_array = |key: &str| -> Option<Vec<String>> {
        msg.params.get(key).and_then(|v| v.as_array()).map(|a| {
            a.iter()
                .filter_map(|x| x.as_str().map(String::from))
                .collect()
        })
    };
    // Per-worktree regression gate, and the integrated-union goal gate. A subtask
    // does only part of the goal, so a goal-level test belongs on the union, not
    // per-worktree; `union_verify_command` falls back to `verify_command`.
    let verify_command = str_array("verify_command");
    let union_verify_command = str_array("union_verify_command");

    // Multiplayer (car#1117): spread the subtasks over every CAR instance that
    // can serve this repository, instead of running them all here. Opt-in,
    // because it spends other machines' quota and needs their operators to have
    // enrolled them. `workers` narrows placement to named instances.
    let distributed = msg
        .params
        .get("distributed")
        .and_then(|v| v.as_bool())
        .unwrap_or(false);
    let worker_filter = str_array("workers");

    // Run the full pipeline: decompose, then farm out + verify the union, OR —
    // when the plan doesn't decompose (invalid, or no parallelism worth it) —
    // fall back to a single whole-goal session. Always produces a result.
    let engine = std::sync::Arc::clone(get_inference_engine(state));
    let run_id = uuid::Uuid::new_v4().to_string();
    let agent = car_external_agents::ForemanExternalAgent::new(adapter.clone());
    // The pool always contains this host too, so a distributed run whose peers
    // all decline still completes locally.
    let (pool, pool_plan) = if distributed {
        let (pool, plan) =
            crate::fleet::build_pool(state, &repo, &run_id, &adapter, worker_filter.as_deref())
                .await?;
        (Some(pool), Some(plan))
    } else {
        (None, None)
    };
    let worktree_agent: &dyn car_multi::WorktreeAgent = match &pool {
        Some(pool) => pool,
        None => &agent,
    };
    // Reuse the session's runtime policies + event log so the merge-verify gate
    // consults the operator's `policy.register`'d rules (it can deny a merge) and
    // its GateAccepted/GateRejected events are audited in the session log —
    // instead of a fresh, empty engine.
    let infra = car_multi::SharedInfra::with_shared(
        std::sync::Arc::clone(&session.runtime.state),
        std::sync::Arc::clone(&session.runtime.log),
        std::sync::Arc::clone(&session.runtime.policies),
    );
    let config = car_multi::FarmOutConfig {
        verify_command,
        union_verify_command,
        // The daemon entrypoint is delivery-first: recover via a single session
        // if the parallel union fails, rather than hand back a non-delivery.
        recover_via_single_session: true,
        ..Default::default()
    };
    let outcome = car_multi::run_foreman(
        &repo,
        &goal,
        max_attempts,
        worktree_agent,
        &config,
        &infra,
        move |prompt| {
            let engine = std::sync::Arc::clone(&engine);
            async move {
                engine
                    .generate(car_inference::GenerateRequest {
                        prompt,
                        ..Default::default()
                    })
                    .await
                    .map_err(|e| e.to_string())
            }
        },
    )
    .await;

    let mode = match outcome.mode {
        car_multi::RunMode::Parallel => "parallel",
        car_multi::RunMode::SingleSession => "single_session",
        car_multi::RunMode::ParallelThenSingleSession => "parallel_then_single_session",
        car_multi::RunMode::RegionalReplan => "regional_replan",
    };
    let report =
        car_multi::ForemanReport::from_run(&outcome.outcomes, outcome.integration.as_ref());
    Ok(serde_json::json!({
        "plan": car_multi::PlanReport::from(&outcome.plan),
        "mode": mode,
        "ran": true,
        "delivered": outcome.delivered(),
        "run": report,
        "run_id": run_id,
        "distributed": distributed,
        // Which instances were in the pool, and where each subtask actually
        // ran (including workers that dropped one before another picked it up).
        // Absent on a local run, where the answer is always "here".
        "workers": pool.as_ref().map(|p| p.worker_ids()),
        "placements": pool.as_ref().map(crate::fleet::placements_json),
        // What the pool left out, and — when it left out everything — the one
        // line saying this "distributed" run was in fact local. Without it a
        // degraded run is indistinguishable from a slow one.
        "pool": pool_plan.as_ref().map(|plan| serde_json::json!({
            "remote_workers": plan.remote_workers,
            "excluded": plan.excluded.iter().map(|(instance, reason)| serde_json::json!({
                "instance": instance,
                "reason": reason,
            })).collect::<Vec<_>>(),
            // Workers the run LOST, as opposed to the ones it never had. A peer
            // that dies mid-run is excluded for the remainder (car#1323), and
            // without naming it here that shows up only as a slower run. Every
            // other key in this object describes the pool as BUILT, so a reader
            // asking whether the run was effectively local subtracts this from
            // `remote_workers` — `local_only` and `degraded_reason` are computed
            // before any subtask ran and cannot see it.
            "quarantined": pool.as_ref().map(|p| p.quarantined()).unwrap_or_default(),
            "local_only": plan.local_only(),
            "degraded_reason": plan.degraded_reason(),
        })),
    }))
}

/// Decrements a session's in-flight chat-infer counter on drop, so the
/// conversation-outcome concurrency guard (neo #1) is released on every return
/// path — including an early error from generation.
struct ChatInflightGuard<'a>(&'a std::sync::atomic::AtomicUsize);
impl Drop for ChatInflightGuard<'_> {
    fn drop(&mut self) {
        self.0.fetch_sub(1, std::sync::atomic::Ordering::SeqCst);
    }
}

/// Capture the conversation-outcome inputs for a (possibly) chat infer, shared
/// by the streaming and non-streaming `infer` paths so the gate + idle-guard
/// rules can't drift apart. Must be called BEFORE `req` is consumed by
/// generation. Returns `(chat_user_text, was_idle, guard)`:
/// - `chat_user_text` is `Some` only for an EXPLICITLY-declared chat turn
///   (`intent.task == Chat`) — "no tools" means "not an agent loop", not "is a
///   conversation", so a one-off summarize/classify infer never feeds the
///   signal (neo #2).
/// - `was_idle` is true only when this turn BEGAN while the session was idle;
///   recording a turn against a concurrent infer's user text would fabricate
///   adjacency and mislabel routing stats (neo #1).
/// - `guard` decrements the in-flight counter on drop; the caller must hold it
///   for the whole generation.
fn begin_chat_turn<'a>(
    req: &car_inference::GenerateRequest,
    session: &'a crate::session::ClientSession,
) -> (Option<String>, bool, Option<ChatInflightGuard<'a>>) {
    let is_chat = req
        .intent
        .as_ref()
        .is_some_and(|i| i.task == Some(car_inference::TaskHint::Chat));
    if !is_chat {
        return (None, false, None);
    }
    let chat_user_text = req
        .messages
        .as_ref()
        .and_then(|ms| {
            ms.iter().rev().find_map(|m| match m {
                car_inference::Message::User { content } => Some(content.clone()),
                _ => None,
            })
        })
        .or_else(|| {
            let p = req.prompt.trim();
            (!p.is_empty()).then(|| p.to_string())
        });
    let was_idle = session
        .chat_inflight
        .fetch_add(1, std::sync::atomic::Ordering::SeqCst)
        == 0;
    (
        chat_user_text,
        was_idle,
        Some(ChatInflightGuard(&session.chat_inflight)),
    )
}

/// Score the session's prior chat turn (`slot`) against `new_user_text` and feed
/// the tracker, then overwrite `slot` with this turn. Pure over the borrowed
/// state (no locks/I/O of its own) so it's unit-testable against a real
/// `OutcomeTracker`. trace_id/model are carried from the `InferenceResult` that
/// produced each turn — credit lands on the exact model that generated the turn.
fn score_and_remember_chat_turn(
    slot: &mut Option<crate::session::LastChatTurn>,
    tracker: &mut car_inference::OutcomeTracker,
    new_user_text: String,
    result_text: &str,
    trace_id: &str,
    model_id: &str,
) -> car_memgine::outcome_bridge::CreditTally {
    use car_memgine::outcome_signal::ConversationTurn;
    let mut tally = car_memgine::outcome_bridge::CreditTally::default();
    if let Some(prev) = slot.as_ref() {
        let turns = vec![
            ConversationTurn::user(prev.user_text.clone(), "u_prev"),
            ConversationTurn::assistant(
                prev.assistant_text.clone(),
                "a_prev",
                Some(prev.model_id.clone()),
                Some(prev.trace_id.clone()),
            ),
            ConversationTurn::user(new_user_text.clone(), "u_new"),
        ];
        tally = car_memgine::outcome_bridge::record_conversation_outcomes(tracker, &turns);
    }
    *slot = Some(crate::session::LastChatTurn {
        user_text: new_user_text,
        assistant_text: result_text.to_string(),
        trace_id: trace_id.to_string(),
        model_id: model_id.to_string(),
    });
    tally
}

#[cfg(test)]
mod chat_outcome_tests {
    use super::score_and_remember_chat_turn;
    use crate::session::LastChatTurn;
    use car_inference::{InferenceTask, OutcomeTracker};

    #[test]
    fn first_turn_records_nothing_and_stashes() {
        let mut slot: Option<LastChatTurn> = None;
        let mut tracker = OutcomeTracker::new();
        let tally = score_and_remember_chat_turn(
            &mut slot,
            &mut tracker,
            "hello".into(),
            "hi there",
            "t1",
            "m1",
        );
        assert_eq!(tally.submitted, 0, "no prior turn → nothing to score");
        let stashed = slot.expect("this turn must be remembered");
        assert_eq!(stashed.trace_id, "t1");
        assert_eq!(stashed.user_text, "hello");
    }

    #[test]
    fn second_turn_scores_prior_turn_and_reverses_mechanical_success() {
        let mut tracker = OutcomeTracker::new();
        // Prior assistant turn: trace t1 / model m1, completed with output →
        // mechanical success booked.
        let tid = tracker.record_start("m1", InferenceTask::Generate, "test");
        tracker.record_complete(&tid, 10, 1, 2);
        assert_eq!(tracker.profile("m1").unwrap().success_count, 1);

        let mut slot = Some(LastChatTurn {
            user_text: "convert this to async".into(),
            assistant_text: "here's a threaded version".into(),
            trace_id: tid.clone(),
            model_id: "m1".into(),
        });
        // The next user turn circles (repair marker) → the prior turn is a failure.
        let tally = score_and_remember_chat_turn(
            &mut slot,
            &mut tracker,
            "no, that's not what i asked".into(),
            "async version",
            "t2",
            "m1",
        );
        assert_eq!(
            tally.resolved, 1,
            "prior turn's trace was pending → resolved"
        );
        let p = tracker.profile("m1").unwrap();
        assert_eq!(p.success_count, 0, "mechanical success reversed");
        assert_eq!(p.fail_count, 1, "circle booked as a failure for m1");
        assert_eq!(slot.unwrap().trace_id, "t2", "this turn is now remembered");
    }
}

/// Raw infer RPCs treat a named model as a hard pin.  The inference layer can
/// otherwise append an on-device last-resort model after a remote failure,
/// which is appropriate only for adaptive (model-less) routing.
fn parse_inference_request(params: &Value) -> Result<car_inference::GenerateRequest, String> {
    let exact_model_id = match params.get("model_id") {
        None | Some(Value::Null) => None,
        Some(Value::String(model_id)) if !model_id.trim().is_empty() => Some(model_id.clone()),
        Some(_) => return Err("`model_id` must be a non-empty string".to_string()),
    };
    if exact_model_id.is_some() && params.get("model").is_some_and(|value| !value.is_null()) {
        return Err("`model` and `model_id` are mutually exclusive".to_string());
    }

    let mut normalized = params.clone();
    if let Some(object) = normalized.as_object_mut() {
        object.remove("model_id");
    }
    let mut req: car_inference::GenerateRequest = typed_params(&normalized)?;
    if let Some(model_id) = exact_model_id {
        car_inference::pin_exact_model_id(&mut req, model_id)?;
    }
    if req.model.is_some() {
        req.params.strict_model = true;
    }
    Ok(req)
}

#[cfg(test)]
mod inference_request_tests {
    use super::parse_inference_request;
    use serde_json::json;

    #[test]
    fn explicit_model_is_strict() {
        let req = parse_inference_request(&json!({
            "prompt": "hello",
            "model": "openrouter/qwen/qwen3-coder-next",
        }))
        .expect("valid explicit-model request");

        assert!(req.params.strict_model);
    }

    #[test]
    fn explicit_model_overrides_requested_non_strict_mode() {
        let req = parse_inference_request(&json!({
            "prompt": "hello",
            "model": "openrouter/qwen/qwen3-coder-next",
            "params": { "strict_model": false },
        }))
        .expect("valid explicit-model request");

        assert!(req.params.strict_model);
    }

    #[test]
    fn exact_model_id_is_strict_and_does_not_alias() {
        let req = parse_inference_request(&json!({
            "prompt": "hello",
            "model_id": "openai/gpt-5.4:latest",
            "params": { "strict_model": false },
        }))
        .expect("valid exact-id request");

        assert_eq!(
            car_inference::exact_pinned_model_id(&req),
            Some("openai/gpt-5.4:latest")
        );
        assert!(req.params.strict_model);
    }

    #[test]
    fn legacy_model_and_exact_model_id_are_rejected_together() {
        let error = parse_inference_request(&json!({
            "prompt": "hello",
            "model": "GPT 5.4",
            "model_id": "openai/gpt-5.4:latest",
        }))
        .expect_err("ambiguous dual pin must fail");

        assert!(error.contains("mutually exclusive"));
    }

    #[test]
    fn model_less_requests_preserve_requested_strict_mode() {
        let loose = parse_inference_request(&json!({
            "prompt": "hello",
            "params": { "strict_model": false },
        }))
        .expect("valid adaptive request");
        let strict = parse_inference_request(&json!({
            "prompt": "hello",
            "params": { "strict_model": true },
        }))
        .expect("valid strict adaptive request");

        assert!(!loose.params.strict_model);
        assert!(strict.params.strict_model);
    }
}

/// Stringify an inference failure for the dispatcher, tagging a content refusal
/// with its stable wire prefix.
///
/// This is the WRITER half of the pair whose reader is
/// [`HandlerFailure::from_dispatch`]; both sides key off
/// [`car_proto::CONTENT_REFUSED_MESSAGE_PREFIX`] and must be changed together.
///
/// Classification happens HERE, by variant, because this is the last point that
/// still holds the typed `InferenceError` — `car-inference` already decided
/// whether the gateway refused on content grounds (it excludes the case from the
/// circuit breaker and books it as a capability rejection), and re-deriving that
/// verdict by substring-matching Display text downstream would be a guess.
/// `ContentRefused`'s Display carries the gateway's own `type=` / `code=` tags
/// and message, so tagging preserves them rather than replacing them.
fn inference_dispatch_error(e: &car_inference::InferenceError) -> String {
    match e {
        car_inference::InferenceError::ContentRefused { .. } => {
            format!("{} {e}", car_proto::CONTENT_REFUSED_MESSAGE_PREFIX)
        }
        car_inference::InferenceError::CatalogPreconditionMismatch { detail } => format!(
            "{} {detail}",
            car_proto::CATALOG_PRECONDITION_MISMATCH_MESSAGE_PREFIX
        ),
        _ => e.to_string(),
    }
}

/// Same tagging, for a stream failure that reaches us as flattened TEXT.
///
/// A refusal raised BEFORE the stream opens is a typed `InferenceError` and goes
/// through [`inference_dispatch_error`]. One raised mid-stream does not: the
/// provider layer has already turned it into `StreamEvent::Error(String)` by the
/// time it gets here, so the variant is gone and only the message survives.
///
/// That is not a licence to invent a substring rule. The verdict is taken from
/// `car_inference::stream::content_refusal_tags`, which reads the `type=` /
/// `code=` tags the same module's SSE writer appended — the same function
/// `car-inference` itself uses on the non-streaming path, so both paths agree on
/// what a refusal IS by construction rather than by two rules kept in step by
/// hand. A stream whose gateway sent no tags stays a generic failure, which is
/// the safe direction (Parslee-ai/car#796).
fn stream_dispatch_error(detail: String) -> String {
    match car_inference::stream::content_refusal_tags(&detail) {
        Some(_) => format!("{} {detail}", car_proto::CONTENT_REFUSED_MESSAGE_PREFIX),
        None => detail,
    }
}

async fn run_owned_inference_backend<F>(
    registry: Arc<crate::inference_control::InferenceRegistry>,
    inference_id: String,
    result_tx: tokio::sync::oneshot::Sender<Result<Value, String>>,
    work: F,
) where
    F: std::future::Future<Output = Result<Value, String>>,
{
    use futures::FutureExt;
    use std::panic::AssertUnwindSafe;

    let result = match AssertUnwindSafe(work).catch_unwind().await {
        Ok(result) => result,
        Err(payload) => {
            let detail = payload
                .downcast_ref::<&str>()
                .map(|message| (*message).to_string())
                .or_else(|| payload.downcast_ref::<String>().cloned())
                .unwrap_or_else(|| "unknown panic payload".to_string());
            Err(format!("inference backend panicked: {detail}"))
        }
    };
    registry.backend_terminated(&inference_id);
    let _ = result_tx.send(result);
}

async fn handle_infer(
    msg: &JsonRpcMessage,
    state: Arc<ServerState>,
    session: Arc<crate::session::ClientSession>,
) -> Result<Value, String> {
    reject_client_inference_id(&msg.params)?;
    let current_run = session.current_run_id.lock().await.clone();
    let request_id = msg.id.as_str().map(str::to_string);
    let (inference_id, mut terminal) = session
        .inference_control
        .begin_for_run(current_run, request_id)
        .map_err(|error| format!("cannot start inference: {error:?}"))?;
    let (result_tx, mut result_rx) = tokio::sync::oneshot::channel();
    let task_msg = msg.clone();
    let task_state = state.clone();
    let task_session = session.clone();
    let task_registry = session.inference_control.clone();
    let task_id = inference_id.clone();
    let backend = tokio::spawn(run_owned_inference_backend(
        task_registry,
        task_id.clone(),
        result_tx,
        async move {
            car_inference::scope_inference_control_id(
                task_id.clone(),
                handle_infer_active(&task_msg, &task_state, &task_session, &task_id),
            )
            .await
        },
    ));
    let mut owner =
        attach_owned_inference_backend(session.inference_control.clone(), &inference_id, backend)
            .map_err(|error| format!("cannot own inference backend: {error:?}"))?;
    let exposes_control = session_has_capability(&session, car_proto::INFER_CANCEL_CAPABILITY)
        || session_has_capability(&session, car_proto::INFER_DEADLINE_CAPABILITY);
    if exposes_control {
        if let Err(error) = send_infer_started(&session, &msg.id, &inference_id).await {
            return Err(clean_up_failed_infer_started(
                &session.inference_control,
                &inference_id,
                error,
            ));
        }
    }

    let result = tokio::select! {
        biased;
        result = &mut result_rx => match result {
          Ok(Ok(mut value)) => {
            if session.inference_control.complete(&inference_id) {
                if exposes_control {
                    insert_inference_id(&mut value, &inference_id)?;
                }
                Ok(value)
            } else {
                Ok(wait_terminal_control_value(terminal.clone(), &inference_id).await)
            }
          }
          Ok(Err(error)) => {
            if session.inference_control.complete(&inference_id) {
                Err(error)
            } else {
                Ok(wait_terminal_control_value(terminal.clone(), &inference_id).await)
            }
          }
          Err(_) => Err("owned inference backend ended without a result".to_string()),
        },
        _ = terminal.changed() => {
            Ok(wait_terminal_control_value(terminal, &inference_id).await)
        }
    };
    // The engine-side deadline entry must not outlive the inference: a reused
    // control id inheriting a stale deadline would cut an innocent request.
    car_inference::clear_remote_deadline(&inference_id);
    owner.complete_normally();
    result
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct InferCancelParams {
    inference_id: String,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct InferDeadlineParams {
    inference_id: String,
    timeout_ms: u64,
}

async fn exact_backend_termination_ack(inference_id: &str) -> bool {
    let Some(offload) = car_inference::current_local_offload() else {
        return false;
    };
    matches!(
        offload.terminate_inference(inference_id).await,
        car_inference::InferenceTerminationAck::Confirmed
    )
}

async fn handle_infer_cancel(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    if !session_has_capability(session, car_proto::INFER_CANCEL_CAPABILITY) {
        return Err(format!(
            "{} negotiate `{}` as a required or optional capability before calling `infer.cancel`",
            car_proto::PROTOCOL_CAPABILITY_MISMATCH_MESSAGE_PREFIX,
            car_proto::INFER_CANCEL_CAPABILITY
        ));
    }
    let params: InferCancelParams = typed_params(&msg.params)?;
    if params.inference_id.is_empty() {
        return Err("`inference_id` must be a non-empty opaque string".into());
    }
    let _pending = session
        .inference_control
        .try_acquire_control()
        .map_err(|error| format!("infer.cancel control admission rejected: {error:?}"))?;
    let status = session
        .inference_control
        .control(
            &params.inference_id,
            crate::inference_control::ControlCause::Cancel,
            exact_backend_termination_ack(&params.inference_id),
        )
        .await;
    serde_json::to_value(car_proto::InferenceControlResponse {
        inference_id: params.inference_id,
        status,
    })
    .map_err(|error| format!("serialize infer.cancel response: {error}"))
}

async fn handle_infer_deadline(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    if !session_has_capability(session, car_proto::INFER_DEADLINE_CAPABILITY) {
        return Err(format!(
            "{} negotiate `{}` as a required or optional capability before calling `infer.deadline`",
            car_proto::PROTOCOL_CAPABILITY_MISMATCH_MESSAGE_PREFIX,
            car_proto::INFER_DEADLINE_CAPABILITY
        ));
    }
    let params: InferDeadlineParams = typed_params(&msg.params)?;
    if params.inference_id.is_empty() {
        return Err("`inference_id` must be a non-empty opaque string".into());
    }
    if params.timeout_ms == 0
        || params.timeout_ms > crate::inference_control::MAX_DEADLINE_TIMEOUT_MS
    {
        return Err(format!(
            "`timeout_ms` must be between 1 and {}",
            crate::inference_control::MAX_DEADLINE_TIMEOUT_MS
        ));
    }

    let ack_id = params.inference_id.clone();
    let status = match session
        .inference_control
        .schedule_deadline(
            &params.inference_id,
            std::time::Duration::from_millis(params.timeout_ms),
            || exact_backend_termination_ack(&ack_id),
        )
        .await
    {
        Ok(status) => {
            // Beyond the registry's kill-switch, arm the ENGINE-side deadline:
            // the remote retry loop derives its per-phase and retry budgets
            // from it, so the provider request survives past the unarmed
            // transport defaults up to the caller's bound, and a termination
            // names the deadline that was applied (car-eyj).
            car_inference::set_remote_deadline(
                &params.inference_id,
                std::time::Duration::from_millis(params.timeout_ms),
            );
            status
        }
        Err(crate::inference_control::DeadlineReservationError::Terminal(status)) => {
            return serde_json::to_value(car_proto::InferenceControlResponse {
                inference_id: params.inference_id,
                status,
            })
            .map_err(|error| format!("serialize infer.deadline response: {error}"));
        }
        Err(crate::inference_control::DeadlineReservationError::Registry(
            crate::inference_control::RegistryError::PendingControlLimitReached,
        )) => {
            return Err(
                "infer.deadline control admission rejected: PendingControlLimitReached".into(),
            );
        }
        Err(crate::inference_control::DeadlineReservationError::Registry(error)) => {
            return Err(format!("infer.deadline rejected: {error:?}"));
        }
    };
    serde_json::to_value(car_proto::InferenceControlResponse {
        inference_id: params.inference_id,
        status,
    })
    .map_err(|error| format!("serialize infer.deadline response: {error}"))
}

fn reject_client_inference_id(params: &Value) -> Result<(), String> {
    if params.get("inference_id").is_some() {
        return Err("`inference_id` is server-assigned and cannot be supplied or reused".into());
    }
    Ok(())
}

#[derive(Debug)]
enum InferStartedSendError {
    BeforeAdmission(String),
    AfterAdmission(String),
}

impl InferStartedSendError {
    fn may_have_been_admitted(&self) -> bool {
        matches!(self, Self::AfterAdmission(_))
    }
}

impl std::fmt::Display for InferStartedSendError {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::BeforeAdmission(message) | Self::AfterAdmission(message) => {
                formatter.write_str(message)
            }
        }
    }
}

fn clean_up_failed_infer_started(
    registry: &crate::inference_control::InferenceRegistry,
    inference_id: &str,
    error: InferStartedSendError,
) -> String {
    if error.may_have_been_admitted() {
        registry.abort_after_started_admission(inference_id);
    } else {
        registry.abandon(inference_id);
    }
    error.to_string()
}

struct InferenceOwnerGuard {
    registry: Arc<crate::inference_control::InferenceRegistry>,
    inference_id: String,
    completed_normally: bool,
}

impl InferenceOwnerGuard {
    fn new(
        registry: Arc<crate::inference_control::InferenceRegistry>,
        inference_id: String,
    ) -> Self {
        Self {
            registry,
            inference_id,
            completed_normally: false,
        }
    }

    fn complete_normally(&mut self) {
        self.completed_normally = true;
    }
}

impl Drop for InferenceOwnerGuard {
    fn drop(&mut self) {
        if !self.completed_normally {
            self.registry.abort_owned_backend(&self.inference_id);
        }
    }
}

fn attach_owned_inference_backend(
    registry: Arc<crate::inference_control::InferenceRegistry>,
    inference_id: &str,
    backend: tokio::task::JoinHandle<()>,
) -> Result<InferenceOwnerGuard, crate::inference_control::RegistryError> {
    registry.attach_backend(inference_id, backend)?;
    Ok(InferenceOwnerGuard::new(registry, inference_id.to_string()))
}

async fn send_infer_started(
    session: &crate::session::ClientSession,
    request_id: &Value,
    inference_id: &str,
) -> Result<(), InferStartedSendError> {
    use futures::SinkExt;
    use tokio_tungstenite::tungstenite::Message;

    let frame = serde_json::json!({
        "jsonrpc": "2.0",
        "method": "infer.started",
        "params": {
            "request_id": request_id,
            "inference_id": inference_id,
        },
    });
    let text = serde_json::to_string(&frame)
        .map_err(|error| InferStartedSendError::BeforeAdmission(error.to_string()))?;
    let deadline = tokio::time::Instant::now() + KEEPALIVE_WRITE_TIMEOUT;
    let mut write = tokio::time::timeout_at(deadline, session.channel.write.lock())
        .await
        .map_err(|_| {
            InferStartedSendError::BeforeAdmission(format!(
                "send infer.started timed out before admission after {}s",
                KEEPALIVE_WRITE_TIMEOUT.as_secs()
            ))
        })?;

    match tokio::time::timeout_at(deadline, write.feed(Message::Text(text.into()))).await {
        Ok(Ok(())) => {}
        Ok(Err(error)) => {
            // A custom sink may enqueue in `start_send` before returning an
            // error. Retain the ID as terminal rather than assuming it stayed
            // invisible.
            return Err(InferStartedSendError::AfterAdmission(format!(
                "send infer.started admission failed: {error}"
            )));
        }
        Err(_) => {
            // `feed` only yields Pending while waiting for poll_ready; it has
            // not called synchronous start_send yet.
            return Err(InferStartedSendError::BeforeAdmission(format!(
                "send infer.started timed out before admission after {}s",
                KEEPALIVE_WRITE_TIMEOUT.as_secs()
            )));
        }
    }

    match tokio::time::timeout_at(deadline, write.flush()).await {
        Ok(Ok(())) => Ok(()),
        Ok(Err(error)) => Err(InferStartedSendError::AfterAdmission(format!(
            "flush infer.started: {error}"
        ))),
        Err(_) => Err(InferStartedSendError::AfterAdmission(format!(
            "flush infer.started timed out after {}s; inference is terminal",
            KEEPALIVE_WRITE_TIMEOUT.as_secs()
        ))),
    }
}

#[cfg(test)]
mod inference_backend_reliability_tests {
    use super::{
        attach_owned_inference_backend, clean_up_failed_infer_started, run_owned_inference_backend,
        send_infer_started, send_inference_notification_if_active, KEEPALIVE_WRITE_TIMEOUT,
    };
    use crate::inference_control::{InferenceRegistry, RegistryConfig};
    use crate::session::{ServerState, WsChannel, WsSink};
    use futures::{Sink, SinkExt};
    use serde_json::json;
    use std::collections::HashMap;
    use std::pin::Pin;
    use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
    use std::sync::Arc;
    use std::task::{Context, Poll};
    use std::time::Duration;
    use tokio::sync::Mutex;
    use tokio_tungstenite::tungstenite::{Error as WsError, Message};

    struct FlushStallingSink {
        pending: Arc<std::sync::Mutex<Vec<Message>>>,
        visible: Arc<std::sync::Mutex<Vec<Message>>>,
        flush_ready: Arc<AtomicBool>,
    }

    impl Sink<Message> for FlushStallingSink {
        type Error = WsError;

        fn poll_ready(
            self: Pin<&mut Self>,
            _context: &mut Context<'_>,
        ) -> Poll<Result<(), Self::Error>> {
            Poll::Ready(Ok(()))
        }

        fn start_send(self: Pin<&mut Self>, message: Message) -> Result<(), Self::Error> {
            self.pending
                .lock()
                .expect("pending frames lock")
                .push(message);
            Ok(())
        }

        fn poll_flush(
            self: Pin<&mut Self>,
            _context: &mut Context<'_>,
        ) -> Poll<Result<(), Self::Error>> {
            if !self.flush_ready.load(Ordering::SeqCst) {
                return Poll::Pending;
            }
            let mut pending = self.pending.lock().expect("pending frames lock");
            self.visible
                .lock()
                .expect("visible frames lock")
                .extend(pending.drain(..));
            Poll::Ready(Ok(()))
        }

        fn poll_close(
            self: Pin<&mut Self>,
            context: &mut Context<'_>,
        ) -> Poll<Result<(), Self::Error>> {
            self.poll_flush(context)
        }
    }

    fn one_slot_registry() -> Arc<InferenceRegistry> {
        Arc::new(InferenceRegistry::with_config(RegistryConfig {
            max_active: 1,
            max_tombstones: 1,
            max_pending_controls: 1,
            max_orphans: 1,
            tombstone_ttl: Duration::from_secs(300),
            termination_ack_timeout: Duration::from_millis(20),
        }))
    }

    #[tokio::test]
    async fn panicking_backend_publishes_terminal_error_and_releases_registry_capacity() {
        let registry = one_slot_registry();
        registry
            .begin_with_id("panic-stream")
            .expect("register panicking stream");
        let (result_tx, result_rx) = tokio::sync::oneshot::channel();
        let task = tokio::spawn(run_owned_inference_backend(
            registry.clone(),
            "panic-stream".to_string(),
            result_tx,
            async {
                panic!("fixture stream backend panic");
                #[allow(unreachable_code)]
                Ok(json!({}))
            },
        ));
        registry
            .attach_backend("panic-stream", task)
            .expect("attach panicking stream");

        let error = result_rx
            .await
            .expect("panic must be converted into a published result")
            .expect_err("panic must be a terminal error");
        assert!(error.contains("backend panicked"), "{error}");
        assert!(
            registry.complete("panic-stream"),
            "client-visible failure must terminalize the active entry"
        );
        assert_eq!(registry.counts().0, 0);
        registry
            .begin_with_id("replacement-stream")
            .expect("panicking backend must not consume the one session slot forever");
    }

    #[tokio::test]
    async fn panic_before_attach_and_receiver_drop_still_releases_backend_ownership() {
        let registry = one_slot_registry();
        registry
            .begin_with_id("panic-before-attach")
            .expect("register panicking backend");
        let (result_tx, result_rx) = tokio::sync::oneshot::channel();
        drop(result_rx);
        run_owned_inference_backend(
            registry.clone(),
            "panic-before-attach".to_string(),
            result_tx,
            async {
                panic!("panic before JoinHandle attachment");
                #[allow(unreachable_code)]
                Ok(json!({}))
            },
        )
        .await;
        registry
            .attach_backend("panic-before-attach", tokio::spawn(async {}))
            .expect("late attachment observes prior termination");
        assert!(registry.complete("panic-before-attach"));
        assert_eq!(registry.counts().0, 0);
        registry
            .begin_with_id("after-panic-before-attach")
            .expect("panic before attachment must not strand capacity");
    }

    #[tokio::test(start_paused = true)]
    async fn infer_started_write_timeout_cleans_up_instead_of_waiting_on_the_socket_forever() {
        let tmp = tempfile::TempDir::new().expect("temporary server state");
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        let channel = Arc::new(WsChannel::test_stub());
        let session = state
            .create_session("stalled-infer-start", channel.clone())
            .await
            .expect("create test session");
        let registry = session.inference_control.clone();
        registry
            .begin_with_id("stalled-start")
            .expect("register pending inference");
        let backend = tokio::spawn(std::future::pending::<()>());
        registry
            .attach_backend("stalled-start", backend)
            .expect("attach pending backend");

        let _held_write = channel.write.lock().await;
        let task_session = session.clone();
        let send = tokio::spawn(async move {
            let result = send_infer_started(&task_session, &json!(7), "stalled-start").await;
            if result.is_err() {
                task_session.inference_control.abandon("stalled-start");
            }
            result
        });
        tokio::task::yield_now().await;
        tokio::time::advance(KEEPALIVE_WRITE_TIMEOUT + Duration::from_millis(1)).await;

        let error = tokio::time::timeout(Duration::from_millis(1), send)
            .await
            .expect("infer.started must carry its own bounded-write policy")
            .expect("send task joins")
            .expect_err("held write lock must time out");
        assert!(error.to_string().contains("timed out"), "{error}");
        assert_eq!(registry.counts(), (0, 0), "failed start must be removed");
    }

    #[tokio::test(start_paused = true)]
    async fn infer_started_flush_timeout_keeps_any_later_visible_id_terminally_queryable() {
        let tmp = tempfile::TempDir::new().expect("temporary server state");
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        let pending = Arc::new(std::sync::Mutex::new(Vec::new()));
        let visible = Arc::new(std::sync::Mutex::new(Vec::new()));
        let flush_ready = Arc::new(AtomicBool::new(false));
        let sink: WsSink = Box::pin(FlushStallingSink {
            pending: pending.clone(),
            visible: visible.clone(),
            flush_ready: flush_ready.clone(),
        });
        let channel = Arc::new(WsChannel {
            write: Mutex::new(sink),
            pending: Mutex::new(HashMap::new()),
            active_actions: Mutex::new(HashMap::new()),
            next_id: AtomicU64::new(0),
        });
        let session = state
            .create_session("partial-infer-start", channel.clone())
            .await
            .expect("create test session");
        let registry = session.inference_control.clone();
        registry
            .begin_with_id("partially-admitted-start")
            .expect("register pending inference");
        registry
            .attach_backend(
                "partially-admitted-start",
                tokio::spawn(std::future::pending::<()>()),
            )
            .expect("attach pending backend");

        let task_session = session.clone();
        let send = tokio::spawn(async move {
            let error = send_infer_started(&task_session, &json!(8), "partially-admitted-start")
                .await
                .expect_err("flush must stall");
            clean_up_failed_infer_started(
                &task_session.inference_control,
                "partially-admitted-start",
                error,
            )
        });
        tokio::task::yield_now().await;
        assert_eq!(pending.lock().expect("pending frames lock").len(), 1);
        assert!(visible.lock().expect("visible frames lock").is_empty());

        tokio::time::advance(KEEPALIVE_WRITE_TIMEOUT + Duration::from_millis(1)).await;
        let error = send.await.expect("send task joins");
        assert!(error.contains("terminal"), "{error}");
        assert_eq!(registry.counts(), (0, 1));
        assert!(
            registry
                .terminal_outcome("partially-admitted-start")
                .is_some(),
            "a queued infer.started ID must remain queryable"
        );

        flush_ready.store(true, Ordering::SeqCst);
        channel
            .write
            .lock()
            .await
            .send(Message::Text(
                json!({"jsonrpc":"2.0","id":8,"error":{"code":-32603}})
                    .to_string()
                    .into(),
            ))
            .await
            .expect("later dispatcher response flushes queued frames");
        let visible = visible.lock().expect("visible frames lock");
        assert_eq!(visible.len(), 2);
        let started: serde_json::Value = match &visible[0] {
            Message::Text(text) => serde_json::from_str(text).expect("started JSON"),
            other => panic!("expected text frame, got {other:?}"),
        };
        assert_eq!(
            started["params"]["inference_id"],
            "partially-admitted-start"
        );
        assert!(
            registry
                .terminal_outcome("partially-admitted-start")
                .is_some(),
            "later visibility must not turn the admitted ID into Unknown"
        );
    }

    #[tokio::test(start_paused = true)]
    async fn notification_write_budget_reports_whether_a_frame_was_admitted() {
        let registry = one_slot_registry();
        registry
            .begin_with_id("notification-lock-timeout")
            .expect("register lock-stalled notification");
        let channel = Arc::new(WsChannel::test_stub());
        let held_write = channel.write.lock().await;
        let task_channel = channel.clone();
        let task_registry = registry.clone();
        let lock_timeout = tokio::spawn(async move {
            send_inference_notification_if_active(
                &task_channel,
                &task_registry,
                "notification-lock-timeout",
                json!({"method":"infer.progress"}).to_string(),
            )
            .await
            .expect_err("held writer lock must time out")
        });
        tokio::task::yield_now().await;
        tokio::time::advance(KEEPALIVE_WRITE_TIMEOUT + Duration::from_millis(1)).await;
        let error = lock_timeout.await.expect("lock-timeout task joins");
        assert!(!error.may_have_been_admitted(), "{error}");
        assert!(
            error.to_string().contains("write lock timed out"),
            "{error}"
        );
        drop(held_write);
        registry.abandon("notification-lock-timeout");

        let registry = one_slot_registry();
        registry
            .begin_with_id("progress-flush-timeout")
            .expect("register flush-stalled notification");
        let pending = Arc::new(std::sync::Mutex::new(Vec::new()));
        let visible = Arc::new(std::sync::Mutex::new(Vec::new()));
        let flush_ready = Arc::new(AtomicBool::new(false));
        let sink: WsSink = Box::pin(FlushStallingSink {
            pending: pending.clone(),
            visible: visible.clone(),
            flush_ready,
        });
        let channel = Arc::new(WsChannel {
            write: Mutex::new(sink),
            pending: Mutex::new(HashMap::new()),
            active_actions: Mutex::new(HashMap::new()),
            next_id: AtomicU64::new(0),
        });
        let task_registry = registry.clone();
        let flush_timeout = tokio::spawn(async move {
            send_inference_notification_if_active(
                &channel,
                &task_registry,
                "progress-flush-timeout",
                json!({"method":"infer.progress"}).to_string(),
            )
            .await
            .expect_err("flush-stalled notification must time out")
        });
        tokio::task::yield_now().await;
        assert_eq!(pending.lock().expect("pending frames lock").len(), 1);
        assert!(visible.lock().expect("visible frames lock").is_empty());
        tokio::time::advance(KEEPALIVE_WRITE_TIMEOUT + Duration::from_millis(1)).await;
        let error = flush_timeout.await.expect("flush-timeout task joins");
        assert!(error.may_have_been_admitted(), "{error}");
        assert!(error.to_string().contains("flush timed out"), "{error}");
        registry.abort_owned_backend("progress-flush-timeout");
        assert!(registry
            .terminal_outcome("progress-flush-timeout")
            .is_some());
    }

    #[tokio::test]
    async fn dropping_an_attached_owner_aborts_infer_backend() {
        for method in ["infer"] {
            let registry = one_slot_registry();
            let inference_id = format!("dropped-owner-{method}");
            registry
                .begin_with_id(&inference_id)
                .expect("register owned backend");
            let admission = Arc::new(tokio::sync::Semaphore::new(1));
            let task_admission = admission.clone();
            let backend = tokio::spawn(async move {
                let _permit = task_admission
                    .acquire_owned()
                    .await
                    .expect("admission open");
                std::future::pending::<()>().await;
            });
            let owner_guard =
                attach_owned_inference_backend(registry.clone(), &inference_id, backend)
                    .expect("attach through the shared handler ownership path");
            let owner = tokio::spawn(async move {
                let _owner = owner_guard;
                std::future::pending::<()>().await;
            });
            tokio::task::yield_now().await;
            assert_eq!(admission.available_permits(), 0);

            owner.abort();
            assert!(owner
                .await
                .expect_err("owner future is cancelled")
                .is_cancelled());
            tokio::task::yield_now().await;

            assert_eq!(admission.available_permits(), 1, "{method}");
            assert_eq!(registry.counts(), (0, 1), "{method}");
            assert_eq!(registry.orphan_count(), 0, "{method}");
            assert!(
                registry.terminal_outcome(&inference_id).is_some(),
                "{method}"
            );
            registry
                .begin_with_id(&format!("replacement-{method}"))
                .expect("owner drop releases per-session capacity");
            registry.abort_all();
        }
    }
}

fn insert_inference_id(value: &mut Value, inference_id: &str) -> Result<(), String> {
    value
        .as_object_mut()
        .ok_or_else(|| "inference result must be a JSON object".to_string())?
        .insert(
            "inference_id".to_string(),
            Value::String(inference_id.to_string()),
        );
    Ok(())
}

/// Serialize inference notifications with terminal responses on the WebSocket
/// write lock, then re-check lifecycle state at the last safe point before the
/// frame reaches the wire. A terminal response can therefore never be
/// overtaken by a stream/progress frame that observed stale active state while
/// waiting for the shared sink.
async fn send_inference_notification_if_active(
    channel: &WsChannel,
    registry: &crate::inference_control::InferenceRegistry,
    inference_id: &str,
    text: String,
) -> Result<bool, InferenceNotificationSendError> {
    let deadline = tokio::time::Instant::now() + KEEPALIVE_WRITE_TIMEOUT;
    let mut write = tokio::time::timeout_at(deadline, channel.write.lock())
        .await
        .map_err(|_| {
            InferenceNotificationSendError::BeforeAdmission(format!(
                "notification write lock timed out after {}s",
                KEEPALIVE_WRITE_TIMEOUT.as_secs()
            ))
        })?;
    if !registry.is_active(inference_id) {
        return Ok(false);
    }

    match tokio::time::timeout_at(deadline, write.feed(Message::Text(text.into()))).await {
        Ok(Ok(())) => {}
        Ok(Err(error)) => {
            return Err(InferenceNotificationSendError::AfterAdmission(format!(
                "notification admission failed: {error}"
            )));
        }
        Err(_) => {
            return Err(InferenceNotificationSendError::BeforeAdmission(format!(
                "notification admission timed out after {}s",
                KEEPALIVE_WRITE_TIMEOUT.as_secs()
            )));
        }
    }

    match tokio::time::timeout_at(deadline, write.flush()).await {
        Ok(Ok(())) => Ok(true),
        Ok(Err(error)) => Err(InferenceNotificationSendError::AfterAdmission(format!(
            "notification flush failed: {error}"
        ))),
        Err(_) => Err(InferenceNotificationSendError::AfterAdmission(format!(
            "notification flush timed out after {}s",
            KEEPALIVE_WRITE_TIMEOUT.as_secs()
        ))),
    }
}

#[derive(Debug)]
enum InferenceNotificationSendError {
    BeforeAdmission(String),
    AfterAdmission(String),
}

impl InferenceNotificationSendError {
    #[cfg(test)]
    fn may_have_been_admitted(&self) -> bool {
        matches!(self, Self::AfterAdmission(_))
    }
}

impl std::fmt::Display for InferenceNotificationSendError {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::BeforeAdmission(message) | Self::AfterAdmission(message) => {
                formatter.write_str(message)
            }
        }
    }
}

#[cfg(test)]
mod inference_notification_terminal_boundary_tests {
    use super::send_inference_notification_if_active;
    use crate::inference_control::{ControlCause, InferenceRegistry};
    use crate::session::WsChannel;
    use car_proto::InferenceControlStatus;
    use futures::SinkExt;
    use std::sync::Arc;
    use tokio::sync::oneshot;
    use tokio_tungstenite::tungstenite::Message;

    #[tokio::test]
    async fn terminal_response_is_a_hard_boundary_for_progress_frames() {
        for (inference_id, cause, expected, wire_status) in [
            (
                "inf_terminal_boundary_cancel",
                ControlCause::Cancel,
                InferenceControlStatus::CancelledConfirmed,
                "cancelled_confirmed",
            ),
            (
                "inf_terminal_boundary_deadline",
                ControlCause::Deadline,
                InferenceControlStatus::DeadlineExceededConfirmed,
                "deadline_exceeded_confirmed",
            ),
        ] {
            let registry = Arc::new(InferenceRegistry::default());
            registry
                .begin_with_id(inference_id)
                .expect("register active inference");
            let (channel, captured) = WsChannel::test_capture();
            let channel = Arc::new(channel);

            // The held write guard is the deterministic barrier: both notification
            // tasks have received and serialized their event, but neither can reach
            // the wire until after the terminal response is committed below.
            let mut boundary = channel.write.lock().await;
            assert!(registry.is_active(inference_id), "event precheck is active");

            let frame = serde_json::json!({
                "jsonrpc": "2.0",
                "method": "infer.progress",
                "params": {"id": 1},
            });
            let channel = channel.clone();
            let notification_registry = registry.clone();
            let text = serde_json::to_string(&frame).expect("serialize notification");
            let (started_tx, started_rx) = oneshot::channel();
            let pending = tokio::spawn(async move {
                started_tx.send(()).expect("signal event receipt");
                send_inference_notification_if_active(
                    &channel,
                    &notification_registry,
                    inference_id,
                    text,
                )
                .await
            });
            started_rx.await.expect("notification task reached barrier");

            let terminal = registry.control(inference_id, cause, async { true }).await;
            assert_eq!(terminal, expected);
            boundary
                .send(Message::Text(
                    serde_json::json!({
                        "jsonrpc": "2.0",
                        "id": "terminal-1",
                        "result": {
                            "inference_id": inference_id,
                            "status": wire_status,
                        },
                    })
                    .to_string()
                    .into(),
                ))
                .await
                .expect("write terminal response");
            drop(boundary);

            assert!(
                !pending
                    .await
                    .expect("notification task")
                    .expect("notification send"),
                "terminal notification must be suppressed"
            );

            let frames = captured.lock().expect("capture lock");
            assert_eq!(frames.len(), 1, "no frame may follow terminal response");
            assert!(frames[0].contains(wire_status));
        }
        eprintln!(
            "C3_TERMINAL_BOUNDARY_SHARED=terminals=cancelled_confirmed+deadline_exceeded_confirmed,late_progress=suppressed,frames=1_each"
        );
    }
}

async fn wait_terminal_control_value(
    mut terminal: tokio::sync::watch::Receiver<Option<crate::inference_control::TerminalOutcome>>,
    inference_id: &str,
) -> Value {
    if terminal.borrow().is_none() {
        let _ = terminal.changed().await;
    }
    let status = match *terminal.borrow() {
        Some(crate::inference_control::TerminalOutcome::Controlled(status)) => status,
        _ => car_proto::InferenceControlStatus::AlreadyTerminal,
    };
    serde_json::to_value(car_proto::InferenceControlResponse {
        inference_id: inference_id.to_string(),
        status,
    })
    .unwrap_or_else(|_| {
        serde_json::json!({
            "inference_id": inference_id,
            "status": "already_terminal",
        })
    })
}

async fn handle_infer_active(
    msg: &JsonRpcMessage,
    state: &ServerState,
    session: &crate::session::ClientSession,
    inference_id: &str,
) -> Result<Value, String> {
    use futures::FutureExt;
    use std::panic::AssertUnwindSafe;
    use std::time::Duration;

    let engine = get_inference_engine(state);
    let mut req = parse_inference_request(&msg.params)?;

    // If context_query is provided, build context from memgine and inject it
    if let Some(cq) = msg.params.get("context_query").and_then(|v| v.as_str()) {
        // `effective_memgine` (#82): injected context must come from the graph
        // the session's facts went into, not the ephemeral one.
        let memgine_arc = session.effective_memgine().await;
        let mut memgine = memgine_arc.lock().await;
        // Split at the stable Identity+Constraints boundary so an Anthropic
        // cached request breaks after the stable prefix (which hits) instead of
        // over the whole churning context. `full` is byte-identical to the old
        // `build_context`, so non-Anthropic providers and StateBench see the
        // same context; the prefix is just a hint the handler validates.
        let split = memgine.build_context_split_for_model(cq, None);
        if !split.full.is_empty() {
            req.context_stable_prefix = split.stable_prefix();
            req.context = Some(split.full);
        }
    }
    // Stamp the originating session so a delegated call reaches the runner THIS
    // host registered, not whichever registered last (car-releases#77). Never
    // serialized — `caller` is `#[serde(skip)]`, so it does not reach the host.
    req.caller = Some(session.client_id.clone());
    maybe_apply_proactive_memory(msg, session, &mut req).await?;

    // Stakes-aware routing: a session authorized for FullAccess (irreversible /
    // externally-consequential) actions routes its inference quality-first — we
    // never economize on a session that can take actions it can't take back. The
    // policy→intent mapping lives here (car-server-core has both the session
    // tier and the request); car-inference stays policy-free.
    if session.permission_gate.read().await.granted_tier() == car_policy::PermissionTier::FullAccess
    {
        req.intent.get_or_insert_with(Default::default).high_stakes = true;
    }

    // Conversation-outcome (Part B): capture the chat user turn + idle-guard
    // verdict before `req` is consumed by generate_tracked. Shared with the
    // streaming path via `begin_chat_turn` (gate + concurrency rules live there).
    let (chat_user_text, chat_was_idle, _chat_inflight) = begin_chat_turn(&req, session);

    // Heartbeat (car#476). A cold local model-load, a queued admission slot, or
    // a slow remote can each keep this handler busy well past the FFI client's
    // old flat 30s read window. Emit an `infer.progress` notification carrying
    // this request id every INFER_HEARTBEAT_INTERVAL for the whole in-flight
    // span, so the client holds an *idle* read deadline (reset per heartbeat)
    // and only reaps true daemon silence. Model-agnostic on purpose: a local
    // cold-start and a slow remote are both covered without the client having
    // to know which model the router picked. The guard aborts the ticker the
    // instant this handler returns (any path); an older client that doesn't
    // idle-reset simply drops the unknown notification.
    const INFER_HEARTBEAT_INTERVAL: Duration = Duration::from_secs(10);
    struct HeartbeatGuard(tokio::task::JoinHandle<()>);
    impl Drop for HeartbeatGuard {
        fn drop(&mut self) {
            self.0.abort();
        }
    }
    let _heartbeat = {
        let channel = session.channel.clone();
        let request_id = msg.id.clone();
        let registry = session.inference_control.clone();
        let inference_id = inference_id.to_string();
        HeartbeatGuard(tokio::spawn(async move {
            let mut ticker = tokio::time::interval(INFER_HEARTBEAT_INTERVAL);
            ticker.tick().await; // consume the immediate first tick (fires at t=0)
            loop {
                ticker.tick().await;
                let notif = serde_json::json!({
                    "jsonrpc": "2.0",
                    "method": "infer.progress",
                    "params": { "id": request_id },
                });
                let Ok(text) = serde_json::to_string(&notif) else {
                    break;
                };
                match send_inference_notification_if_active(
                    &channel,
                    &registry,
                    &inference_id,
                    text,
                )
                .await
                {
                    Ok(true) => {}
                    Ok(false) | Err(_) => break,
                }
            }
        }))
    };

    // Process-wide admission gate. Held for the duration of the
    // generation so a burst of concurrent infer RPCs can't multiply
    // KV-cache + activation memory and take the host out. The
    // `_permit` binding is intentional — its `Drop` releases the slot
    // when this future returns.
    //
    // Which POOL depends on whether this host will do the compute. A remote
    // call allocates no KV cache here, so charging it a RAM-sized permit capped
    // remote throughput by local memory (car#800). We can only tell when the
    // request PINS a model: routing picks the model later, inside
    // generate_tracked, and by then the permit is already held. Unpinned — and
    // delegated, which may be a cloud API or a host driving a local llama.cpp —
    // stays on the local pool. Guessing "remote" would strip the guard from
    // exactly the call that needs it.
    let does_local_compute =
        match car_inference::exact_pinned_model_id(&req).or(req.model.as_deref()) {
            Some(pinned) => !engine
                .registered_schema(pinned)
                .map(|s| s.is_remote())
                .unwrap_or(false),
            None => true,
        };
    let _permit = state.admission.acquire_for(does_local_compute).await;

    // Use generate_tracked() so tool_calls, usage, model_used, trace_id, and
    // latency_ms are preserved in the response. Plain `generate()` discards
    // everything except `.text`, which silently breaks tool-use over the
    // WebSocket protocol (issue #43).
    //
    // NOTE: This directly serializes `InferenceResult`. Any field added to
    // that struct in `car-inference` becomes part of the public WebSocket
    // protocol. The shape is locked by `inference_result_serializes_*` tests
    // in car-inference; updating those tests is part of intentionally
    // changing the wire contract.
    // Bound the inference so a dead compute backend can never hang the client
    // forever. The 10s heartbeat above keeps the client's idle read deadline
    // alive for the whole in-flight span, so without this bound a compute that
    // dies silently reads as an infinite hang rather than an error. Two failure
    // modes are covered: (1) the compute panics and unwinds through this future
    // (e.g. candle re-panicking a spawn_blocking JoinError — the observed
    // cudarc/cuBLAS-load case) → caught by catch_unwind; (2) the compute dies on
    // a detached task, leaving this await pending forever → caught by the
    // timeout. Tunable via CAR_INFER_TIMEOUT_SECS (default 600s — generous
    // enough for a cold large-model load, which the heartbeat also covers).
    let infer_timeout = inference_total_timeout();
    let result = match tokio::time::timeout(
        infer_timeout,
        AssertUnwindSafe(engine.generate_tracked(req)).catch_unwind(),
    )
    .await
    {
        Ok(Ok(r)) => r.map_err(|e| inference_dispatch_error(&e))?,
        Ok(Err(panic)) => {
            let detail = panic
                .downcast_ref::<&str>()
                .map(|s| (*s).to_string())
                .or_else(|| panic.downcast_ref::<String>().cloned())
                .unwrap_or_else(|| "unknown panic".to_string());
            return Err(format!(
                "inference failed (internal panic): {detail}. If this is a CUDA build, \
                 ensure the CUDA toolkit `bin` directory is on PATH so cudarc can load \
                 cublas/cudart."
            ));
        }
        Err(_) => {
            return Err(format!(
                "inference timed out after {}s with no result — the compute backend may \
                 have failed to initialize (e.g. a CUDA/cuBLAS library load error). \
                 Set CAR_INFER_TIMEOUT_SECS to adjust the limit.",
                infer_timeout.as_secs()
            ));
        }
    };

    // Conversation-outcome (Part B): score the session's PRIOR assistant turn by
    // this new user turn (the next-turn-is-the-label signal), then remember this
    // turn for the next round. trace_id/model are carried straight from the
    // result that produced each turn — never reconstructed from order — so credit
    // lands on the exact model that generated the judged turn. Gated on
    // `chat_was_idle` so overlapping infers don't fabricate adjacency (neo #1).
    // Best-effort: never fails the inference response.
    if let Some(user_text) = chat_user_text.filter(|_| chat_was_idle) {
        let mut slot = session.last_chat_turn.lock().await;
        let tracker_arc = engine.outcome_tracker();
        let mut tracker = tracker_arc.write().await;
        let tally = score_and_remember_chat_turn(
            &mut slot,
            &mut tracker,
            user_text,
            &result.text,
            &result.trace_id,
            &result.model_used,
        );
        if tally.submitted > 0 {
            tracing::debug!(
                submitted = tally.submitted,
                resolved = tally.resolved,
                "conversation-outcome recorded for prior chat turn"
            );
        }
    }

    serde_json::to_value(&result).map_err(|e| format!("serialize result: {}", e))
}

/// Streaming inference — mirrors NAPI `inferStream`. Closes
/// Parslee-ai/car-releases#30. Same `GenerateRequest` shape as
/// `infer`; emits `inference.stream.event` JSON-RPC notifications
/// during the run, and returns the final `InferenceResult` as the
/// JSON-RPC response when the stream completes.
///
/// Notification shape (server → client):
/// ```jsonc
/// {
///   "jsonrpc": "2.0",
///   "method": "inference.stream.event",
///   "params": {
///     "request_id": "<original RPC id>",
///     "event": { "type": "text" | "tool_start" | "tool_delta" | "usage", ... }
///   }
/// }
/// ```
///
/// The final `done` event is not pushed as a notification — it's
/// the JSON-RPC response with the accumulated `InferenceResult`.
/// `video.generate` — daemon-side wrapper for
/// `InferenceEngine::generate_video`. Mirrors `handle_infer`'s
/// admission gate + JSON request shape (Parslee-ai/car#185).
///
/// Previously the CLI's `cmd_video` constructed an in-process
/// engine and called `generate_video` directly — a v0.7 holdover
/// that bypassed the daemon. With this handler the CLI proxies
/// here, so the engine-level audio_passthrough gate fires
/// inside the daemon process where all FFI surfaces converge.
async fn handle_image_generate(msg: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    let req: car_inference::GenerateImageRequest = typed_params(&msg.params)?;
    // Share the same admission gate as text/video generation — a burst
    // of image requests shouldn't smuggle around the concurrency cap.
    let _permit = state.admission.acquire().await;
    let result = engine
        .generate_image(req)
        .await
        .map_err(|e| e.to_string())?;
    serde_json::to_value(&result).map_err(|e| format!("serialize result: {}", e))
}

async fn handle_video_generate(msg: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    let req: car_inference::GenerateVideoRequest = typed_params(&msg.params)?;
    let _permit = state.admission.acquire().await;
    let result = engine
        .generate_video(req)
        .await
        .map_err(|e| e.to_string())?;
    serde_json::to_value(&result).map_err(|e| format!("serialize result: {}", e))
}

async fn handle_infer_stream(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    let mut req = parse_inference_request(&msg.params)?;

    // Same context-injection convenience as non-streaming `infer` so
    // the two methods have parity on the call shape.
    if let Some(cq) = msg.params.get("context_query").and_then(|v| v.as_str()) {
        // `effective_memgine` (#82): injected context must come from the graph
        // the session's facts went into, not the ephemeral one.
        let memgine_arc = session.effective_memgine().await;
        let mut memgine = memgine_arc.lock().await;
        // Split at the stable Identity+Constraints boundary so an Anthropic
        // cached request breaks after the stable prefix (which hits) instead of
        // over the whole churning context. `full` is byte-identical to the old
        // `build_context`, so non-Anthropic providers and StateBench see the
        // same context; the prefix is just a hint the handler validates.
        let split = memgine.build_context_split_for_model(cq, None);
        if !split.full.is_empty() {
            req.context_stable_prefix = split.stable_prefix();
            req.context = Some(split.full);
        }
    }
    // Stamp the originating session so a delegated call reaches the runner THIS
    // host registered, not whichever registered last (car-releases#77). Never
    // serialized — `caller` is `#[serde(skip)]`, so it does not reach the host.
    req.caller = Some(session.client_id.clone());
    maybe_apply_proactive_memory(msg, session, &mut req).await?;

    // Stakes-aware routing (parity with non-streaming `infer`): a FullAccess
    // session routes inference quality-first.
    if session.permission_gate.read().await.granted_tier() == car_policy::PermissionTier::FullAccess
    {
        req.intent.get_or_insert_with(Default::default).high_stakes = true;
    }

    // Conversation-outcome (Part B, streaming parity): capture the chat user
    // turn + idle-guard verdict before `req` is consumed. Same gate + rules as
    // the non-streaming path (shared `begin_chat_turn`).
    let (chat_user_text, chat_was_idle, _chat_inflight) = begin_chat_turn(&req, session);

    let _permit = state.admission.acquire().await;
    // Same classification as the non-streaming path: `generate_tracked_stream`
    // returns a typed `InferenceError` when the call is rejected BEFORE the
    // stream opens, which is where a gateway content refusal lands. (A refusal
    // that arrives mid-stream reaches us as `StreamEvent::Error(String)` —
    // already flattened to text by the provider layer — so it cannot be
    // classified by variant here.)
    let mut handle = engine
        .generate_tracked_stream(req)
        .await
        .map_err(|e| inference_dispatch_error(&e))?;

    let mut accumulator = car_inference::StreamAccumulator::default();
    let mut stream_error: Option<String> = None;
    let mut saw_done = false;
    let request_id = msg.id.clone();

    while let Some(event) = handle.events.recv().await {
        let event_payload = match &event {
            car_inference::StreamEvent::TextDelta(text) => {
                serde_json::json!({"type": "text", "data": text})
            }
            car_inference::StreamEvent::ToolCallStart { name, index, .. } => {
                serde_json::json!({"type": "tool_start", "name": name, "index": index})
            }
            car_inference::StreamEvent::ToolCallDelta {
                index,
                arguments_delta,
            } => serde_json::json!({
                "type": "tool_delta",
                "index": index,
                "data": arguments_delta,
            }),
            car_inference::StreamEvent::Usage {
                input_tokens,
                output_tokens,
                cache_read_input_tokens,
                cache_creation_input_tokens,
            } => serde_json::json!({
                "type": "usage",
                "input_tokens": input_tokens,
                "output_tokens": output_tokens,
                "cache_read_input_tokens": cache_read_input_tokens,
                "cache_creation_input_tokens": cache_creation_input_tokens,
            }),
            car_inference::StreamEvent::StopReason(reason) => {
                serde_json::json!({"type": "stop_reason", "data": reason})
            }
            car_inference::StreamEvent::ProviderOutputItem(item) => {
                serde_json::json!({"type": "provider_output_item", "item": item})
            }
            car_inference::StreamEvent::Error(message) => {
                stream_error = Some(message.clone());
                serde_json::json!({"type": "error", "message": message})
            }
            // Done is delivered as the JSON-RPC response, not a
            // notification — matches the NAPI contract where the
            // standalone function's return value is the accumulated
            // result and the callback only sees in-progress events.
            car_inference::StreamEvent::Done { .. } => {
                saw_done = true;
                accumulator.push(&event);
                continue;
            }
        };

        let notif = serde_json::json!({
            "jsonrpc": "2.0",
            "method": "inference.stream.event",
            "params": {
                "request_id": request_id,
                "event": event_payload,
            },
        });
        if let Ok(text) = serde_json::to_string(&notif) {
            let _ = session
                .channel
                .write
                .lock()
                .await
                .send(Message::Text(text.into()))
                .await;
        }
        accumulator.push(&event);
    }

    let (text, tool_calls, usage, stop_reason) = accumulator.finish_with_usage();

    if let Some(error) = stream_error {
        // A refusal that lands mid-stream is the same ruling as one that lands
        // before the stream opens, and a benchmark scoring the tracked inference
        // path cannot see a difference it did not ask for. Classify it too, so
        // `infer_stream` reaches -32007 by both routes (Parslee-ai/car#796).
        return Err(stream_dispatch_error(error));
    }
    if !saw_done {
        return Err("stream ended without positive completion".to_string());
    }

    // Record inference token telemetry into the session event log as deep
    // telemetry (§3.5.1) so trajectory-level token totals
    // (`EventLog::metrics_totals`) reflect model cost, not just tool
    // latency. Emitted **once** from the accumulator's reconciled usage —
    // providers (e.g. Anthropic) emit cumulative `Usage` multiple times
    // per stream, so metering inside the loop would double-count. The
    // dedicated `InferenceMetered` kind keeps this out of action stats.
    if let Some(u) = &usage {
        session.runtime.log.lock().await.append_metered(
            car_eventlog::EventKind::InferenceMetered,
            None,
            None,
            HashMap::new(),
            car_eventlog::Metrics::inference(u.prompt_tokens, u.completion_tokens, None),
        );
    }

    // Conversation-outcome (Part B, streaming parity): score the session's PRIOR
    // chat turn by this new user turn, then stash this turn's trace_id/model for
    // the next round. They come from the `TrackedStream` handle (minted by the
    // same `record_start` the tap task resolves), so credit lands on the exact
    // model that produced the turn — the streaming analogue of `infer`'s
    // `InferenceResult`. What's load-bearing is that the PRIOR turn's trace still
    // survives in the tracker's `pending` set across the inter-turn gap; the only
    // thing that evicts it early is the 300s pending-sweep, identical to the
    // non-streaming path (a long-idle session loses the signal either way).
    // Best-effort: never fails the response.
    if let Some(user_text) = chat_user_text.filter(|_| chat_was_idle) {
        let mut slot = session.last_chat_turn.lock().await;
        let tracker_arc = engine.outcome_tracker();
        let mut tracker = tracker_arc.write().await;
        let tally = score_and_remember_chat_turn(
            &mut slot,
            &mut tracker,
            user_text,
            &text,
            &handle.trace_id,
            &handle.model_used,
        );
        if tally.submitted > 0 {
            tracing::debug!(
                submitted = tally.submitted,
                resolved = tally.resolved,
                "conversation-outcome recorded for prior chat turn (streaming)"
            );
        }
    }

    Ok(serde_json::json!({
        "text": text,
        "tool_calls": tool_calls,
        "usage": usage,
        "stop_reason": stop_reason,
        // Parity with non-streaming `infer`: surface the trace + model so a
        // client can attribute the turn / resolve outcomes later.
        "trace_id": handle.trace_id,
        "model_used": handle.model_used,
    }))
}

async fn handle_embed(msg: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    let req: car_inference::EmbedRequest = typed_params(&msg.params)?;
    // Embeds load their own model weights; share the same admission
    // gate as generations so a burst of embed requests can't smuggle
    // around the concurrency cap.
    let _permit = state.admission.acquire().await;
    let result = engine.embed(req).await.map_err(|e| e.to_string())?;
    Ok(serde_json::json!({"embeddings": result}))
}

async fn handle_classify(msg: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    let req: car_inference::ClassifyRequest = typed_params(&msg.params)?;
    let _permit = state.admission.acquire().await;
    let result = engine.classify(req).await.map_err(|e| e.to_string())?;
    Ok(serde_json::json!({"classifications": result}))
}

/// Surface the current admission state so the menubar tray and
/// `car daemon status` can show "queued: N" / "permits: P/T". Read-only
/// snapshot — racy by definition but correct enough for status panels.
fn handle_admission_status(state: &ServerState) -> Result<Value, String> {
    let total = state.admission.permits();
    let available = state.admission.permits_available();
    let in_use = total.saturating_sub(available);
    Ok(serde_json::json!({
        "permits_total": total,
        "permits_available": available,
        "permits_in_use": in_use,
        "env_override": crate::admission::ENV_MAX_CONCURRENT,
    }))
}

async fn handle_tokenize(msg: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let model = msg
        .params
        .get("model")
        .and_then(|v| v.as_str())
        .ok_or("missing 'model' parameter")?;
    let text = msg
        .params
        .get("text")
        .and_then(|v| v.as_str())
        .ok_or("missing 'text' parameter")?;
    let engine = get_inference_engine(state);
    let ids = engine
        .tokenize(model, text)
        .await
        .map_err(|e| e.to_string())?;
    Ok(serde_json::json!({"tokens": ids}))
}

async fn handle_detokenize(msg: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let model = msg
        .params
        .get("model")
        .and_then(|v| v.as_str())
        .ok_or("missing 'model' parameter")?;
    let tokens: Vec<u32> = msg
        .params
        .get("tokens")
        .and_then(|v| v.as_array())
        .ok_or("missing 'tokens' parameter")?
        .iter()
        .map(|t| {
            t.as_u64()
                .and_then(|n| u32::try_from(n).ok())
                .ok_or_else(|| "tokens[] must be u32 values".to_string())
        })
        .collect::<Result<Vec<_>, _>>()?;
    let engine = get_inference_engine(state);
    let text = engine
        .detokenize(model, &tokens)
        .await
        .map_err(|e| e.to_string())?;
    Ok(serde_json::json!({"text": text}))
}

/// `models.register` — persist a user-supplied `ModelSchema` to `models.json`
/// under the CAR state root, i.e. `~/.car/models.json` unless `CAR_HOME` moves
/// it (Parslee-ai/car-releases#39). Replaces any existing entry with the same
/// `id`. Returns `{id, registered}`.
///
/// **Phase 1 limitation**: the daemon's live `UnifiedRegistry` is
/// not updated in-process — the new model becomes visible to
/// `models.list`, `infer`, `infer_stream` on the **next daemon
/// boot** when `load_user_config` re-reads the file. This is
/// enough to unblock opencode's setup flow (register ahead of
/// time, then start the daemon). Hot-update requires either an
/// `RwLock<InferenceEngine>` on `ServerState` or an
/// interior-mutable `UnifiedRegistry`; both touch 20+ call sites
/// and are tracked as a follow-up.
///
/// Until hot-update lands, callers SHOULD register their models
/// before issuing `infer` calls against them, and operators
/// SHOULD restart the daemon after batches of model
/// registrations.
fn parse_user_registered_model_schema(
    schema_value: Value,
) -> Result<car_inference::ModelSchema, String> {
    let mut schema: car_inference::ModelSchema =
        serde_json::from_value(schema_value).map_err(|e| format!("invalid ModelSchema: {e}"))?;
    if car_inference::openrouter::is_curated_managed_gateway_alias(&schema.id) {
        return Err(
            "Parslee-managed OpenRouter aliases are reserved and cannot be registered".into(),
        );
    }
    schema.mark_user_registered();
    Ok(schema)
}

async fn handle_models_register(
    req: &JsonRpcMessage,
    _state: &Arc<ServerState>,
) -> Result<Value, String> {
    // The params shape mirrors v0.7's FFI `rt.registerModel(schemaJson)`:
    // either the bare `ModelSchema` value, OR `{ schema: ModelSchema }`.
    // Honor both so existing in-process callers don't have to reshape.
    let schema_value = match req.params.get("schema") {
        Some(v) => v.clone(),
        None => req.params.clone(),
    };
    let schema = parse_user_registered_model_schema(schema_value)?;
    let id = schema.id.clone();

    // One resolver, shared with the read side: `models.json` under the CAR
    // state root (`~/.car/models.json` unless `CAR_HOME` moves it). The
    // registry's `user_config_path` is the same call, so what this writes is
    // what the next daemon boot loads. Read whatever's there, swap in the new
    // entry, write back atomically.
    let path = car_inference::registry::user_config_path()
        .ok_or_else(|| "no CAR_HOME / HOME / USERPROFILE in env".to_string())?;
    if let Some(car_dir) = path.parent() {
        std::fs::create_dir_all(car_dir)
            .map_err(|e| format!("create {}: {e}", car_dir.display()))?;
    }

    let mut models: Vec<car_inference::ModelSchema> = if path.exists() {
        let text =
            std::fs::read_to_string(&path).map_err(|e| format!("read {}: {e}", path.display()))?;
        if text.trim().is_empty() {
            Vec::new()
        } else {
            serde_json::from_str(&text).map_err(|e| format!("parse {}: {e}", path.display()))?
        }
    } else {
        Vec::new()
    };
    for model in &mut models {
        // Rewriting models.json is also a migration boundary for legacy rows
        // that omitted trust_tier or claimed Curated explicitly.
        model.mark_user_registered();
    }
    // Replace existing entry with the same id, else append.
    if let Some(slot) = models.iter_mut().find(|m| m.id == id) {
        *slot = schema;
    } else {
        models.push(schema);
    }
    let json =
        serde_json::to_string_pretty(&models).map_err(|e| format!("serialize models.json: {e}"))?;
    let tmp = path.with_extension("json.tmp");
    std::fs::write(&tmp, json).map_err(|e| format!("write {}: {e}", tmp.display()))?;
    std::fs::rename(&tmp, &path)
        .map_err(|e| format!("rename {} -> {}: {e}", tmp.display(), path.display()))?;
    Ok(serde_json::json!({
        "id": id,
        "registered": true,
        "path": path.to_string_lossy(),
        "note": "Daemon restart required for live UnifiedRegistry visibility \
                 (Parslee-ai/car-releases#39 phase 1). The model is persisted; \
                 next car-server boot loads it via UnifiedRegistry::load_user_config.",
    }))
}

#[cfg(test)]
mod model_registration_trust_tests {
    use super::parse_user_registered_model_schema;

    #[test]
    fn daemon_models_register_rejects_reserved_managed_aliases() {
        let schema = car_inference::openrouter::curated_schemas()
            .into_iter()
            .find(|schema| schema.id == "parslee/openrouter/frontier-general")
            .unwrap();
        let error =
            parse_user_registered_model_schema(serde_json::to_value(schema).unwrap()).unwrap_err();
        assert_eq!(
            error,
            "Parslee-managed OpenRouter aliases are reserved and cannot be registered"
        );
    }

    #[test]
    fn daemon_models_register_forces_non_reserved_schema_to_community() {
        let mut schema = car_inference::openrouter::curated_schemas()
            .into_iter()
            .find(|schema| schema.id == "parslee/openrouter/frontier-general")
            .unwrap();
        schema.id = "user/nearby-model".into();

        let registered =
            parse_user_registered_model_schema(serde_json::to_value(schema).unwrap()).unwrap();
        assert_eq!(registered.trust_tier, car_inference::TrustTier::Community);
    }
}

/// `models.unregister` — remove an entry by id from the same state-root
/// `models.json` `models.register` writes (`~/.car/models.json` unless
/// `CAR_HOME` moves it; Parslee-ai/car#186 — symmetric to `models.register`).
/// Returns `{ id, unregistered, path }` on success. Returns an error
/// when the model isn't present.
///
/// **Phase 1 limitation** (same as `models.register`): the daemon's
/// live `UnifiedRegistry` is not rebuilt — the removal takes effect
/// on the next daemon boot. Callers SHOULD restart the daemon after
/// a batch of unregistrations if they expect `models.list_unified`
/// to reflect the change immediately.
async fn handle_models_unregister(
    req: &JsonRpcMessage,
    _state: &Arc<ServerState>,
) -> Result<Value, String> {
    // Params shape mirrors the CLI flag: `{ id: string }`. Bare-string
    // params are honored for symmetry with the register handler's
    // tolerant shape (`{schema: ...}` OR bare schema).
    let id = match req.params.get("id") {
        Some(v) => v
            .as_str()
            .ok_or_else(|| "`id` must be a string".to_string())?
            .to_string(),
        None => match req.params.as_str() {
            Some(s) => s.to_string(),
            None => return Err("missing `id` parameter".to_string()),
        },
    };

    // Same resolver `models.register` and the registry use, so an unregister
    // finds the file a register just wrote even when `CAR_HOME` moved the root.
    let path = car_inference::registry::user_config_path()
        .ok_or_else(|| "no CAR_HOME / HOME / USERPROFILE in env".to_string())?;

    if !path.exists() {
        // Idempotent no-op: with no models.json the desired end-state (id not in
        // the user registry) already holds. The UI's Remove on a builtin-catalog
        // model that was never user-registered hit this as an alarming -32603
        // "no models.json — nothing to unregister" (PAR-7266). Report success.
        return Ok(serde_json::json!({
            "id": id,
            "unregistered": false,
            "note": "no models.json — nothing to unregister (already absent)",
        }));
    }
    let text =
        std::fs::read_to_string(&path).map_err(|e| format!("read {}: {e}", path.display()))?;
    let mut models: Vec<car_inference::ModelSchema> = if text.trim().is_empty() {
        Vec::new()
    } else {
        serde_json::from_str(&text).map_err(|e| format!("parse {}: {e}", path.display()))?
    };
    let before = models.len();
    models.retain(|m| m.id != id);
    if models.len() == before {
        // Not in the user registry (e.g. a builtin-catalog model the UI offered a
        // Remove button for) — idempotent no-op, not a UI-surfaced error (PAR-7266).
        return Ok(serde_json::json!({
            "id": id,
            "unregistered": false,
            "note": "model not in models.json — nothing to unregister",
        }));
    }
    let json =
        serde_json::to_string_pretty(&models).map_err(|e| format!("serialize models.json: {e}"))?;
    let tmp = path.with_extension("json.tmp");
    std::fs::write(&tmp, json).map_err(|e| format!("write {}: {e}", tmp.display()))?;
    std::fs::rename(&tmp, &path)
        .map_err(|e| format!("rename {} -> {}: {e}", tmp.display(), path.display()))?;
    Ok(serde_json::json!({
        "id": id,
        "unregistered": true,
        "path": path.to_string_lossy(),
        "note": "Daemon restart required for live UnifiedRegistry visibility \
                 (phase 1, matching models.register).",
    }))
}

fn handle_models_list(state: &ServerState) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    let models = engine.list_models();
    serde_json::to_value(&models).map_err(|e| e.to_string())
}

#[derive(Debug, Default, Deserialize)]
struct ModelsListUnifiedParams {
    #[serde(default)]
    refresh_openrouter_status: bool,
}

async fn handle_models_list_unified(
    message: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let params = if message.params.is_null() {
        ModelsListUnifiedParams::default()
    } else {
        typed_params(&message.params)?
    };
    if params.refresh_openrouter_status {
        let _ = car_inference::openrouter::refresh_credential_source_for_status().await;
    }
    let engine = get_inference_engine(state);
    let models = engine.list_models_unified();
    serde_json::to_value(&models).map_err(|e| e.to_string())
}

#[cfg(test)]
mod models_list_unified_status_tests {
    use super::{handle_models_list_unified, JsonRpcMessage};
    use crate::session::{ServerState, ServerStateConfig};
    use serde_json::{json, Value};
    use std::sync::Arc;

    #[tokio::test]
    async fn daemon_list_refreshes_openrouter_only_when_explicitly_requested() {
        const SENTINEL: &str = "CAR_SERVER_MODELS_LIST_STATUS_CHILD";
        if std::env::var_os(SENTINEL).is_none() {
            let status = std::process::Command::new(std::env::current_exe().unwrap())
                .arg("--exact")
                .arg(
                    "handler::models_list_unified_status_tests::daemon_list_refreshes_openrouter_only_when_explicitly_requested",
                )
                .arg("--nocapture")
                .arg("--test-threads=1")
                .env(SENTINEL, "1")
                .env_remove(car_home::ENV_VAR)
                .env_remove("CAR_SECRETS_FILE_DIR")
                .env_remove(car_inference::openrouter::API_KEY_ENV)
                .status()
                .expect("spawn isolated daemon models-list status test");
            assert!(status.success(), "isolated daemon models-list test failed");
            return;
        }

        let fixture = tempfile::TempDir::new().unwrap();
        unsafe {
            std::env::set_var(car_home::ENV_VAR, fixture.path().join("car-home"));
            std::env::set_var(
                "CAR_SECRETS_FILE_DIR",
                fixture.path().join("isolated-secrets"),
            );
            std::env::remove_var(car_inference::openrouter::API_KEY_ENV);
        }
        car_secrets::SecretStore::new()
            .put(
                &car_secrets::SecretRef::with_default_service(
                    car_inference::openrouter::API_KEY_ENV,
                ),
                "fixture-value",
            )
            .unwrap();
        let engine = Arc::new(car_inference::InferenceEngine::new(
            car_inference::InferenceConfig {
                state_root: fixture.path().join("state"),
                models_dir: fixture.path().join("models"),
                ..car_inference::InferenceConfig::default()
            },
        ));
        let state = ServerState::with_config(
            ServerStateConfig::new(fixture.path().join("journal")).with_inference(engine),
        );
        let request = |params| JsonRpcMessage {
            jsonrpc: "2.0".into(),
            method: Some("models.list_unified".into()),
            params,
            id: json!(1),
            result: None,
            error: None,
        };

        assert_eq!(car_inference::openrouter::credential_source(), None);
        let before = car_secrets::secret_store_activity();
        let passive = handle_models_list_unified(&request(Value::Null), &state)
            .await
            .unwrap();
        let after_passive = car_secrets::secret_store_activity();
        assert_eq!(after_passive.status_attempts, before.status_attempts);
        assert_eq!(after_passive.get_attempts, before.get_attempts);
        let passive_openrouter = passive
            .as_array()
            .unwrap()
            .iter()
            .filter(|model| model["id"].as_str().unwrap().starts_with("openrouter/"))
            .collect::<Vec<_>>();
        assert!(!passive_openrouter.is_empty());
        assert!(passive_openrouter
            .iter()
            .all(|model| model["available"] == false));

        let refreshed = handle_models_list_unified(
            &request(json!({ "refresh_openrouter_status": true })),
            &state,
        )
        .await
        .unwrap();
        let after_refresh = car_secrets::secret_store_activity();
        assert!(after_refresh.status_attempts > after_passive.status_attempts);
        assert_eq!(after_refresh.get_attempts, after_passive.get_attempts);
        let refreshed_openrouter = refreshed
            .as_array()
            .unwrap()
            .iter()
            .filter(|model| model["id"].as_str().unwrap().starts_with("openrouter/"))
            .collect::<Vec<_>>();
        assert!(!refreshed_openrouter.is_empty());
        assert!(refreshed_openrouter
            .iter()
            .all(|model| model["available"] == true));
    }
}

fn handle_models_catalog_snapshot(
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    if !session_has_capability(session, car_proto::MODELS_CATALOG_IDENTITY_CAPABILITY) {
        return Err(format!(
            "{} negotiate `{}` as a required or optional capability before calling `models.catalog_snapshot`",
            car_proto::PROTOCOL_CAPABILITY_MISMATCH_MESSAGE_PREFIX,
            car_proto::MODELS_CATALOG_IDENTITY_CAPABILITY,
        ));
    }
    let engine = get_inference_engine(state);
    let snapshot = engine.catalog_snapshot()?;
    serde_json::to_value(snapshot).map_err(|error| error.to_string())
}

#[derive(Debug, Default, Deserialize)]
#[serde(deny_unknown_fields)]
struct EmptyModelManagementParams {}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct ModelPreflightParams {
    model_id: String,
    #[serde(default)]
    context_tokens: usize,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct ModelIdParams {
    model_id: String,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct ModelPullParams {
    #[serde(alias = "id", alias = "model")]
    name: String,
}

fn strict_model_params<T: serde::de::DeserializeOwned>(
    message: &JsonRpcMessage,
) -> Result<T, String> {
    let params = if message.params.is_null() {
        serde_json::json!({})
    } else {
        message.params.clone()
    };
    serde_json::from_value(params)
        .map_err(|error| format!("invalid model-management params: {error}"))
}

fn handle_models_resource_policy_get(
    message: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let _: EmptyModelManagementParams = strict_model_params(message)?;
    let engine = get_inference_engine(state);
    let repository = car_inference::resource_policy::FileResourcePolicyRepository::new(
        engine.config.state_root.clone(),
    );
    let evidence = repository
        .load_with_evidence()
        .map_err(|error| error.to_string())?;
    let hardware = car_inference::HardwareInfo::detect();
    let evaluated_budget = evidence.policy.effective_budget(hardware.total_ram_mb);
    Ok(serde_json::json!({
        "policy": evidence.policy,
        "evaluated_budget": evaluated_budget,
        "hardware_total_mb": hardware.total_ram_mb,
        "source": evidence.source,
        "warning": evidence.warning,
    }))
}

fn handle_models_resource_policy_set(
    message: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    let policy: car_inference::resource_policy::ResourcePolicy = strict_model_params(message)?;
    policy.validate().map_err(|error| error.to_string())?;
    let engine = get_inference_engine(state);
    let repository = car_inference::resource_policy::FileResourcePolicyRepository::new(
        engine.config.state_root.clone(),
    );
    car_inference::resource_policy::ResourcePolicyRepository::save(&repository, &policy)
        .map_err(|error| error.to_string())?;
    engine.apply_local_resource_policy(policy.clone());
    let hardware = car_inference::HardwareInfo::detect();
    let evaluated_budget = policy.effective_budget(hardware.total_ram_mb);
    Ok(serde_json::json!({
        "policy": policy,
        "evaluated_budget": evaluated_budget,
        "hardware_total_mb": hardware.total_ram_mb,
        "notice": evaluated_budget.normalization_notice,
    }))
}

fn handle_models_preflight(message: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let params: ModelPreflightParams = strict_model_params(message)?;
    let preflight = get_inference_engine(state)
        .local_model_preflight(&params.model_id, params.context_tokens)
        .map_err(|error| error.to_string())?;
    serde_json::to_value(preflight).map_err(|error| error.to_string())
}

fn handle_models_storage_roots(
    message: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    let _: EmptyModelManagementParams = strict_model_params(message)?;
    let engine = get_inference_engine(state);
    let store = engine.model_management_store();
    let hf_home = std::env::var_os("HF_HOME")
        .map(std::path::PathBuf::from)
        .or_else(|| {
            std::env::var_os("HOME")
                .or_else(|| std::env::var_os("USERPROFILE"))
                .map(|home| std::path::PathBuf::from(home).join(".cache/huggingface"))
        })
        .unwrap_or_else(|| std::path::PathBuf::from(".cache/huggingface"));
    let normalize = car_inference::resource_policy::normalized_state_root_key;
    Ok(serde_json::json!({
        "state_root": normalize(&engine.config.state_root),
        "models_dir": normalize(&engine.config.models_dir),
        "hf_home": normalize(&hf_home),
        "hf_hub": normalize(&hf_home.join("hub")),
        "install_receipts_dir": normalize(store.receipts_root()),
        "management_state_dir": normalize(store.management_state_dir()),
    }))
}

async fn handle_models_remove(
    message: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    let params: ModelIdParams = strict_model_params(message)?;
    let engine = Arc::clone(get_inference_engine(state));
    let operation = state
        .spawn_durable_operation("models.remove", async move {
            let result = engine
                .remove_model_from_car(&params.model_id)
                .await
                .map_err(|error| error.to_string())?;
            Ok(serde_json::json!({
                "model_id": result.model_id,
                "removed_from_car": true,
                "artifact_kind": result.artifact_kind,
                "shared_cache_preserved": true,
            }))
        })
        .await;
    operation.await.map_err(|_| {
        "daemon-owned models.remove operation stopped before publishing a result".to_string()
    })?
}

async fn handle_models_adopt(
    message: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    let params: ModelIdParams = strict_model_params(message)?;
    let engine = Arc::clone(get_inference_engine(state));
    let operation = state
        .spawn_durable_operation("models.adopt", async move {
            let receipt = engine
                .adopt_model_into_car(&params.model_id)
                .await
                .map_err(|error| error.to_string())?;
            Ok(serde_json::json!({
                "model_id": receipt.model_id,
                "adopted": true,
                "can_remove": true,
            }))
        })
        .await;
    operation.await.map_err(|_| {
        "daemon-owned models.adopt operation stopped before publishing a result".to_string()
    })?
}

/// Return the runtime-resolved, non-secret gateway base for one canonical
/// Parslee-managed OpenRouter alias. This is intentionally a separate,
/// authenticated read: `models.list_unified` remains the public catalog view
/// and never publishes routing authorities for every model. The registry must
/// already be initialized explicitly; provenance never triggers engine setup.
async fn handle_models_route_provenance(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let id = require_str(&req.params, "id")?;
    let engine = state.inference.get().ok_or_else(|| {
        "models.route_provenance requires an initialized model registry; \
         call `models.list_unified` to initialize it, then retry"
            .to_string()
    })?;
    let schema = engine
        .registered_schema(id)
        .ok_or_else(|| format!("unknown model id `{id}`"))?;
    let canonical_id = canonical_managed_route_provenance_id(&schema)?;

    let (endpoint, authority) = resolved_managed_parslee_base().await?;
    serde_json::to_value(ManagedRouteProvenance {
        id: canonical_id,
        provider: "parslee",
        source: "proprietary_oauth_pkce",
        is_local: false,
        endpoint,
        authority,
    })
    .map_err(|error| error.to_string())
}

/// Keep provenance tied to the actual registered row (including a valid signed
/// catalog replacement), using the same managed transport predicate inference
/// uses for outbound requests.
fn canonical_managed_route_provenance_id(
    schema: &car_inference::ModelSchema,
) -> Result<&str, String> {
    let Some(id) = car_inference::openrouter::canonical_managed_gateway_selector(schema) else {
        return Err(
            "models.route_provenance supports only canonical Parslee-managed OpenRouter aliases"
                .into(),
        );
    };
    Ok(id)
}

#[derive(Debug, Serialize)]
struct ManagedRouteProvenance<'a> {
    id: &'a str,
    provider: &'static str,
    source: &'static str,
    is_local: bool,
    endpoint: String,
    authority: String,
}

/// Resolve through the exact runtime source used by Parslee inference, then
/// emit only its non-secret HTTP(S) origin. With no process override,
/// `car_auth::api_base` performs one authoritative V2 secret-store read, which
/// may invoke a platform credential helper. Keep that synchronous local I/O off
/// Tokio's worker threads; the lookup neither refreshes, writes, nor contacts
/// the resolved base.
async fn resolved_managed_parslee_base() -> Result<(String, String), String> {
    let api_base = tokio::task::spawn_blocking(|| car_auth::api_base(None))
        .await
        .map_err(|error| format!("managed inference API base worker failed: {error}"))?;
    redact_resolved_managed_api_base(&api_base)
}

fn redact_resolved_managed_api_base(api_base: &str) -> Result<(String, String), String> {
    let url = reqwest::Url::parse(api_base)
        .map_err(|_| "invalid managed inference API base".to_string())?;
    if !matches!(url.scheme(), "http" | "https") || url.host_str().is_none() {
        return Err("invalid managed inference API base".into());
    }

    let authority = url.origin().ascii_serialization();
    Ok((authority.clone(), authority))
}

#[cfg(test)]
mod managed_route_provenance_tests {
    use super::{canonical_managed_route_provenance_id, redact_resolved_managed_api_base};
    use car_inference::openrouter::{
        canonical_managed_gateway_selector, curated_schemas, is_curated_managed_gateway_alias,
    };

    #[test]
    fn managed_route_provenance_redacts_the_runtime_resolved_base_without_refresh() {
        assert_eq!(
            redact_resolved_managed_api_base("https://persisted.example/").unwrap(),
            (
                "https://persisted.example".into(),
                "https://persisted.example".into()
            )
        );
    }

    #[test]
    fn managed_route_provenance_normalizes_and_redacts_url_components() {
        assert_eq!(
            redact_resolved_managed_api_base("HTTPS://Staging-Api.Example:443/").unwrap(),
            (
                "https://staging-api.example".into(),
                "https://staging-api.example".into()
            )
        );
        for (base, expected) in [
            ("https://gateway.example/prefix", "https://gateway.example"),
            (
                "https://user:sensitive@gateway.example/private?token=value#fragment",
                "https://gateway.example",
            ),
        ] {
            assert_eq!(
                redact_resolved_managed_api_base(base).unwrap(),
                (expected.into(), expected.into())
            );
        }
        for invalid in [
            "ftp://gateway.example",
            "mailto:ops@example.com",
            "https://",
        ] {
            let error = redact_resolved_managed_api_base(invalid).unwrap_err();
            assert_eq!(error, "invalid managed inference API base");
        }
    }

    #[test]
    fn managed_route_provenance_accepts_only_canonical_managed_aliases() {
        assert!(is_curated_managed_gateway_alias(
            "parslee/openrouter/frontier-general"
        ));
        assert!(!is_curated_managed_gateway_alias(
            "openrouter/openai/gpt-5.4"
        ));
        assert!(!is_curated_managed_gateway_alias("parslee/not-managed"));

        let schemas = curated_schemas();
        let managed = schemas
            .iter()
            .find(|schema| schema.id == "parslee/openrouter/frontier-general")
            .unwrap();
        assert_eq!(
            canonical_managed_gateway_selector(managed),
            Some("parslee/openrouter/frontier-general")
        );

        let personal = schemas
            .iter()
            .find(|schema| schema.id == "openrouter/openai/gpt-5.4")
            .unwrap();
        assert!(canonical_managed_gateway_selector(personal).is_none());

        let mut non_parslee = managed.clone();
        non_parslee.provider = "other".into();
        assert!(canonical_managed_gateway_selector(&non_parslee).is_none());

        let mut noncanonical_id = managed.clone();
        noncanonical_id.id = "parslee/not-managed".into();
        assert!(canonical_managed_gateway_selector(&noncanonical_id).is_none());
    }

    #[test]
    fn managed_route_provenance_uses_live_signed_transport_contract() {
        let mut signed_override = curated_schemas()
            .into_iter()
            .find(|schema| schema.id == "parslee/openrouter/frontier-general")
            .unwrap();
        signed_override.name = "signed-catalog-display-metadata-drift".into();
        assert_eq!(
            canonical_managed_route_provenance_id(&signed_override),
            Ok("parslee/openrouter/frontier-general")
        );

        signed_override.provider = "not-parslee".into();
        assert_eq!(
            canonical_managed_route_provenance_id(&signed_override).unwrap_err(),
            "models.route_provenance supports only canonical Parslee-managed OpenRouter aliases"
        );
    }
}

#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
struct ModelSearchParams {
    #[serde(default)]
    query: Option<String>,
    #[serde(default)]
    capability: Option<car_inference::ModelCapability>,
    #[serde(default)]
    provider: Option<String>,
    #[serde(default)]
    local_only: bool,
    #[serde(default)]
    available_only: bool,
    #[serde(default)]
    limit: Option<usize>,
}

#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
struct ModelSearchEntry {
    /// Carries `family` and `version` for EVERY row (the search view is the
    /// documented place that names an alias's upstream family), where the
    /// flattened `ModelInfo` publishes them for local rows only. The search
    /// handler overwrites both on the info before wrapping it.
    #[serde(flatten)]
    info: car_inference::ModelInfo,
    tags: Vec<String>,
    pullable: bool,
    upgrade: Option<car_inference::ModelUpgrade>,
}

#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
struct ModelSearchResponse {
    models: Vec<ModelSearchEntry>,
    upgrades: Vec<car_inference::ModelUpgrade>,
    total: usize,
    available: usize,
    local: usize,
    remote: usize,
}

async fn handle_models_search(req: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let params: ModelSearchParams =
        serde_json::from_value(req.params.clone()).unwrap_or(ModelSearchParams {
            query: None,
            capability: None,
            provider: None,
            local_only: false,
            available_only: false,
            limit: None,
        });
    let engine = get_inference_engine(state);
    let upgrades = engine.available_model_upgrades();
    let upgrades_by_from: HashMap<String, car_inference::ModelUpgrade> = upgrades
        .iter()
        .cloned()
        .map(|upgrade| (upgrade.from_id.clone(), upgrade))
        .collect();
    let query = params
        .query
        .as_deref()
        .map(str::trim)
        .filter(|q| !q.is_empty())
        .map(|q| q.to_ascii_lowercase());
    let provider = params
        .provider
        .as_deref()
        .map(str::trim)
        .filter(|p| !p.is_empty())
        .map(|p| p.to_ascii_lowercase());

    let mut entries: Vec<ModelSearchEntry> = engine
        .list_schemas()
        .into_iter()
        .filter(|schema| {
            if let Some(capability) = params.capability {
                if !schema.has_capability(capability) {
                    return false;
                }
            }
            if let Some(provider) = provider.as_deref() {
                if schema.provider.to_ascii_lowercase() != provider {
                    return false;
                }
            }
            if params.local_only && !schema.is_local() {
                return false;
            }
            if params.available_only && !schema.available {
                return false;
            }
            if let Some(query) = query.as_deref() {
                let capability_text = schema
                    .capabilities
                    .iter()
                    .map(|cap| format!("{cap:?}").to_ascii_lowercase())
                    .collect::<Vec<_>>()
                    .join(" ");
                let haystack = format!(
                    "{} {} {} {} {} {}",
                    schema.id,
                    schema.name,
                    schema.provider,
                    schema.family,
                    schema.tags.join(" "),
                    capability_text
                )
                .to_ascii_lowercase();
                if !haystack.contains(query) {
                    return false;
                }
            }
            true
        })
        .map(|schema| {
            let pullable = model_is_pullable(&schema);
            let mut info =
                car_inference::ModelInfo::from(&schema).with_fit(engine.model_fit(&schema));
            info.family = Some(schema.family);
            info.version = Some(schema.version);
            let upgrade = upgrades_by_from.get(&schema.id).cloned();
            ModelSearchEntry {
                info,
                tags: schema.tags,
                pullable,
                upgrade,
            }
        })
        .collect();
    entries.sort_by(|a, b| {
        b.info
            .available
            .cmp(&a.info.available)
            .then(b.info.is_local.cmp(&a.info.is_local))
            .then(a.info.name.cmp(&b.info.name))
    });
    if let Some(limit) = params.limit {
        entries.truncate(limit);
    }

    let total = entries.len();
    let available = entries.iter().filter(|entry| entry.info.available).count();
    let local = entries.iter().filter(|entry| entry.info.is_local).count();
    let response = ModelSearchResponse {
        models: entries,
        upgrades,
        total,
        available,
        local,
        remote: total.saturating_sub(local),
    };
    serde_json::to_value(response).map_err(|e| e.to_string())
}

fn model_is_pullable(schema: &car_inference::ModelSchema) -> bool {
    schema.downloads_weights() && !schema.weights_ready
}

/// Parse an optional serde enum param: absent/null → `None` (caller defaults);
/// present-but-unparseable → a clear invalid-params error rather than a silent
/// fallback, so a host app learns it sent a bad value.
fn optional_enum_param<T: serde::de::DeserializeOwned>(
    req: &JsonRpcMessage,
    key: &str,
) -> Result<Option<T>, String> {
    match req.params.get(key) {
        None | Some(Value::Null) => Ok(None),
        Some(v) => serde_json::from_value(v.clone())
            .map(Some)
            .map_err(|_| format!("invalid '{key}': {v}")),
    }
}

/// Parse `use_case`/`tier`/`cloud_ok` from JSON-RPC params and run the
/// recommender. `HardwareInfo::detect()` runs per call — acceptable because
/// recommend/setup_plan are onboarding-frequency (not the inference hot path),
/// and detection is a couple of cheap, non-blocking system probes.
fn recommend_from_params(
    req: &JsonRpcMessage,
    engine: &car_inference::InferenceEngine,
) -> Result<car_inference::RecommendationSet, String> {
    let hw = car_inference::HardwareInfo::detect();
    recommend_from_params_with_hardware(req, engine, &hw)
}

fn recommend_from_params_with_hardware(
    req: &JsonRpcMessage,
    engine: &car_inference::InferenceEngine,
    hw: &car_inference::HardwareInfo,
) -> Result<car_inference::RecommendationSet, String> {
    let schemas = engine.list_schemas();
    let policy = engine.active_local_resource_policy();
    recommend_from_params_with_policy(req, &schemas, hw, &policy.policy, policy.warning)
}

/// Dependency-injected core for recommendation-policy fallback tests. Keeping
/// hardware, registry rows, and policy storage explicit makes corrupt/missing
/// file behavior testable without touching a developer's machine state.
#[cfg(test)]
fn recommend_from_params_with_inputs(
    req: &JsonRpcMessage,
    schemas: &[car_inference::ModelSchema],
    hw: &car_inference::HardwareInfo,
    policy_repository: &car_inference::FileResourcePolicyRepository,
) -> Result<car_inference::RecommendationSet, String> {
    let (policy, _, warning) = load_recommendation_policy(policy_repository);
    recommend_from_params_with_policy(req, schemas, hw, &policy, warning)
}

#[cfg(test)]
fn load_recommendation_policy(
    policy_repository: &car_inference::FileResourcePolicyRepository,
) -> (
    car_inference::ResourcePolicy,
    car_inference::ResourcePolicyLoadSource,
    Option<String>,
) {
    match policy_repository.load_with_evidence() {
        Ok(evidence) => (evidence.policy, evidence.source, evidence.warning),
        Err(error) => (
            car_inference::ResourcePolicy::everyday(),
            car_inference::ResourcePolicyLoadSource::CorruptDefault,
            Some(format!(
                "The local-model resource policy could not be read ({error}); CAR used Everyday."
            )),
        ),
    }
}

fn recommend_from_params_with_policy(
    req: &JsonRpcMessage,
    schemas: &[car_inference::ModelSchema],
    hw: &car_inference::HardwareInfo,
    policy: &car_inference::ResourcePolicy,
    warning: Option<String>,
) -> Result<car_inference::RecommendationSet, String> {
    let use_case =
        optional_enum_param::<car_inference::UseCase>(req, "use_case")?.unwrap_or_default();
    let tier = optional_enum_param::<car_inference::QualityTier>(req, "tier")?.unwrap_or_default();
    let privacy = if req
        .params
        .get("cloud_ok")
        .and_then(|v| v.as_bool())
        .unwrap_or(false)
    {
        car_inference::Privacy::CloudOk
    } else {
        car_inference::Privacy::OnDevice
    };
    let refs: Vec<&car_inference::ModelSchema> = schemas.iter().collect();
    let mut set = car_inference::recommend_with_policy(&refs, hw, policy, use_case, tier, privacy);
    if let Some(warning) = warning {
        set.note = Some(match set.note.take() {
            Some(note) => format!("Resource policy warning: {warning} {note}"),
            None => format!("Resource policy warning: {warning}"),
        });
    }
    Ok(set)
}

/// `models.recommend` — ranked, explained model picks for this machine + intent.
fn handle_models_recommend(req: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    let set = recommend_from_params(req, engine)?;
    serde_json::to_value(set).map_err(|e| e.to_string())
}

/// `models.setup_plan` — a concrete onboarding plan the host/SDK can present:
/// machine description, the top pick, alternatives, and what needs more memory.
fn handle_models_setup_plan(req: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    let hw = car_inference::HardwareInfo::detect();
    let schemas = engine.list_schemas();
    let policy = engine.active_local_resource_policy();
    setup_plan_from_params_with_policy_inputs(
        req,
        &schemas,
        &hw,
        &policy.policy,
        policy.source,
        policy.warning,
    )
}

#[cfg(test)]
fn setup_plan_from_params_with_inputs(
    req: &JsonRpcMessage,
    schemas: &[car_inference::ModelSchema],
    hw: &car_inference::HardwareInfo,
    policy_repository: &car_inference::FileResourcePolicyRepository,
) -> Result<Value, String> {
    let (policy, source, warning) = load_recommendation_policy(policy_repository);
    setup_plan_from_params_with_policy_inputs(req, schemas, hw, &policy, source, warning)
}

fn setup_plan_from_params_with_policy_inputs(
    req: &JsonRpcMessage,
    schemas: &[car_inference::ModelSchema],
    hw: &car_inference::HardwareInfo,
    active_policy: &car_inference::ResourcePolicy,
    active_policy_source: car_inference::ResourcePolicyLoadSource,
    active_policy_warning: Option<String>,
) -> Result<Value, String> {
    let preview_policy = match req.params.get("resource_policy") {
        None => None,
        Some(value) => {
            let policy: car_inference::ResourcePolicy = serde_json::from_value(value.clone())
                .map_err(|error| format!("invalid 'resource_policy': {error}"))?;
            policy
                .validate()
                .map_err(|error| format!("invalid 'resource_policy': {error}"))?;
            Some(policy)
        }
    };
    let (policy, policy_source, warning) = match preview_policy {
        Some(policy) => (policy, serde_json::json!("preview"), None),
        None => (
            active_policy.clone(),
            serde_json::json!(active_policy_source),
            active_policy_warning,
        ),
    };
    let evaluated_budget = policy.effective_budget(hw.total_ram_mb);
    let mut set = recommend_from_params_with_policy(req, schemas, hw, &policy, warning)?;
    let (recommended, alternatives) = split_setup_recommendations(set.picks);
    if recommended.is_none() {
        let notice = "No model is within CAR's automatic recommendation target; heavier or unknown-memory alternatives require an explicit choice.";
        set.note = Some(match set.note.take() {
            Some(note) => format!("{note} {notice}"),
            None => notice.into(),
        });
    }
    serde_json::to_value(serde_json::json!({
        "machine": describe_machine_for_plan(hw),
        "recommended": recommended,
        "alternatives": alternatives,
        "needs_more_memory": set.not_enough_memory,
        "note": set.note,
        "resource_policy": policy,
        "evaluated_budget": evaluated_budget,
        "policy_source": policy_source,
    }))
    .map_err(|e| e.to_string())
}

fn split_setup_recommendations(
    mut picks: Vec<car_inference::Recommendation>,
) -> (
    Option<car_inference::Recommendation>,
    Vec<car_inference::Recommendation>,
) {
    let recommended_index = picks
        .iter()
        .position(|pick| pick.within_recommendation_target);
    let recommended = recommended_index.map(|index| picks.remove(index));
    (recommended, picks)
}

/// Plain-language one-liner about the host machine for setup plans.
fn describe_machine_for_plan(hw: &car_inference::HardwareInfo) -> String {
    use car_inference::hardware::SupportedAcceleration::*;
    match hw.supported_acceleration() {
        Apple { unified_memory_mb } => format!(
            "Apple Silicon, {} GB unified memory (Metal)",
            unified_memory_mb / 1024
        ),
        Cuda { device_memory_mb } => match device_memory_mb {
            Some(mb) => format!("NVIDIA GPU, {} GB VRAM (CUDA)", mb / 1024),
            None => "NVIDIA GPU (CUDA)".to_string(),
        },
        UnsupportedDiscreteGpu { name, .. } => format!(
            "{} GB RAM, CPU inference ({name} not yet supported)",
            hw.total_ram_mb / 1024
        ),
        Cpu => format!("{} GB RAM, CPU inference", hw.total_ram_mb / 1024),
    }
}

#[cfg(test)]
mod model_resource_policy_recommendation_tests {
    use super::{
        model_is_pullable, recommend_from_params_with_inputs, setup_plan_from_params_with_inputs,
        split_setup_recommendations, JsonRpcMessage,
    };
    use car_inference::hardware::GpuBackend;
    use car_inference::{
        FileResourcePolicyRepository, HardwareInfo, ModelSchema, ResourcePolicy,
        ResourcePolicyRepository,
    };
    use serde_json::json;

    fn request() -> JsonRpcMessage {
        JsonRpcMessage {
            jsonrpc: "2.0".into(),
            method: Some("models.recommend".into()),
            params: json!({"use_case": "assistant", "tier": "balanced"}),
            id: json!(1),
            result: None,
            error: None,
        }
    }

    fn mac_32gb() -> HardwareInfo {
        HardwareInfo {
            os: "macos".into(),
            arch: "aarch64".into(),
            cpu_cores: 10,
            total_ram_mb: 32 * 1024,
            gpu_backend: GpuBackend::Metal,
            gpu_memory_mb: None,
            gpu_devices: vec![],
            recommended_model: String::new(),
            recommended_context: 8_192,
            max_model_mb: 0,
        }
    }

    fn setup_schemas(home: &tempfile::TempDir) -> Vec<ModelSchema> {
        let models_dir = home.path().join("weights");
        let huggingface_hub_root = home.path().join("huggingface-hub");
        std::fs::create_dir_all(&huggingface_hub_root).unwrap();
        car_inference::registry::builtin_catalog_with_huggingface_hub_for_testing(
            &models_dir,
            &huggingface_hub_root,
        )
        .into_iter()
        .filter(|model| matches!(model.id.as_str(), "mlx/qwen3-4b:4bit" | "mlx/qwen3-8b:4bit"))
        .collect()
    }

    fn setup_request(params: serde_json::Value) -> JsonRpcMessage {
        JsonRpcMessage {
            jsonrpc: "2.0".into(),
            method: Some("models.setup_plan".into()),
            params,
            id: json!(1),
            result: None,
            error: None,
        }
    }

    #[test]
    fn setup_plan_preview_custom_zero_changes_eligibility_without_persisting() {
        let home = tempfile::tempdir().unwrap();
        let repository = FileResourcePolicyRepository::new(home.path().to_path_buf());
        repository.save(&ResourcePolicy::everyday()).unwrap();
        let policy_path = repository.path();
        let saved_bytes = std::fs::read(&policy_path).unwrap();
        let schemas = setup_schemas(&home);

        // The preview core intentionally has no engine/mutation dependency.
        let preview = setup_plan_from_params_with_inputs(
            &setup_request(json!({
                "use_case": "assistant",
                "tier": "balanced",
                "resource_policy": {
                    "profile": "custom",
                    "custom_max_model_mb": 0
                }
            })),
            &schemas,
            &mac_32gb(),
            &repository,
        )
        .unwrap();

        assert_eq!(preview["resource_policy"]["profile"], "custom");
        assert_eq!(preview["resource_policy"]["custom_max_model_mb"], 0);
        assert_eq!(
            preview["evaluated_budget"]["configured_model_ceiling_mb"],
            0
        );
        assert_eq!(
            preview["evaluated_budget"]["effective_new_load_ceiling_mb"],
            0
        );
        assert_eq!(preview["policy_source"], "preview");
        assert!(preview["recommended"].is_null());
        assert_eq!(preview["alternatives"].as_array().unwrap().len(), 0);
        assert_eq!(preview["needs_more_memory"].as_array().unwrap().len(), 2);

        assert_eq!(std::fs::read(&policy_path).unwrap(), saved_bytes);
        let fresh_repository = FileResourcePolicyRepository::new(home.path().to_path_buf());
        assert_eq!(fresh_repository.load().unwrap(), ResourcePolicy::everyday());

        let persisted = setup_plan_from_params_with_inputs(
            &setup_request(json!({"use_case":"assistant","tier":"balanced"})),
            &schemas,
            &mac_32gb(),
            &fresh_repository,
        )
        .unwrap();
        assert_eq!(persisted["policy_source"], "loaded");
        assert_eq!(persisted["resource_policy"]["profile"], "everyday");
        assert_eq!(persisted["recommended"]["model_id"], "mlx/qwen3-4b:4bit");
        assert!(persisted["alternatives"]
            .as_array()
            .unwrap()
            .iter()
            .any(|pick| pick["model_id"] == "mlx/qwen3-8b:4bit"));
    }

    #[test]
    fn setup_plan_preview_preserves_exact_custom_ten_and_a_half_gb() {
        let home = tempfile::tempdir().unwrap();
        let repository = FileResourcePolicyRepository::new(home.path().to_path_buf());
        repository.save(&ResourcePolicy::everyday()).unwrap();

        let plan = setup_plan_from_params_with_inputs(
            &setup_request(json!({
                "resource_policy": {
                    "profile": "custom",
                    "custom_max_model_mb": 10_752
                }
            })),
            &setup_schemas(&home),
            &mac_32gb(),
            &repository,
        )
        .unwrap();

        assert_eq!(plan["resource_policy"]["custom_max_model_mb"], 10_752);
        assert_eq!(
            plan["evaluated_budget"]["configured_model_ceiling_mb"],
            10_752
        );
        assert_eq!(
            plan["evaluated_budget"]["effective_new_load_ceiling_mb"],
            10_752
        );
        assert_eq!(repository.load().unwrap(), ResourcePolicy::everyday());
    }

    #[test]
    fn setup_plan_preview_rejects_invalid_policy_shapes() {
        let home = tempfile::tempdir().unwrap();
        let repository = FileResourcePolicyRepository::new(home.path().to_path_buf());
        let schemas = setup_schemas(&home);
        let invalid = [
            json!({"profile":"custom","custom_max_model_mb":10_752,"unknown":true}),
            json!({"profile":"custom"}),
            json!({"profile":"everyday","custom_max_model_mb":512}),
            json!({"profile":"custom","custom_max_model_mb":10_547}),
            json!({"profile":"custom","custom_max_model_mb":-512}),
            json!({"profile":"custom","custom_max_model_mb":10_752.0}),
            serde_json::Value::Null,
            json!("custom"),
            json!([]),
            json!(true),
        ];

        for resource_policy in invalid {
            let error = setup_plan_from_params_with_inputs(
                &setup_request(json!({"resource_policy": resource_policy.clone()})),
                &schemas,
                &mac_32gb(),
                &repository,
            )
            .expect_err(&format!(
                "invalid preview must fail closed: {resource_policy}"
            ));
            assert!(
                error.contains("invalid 'resource_policy'"),
                "unexpected error for {resource_policy}: {error}"
            );
        }
    }

    #[test]
    fn setup_plan_without_preview_keeps_corrupt_policy_warning_and_everyday_fallback() {
        let home = tempfile::tempdir().unwrap();
        std::fs::write(home.path().join("model-resource-policy.json"), b"not-json").unwrap();
        let repository = FileResourcePolicyRepository::new(home.path().to_path_buf());

        let plan = setup_plan_from_params_with_inputs(
            &setup_request(json!({})),
            &setup_schemas(&home),
            &mac_32gb(),
            &repository,
        )
        .unwrap();

        assert_eq!(plan["policy_source"], "corrupt_default");
        assert_eq!(
            plan["resource_policy"],
            json!({
                "profile": "everyday",
                "custom_max_model_mb": null
            })
        );
        assert_eq!(
            plan["evaluated_budget"]["configured_model_ceiling_mb"],
            13_107
        );
        assert!(plan["note"]
            .as_str()
            .is_some_and(|note| note.contains("saved resource policy could not be loaded")));
    }

    #[test]
    fn isolated_car_home_everyday_policy_recommends_real_4b_and_keeps_8b_heavier() {
        let home = tempfile::tempdir().unwrap();
        let schemas = setup_schemas(&home);
        assert_eq!(schemas.len(), 2, "real built-in 4B/8B rows must exist");

        let set = recommend_from_params_with_inputs(
            &request(),
            &schemas,
            &mac_32gb(),
            &FileResourcePolicyRepository::new(home.path().to_path_buf()),
        )
        .unwrap();

        assert_eq!(set.picks[0].model_id, "mlx/qwen3-4b:4bit");
        assert!(set.picks[0].within_recommendation_target);
        let eight = set
            .picks
            .iter()
            .find(|pick| pick.model_id == "mlx/qwen3-8b:4bit")
            .expect("8B remains visible as a heavier alternative");
        assert_eq!(eight.display_name, "Qwen3-8B-MLX");
        let mut over_target = eight.clone();
        over_target.within_recommendation_target = false;
        let (automatic, visible) = split_setup_recommendations(vec![over_target]);
        assert!(automatic.is_none());
        assert_eq!(visible.len(), 1);

        let (recommended, alternatives) = split_setup_recommendations(set.picks);
        assert_eq!(recommended.unwrap().model_id, "mlx/qwen3-4b:4bit");
        assert!(alternatives
            .iter()
            .any(|pick| pick.model_id == "mlx/qwen3-8b:4bit"));
    }

    #[test]
    fn corrupt_policy_is_visible_in_recommendation_notice() {
        let home = tempfile::tempdir().unwrap();
        std::fs::write(home.path().join("model-resource-policy.json"), b"not-json").unwrap();
        let schemas: Vec<ModelSchema> = setup_schemas(&home)
            .into_iter()
            .filter(|model| model.id == "mlx/qwen3-4b:4bit")
            .collect();

        let set = recommend_from_params_with_inputs(
            &request(),
            &schemas,
            &mac_32gb(),
            &FileResourcePolicyRepository::new(home.path().to_path_buf()),
        )
        .unwrap();
        assert!(
            set.note
                .as_deref()
                .is_some_and(|note| note.contains("saved resource policy could not be loaded")),
            "corrupt policy recovery must remain visible: {:?}",
            set.note
        );
    }

    #[test]
    fn routable_mlx_model_without_weights_remains_pullable() {
        let home = tempfile::tempdir().unwrap();
        let mut schema = setup_schemas(&home)
            .into_iter()
            .find(|model| model.id == "mlx/qwen3-4b:4bit")
            .expect("built-in 4B MLX row from an explicit empty test hub");
        // Exercise the routable-but-not-downloaded lifecycle on every test
        // platform instead of assuming the runner itself supports MLX or has
        // no shared Hugging Face snapshot outside this temporary state root.
        schema.available = true;
        schema.weights_ready = false;

        assert!(schema.available, "the MLX runtime is routable on this host");
        assert!(
            !schema.weights_ready,
            "fresh test root has no model weights"
        );
        assert!(model_is_pullable(&schema));
    }
}

fn handle_models_upgrades(state: &ServerState) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    serde_json::to_value(serde_json::json!({
        "upgrades": engine.available_model_upgrades()
    }))
    .map_err(|e| e.to_string())
}

/// `models.detect_upgrades` — curated + upstream-aware findings (channel-gated,
/// cached, offline-safe).
async fn handle_models_detect_upgrades(state: &ServerState) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    let findings = engine.detect_upgrades().await;
    serde_json::to_value(serde_json::json!({ "upgrades": findings })).map_err(|e| e.to_string())
}

/// `models.check_upgrade_nudge` — the current nudge decision (poll form). The
/// daemon also pushes `models.upgrade_available` proactively; this lets a
/// client ask on demand. `inference_active` defaults to false.
async fn handle_models_check_upgrade_nudge(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    let inference_active = req
        .params
        .get("inference_active")
        .and_then(|v| v.as_bool())
        .unwrap_or(false);
    let (decision, _state) = engine.check_upgrade_nudge(inference_active).await;
    serde_json::to_value(decision).map_err(|e| e.to_string())
}

/// `models.dismiss_upgrade` — remember that the user waved away a nudge.
fn handle_models_dismiss_upgrade(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let key = req
        .params
        .get("dismiss_key")
        .and_then(|v| v.as_str())
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .ok_or("missing or empty 'dismiss_key' parameter")?;
    let engine = get_inference_engine(state);
    engine
        .dismiss_upgrade_nudge(key)
        .map_err(|e| e.to_string())?;
    Ok(serde_json::json!({ "dismissed": key }))
}

/// `models.check_concierge` — the current concierge suggestions (poll form).
/// The daemon also pushes `models.suggestion_available` proactively; this lets
/// a client ask on demand. `inference_active` defaults to false.
async fn handle_models_check_concierge(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    let inference_active = req
        .params
        .get("inference_active")
        .and_then(|v| v.as_bool())
        .unwrap_or(false);
    let (suggestions, _state) = engine.check_concierge(inference_active).await;
    serde_json::to_value(serde_json::json!({ "suggestions": suggestions }))
        .map_err(|e| e.to_string())
}

/// `models.dismiss_suggestion` — remember that the user waved away a concierge
/// suggestion, so it is never surfaced again.
fn handle_models_dismiss_suggestion(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let key = req
        .params
        .get("dismiss_key")
        .and_then(|v| v.as_str())
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .ok_or("missing or empty 'dismiss_key' parameter")?;
    let engine = get_inference_engine(state);
    engine
        .dismiss_concierge_suggestion(key)
        .map_err(|e| e.to_string())?;
    Ok(serde_json::json!({ "dismissed": key }))
}

/// `concierge.status` — the ambient concierge view (Phase C1): per-lane
/// usage + friction, the current grounded decision (Observe or
/// Act+suggestion), and per-model health. Pull, not push.
async fn handle_concierge_status(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    // Don't let a status pull surface a proactive Act while the user is
    // mid-inference — mirror the proactive path's defer.
    let inference_active = req
        .params
        .get("inference_active")
        .and_then(|v| v.as_bool())
        .unwrap_or_else(|| state.admission.in_flight() > 0);
    let status = engine.concierge_status(inference_active).await;
    serde_json::to_value(status).map_err(|e| e.to_string())
}

/// `concierge.dismiss` — record a *labeled* dismissal (Phase B4/C1):
/// `{ dismiss_key, reason }` where reason is one of not_now / wrong /
/// too_expensive / privacy / never_for_project. Permanent reasons
/// suppress the suggestion forever; not_now only cools it down.
fn handle_concierge_dismiss(req: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let key = req
        .params
        .get("dismiss_key")
        .and_then(|v| v.as_str())
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .ok_or("missing or empty 'dismiss_key' parameter")?;
    let reason: car_inference::DismissReason = req
        .params
        .get("reason")
        .cloned()
        .map(serde_json::from_value)
        .transpose()
        .map_err(|e| format!("invalid 'reason': {e}"))?
        .unwrap_or(car_inference::DismissReason::NotNow);
    let engine = get_inference_engine(state);
    engine.dismiss_concierge_labeled(key, reason)?;
    Ok(serde_json::json!({ "dismissed": key, "reason": reason }))
}

/// `concierge.defaults` — all configured lane→model defaults (Phase D1).
fn handle_concierge_defaults(state: &ServerState) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    serde_json::to_value(engine.lane_defaults()).map_err(|e| e.to_string())
}

/// `concierge.set_default { use_case, model_id, project? }` — set the
/// default model for a lane (Phase D1). `use_case` is the snake_case
/// lane name (assistant/coding/…).
async fn handle_concierge_set_default(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let use_case: car_inference::UseCase = req
        .params
        .get("use_case")
        .cloned()
        .map(serde_json::from_value)
        .transpose()
        .map_err(|e| format!("invalid 'use_case': {e}"))?
        .ok_or("missing 'use_case'")?;
    let model_id = req
        .params
        .get("model_id")
        .and_then(|v| v.as_str())
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .ok_or("missing or empty 'model_id'")?;
    let project = req
        .params
        .get("project")
        .and_then(|v| v.as_str())
        .map(str::to_string);
    let engine = get_inference_engine(state);
    engine
        .user_set_lane_default(use_case, model_id, project)
        .await?;
    Ok(serde_json::json!({ "set": model_id, "use_case": use_case }))
}

/// `concierge.clear_default { use_case, project? }` — remove a lane
/// default (Phase D1; also the rollback path in D3).
async fn handle_concierge_clear_default(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let use_case: car_inference::UseCase = req
        .params
        .get("use_case")
        .cloned()
        .map(serde_json::from_value)
        .transpose()
        .map_err(|e| format!("invalid 'use_case': {e}"))?
        .ok_or("missing 'use_case'")?;
    let project = req
        .params
        .get("project")
        .and_then(|v| v.as_str())
        .map(str::to_string);
    let engine = get_inference_engine(state);
    let removed = engine.user_clear_lane_default(use_case, project).await?;
    Ok(serde_json::json!({ "cleared": removed }))
}

/// `concierge.apply { use_case, model_id, project? }` — closed-loop
/// "set it up" (Phase D3): acquire the model + set it as the lane
/// default, capturing the prior default so it's reversible. User-
/// consented (this is a direct user action).
async fn handle_concierge_apply(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let use_case: car_inference::UseCase = req
        .params
        .get("use_case")
        .cloned()
        .map(serde_json::from_value)
        .transpose()
        .map_err(|e| format!("invalid 'use_case': {e}"))?
        .ok_or("missing 'use_case'")?;
    let model_id = req
        .params
        .get("model_id")
        .and_then(|v| v.as_str())
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .ok_or("missing or empty 'model_id'")?;
    let project = req
        .params
        .get("project")
        .and_then(|v| v.as_str())
        .map(str::to_string);
    let engine = get_inference_engine(state);
    let result = engine.apply_concierge(use_case, model_id, project).await?;
    serde_json::to_value(result).map_err(|e| e.to_string())
}

/// `concierge.rollback { use_case, project? }` — revert a lane default to
/// its value before the last `apply` (Phase D3).
async fn handle_concierge_rollback(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let use_case: car_inference::UseCase = req
        .params
        .get("use_case")
        .cloned()
        .map(serde_json::from_value)
        .transpose()
        .map_err(|e| format!("invalid 'use_case': {e}"))?
        .ok_or("missing 'use_case'")?;
    let project = req
        .params
        .get("project")
        .and_then(|v| v.as_str())
        .map(str::to_string);
    let engine = get_inference_engine(state);
    let restored = engine.rollback_lane(use_case, project).await?;
    Ok(serde_json::json!({ "restored": restored }))
}

/// `concierge.actions { limit? }` — the audit log of consented concierge
/// actions (Phase D2), most recent last.
fn handle_concierge_actions(req: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let limit = req
        .params
        .get("limit")
        .and_then(|v| v.as_u64())
        .unwrap_or(50) as usize;
    let engine = get_inference_engine(state);
    serde_json::to_value(serde_json::json!({ "actions": engine.concierge_actions(limit) }))
        .map_err(|e| e.to_string())
}

/// `concierge.refresh_catalog` — fetch + verify the signed model catalog
/// from the configured source (Phase E1). New models apply at next
/// daemon start (the registry is immutable at runtime).
async fn handle_concierge_refresh_catalog(state: &ServerState) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    let count = engine.refresh_catalog().await?;
    Ok(serde_json::json!({
        "refreshed": count,
        "note": "verified catalog cached; new models apply on next daemon restart"
    }))
}

/// `concierge.ask { question }` — conversational concierge (Phase
/// F1/F2): a grounded, ledger-backed answer about the user's models. The
/// LLM explains only from the assembled evidence; it can't invent models
/// or assert fit.
async fn handle_concierge_ask(req: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let question = req
        .params
        .get("question")
        .and_then(|v| v.as_str())
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .ok_or("missing or empty 'question'")?;
    let engine = get_inference_engine(state);
    let answer = engine.concierge_ask(question).await?;
    Ok(serde_json::json!({ "answer": answer }))
}

/// `models.update_prefs_get` — current update preferences.
fn handle_models_update_prefs_get(state: &ServerState) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    serde_json::to_value(engine.update_prefs()).map_err(|e| e.to_string())
}

/// `models.update_prefs_set` — replace update preferences. Params are the
/// `UpdatePreferences` shape (all fields optional; missing → defaults).
fn handle_models_update_prefs_set(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let prefs: car_inference::UpdatePreferences = serde_json::from_value(req.params.clone())
        .map_err(|e| format!("invalid preferences: {e}"))?;
    let engine = get_inference_engine(state);
    engine.set_update_prefs(&prefs).map_err(|e| e.to_string())?;
    serde_json::to_value(prefs).map_err(|e| e.to_string())
}

/// Run one proactive upgrade check and push a `models.upgrade_available`
/// nudge to subscribers if warranted. Stamps `last_nudge_secs` after sending
/// so the per-day throttle holds across ticks. The daemon calls this on a
/// periodic timer; the nudge logic itself decides whether to actually surface
/// anything (policy/throttle/dismissals).
pub async fn run_upgrade_nudge_check(state: &Arc<ServerState>) {
    let engine = get_inference_engine(state);
    // Defer the nudge if any inference is in flight (held admission permits) —
    // the real "machine is busy" signal, not a guess.
    let inference_active = state.admission.in_flight() > 0;
    let (decision, mut nstate) = engine.check_upgrade_nudge(inference_active).await;
    if let Some(nudge) = decision.nudge {
        let delivered = broadcast_upgrade_nudge(state, &nudge).await;
        // Only burn the once-per-day throttle when the nudge actually reached
        // someone — otherwise a nudge fired with no UI connected would silence
        // the user for a day without them ever seeing it.
        if delivered > 0 {
            let now = std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map(|d| d.as_secs())
                .unwrap_or(0);
            nstate.last_nudge_secs = now;
            let _ = nstate.save_to(&car_inference::NudgeState::default_path());
        }
    }
}

/// Push a `models.upgrade_available` notification to all subscribed UI clients,
/// returning how many it reached. Targets the same subscriber set the macOS
/// host already uses for pushed events (`a2ui_subscribers`) — the UI-push
/// channel — rather than standing up a parallel subscription. Mirrors
/// [`broadcast_a2ui_event`].
pub async fn broadcast_upgrade_nudge(
    state: &Arc<ServerState>,
    nudge: &car_inference::UpgradeNudge,
) -> usize {
    use futures::SinkExt;
    use tokio_tungstenite::tungstenite::Message;
    let subscribers: Vec<Arc<crate::session::WsChannel>> = state
        .a2ui_subscribers
        .lock()
        .await
        .values()
        .cloned()
        .collect();
    if subscribers.is_empty() {
        return 0;
    }
    let Ok(json) = serde_json::to_string(&serde_json::json!({
        "jsonrpc": "2.0",
        "method": "models.upgrade_available",
        "params": nudge,
    })) else {
        return 0;
    };
    let mut delivered = 0;
    for channel in subscribers {
        if channel
            .write
            .lock()
            .await
            .send(Message::Text(json.clone().into()))
            .await
            .is_ok()
        {
            delivered += 1;
        }
    }
    delivered
}

/// Run one proactive concierge check and push a `models.suggestion_available`
/// notification per unserved lane to subscribers. Stamps `last_concierge_secs`
/// after sending so the throttle holds across ticks. Mirrors
/// [`run_upgrade_nudge_check`] but on the concierge's independent cadence and
/// throttle field, so the two never starve each other.
pub async fn run_concierge_check(state: &Arc<ServerState>) {
    let engine = get_inference_engine(state);
    let inference_active = state.admission.in_flight() > 0;
    let (suggestions, mut nstate) = engine.check_concierge(inference_active).await;
    if suggestions.is_empty() {
        return;
    }
    let mut any_delivered = false;
    for suggestion in &suggestions {
        if broadcast_concierge_suggestion(state, suggestion).await > 0 {
            any_delivered = true;
        }
    }
    // Only burn the throttle when a suggestion actually reached someone —
    // otherwise a check that fired with no UI connected would silence the user
    // for a week without them ever seeing it.
    if any_delivered {
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_secs())
            .unwrap_or(0);
        nstate.last_concierge_secs = now;
        let _ = nstate.save_to(&car_inference::NudgeState::default_path());
    }
}

/// One pass of idle model-backend eviction. A long-running daemon under
/// the default 24 GB cache budget pins loaded model weights resident
/// forever — capacity eviction never fires below the cap — so RSS climbs
/// to a model's working set and never drops at idle (car-releases#67).
/// This sweeps backends untouched for `CAR_INFERENCE_MODEL_IDLE_SECS`
/// (default 300) out of the caches; their RAM is reclaimed once any
/// outstanding handles drop, which at idle is immediate.
///
/// Only sweeps if the engine has already been created — it never forces
/// lazy engine init just to sweep an empty cache. Meant to be driven on a
/// timer by the daemon.
pub async fn run_idle_backend_eviction(state: &Arc<ServerState>) {
    let Some(engine) = state.inference.get() else {
        return;
    };
    let (entries, bytes) = engine.evict_idle_backends();
    if entries > 0 {
        tracing::info!(
            entries,
            mb = bytes / (1024 * 1024),
            "evicted idle model backends; resident model memory released"
        );
    }
    // Supervised vllm-mlx server processes are managed alongside the in-process
    // backends: stop the ones idle past their TTL so a server-backed model
    // doesn't pin the GPU after use.
    let stopped = engine.evict_idle_vllm_servers().await;
    if stopped > 0 {
        tracing::info!(stopped, "stopped idle vllm-mlx servers");
    }
}

/// Push a `models.suggestion_available` notification to subscribed UI clients,
/// returning how many it reached. Targets the same `a2ui_subscribers` UI-push
/// channel as [`broadcast_upgrade_nudge`].
pub async fn broadcast_concierge_suggestion(
    state: &Arc<ServerState>,
    suggestion: &car_inference::ConciergeSuggestion,
) -> usize {
    use futures::SinkExt;
    use tokio_tungstenite::tungstenite::Message;
    let subscribers: Vec<Arc<crate::session::WsChannel>> = state
        .a2ui_subscribers
        .lock()
        .await
        .values()
        .cloned()
        .collect();
    if subscribers.is_empty() {
        return 0;
    }
    let Ok(json) = serde_json::to_string(&serde_json::json!({
        "jsonrpc": "2.0",
        "method": "models.suggestion_available",
        "params": suggestion,
    })) else {
        return 0;
    };
    let mut delivered = 0;
    for channel in subscribers {
        if channel
            .write
            .lock()
            .await
            .send(Message::Text(json.clone().into()))
            .await
            .is_ok()
        {
            delivered += 1;
        }
    }
    delivered
}

/// Bridges the (sync) download progress sink to async WS broadcasts: each
/// `DownloadEvent` is pushed onto an unbounded channel that a concurrent task
/// drains and broadcasts as `models.pull_progress`.
struct PullProgressSink {
    tx: tokio::sync::mpsc::UnboundedSender<car_inference::DownloadEvent>,
}

impl car_inference::DownloadProgress for PullProgressSink {
    fn on_event(&self, event: &car_inference::DownloadEvent) {
        // Unbounded send from a sync context; ignore if the receiver is gone.
        let _ = self.tx.send(event.clone());
    }
}

async fn handle_models_pull(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    require_approval_authority(session, state)?;
    let params: ModelPullParams = strict_model_params(msg)?;
    let name = params.name;
    if name.is_empty() || name.trim() != name {
        return Err(
            "invalid model-management params: model id must be non-empty exact UTF-8 without surrounding whitespace"
                .into(),
        );
    }
    let engine = Arc::clone(get_inference_engine(state));
    let operation_state = Arc::clone(state);
    let operation = state
        .spawn_durable_operation("models.pull", async move {
            run_models_pull(name, engine, operation_state).await
        })
        .await;
    operation.await.map_err(|_| {
        "daemon-owned models.pull operation stopped before publishing a result".to_string()
    })?
}

async fn run_models_pull(
    name: String,
    engine: Arc<car_inference::InferenceEngine>,
    state: Arc<ServerState>,
) -> Result<Value, String> {
    // Stream progress live: events flow sink → channel → broadcaster task,
    // which runs concurrently with the download. Unbounded is safe here because
    // progress is file-level (O(files): Started + per-file Started/Completed +
    // Completed — a few dozen events per pull), not byte-level, so the channel
    // can't grow without bound.
    let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel::<car_inference::DownloadEvent>();
    let sink = car_inference::ProgressSink::new(Arc::new(PullProgressSink { tx }));
    let broadcaster_state = state.clone();
    let model_label = name.clone();
    let broadcaster = tokio::spawn(async move {
        while let Some(event) = rx.recv().await {
            broadcast_pull_progress(&broadcaster_state, &model_label, &event).await;
        }
    });

    let result = engine.pull_model_with_progress(&name, &sink).await;
    // Drop the sink so its sender closes, ending the broadcaster cleanly.
    drop(sink);
    // A broadcaster panic must not poison the (successful) pull — log and move on.
    if let Err(e) = broadcaster.await {
        tracing::warn!(error = %e, "pull-progress broadcaster task failed");
    }

    let path = result.map_err(|e| e.to_string())?;
    Ok(serde_json::json!({"path": path.display().to_string()}))
}

/// Push a `models.pull_progress` notification to subscribed UI clients.
/// Mirrors [`broadcast_upgrade_nudge`]; best-effort, no-op with no subscribers.
async fn broadcast_pull_progress(
    state: &Arc<ServerState>,
    model: &str,
    event: &car_inference::DownloadEvent,
) {
    use futures::SinkExt;
    use tokio_tungstenite::tungstenite::Message;
    let subscribers: Vec<Arc<crate::session::WsChannel>> = state
        .a2ui_subscribers
        .lock()
        .await
        .values()
        .cloned()
        .collect();
    if subscribers.is_empty() {
        return;
    }
    let Ok(json) = serde_json::to_string(&serde_json::json!({
        "jsonrpc": "2.0",
        "method": "models.pull_progress",
        "params": { "model": model, "event": event },
    })) else {
        return;
    };
    for channel in subscribers {
        let _ = channel
            .write
            .lock()
            .await
            .send(Message::Text(json.clone().into()))
            .await;
    }
}

async fn handle_skills_distill(msg: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let events: Vec<car_memgine::TraceEvent> = serde_json::from_value(
        msg.params
            .get("events")
            .cloned()
            .unwrap_or(msg.params.clone()),
    )
    .map_err(|e| format!("invalid events: {}", e))?;

    let inference = get_inference_engine(state).clone();
    let engine = car_memgine::MemgineEngine::new(None).with_inference(inference);

    let skills = engine.distill_skills(&events).await;
    serde_json::to_value(&skills).map_err(|e| e.to_string())
}

/// Run memory consolidation against this client's session memgine
/// (or the daemon-owned per-agent memgine when bound — #170).
/// Returns the JSON `ConsolidationReport`.
async fn handle_memory_consolidate(
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let engine_arc = session.effective_memgine().await;
    let report = {
        let mut engine = engine_arc.lock().await;
        engine.consolidate().await
    };
    if let Some(id) = session.agent_id.lock().await.clone() {
        if let Err(e) = persist_agent_memgine(&id, &engine_arc).await {
            tracing::warn!(agent_id = %id, error = %e,
                "agent memgine persist after consolidate failed");
        }
    }
    serde_json::to_value(&report).map_err(|e| e.to_string())
}

/// `memory.utility_get` — read the live engine's utility-aware
/// retrieval blend (U-Mem). Returns `{ utility_weight,
/// utility_exploration }`.
///
/// Engine source: `session.memgine` — deliberately the same engine
/// `handle_memory_build_context`/`_fast` retrieve from, so this getter
/// and the setter always report/mutate the engine that live context
/// assembly reads. NOTE: that's `session.memgine`, not
/// `effective_memgine()` — `build_context` is itself the outlier that
/// skipped the #170 bound-memgine routing; when that gap is closed,
/// these two utility handlers must move with it. For a bound agent the
/// persistent default still arrives via the `.car/`-seeded per-agent
/// engine (`get_or_load_agent_memgine`); this runtime override is a
/// daemon-global knob over the shared engine.
async fn handle_memory_utility_get(
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let engine = session.memgine.lock().await;
    let (weight, exploration) = engine.utility_retrieval();
    Ok(serde_json::json!({
        "utility_weight": weight,
        "utility_exploration": exploration,
    }))
}

/// `memory.utility_set` — runtime override of the utility-aware
/// retrieval blend on `session.memgine` (see `memory.utility_get` for
/// the engine-source rationale). The **persistent** baseline comes from
/// `.car/config.toml` at engine construction; this mutates the live
/// engine on top of that and does NOT persist across daemon restarts.
///
/// Read-modify-write: an omitted field keeps the engine's current value,
/// so `{ utility_weight: 0.5 }` tunes weight without resetting
/// exploration (matching the optional param typing + paired getter).
/// Takes effect on the next context build. Returns the applied
/// `{ utility_weight, utility_exploration }` (post-clamp).
///
/// NOTE: the shared engine is daemon-global (one `shared_memgine` across
/// all WS sessions + MCP), so this shifts retrieval ranking for every
/// client — last-writer-wins. For per-team persistent tuning, prefer the
/// `.car/config.toml` `utility_weight`/`utility_exploration` keys.
async fn handle_memory_utility_set(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let (weight, exploration) = {
        let mut engine = session.memgine.lock().await;
        // Read-modify-write: default each missing field to the engine's
        // current value rather than 0.0, so a partial set doesn't silently
        // zero the field the caller didn't pass.
        let (cur_weight, cur_exploration) = engine.utility_retrieval();
        let weight = msg
            .params
            .get("utility_weight")
            .and_then(|v| v.as_f64())
            .unwrap_or(cur_weight);
        let exploration = msg
            .params
            .get("utility_exploration")
            .and_then(|v| v.as_f64())
            .unwrap_or(cur_exploration);
        engine.set_utility_retrieval(weight, exploration);
        engine.utility_retrieval()
    };
    Ok(serde_json::json!({
        "utility_weight": weight,
        "utility_exploration": exploration,
    }))
}

/// `cascade.run` — U-Mem Slice 5 live evolve loop. Runs the cost-aware
/// knowledge cascade (`car_memgine::cascade::run_cascade_async`) for real,
/// escalating cheapest-first on **observed** confidence: it walks the policy's
/// tiers within budget, runs each tier's real CAR mechanic, and stops once an
/// observed confidence meets the target.
///
/// Per the caller-injected-confidence design (CAR doesn't invent a confidence
/// its primitives don't produce): the daemon runs the tier **mechanics** and the
/// budget/target walk, while the **observed confidence** for `self_reflect` /
/// `tool_verify` is supplied by the caller in `observed` (they have no
/// authoritative confidence source). The mechanics per tier:
///   - `self_reflect` → `engine.reflect()` on the session memgine (a real side
///     effect: it ingests reflection insights into memory; skipped when
///     `dry_run` is set). Confidence: caller-supplied.
///   - `tool_verify`  → pass-through (CAR has no built-in verify tool — the
///     confidence/knowledge are **caller-attested** from whatever tool the caller
///     ran; the daemon does not verify).
///   - `human_expert` → the session's `ApprovalLedger` (the same HITL substrate
///     as `permission.*`) keyed by `cascade:<claim>` is the **authority**: a
///     prior **Approved** lets the tier contribute the caller's confidence, a
///     **Rejected** aborts the cascade, and an **undecided** claim forces the
///     tier's confidence to 0.0 (it can NEVER be accepted without a real
///     approval) and surfaces `pending_approval` so a host routes it through
///     `permission.approve` / `permission.reject` by that fingerprint. A
///     `human_expert` tier requires a non-empty `claim`.
///
/// Params: `{ current_confidence: f64, policy: CascadePolicy, observed:
/// { <tier>: { confidence: f64, knowledge?: string } }, claim?: string,
/// dry_run?: bool }`.
/// Returns `{ run: CascadeRun, pending_approval?: { fingerprint, claim } }`.
async fn handle_cascade_run(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &ServerState,
) -> Result<Value, String> {
    use car_memgine::cascade::{run_cascade_async, CascadePolicy, CascadeTier, TierResult};

    #[derive(serde::Deserialize)]
    struct ObservedTier {
        confidence: f64,
        #[serde(default)]
        knowledge: Option<String>,
    }

    let current_confidence = req
        .params
        .get("current_confidence")
        .and_then(|v| v.as_f64())
        .unwrap_or(0.0);
    let policy_val = req.params.get("policy").ok_or("missing 'policy'")?;
    let policy: CascadePolicy =
        serde_json::from_value(policy_val.clone()).map_err(|e| format!("invalid 'policy': {e}"))?;
    let observed: std::collections::HashMap<CascadeTier, ObservedTier> = req
        .params
        .get("observed")
        .map(|v| serde_json::from_value(v.clone()))
        .transpose()
        .map_err(|e| format!("invalid 'observed': {e}"))?
        .unwrap_or_default();
    let claim = req
        .params
        .get("claim")
        .and_then(|v| v.as_str())
        .unwrap_or("")
        .to_string();
    // When true, skip tier side effects (the `self_reflect` `reflect()` memory
    // mutation) — a side-effect-free preview that still walks the cascade on the
    // caller-supplied observed confidence. The `human_expert` ledger read is
    // read-only and always runs (the gate must hold even in a preview).
    let dry_run = req
        .params
        .get("dry_run")
        .and_then(|v| v.as_bool())
        .unwrap_or(false);
    let fingerprint = format!("cascade:{}", claim.trim());

    // A `human_expert` tier needs a non-blank claim: the durable approval is
    // keyed on `cascade:<claim>`, so an empty claim would collapse every
    // claimless cascade onto the shared `cascade:` fingerprint — one stale
    // decision would then bleed across logically independent requests.
    let has_human_tier = policy
        .tiers
        .iter()
        .any(|t| t.tier == CascadeTier::HumanExpert);
    if has_human_tier && claim.trim().is_empty() {
        return Err(
            "a 'human_expert' tier requires a non-empty 'claim' (it keys the durable approval)"
                .into(),
        );
    }

    // The engine that holds (and learns) this session's facts — `reflect()` must
    // ingest into the bound per-agent memgine when one is attached (#170), like
    // `consolidate`.
    let engine_arc = session.effective_memgine().await;

    let observed_ref = &observed;
    let fp_ref = fingerprint.as_str();
    let run = move |tier: CascadeTier| {
        let engine_arc = engine_arc.clone();
        async move {
            let obs = observed_ref.get(&tier);
            let caller_confidence = obs.map(|o| o.confidence).unwrap_or(0.0);
            let caller_knowledge = obs.and_then(|o| o.knowledge.clone());
            // self_reflect / tool_verify have no authoritative confidence source,
            // so the caller's observed value drives escalation (the approved
            // caller-injected design). human_expert is different — the ledger is
            // the authority, so its confidence is GATED on a recorded decision,
            // never on the caller's number.
            let (knowledge, confidence) = match tier {
                CascadeTier::SelfReflect => {
                    let knowledge = if dry_run {
                        caller_knowledge
                            .unwrap_or_else(|| "self_reflect: dry_run (no reflect)".to_string())
                    } else {
                        // Real side effect: reflect over conversation, ingesting insights.
                        let report = {
                            let mut engine = engine_arc.lock().await;
                            engine.reflect().await
                        };
                        caller_knowledge.unwrap_or_else(|| {
                            format!(
                                "self_reflect: {} insight(s) ingested ({} corrections, {} preferences, {} friction)",
                                report.insights_ingested,
                                report.corrections_found,
                                report.preferences_found,
                                report.friction_points_found,
                            )
                        })
                    };
                    (knowledge, caller_confidence)
                }
                CascadeTier::ToolVerify => {
                    let knowledge = caller_knowledge
                        .unwrap_or_else(|| "tool_verify: caller-supplied".to_string());
                    (knowledge, caller_confidence)
                }
                CascadeTier::HumanExpert => {
                    // SHARED daemon ledger (C1): the approving host connection
                    // is not this connection.
                    let decision = {
                        let ledger = state.approval_ledger.read().await;
                        ledger.lookup(fp_ref).map(|r| r.decision)
                    };
                    match decision {
                        // A human rejected this exact claim — abort the cascade.
                        Some(car_policy::ApprovalDecision::Rejected) => {
                            return Err(format!("human_expert rejected: {fp_ref}"));
                        }
                        // Approved → the tier may contribute the caller's confidence
                        // (the human endorsed the claim; the caller scores how
                        // confident given that endorsement).
                        Some(car_policy::ApprovalDecision::Approved) => {
                            let knowledge = caller_knowledge
                                .unwrap_or_else(|| format!("human_expert: approved ({fp_ref})"));
                            (knowledge, caller_confidence)
                        }
                        // Undecided → 0.0, NOT the caller's number. The tier cannot
                        // satisfy the target without a real approval, so the run
                        // can never report `accepted_tier=human_expert` while the
                        // claim is still pending. Acceptance is gated on the ledger.
                        None => {
                            let knowledge = caller_knowledge.unwrap_or_else(|| {
                                format!("human_expert: awaiting approval ({fp_ref})")
                            });
                            (knowledge, 0.0)
                        }
                    }
                }
            };
            Ok::<TierResult, String>(TierResult {
                knowledge,
                confidence,
            })
        }
    };

    let run_result = run_cascade_async(current_confidence, &policy, run).await?;

    // Surface a pending human approval when the human_expert tier ran but no
    // durable decision exists yet — the host routes it through the existing
    // `permission.approve`/`permission.reject` flow by this fingerprint.
    let human_ran = run_result
        .steps
        .iter()
        .any(|s| s.tier == CascadeTier::HumanExpert);
    let pending = if human_ran {
        state
            .approval_ledger
            .read()
            .await
            .lookup(&fingerprint)
            .is_none()
    } else {
        false
    };

    let mut resp = serde_json::json!({ "run": run_result });
    if pending {
        resp.as_object_mut().unwrap().insert(
            "pending_approval".into(),
            serde_json::json!({ "fingerprint": fingerprint, "claim": claim }),
        );
    }
    Ok(resp)
}

/// Assemble the governor's full live component-state input for this session —
/// ALL FIVE components, each from its real signal source:
/// - **Memory / Skills / Context** from the session memgine
///   (`evolution_component_states` — Memory backlog/churn, Skills degradation
///   rate, Context conversation-token saturation);
/// - **Harness** from the session event log
///   (`crate::evolution::harness_component_from_events` — the share of logged
///   events implicated in a recurring interaction-failure pattern);
/// - **Tools** from live connector health
///   (`crate::evolution::tools_component_from_connectors` — disconnected /
///   total connectors).
///
/// A component with no observable signal source (empty store, empty log, no
/// connectors configured) is omitted rather than fabricated at zero.
async fn assemble_evolution_components(
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Vec<car_memgine::self_evolution::ComponentState> {
    // Route through `effective_memgine` (S1) so a session bound to a
    // lifecycle agent (#169/#170) plans over the daemon-owned per-agent
    // engine, like every memory.* handler.
    let mut components = {
        let engine_arc = session.effective_memgine().await;
        let engine = engine_arc.lock().await;
        engine.evolution_component_states()
    };
    {
        let log = session.runtime.log.lock().await;
        if let Some(h) = crate::evolution::harness_component_from_events(log.events()) {
            components.push(h);
        }
    }
    state.ensure_connectors_loaded().await;
    let connectors = state.connectors().list().await;
    if let Some(t) = crate::evolution::tools_component_from_connectors(&connectors) {
        components.push(t);
    }
    components
}

/// Return watch-only detector cadence, last-tick, detector, and active-count
/// state. The response reads the append-only ledger and performs no I/O beyond
/// that already-loaded daemon state.
async fn handle_selfheal_status(state: &Arc<ServerState>) -> Result<Value, String> {
    serde_json::to_value(state.selfheal.status().await).map_err(|error| error.to_string())
}

/// List active (not dismissed) detections with bounded pagination. Optional
/// filters: `kind`, `severity`, `since`; pagination: `offset`, `limit` (max
/// 500). This is a watch-only ledger query.
async fn handle_selfheal_detections(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let query = serde_json::from_value::<crate::selfheal::DetectionQuery>(req.params.clone())
        .map_err(|error| format!("invalid selfheal.detections params: {error}"))?;
    serde_json::to_value(state.selfheal.detections(query).await).map_err(|error| error.to_string())
}

/// Append an operator dismissal marker for one stable SHA-256 dedup key. A
/// dismissal suppresses later detector ticks for that key; it never deletes or
/// rewrites prior ledger records.
async fn handle_selfheal_dismiss(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let key = req
        .params
        .get("dedup_key")
        .and_then(Value::as_str)
        .ok_or_else(|| "selfheal.dismiss requires string param 'dedup_key'".to_string())?;
    serde_json::to_value(state.selfheal.dismiss(key).await?).map_err(|error| error.to_string())
}

/// Start one bounded, template-owned coder round for an eligible stable key.
async fn handle_selfheal_fix(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let key = req
        .params
        .get("dedup_key")
        .and_then(Value::as_str)
        .ok_or_else(|| "selfheal.fix requires string param 'dedup_key'".to_string())?;
    serde_json::to_value(state.selfheal.fix(key).await?).map_err(|error| error.to_string())
}

/// What the repair loop is configured to do, and why it is not doing it.
///
/// Answerable whether or not the loop is enabled — a disabled loop and an idle
/// one are indistinguishable from outside, and on first setup the operator is
/// almost always looking at the first while believing it is the second.
async fn handle_heal_status(state: &Arc<ServerState>) -> Result<Value, String> {
    serde_json::to_value(state.heal.status(get_inference_engine(state)))
        .map_err(|error| error.to_string())
}

/// Run one sweep now, instead of waiting for the cadence.
///
/// Goes through the same `HealService` the cadence uses, so it takes the same
/// try-lock and reads the same claim ledger. A manual run that built its own
/// loop could act on an item a running sweep already holds.
async fn handle_heal_run(state: &Arc<ServerState>) -> Result<Value, String> {
    // SPAWNED, then awaited. Awaiting the sweep directly would tie it to this
    // future's lifetime, so any drop — a deadline, a client disconnect — would
    // take a live coder session with it, and a detached one at that. A spawned
    // task survives the drop: the sweep runs to completion, its claim is
    // already on disk, and its session reaches a terminal state and releases
    // its worktree. The caller may miss the answer; the daemon never loses
    // track of the work.
    let owned = state.clone();
    let handle = tokio::spawn(async move { owned.heal.run_tick(&owned).await });
    match handle.await {
        Ok(result) => serde_json::to_value(result?).map_err(|error| error.to_string()),
        Err(e) => Err(format!("heal sweep task failed: {e}")),
    }
}

/// Run one detection tick now. The method uses the same non-overlap guard as
/// the cadence and may start one eligible default-on auto-fix round after the
/// deterministic detector pass.

async fn handle_selfheal_run(state: &Arc<ServerState>) -> Result<Value, String> {
    serde_json::to_value(state.selfheal.run_tick(state).await?).map_err(|error| error.to_string())
}

/// Plan an evolution cycle over the session's **live** signals — the
/// self-evolution governor's host surface (arXiv 2507.21046, Slice 3 + the
/// daemon populaters). Folds all five components live via
/// [`assemble_evolution_components`] and runs the governor. `params.policy` is
/// an optional `EvolutionPolicy` `{ pressure_threshold?, budget? }`. Returns
/// the `EvolutionPlan` JSON `{ decisions, spent, evolve_now }`. Read-only — it
/// plans; dispatching is `evolution.run` (or the caller's own loop).
async fn handle_evolution_plan(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let policy: car_memgine::self_evolution::EvolutionPolicy = serde_json::from_value(
        req.params
            .get("policy")
            .cloned()
            .unwrap_or_else(|| serde_json::json!({})),
    )
    .map_err(|e| format!("invalid policy: {e}"))?;
    let components = assemble_evolution_components(session, state).await;
    let plan = car_memgine::self_evolution::plan_evolution(&components, &policy);
    serde_json::to_value(plan).map_err(|e| e.to_string())
}

/// Run one evolution cycle over the session's live signals — the real executor
/// behind the self-evolution governor (arXiv 2507.21046; the "remaining daemon
/// step" of `docs/proposals/self-evolution-governor.md`). Plans exactly like
/// `evolution.plan` (all five components live), then dispatches each
/// `EvolveNow` component in priority order:
///
/// - **Memory** → `engine.consolidate()`, sized by
///   `maintenance::decide_maintenance` off the live `memory_stats` (the
///   localized-vs-global choice is recorded; `consolidate()` is the single
///   live mechanism for both today).
/// - **Skills** → `engine.evolve_skills(failed_events, domain)` for every
///   domain `domains_needing_evolution` flags, with `failed_events` folded
///   from the session event log's failure records
///   (`crate::evolution::failed_trace_events` — per-action failures; the log
///   carries no state-before/after trajectories, so those fields are honest
///   `None`s). Errors `"no inference engine"` when the session engine has no
///   model — never a stub.
/// - **Harness** → the `harness_evolution` diagnose→gate→apply loop, HITL-
///   gated on the daemon's SHARED durable `ApprovalLedger`
///   (`~/.car/approvals.jsonl` — the same store `permission.*` writes, from
///   ANY connection; C1), fingerprint `harness:<component>:<patch-digest>`
///   (bound to the patch *content*, not diagnostic prose, so an approval
///   matches every re-diagnosis of the same change; C2):
///   - a mutation whose fingerprint a human already **approved** applies its
///     patch to the session runtime's live `HarnessConfig` under one atomic
///     read-modify-write (`Governance::HumanApproved`); **rejected** →
///     blocked;
///   - undecided mutations surface in `pending_approvals` (resolve via
///     `permission.approve`/`permission.reject` by fingerprint — on any
///     connection — then re-run);
///   - the regression gate (`EvolutionAgent::evaluate`) needs *candidate*
///     metrics measured on held-out telemetry after applying the mutation, so
///     auto-promotion only runs when such metrics exist. Two ways to get them:
///     the caller supplies `harness_candidate_metrics` (and optionally
///     `harness_baseline_metrics`; baseline defaults to the live session
///     metrics), or the caller opts into `harness_measure` and the daemon
///     measures them ITSELF via the installed
///     [`HarnessMeasurer`](crate::evolution::HarnessMeasurer) — one baseline
///     replay under the session's live `HarnessConfig`, then one replay per
///     measurable mutation under that config plus the mutation's patch. A
///     gate-passed non-safety mutation then auto-applies
///     (`Governance::Promoted`); a safety-affecting one still goes to HITL.
///   - `harness_measure` is mutually exclusive with the two supplied-metrics
///     params (an ERROR naming both, never a silent winner); under `dry_run`
///     it measures NOTHING (a paid replay is a side effect) and reports
///     `measurement.status = "skipped_dry_run"`; with no measurer installed on
///     this build it ERRS rather than degrading to HITL, because an opt-in
///     that silently does nothing would report an unattended cycle that never
///     measured anything. Mutations with no patch and safety-affecting
///     mutations are never measured — the first has nothing to apply, the
///     second can never auto-promote, so a replay would spend real model calls
///     to reach an outcome already decided.
///   - a supplied (or daemon-measured) `harness_baseline_metrics` also
///     REPLACES the Harness planning signal (`harness_component_from_metrics`
///     — failed/total attempts) so the declared telemetry both elects and
///     diagnoses the component coherently.
///   - the harness step summary carries a `measurement` object (status, split,
///     model, seed and the full baseline document) and every measured
///     mutation's detail carries its full `candidate_metrics`: a promotion
///     nobody can re-derive is not an audited promotion.
/// - **Context** → [`run_context_evolution`](crate::evolution::run_context_evolution):
///   diagnose from the engine's live conversation-layer saturation, then
///   resolve each mutation most-binding-first over two authorization paths.
///   - A durable ledger decision wins outright (`rejected_by_operator`, or the
///     human-approved apply→compact→re-read→REVERT-unless-tokens-fell path,
///     whose reverted mutations report `rolled_back` and count as nothing
///     applied).
///   - Otherwise, if the caller opted into **`context_measure`**, the
///     **pre-activation grader** runs: two bench replays over the same
///     deterministic split, one under the engine's live `MemgineConfig` and one
///     under that config plus the mutation's patch, graded on TASK outcomes by
///     `EvolutionAgent::evaluate_context` — the same gate, with the same
///     guards, that grades a harness mutation. A promoted mutation applies with
///     `governance: "promoted"` and no human in the loop; a rejected one
///     reports `rejected_by_gate` and applies nothing (and does NOT then ask an
///     operator to approve what the daemon just measured as a regression); a
///     failed replay reports `measurement_failed`; `NeedsApproval` /
///     `Incomparable` fall through to `pending_approval` carrying the gate's
///     own reason.
///   - Otherwise the human gate, with a reason naming the missing precondition
///     (`context_measure` absent, `dry_run`, or a patchless mutation). As with
///     `harness_measure`, requesting `context_measure` on a build with no
///     evaluator installed is an ERROR, and `dry_run` performs no paid replay.
/// - **Tools** → recorded as `out_of_scope` with its reason: connector
///   remediation is a credential operation this loop holds no authority to
///   perform (reconnect/re-auth stay operator actions via `connectors.*`).
///   That is a decision, not a failure, and `out_of_scope: true` with
///   `ran: true` is how it is now reported — an `Err` here used to make it
///   indistinguishable from a crashed mechanism.
///
/// `params`: `{ policy?, dry_run?, harness_baseline_metrics?,
/// harness_candidate_metrics?, harness_measure?, context_measure? }`, where
/// `harness_measure` and `context_measure` are each a
/// [`HarnessMeasureRequest`](crate::evolution::HarnessMeasureRequest)
/// `{ model, split?, held_in_fraction?, split_seed?, max_turns?, tasks_dir? }`
/// — the same type, because the two arms replay the same suite over the same
/// split and differ only in which config is varied. They are NOT mutually
/// exclusive with each other (they grade different pillars); `harness_measure`
/// remains mutually exclusive with the two supplied-metrics params. `dry_run` skips every side effect (no
/// consolidate, no evolve, no config apply, no event append) and reports what
/// would run — including the `pending_approvals` that a real run would
/// surface (listing them is response data, not a side effect). `evolved`
/// lists only components that **applied a change** (S2) — an Ok-but-no-op
/// step (nothing to evolve, everything still pending approval, dry run) is
/// reported in `steps` with `applied: false` but not in `evolved`. At most
/// one `evolution.run` executes per session at a time; a concurrent second
/// call errs instead of overlapping (S3). Returns
/// `{ plan, steps, evolved, out_of_scope, pending_approvals? }`, where
/// `out_of_scope` lists the components that were planned but have no mechanism
/// by decision (their steps carry `out_of_scope: true` and the reason); a real
/// run appends one
/// `EvolutionTriggered` event (`data.source = "evolution.run"`) to the session
/// event log and, when bound to a lifecycle agent, persists the per-agent
/// memgine after a cycle that applied something (S1).
/// Where one mutation's candidate telemetry came from — or why there is none.
///
/// The gate's input is never fabricated, so "no candidate metrics" and "the
/// measurement failed" are separate outcomes with separate statuses, and
/// neither is ever rounded to a zero document.
enum CandidateSource {
    /// Measured out of process by the caller (`harness_candidate_metrics`).
    Supplied(car_eventlog::harness_metrics::HarnessMetrics),
    /// Measured in process by this cycle's [`HarnessMeasurer`](crate::evolution::HarnessMeasurer).
    Measured(car_eventlog::harness_metrics::HarnessMetrics),
    /// A measurement was attempted and errored. Nothing is applied, nothing is
    /// synthesized, and the cycle continues to the next mutation.
    Failed(String),
    /// No measurement exists or could be taken, with the reason — routes to
    /// HITL exactly as it did before in-daemon measurement existed.
    Unavailable(String),
}

async fn handle_evolution_run(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    use car_memgine::harness_evolution::{
        mutation_fingerprint, EvolutionAgent, Governance, PromotionDecision,
    };
    use car_memgine::self_evolution::{EvolutionOutcome, EvolvableComponent};

    // Non-overlap guard (S3): the dispatcher spawns a task per request, so
    // even one connection can land two evolution.run frames concurrently —
    // which would double-dispatch consolidate/evolve and race the harness
    // apply. Held (RAII) until this handler returns.
    let _cycle_token = session
        .evolution_guard
        .try_begin()
        .ok_or("evolution.run already in flight on this session")?;

    let policy: car_memgine::self_evolution::EvolutionPolicy = serde_json::from_value(
        req.params
            .get("policy")
            .cloned()
            .unwrap_or_else(|| serde_json::json!({})),
    )
    .map_err(|e| format!("invalid policy: {e}"))?;
    let dry_run = req
        .params
        .get("dry_run")
        .and_then(|v| v.as_bool())
        .unwrap_or(false);
    let baseline_override: Option<car_eventlog::harness_metrics::HarnessMetrics> =
        match req.params.get("harness_baseline_metrics") {
            Some(v) if !v.is_null() => Some(
                serde_json::from_value(v.clone())
                    .map_err(|e| format!("invalid harness_baseline_metrics: {e}"))?,
            ),
            _ => None,
        };
    let candidate_metrics: Option<car_eventlog::harness_metrics::HarnessMetrics> =
        match req.params.get("harness_candidate_metrics") {
            Some(v) if !v.is_null() => Some(
                serde_json::from_value(v.clone())
                    .map_err(|e| format!("invalid harness_candidate_metrics: {e}"))?,
            ),
            _ => None,
        };

    // In-daemon measurement (opt-in). Parsed before anything runs so a
    // malformed request costs nothing.
    let measure_request = crate::evolution::parse_harness_measure_request(&req.params)?;

    // 1. Mutual exclusion. Measuring and handing metrics in are two answers to
    //    the same question; picking a winner silently would let a caller
    //    believe the daemon graded a replay it never ran (or the reverse).
    if measure_request.is_some() && (baseline_override.is_some() || candidate_metrics.is_some()) {
        let supplied = match (baseline_override.is_some(), candidate_metrics.is_some()) {
            (true, true) => "harness_baseline_metrics and harness_candidate_metrics",
            (true, false) => "harness_baseline_metrics",
            _ => "harness_candidate_metrics",
        };
        return Err(format!(
            "harness_measure cannot be combined with {supplied}: harness_measure makes the \
             daemon measure the baseline and every candidate itself, so supplied metrics would \
             have to be either ignored or silently preferred. Send one or the other."
        ));
    }

    // 2. dry_run measures NOTHING. A benchmark replay is a paid side effect and
    //    dry_run skips every side effect.
    let measuring = measure_request.is_some() && !dry_run;

    // 3. No measurer installed on this build → error, not a quiet fall back to
    //    HITL. An opt-in that silently does nothing would report an unattended
    //    cycle that never measured anything.
    let measurer = if measuring {
        Some(state.harness_measurer().ok_or(
            "harness_measure requested but this daemon build has no in-process harness \
             evaluator installed (car-server installs car-bench's BenchHarnessMeasurer at \
             startup; embedders must call ServerState::set_harness_measurer)",
        )?)
    } else {
        None
    };

    // 3b. The CONTEXT arm's pre-activation grader, opt-in via `context_measure`
    //     and resolved off the same installed measurer — the replay is the same
    //     replay over the same split, and only which config is varied differs.
    //
    //     Two differences from `harness_measure` above, both deliberate:
    //
    //     - It is NOT mutually exclusive with `harness_measure`. They grade
    //       different pillars against different configs, and a caller who wants
    //       one cycle to do both is asking for two independent measurements,
    //       not two answers to the same question. (It costs two more replays;
    //       that is the caller's explicit choice.)
    //     - The measurer is resolved even under `dry_run`, where the harness
    //       arm skips resolution entirely. A dry run is supposed to report what
    //       a REAL run would do, and what a real run would do on a build with
    //       no evaluator installed is fail — reporting "nothing was measured
    //       because this was a dry run" would hide that. The dry-run rule
    //       itself (no paid replay) is enforced inside
    //       `run_context_evolution`, which is also what lets its pending reason
    //       name `dry_run` as the precondition that was missing.
    let context_measure_request = crate::evolution::parse_context_measure_request(&req.params)?;
    let context_measurer = match context_measure_request.as_ref() {
        Some(_) => Some(state.harness_measurer().ok_or(
            "context_measure requested but this daemon build has no in-process harness \
             evaluator installed (car-server installs car-bench's BenchHarnessMeasurer at \
             startup; embedders must call ServerState::set_harness_measurer)",
        )?),
        None => None,
    };

    // The config the whole comparison is anchored on: the session runtime's
    // live `HarnessConfig` at cycle start (`None` = the runtime default).
    // Captured ONCE — a mutation that applies mid-cycle must not move the base
    // for the next mutation's candidate, or that candidate would be graded
    // against a baseline measured under a different config.
    let live_harness_config = session.runtime.harness_config().await;

    // 4. The baseline, measured once under that live config. An error here
    //    fails the Harness STEP (recorded, nothing applied) rather than the
    //    whole cycle — Memory and Skills are unaffected by a bench failure.
    let mut baseline_measurement_error: Option<String> = None;
    let mut measured_baseline: Option<car_eventlog::harness_metrics::HarnessMetrics> = None;
    if let (Some(m), Some(rq)) = (measurer.as_ref(), measure_request.as_ref()) {
        match crate::evolution::measure_baseline(m.as_ref(), rq, live_harness_config.as_ref()).await
        {
            Ok(metrics) => measured_baseline = Some(metrics),
            Err(e) => baseline_measurement_error = Some(e),
        }
    }

    let mut components = assemble_evolution_components(session, state).await;
    // S1: the same engine the assembler planned over — the daemon-owned
    // per-agent engine for bound sessions, else the session engine.
    let engine_arc = session.effective_memgine().await;

    // Pre-fold the session-log-derived executor inputs once (single lock).
    let (failed_events, live_metrics) = {
        let log = session.runtime.log.lock().await;
        (
            crate::evolution::failed_trace_events(log.events()),
            car_eventlog::harness_metrics::compute_harness_metrics(log.events()),
        )
    };
    // A daemon-measured baseline is the declared telemetry exactly like a
    // supplied one — same document, same role — so the telemetry that elects
    // the Harness component is the telemetry that diagnoses it.
    let has_baseline_override = baseline_override.is_some() || measured_baseline.is_some();
    let baseline_metrics = measured_baseline
        .clone()
        .or(baseline_override)
        .unwrap_or(live_metrics);
    // A caller-supplied baseline is the declared harness telemetry for this
    // cycle: it drives the diagnosis below AND the Harness planning signal —
    // otherwise a held-out baseline could diagnose mutations the plan never
    // dispatches (the live session log may be empty).
    if has_baseline_override {
        components
            .retain(|c| c.component != car_memgine::self_evolution::EvolvableComponent::Harness);
        if let Some(h) = crate::evolution::harness_component_from_metrics(&baseline_metrics) {
            components.push(h);
        }
    }
    let harness_mutations = EvolutionAgent::new().diagnose(&baseline_metrics);

    // 6. Auditability: what was measured, on which split, under which model,
    //    and the full baseline document the verdicts were computed against.
    //    Metrics are numbers; publishing them is what makes a promotion
    //    re-derivable by whoever reviews the cycle.
    //
    //    A FAILED baseline replay gets a shape of its own here rather than
    //    being left implicit: it is the one outcome where the response would
    //    otherwise read as a clean cycle. Reported at step 7 below whether or
    //    not the Harness component was ever elected.
    let measurement_summary: Option<Value> = measure_request.as_ref().map(|rq| {
        let mut o = serde_json::json!({
            "split": rq.split,
            "model": rq.model,
            "split_seed": rq.split_seed,
        });
        let obj = o.as_object_mut().expect("object literal");
        if dry_run {
            obj.insert("status".into(), Value::from("skipped_dry_run"));
        } else if let Some(b) = &measured_baseline {
            obj.insert("status".into(), Value::from("measured"));
            obj.insert(
                "baseline_metrics".into(),
                serde_json::to_value(b).unwrap_or(Value::Null),
            );
        } else {
            obj.insert("status".into(), Value::from("measurement_failed"));
            obj.insert(
                "error".into(),
                baseline_measurement_error
                    .clone()
                    .map(Value::from)
                    .unwrap_or(Value::Null),
            );
        }
        o
    });

    let pending_approvals: std::sync::Mutex<Vec<Value>> = std::sync::Mutex::new(Vec::new());
    let failed_events = &failed_events;
    let harness_mutations = &harness_mutations;
    let baseline_metrics = &baseline_metrics;
    let candidate_metrics = &candidate_metrics;
    let pending_ref = &pending_approvals;
    let engine_ref = &engine_arc;
    let measurer_ref = &measurer;
    let measure_request_ref = &measure_request;
    let context_measurer_ref = &context_measurer;
    let context_measure_request_ref = &context_measure_request;
    // The base every candidate config is projected from: the live config, or
    // the runtime default when none is installed (which is what the baseline
    // replay ran under).
    let base_harness_config = live_harness_config.clone().unwrap_or_default();
    let base_harness_config = &base_harness_config;
    let baseline_measurement_error = &baseline_measurement_error;
    let measurement_summary = &measurement_summary;

    let run = |component: EvolvableComponent| {
        let engine = engine_ref.clone();
        async move {
            match component {
                EvolvableComponent::Memory => {
                    crate::evolution::run_memory_evolution(&engine, dry_run).await
                }
                EvolvableComponent::Skills => {
                    crate::evolution::run_skills_evolution(&engine, failed_events, dry_run).await
                }
                EvolvableComponent::Harness => {
                    // A failed baseline replay fails THIS step and nothing
                    // else: no diagnosis it produced can be trusted, nothing is
                    // applied, and no metrics are synthesized to stand in.
                    if let Some(e) = baseline_measurement_error {
                        return Err(e.clone());
                    }
                    if harness_mutations.is_empty() {
                        return Ok(EvolutionOutcome::no_op(
                            "no harness mutations diagnosed from session telemetry",
                        ));
                    }
                    let agent = EvolutionAgent::new();
                    let mut details: Vec<Value> = Vec::new();
                    let mut applied = 0usize;
                    let mut pending = 0usize;
                    for m in harness_mutations {
                        // C2: the fingerprint binds the authorized CHANGE
                        // (component + patch content), not diagnostic prose —
                        // stable across re-diagnoses, so a standing approval
                        // matches.
                        let fingerprint = mutation_fingerprint(m);
                        // C1: prior decisions come from the daemon's SHARED
                        // durable ledger — the approver is typically another
                        // connection (a host UI).
                        let prior = {
                            let ledger = state.approval_ledger.read().await;
                            ledger.lookup(&fingerprint).map(|r| r.decision)
                        };
                        // Authorization resolution, most binding first: a
                        // durable human decision, then the regression gate
                        // (only when the caller measured candidate telemetry),
                        // else HITL. A pending entry is always LISTED —
                        // reporting what needs approval is response data;
                        // dry_run only skips real side effects.
                        let status: Value = match prior {
                            Some(car_policy::ApprovalDecision::Rejected) => {
                                serde_json::json!({ "status": "rejected_by_operator" })
                            }
                            Some(car_policy::ApprovalDecision::Approved) => {
                                if m.patch.is_none() {
                                    serde_json::json!({
                                        "status": "approved_no_patch",
                                        "note": "approved but carries no concrete config patch — a human designs this change",
                                    })
                                } else if dry_run {
                                    serde_json::json!({ "status": "would_apply", "governance": "human_approved" })
                                } else {
                                    // S3: one atomic read-modify-write under
                                    // the runtime's config write lock.
                                    match session
                                        .runtime
                                        .update_harness_config(|cfg| {
                                            cfg.apply(m, Governance::HumanApproved)
                                        })
                                        .await
                                    {
                                        Ok(inverse) => {
                                            applied += 1;
                                            serde_json::json!({
                                                "status": "applied",
                                                "governance": "human_approved",
                                                "rollback_patch": inverse,
                                            })
                                        }
                                        Err(e) => serde_json::json!({
                                            "status": "apply_failed", "error": e,
                                        }),
                                    }
                                }
                            }
                            None => {
                                // Resolve this mutation's candidate telemetry:
                                // the caller's measured document, or — when
                                // in-daemon measuring is on — a replay we run
                                // ourselves under the candidate config.
                                const NO_CANDIDATE_REASON: &str = "no held-out candidate telemetry supplied — the regression gate needs measured post-mutation metrics (pass harness_candidate_metrics, or harness_measure to have the daemon measure them), so activation requires operator approval";
                                const DRY_RUN_REASON: &str = "harness_measure was requested with dry_run — a benchmark replay is a paid side effect and dry_run performs none, so nothing was measured and activation requires operator approval";
                                const NO_PATCH_REASON: &str = "carries no concrete config patch, so there is nothing to apply and nothing to measure — a human designs this change";
                                const SAFETY_SKIP_REASON: &str = "measurement skipped: the component is safety-affecting, so it can never auto-promote however it measures — spending a benchmark replay to reach an outcome already decided would be waste. Activation requires operator approval";

                                let source = if let Some(cand) = candidate_metrics {
                                    CandidateSource::Supplied(cand.clone())
                                } else if let (Some(measurer), Some(rq)) =
                                    (measurer_ref.as_ref(), measure_request_ref.as_ref())
                                {
                                    match m.patch.as_ref().filter(|p| !p.is_empty()) {
                                        None => CandidateSource::Unavailable(
                                            NO_PATCH_REASON.to_string(),
                                        ),
                                        Some(_) if m.requires_human_approval() => {
                                            CandidateSource::Unavailable(
                                                SAFETY_SKIP_REASON.to_string(),
                                            )
                                        }
                                        Some(patch) => {
                                            match crate::evolution::measure_candidate(
                                                measurer.as_ref(),
                                                rq,
                                                base_harness_config,
                                                patch,
                                            )
                                            .await
                                            {
                                                Ok(metrics) => CandidateSource::Measured(metrics),
                                                Err(e) => CandidateSource::Failed(e),
                                            }
                                        }
                                    }
                                } else if measure_request_ref.is_some() {
                                    CandidateSource::Unavailable(DRY_RUN_REASON.to_string())
                                } else {
                                    CandidateSource::Unavailable(NO_CANDIDATE_REASON.to_string())
                                };

                                // Audit the document the verdict was computed
                                // from — a decision nobody can re-derive is not
                                // an audited decision.
                                let measured_here = matches!(source, CandidateSource::Measured(_));

                                match source {
                                    CandidateSource::Supplied(ref cand)
                                    | CandidateSource::Measured(ref cand) => {
                                        let decision = agent.evaluate(m, baseline_metrics, cand);
                                        let mut status = match &decision {
                                            PromotionDecision::Promote { reason } => {
                                                let reason = reason.clone();
                                                if dry_run {
                                                    serde_json::json!({ "status": "would_apply", "governance": "promoted", "reason": reason })
                                                } else {
                                                    match session
                                                        .runtime
                                                        .update_harness_config(|cfg| {
                                                            cfg.apply(
                                                                m,
                                                                Governance::Promoted(
                                                                    decision.clone(),
                                                                ),
                                                            )
                                                        })
                                                        .await
                                                    {
                                                        Ok(inverse) => {
                                                            applied += 1;
                                                            serde_json::json!({
                                                                "status": "applied",
                                                                "governance": "promoted",
                                                                "reason": reason,
                                                                "rollback_patch": inverse,
                                                            })
                                                        }
                                                        Err(e) => serde_json::json!({
                                                            "status": "apply_failed", "error": e,
                                                        }),
                                                    }
                                                }
                                            }
                                            PromotionDecision::NeedsApproval { reason } => {
                                                pending += 1;
                                                pending_ref.lock().unwrap().push(
                                                    serde_json::json!({
                                                        "fingerprint": fingerprint,
                                                        "mutation": m.id,
                                                        "component": m.contract.component,
                                                        "safety_affecting": true,
                                                        "rationale": m.rationale,
                                                        "reason": reason,
                                                    }),
                                                );
                                                serde_json::json!({ "status": "pending_approval", "reason": reason })
                                            }
                                            PromotionDecision::Reject { reason } => {
                                                serde_json::json!({ "status": "rejected_by_gate", "reason": reason })
                                            }
                                            // No verdict: the two telemetry
                                            // documents are not measurable against
                                            // each other (today, task pass rates
                                            // over different task sets). Reported
                                            // as its own status rather than folded
                                            // into `rejected_by_gate` — the caller
                                            // needs to fix the comparison and
                                            // re-run, which is different advice
                                            // from "this mutation is bad".
                                            // Nothing is applied either way.
                                            PromotionDecision::Incomparable { reason } => {
                                                serde_json::json!({ "status": "incomparable", "reason": reason })
                                            }
                                        };
                                        if measured_here {
                                            if let Some(obj) = status.as_object_mut() {
                                                obj.insert(
                                                    "candidate_metrics".into(),
                                                    serde_json::to_value(cand)
                                                        .unwrap_or(Value::Null),
                                                );
                                            }
                                        }
                                        status
                                    }
                                    // A measurement that errored is reported as
                                    // exactly that. Nothing is applied, nothing is
                                    // fabricated, and the cycle moves on to the
                                    // next mutation.
                                    CandidateSource::Failed(error) => serde_json::json!({
                                        "status": "measurement_failed",
                                        "error": error,
                                    }),
                                    // No candidate telemetry → the regression gate
                                    // cannot be run honestly in-cycle; every
                                    // activation routes to HITL. Patchless
                                    // mutations are proposals a human addresses
                                    // either way.
                                    CandidateSource::Unavailable(reason) => {
                                        pending += 1;
                                        pending_ref.lock().unwrap().push(serde_json::json!({
                                            "fingerprint": fingerprint,
                                            "mutation": m.id,
                                            "component": m.contract.component,
                                            "safety_affecting": m.requires_human_approval(),
                                            "rationale": m.rationale,
                                            "reason": reason,
                                        }));
                                        serde_json::json!({
                                            "status": "pending_approval",
                                            "reason": reason,
                                        })
                                    }
                                }
                            }
                        };
                        let mut d = serde_json::json!({
                            "mutation": m.id,
                            "component": m.contract.component,
                            "fingerprint": fingerprint,
                            "rationale": m.rationale,
                        });
                        if let (Some(obj), Some(s)) = (d.as_object_mut(), status.as_object()) {
                            for (k, v) in s {
                                obj.insert(k.clone(), v.clone());
                            }
                        }
                        details.push(d);
                    }
                    let mut summary_obj = serde_json::json!({
                        "mechanism": "harness_evolution",
                        "mutations": harness_mutations.len(),
                        "applied": applied,
                        "pending": pending,
                        "details": details,
                    });
                    if let (Some(obj), Some(measurement)) =
                        (summary_obj.as_object_mut(), measurement_summary.as_ref())
                    {
                        obj.insert("measurement".into(), measurement.clone());
                    }
                    let summary = serde_json::to_string(&summary_obj).map_err(|e| e.to_string())?;
                    // S2: "evolved" means a patch actually landed — an
                    // all-pending/all-rejected pass is a no-op.
                    Ok(if applied > 0 {
                        EvolutionOutcome::applied(summary)
                    } else {
                        EvolutionOutcome::no_op(summary)
                    })
                }
                EvolvableComponent::Context => {
                    // `None` backoff: a session-driven run is a person asking
                    // for the check now. The unattended cadence is the loop
                    // that needs a brake, and it passes `Some`.
                    //
                    // The measure pair is `Some` exactly when the caller
                    // supplied `context_measure` (the measurer resolution
                    // above already erred if this build cannot measure), which
                    // is what turns the Context pillar unattended: a graded
                    // mutation promotes or is rejected without ever reaching
                    // the ledger.
                    let context_measure = match (
                        context_measurer_ref.as_ref(),
                        context_measure_request_ref.as_ref(),
                    ) {
                        (Some(m), Some(rq)) => {
                            Some((m.as_ref() as &dyn crate::evolution::HarnessMeasurer, rq))
                        }
                        _ => None,
                    };
                    crate::evolution::run_context_evolution(
                        &engine,
                        state,
                        dry_run,
                        pending_ref,
                        None,
                        context_measure,
                    )
                    .await
                }
                // A deliberate scope decision, reported as one. Returning an
                // `Err` here recorded `ran: false` — the same shape a crashed
                // mechanism produces — so a boundary the project chose on
                // purpose read as a failing subsystem in every cycle report.
                EvolvableComponent::Tools => Ok(EvolutionOutcome::out_of_scope(
                    crate::evolution::TOOLS_OUT_OF_SCOPE_REASON,
                )),
            }
        }
    };

    let report = car_memgine::self_evolution::run_evolution_cycle(&components, &policy, run).await;

    if !dry_run {
        let mut data: std::collections::HashMap<String, Value> = std::collections::HashMap::new();
        data.insert("source".into(), Value::from("evolution.run"));
        data.insert(
            "evolve_now".into(),
            serde_json::to_value(&report.plan.evolve_now).unwrap_or(Value::Null),
        );
        data.insert(
            "evolved".into(),
            serde_json::to_value(&report.evolved).unwrap_or(Value::Null),
        );
        session.runtime.log.lock().await.append(
            car_eventlog::EventKind::EvolutionTriggered,
            None,
            None,
            data,
        );
        // S1: a bound lifecycle agent's engine is daemon-persisted after a
        // mutating run, like memory.add/memory.consolidate.
        if !report.evolved.is_empty() {
            if let Some(id) = session.agent_id.lock().await.clone() {
                if let Err(e) = persist_agent_memgine(&id, &engine_arc).await {
                    tracing::warn!(agent_id = %id, error = %e,
                        "agent memgine persist after evolution.run failed; in-memory state is canonical");
                }
            }
        }
    }

    let pending = pending_approvals.into_inner().unwrap();
    let mut resp = serde_json::json!({
        "plan": report.plan,
        "steps": report.steps,
        "evolved": report.evolved,
        // Components this cycle deliberately did not evolve. Always present
        // (empty when there were none) so a caller can distinguish "no boundary
        // was hit" from "this daemon predates the field".
        "out_of_scope": report.out_of_scope,
    });
    if !pending.is_empty() {
        resp.as_object_mut()
            .unwrap()
            .insert("pending_approvals".into(), Value::Array(pending));
    }
    // 7. The measurement is reported at the TOP LEVEL, not only inside the
    //    Harness step.
    //
    //    A benchmark replay is a paid side effect — real model calls, real
    //    money — and a side effect nobody can see in the response is one nobody
    //    can audit. The baseline replay runs BEFORE the plan is assembled (it
    //    is what supplies the Harness planning signal), but the plan may
    //    legitimately never reach the Harness arm: `harness_component_from_
    //    metrics` returns `None` at zero attempts, and an elected component can
    //    still `skip` (pressure below threshold) or `defer` (evidence below
    //    `min_evidence`). Reported only from the step, a caller who asked for
    //    `harness_measure` on a healthy harness would be billed for a replay
    //    the response never mentions — and a replay that FAILED would vanish
    //    the same way, leaving a normal-looking cycle with no hint that the
    //    measurement they explicitly requested never happened.
    //
    //    So this key is present whenever `harness_measure` was requested, in
    //    every shape the measurement can end in: `measured`,
    //    `skipped_dry_run`, or `measurement_failed` carrying the error. The
    //    Harness step keeps its own copy — the elected case loses nothing.
    if let Some(measurement) = measurement_summary.as_ref() {
        resp.as_object_mut()
            .unwrap()
            .insert("measurement".into(), measurement.clone());
    }
    Ok(resp)
}

/// Repair a degraded skill on this client's session memgine.
/// Returns `{ code: "..." }` on success, `null` if the skill
/// isn't broken or repair failed.
async fn handle_skill_repair(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let name = msg
        .params
        .get("skill_name")
        .and_then(|v| v.as_str())
        .ok_or("missing 'skill_name' parameter")?;
    let mut engine = session.memgine.lock().await;
    let code = engine.repair_skill(name).await;
    Ok(match code {
        Some(c) => serde_json::json!({ "code": c }),
        None => Value::Null,
    })
}

/// Ingest distilled skills into this client's session memgine.
/// Returns the number of nodes inserted.
async fn handle_skills_ingest_distilled(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let skills: Vec<car_memgine::DistilledSkill> = serde_json::from_value(
        msg.params
            .get("skills")
            .cloned()
            .unwrap_or(msg.params.clone()),
    )
    .map_err(|e| format!("invalid skills: {}", e))?;
    let mut engine = session.memgine.lock().await;
    let nodes = engine.ingest_distilled_skills(&skills);
    Ok(serde_json::json!({ "ingested": nodes.len() }))
}

/// Run skill evolution against this session's memgine for a
/// specified domain.  Returns the resulting `DistilledSkill` array.
async fn handle_skills_evolve(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let domain = msg
        .params
        .get("domain")
        .and_then(|v| v.as_str())
        .ok_or("missing 'domain' parameter")?
        .to_string();
    let events: Vec<car_memgine::TraceEvent> = serde_json::from_value(
        msg.params
            .get("events")
            .cloned()
            .unwrap_or(Value::Array(vec![])),
    )
    .map_err(|e| format!("invalid events: {}", e))?;
    let mut engine = session.memgine.lock().await;
    let skills = engine.evolve_skills(&events, &domain).await;
    serde_json::to_value(&skills).map_err(|e| e.to_string())
}

/// List domains whose skills are underperforming on this session.
async fn handle_skills_domains_needing_evolution(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let threshold = msg
        .params
        .get("threshold")
        .and_then(|v| v.as_f64())
        .unwrap_or(0.6);
    let engine = session.memgine.lock().await;
    let domains = engine.domains_needing_evolution(threshold);
    serde_json::to_value(&domains).map_err(|e| e.to_string())
}

/// Ingest distilled/evolved skills as PROVISIONAL candidates on trial
/// (validation-gated optimization — see docs/solutions/gated-skill-optimization.md).
/// Unlike `skills.ingest_distilled`, these must prove themselves before the
/// promotion gate makes them Active. Returns `{ ingested: n }` (drops
/// already-rejected or already-trialing candidates).
async fn handle_skills_ingest_provisional(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let skills: Vec<car_memgine::DistilledSkill> = serde_json::from_value(
        msg.params
            .get("skills")
            .cloned()
            .unwrap_or(msg.params.clone()),
    )
    .map_err(|e| format!("invalid skills: {}", e))?;
    let tenant = msg.params.get("tenant").and_then(|v| v.as_str());
    let mut engine = session.memgine.lock().await;
    let ingested = engine.ingest_provisional_candidates(&skills, tenant);
    Ok(serde_json::json!({ "ingested": ingested }))
}

/// Run the skill promotion gate against this session's memgine: provisional
/// candidates with enough trial outcomes are promoted (strictly-better Wilson
/// lower bound) or rejected. Normally fires automatically in `consolidate()`;
/// this exposes a manual trigger. Returns `{ promoted: [...], rejected: [...] }`.
async fn handle_skills_gate(
    _msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let mut engine = session.memgine.lock().await;
    let (promoted, rejected) = engine.gate_skill_candidates();
    Ok(serde_json::json!({ "promoted": promoted, "rejected": rejected }))
}

/// Fetch a skill's full `SkillMeta` by key — including lifecycle `status`
/// (active/provisional), `incumbent`, `version`, and `stats`. Returns the JSON
/// SkillMeta, or `null` if no active skill node holds the key.
async fn handle_skill_meta(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let key = msg
        .params
        .get("key")
        .and_then(|v| v.as_str())
        .ok_or("missing 'key' parameter")?;
    let engine = session.memgine.lock().await;
    match engine.skill_meta(key) {
        Some(meta) => serde_json::to_value(&meta).map_err(|e| e.to_string()),
        None => Ok(Value::Null),
    }
}

/// Export a VALIDATED skill as a portable markdown document (the SkillOpt
/// best_skill.md analog). Only Active, healthy skills export; returns the
/// markdown string, or `null` if the key is absent / not exportable.
async fn handle_skill_export(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let key = msg
        .params
        .get("key")
        .and_then(|v| v.as_str())
        .ok_or("missing 'key' parameter")?;
    let engine = session.memgine.lock().await;
    Ok(engine
        .export_skill(key)
        .map(Value::String)
        .unwrap_or(Value::Null))
}

/// Import a skill from a portable markdown document (digest-verified). Ingests
/// as a fresh Active skill. Returns `{ imported: true }`, or a JSON-RPC error if
/// the document is malformed or its content digest doesn't verify.
async fn handle_skill_import(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let md = msg
        .params
        .get("markdown")
        .and_then(|v| v.as_str())
        .ok_or("missing 'markdown' parameter")?;
    let mut engine = session.memgine.lock().await;
    engine.import_skill_markdown(md)?;
    Ok(serde_json::json!({ "imported": true }))
}

/// Rerank documents against a query using a cross-encoder model.
async fn handle_rerank(msg: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    let req: car_inference::RerankRequest = typed_params(&msg.params)?;
    let _permit = state.admission.acquire().await;
    let result = engine.rerank(req).await.map_err(|e| e.to_string())?;
    serde_json::to_value(&result).map_err(|e| e.to_string())
}

/// Transcribe audio at the given path. The path is interpreted on
/// the daemon's filesystem, not the FFI caller's — Daemon-mode
/// callers must pass a path the daemon can read (typically a
/// shared `~/.car/...` location or stdin push via the streaming
/// API).
/// `search` — web search, fulfilled natively (Parslee-hosted when signed in,
/// else a bring-your-own Tavily key). Engine-independent; resolves the provider
/// from the environment. See `car_inference::search`.
async fn handle_search(msg: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let req: car_inference::search::SearchRequest =
        serde_json::from_value(msg.params.clone()).map_err(|e| format!("invalid params: {e}"))?;
    let _permit = state.admission.acquire().await;
    let result = car_inference::search::web_search(&req.query, req.max_results)
        .await
        .map_err(|e| e.to_string())?;
    serde_json::to_value(&result).map_err(|e| e.to_string())
}

/// `web_fetch` — fetch a URL and extract readable text. Keyless; the companion
/// to `search`. See `car_inference::search::web_fetch`.
async fn handle_web_fetch(msg: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let req: car_inference::search::FetchRequest =
        serde_json::from_value(msg.params.clone()).map_err(|e| format!("invalid params: {e}"))?;
    let _permit = state.admission.acquire().await;
    let result = car_inference::search::web_fetch(&req.url)
        .await
        .map_err(|e| e.to_string())?;
    serde_json::to_value(&result).map_err(|e| e.to_string())
}

async fn handle_transcribe(msg: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    use base64::Engine as _;
    let engine = get_inference_engine(state);

    // Sandbox-crossing escape hatch (Parslee-ai/car-releases#31): when
    // the caller can't share a filesystem view with the daemon (e.g.
    // unsandboxed Milo talking to a sandboxed car-host), they pass
    // `audio_b64` instead of `audio_path`. We decode to a tempfile,
    // run transcribe against the path the engine expects, and clean up
    // on drop. Accepts either form; `audio_b64` wins if both are set.
    let mut params = msg.params.clone();
    let audio_b64 = params
        .as_object_mut()
        .and_then(|m| m.remove("audio_b64"))
        .and_then(|v| v.as_str().map(str::to_string));
    let _tmp_audio = if let Some(b64) = audio_b64 {
        let bytes = base64::engine::general_purpose::STANDARD
            .decode(b64.as_bytes())
            .map_err(|e| format!("audio_b64 decode failed: {e}"))?;
        let tmp = tempfile::NamedTempFile::new().map_err(|e| e.to_string())?;
        std::fs::write(tmp.path(), &bytes).map_err(|e| e.to_string())?;
        let path = tmp.path().to_string_lossy().into_owned();
        if let Some(obj) = params.as_object_mut() {
            obj.insert("audio_path".to_string(), Value::String(path));
        }
        Some(tmp)
    } else {
        None
    };

    let req: car_inference::TranscribeRequest =
        serde_json::from_value(params).map_err(|e| format!("invalid params: {}", e))?;
    let _permit = state.admission.acquire().await;
    let result = engine.transcribe(req).await.map_err(|e| e.to_string())?;
    serde_json::to_value(&result).map_err(|e| e.to_string())
}

/// Synthesize speech. By default writes to `output_path` on the
/// daemon's filesystem; when `return_b64: true` (or no `output_path`
/// was supplied) the result also includes an `audio_b64` field with
/// the rendered bytes inline so cross-sandbox callers can avoid
/// filesystem coordination. Closes Parslee-ai/car-releases#31.
async fn handle_synthesize(msg: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    use base64::Engine as _;
    let engine = get_inference_engine(state);

    let mut params = msg.params.clone();
    let return_b64 = params
        .as_object_mut()
        .and_then(|m| m.remove("return_b64"))
        .and_then(|v| v.as_bool())
        .unwrap_or(false);
    let no_output_path = params
        .as_object()
        .map(|m| !m.contains_key("output_path"))
        .unwrap_or(true);

    let req: car_inference::SynthesizeRequest =
        serde_json::from_value(params).map_err(|e| format!("invalid params: {}", e))?;
    let _permit = state.admission.acquire().await;
    let result = engine.synthesize(req).await.map_err(|e| e.to_string())?;
    let mut value = serde_json::to_value(&result).map_err(|e| e.to_string())?;

    // Inline the bytes when the caller asked for them OR when no
    // output_path was specified (typical sandbox-crossing case —
    // they didn't pick a path because they have no shared one).
    if return_b64 || no_output_path {
        let bytes = std::fs::read(&result.audio_path).map_err(|e| {
            format!(
                "synthesize: failed to read rendered audio at {}: {e}",
                result.audio_path
            )
        })?;
        let encoded = base64::engine::general_purpose::STANDARD.encode(&bytes);
        if let Some(obj) = value.as_object_mut() {
            obj.insert("audio_b64".to_string(), Value::String(encoded));
        }
    }
    Ok(value)
}

/// Provision the managed speech runtime. Returns its root path as a JSON
/// string, mirroring the embedded `prepare_speech_runtime` shape — the same
/// root `speech.health` reports. Can take minutes on a fresh machine (venv +
/// pip). Not a success signal on Apple Silicon, where the runtime is a
/// fallback behind the native MLX backends and a failed bootstrap degrades
/// rather than errors; read `speech.health.runtime.installed` (car#649).
async fn handle_speech_prepare(state: &ServerState) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    let status = engine
        .prepare_speech_runtime()
        .await
        .map_err(|e| e.to_string())?;
    serde_json::to_value(&status).map_err(|e| e.to_string())
}

/// Adaptive route decision for a prompt — returns the routing
/// JSON the FFI's `route_model` returns.
async fn handle_models_route(msg: &JsonRpcMessage, state: &ServerState) -> Result<Value, String> {
    let prompt = msg
        .params
        .get("prompt")
        .and_then(|v| v.as_str())
        .ok_or("missing 'prompt' parameter")?;
    // Optional routing intent — notably `exclude_models` for
    // adversarial-reviewer separation (car#358). Absent = no intent.
    let intent: Option<car_inference::IntentHint> = match msg.params.get("intent") {
        Some(v) if !v.is_null() => {
            Some(serde_json::from_value(v.clone()).map_err(|e| format!("invalid 'intent': {e}"))?)
        }
        _ => None,
    };
    let engine = get_inference_engine(state);
    let decision = engine.route_adaptive_with_intent(prompt, intent).await;
    serde_json::to_value(&decision).map_err(|e| e.to_string())
}

/// Model performance profiles snapshot.
async fn handle_models_stats(state: &ServerState) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    let profiles = engine.export_profiles().await;
    Ok(serde_json::json!({ "profiles": models_stats_view(&profiles) }))
}

/// `outcomes.scoreboard` — the persistent, OUTCOME-DENOMINATED scoreboard
/// folded from the durable outcome ledger: per-model cost-per-success,
/// tokens-per-success, and success-rate, plus the deployment headline
/// `overall_usd_per_success`. Unlike `models.stats` (the live in-memory
/// profiles), this reads the cross-session ledger so it survives restart and is
/// de-biased by the pending-sweep. The dollars-per-correct-outcome view the
/// "results, not KPIs" thesis is legible in.
async fn handle_outcomes_scoreboard(state: &ServerState) -> Result<Value, String> {
    let engine = get_inference_engine(state);
    let scoreboard = engine.outcome_scoreboard();
    serde_json::to_value(&scoreboard).map_err(|e| e.to_string())
}

/// Build the `models.stats` per-profile view. The raw `ModelProfile`
/// serializes counts (`success_count`/`fail_count`) but not the
/// `success_rate` / `avg_latency_ms` the tool schema promised — so the schema
/// was a contract lie (#335). Rather than drop fields (the CLI's cost join
/// needs `total_output_tokens` etc.), serialize the full profile and *add* the
/// two derived values. `success_rate` is `number | null` (`null` until
/// something resolves — never the router's 0.5 prior), consistent with the
/// `concierge.status` health contract.
fn models_stats_view(profiles: &[car_inference::ModelProfile]) -> Vec<Value> {
    profiles
        .iter()
        .map(|p| {
            let mut v = serde_json::to_value(p).expect("ModelProfile is infallibly serializable");
            if let Some(obj) = v.as_object_mut() {
                obj.insert(
                    "success_rate".into(),
                    serde_json::json!(p.success_rate_resolved()),
                );
                obj.insert(
                    "avg_latency_ms".into(),
                    serde_json::json!(p.avg_latency_ms()),
                );
            }
            v
        })
        .collect()
}

#[cfg(test)]
mod models_stats_view_tests {
    use super::models_stats_view;

    #[test]
    fn success_rate_is_null_until_resolved_then_the_real_ratio() {
        let mut unmeasured = car_inference::ModelProfile::new("m-new".into());
        unmeasured.total_calls = 5; // calls logged, nothing resolved yet

        let mut measured = car_inference::ModelProfile::new("m-seen".into());
        measured.total_calls = 4;
        measured.success_count = 3;
        measured.fail_count = 1;

        let view = models_stats_view(&[unmeasured, measured]);

        // Never-measured: explicit null, NOT a fabricated 0.5.
        assert!(view[0]["success_rate"].is_null());
        assert_eq!(view[0]["success_count"], 0);
        assert_eq!(view[0]["total_calls"], 5);

        // Measured: the real resolved ratio, and the declared field names.
        assert_eq!(view[1]["success_rate"], 0.75);
        assert_eq!(view[1]["fail_count"], 1);
        assert_eq!(view[1]["model_id"], "m-seen");
    }

    #[test]
    fn view_is_non_lossy_and_round_trips_into_model_profile() {
        // Regression: the CLI (`car models stats`) deserializes the daemon
        // payload back into `Vec<ModelProfile>` for its cost join. The derived
        // view must therefore stay a *superset* of ModelProfile — adding
        // success_rate/avg_latency_ms, never dropping fields like
        // total_output_tokens. Guards the wire shape against silent breakage.
        let mut p = car_inference::ModelProfile::new("m".into());
        p.total_calls = 2;
        p.success_count = 1;
        p.total_output_tokens = 4096;

        let view = models_stats_view(&[p]);
        assert_eq!(view[0]["avg_latency_ms"], 0.0); // derived field present
        let round: Vec<car_inference::ModelProfile> =
            serde_json::from_value(serde_json::Value::Array(view)).expect("round-trips");
        assert_eq!(round[0].total_output_tokens, 4096, "field not dropped");
        assert_eq!(round[0].model_id, "m");
    }
}

#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct OutcomesResolvePendingParams {
    /// Flat `(trace_id, success, confidence, output)` tuples from the
    /// caller. Same shape `car-reason`'s session produces from its
    /// `ActionOutcome` vector. Daemon side runs the inference rules
    /// and writes resolved outcomes back to the shared tracker.
    action_results: Vec<(String, bool, f64, String)>,
}

/// `outcomes.resolve_pending` — write inferred outcomes back to the
/// shared engine's `OutcomeTracker` (Parslee-ai/car#189 follow-up).
///
/// Symmetric to the in-process path
/// `ReasoningInferenceHandle::record_inferred_outcomes` on
/// `InferenceEngine`: takes the per-action result tuples the
/// reasoning session produces, runs
/// `OutcomeTracker::infer_outcomes_from_action_sequence` to convert
/// them into `InferredOutcome` records, and calls
/// `resolve_pending_from_signals` under the tracker write lock. The
/// learning loop that adjusts routing decisions therefore survives
/// daemon-routed reasoning runs (previously a best-effort no-op on
/// the daemon side).
///
/// Returns `{ recorded: N }` where N is the number of action results
/// the caller passed. The tracker doesn't surface how many of those
/// actually had pending entries to resolve; that count would require
/// expanding the tracker API and isn't load-bearing for any caller
/// yet.
async fn handle_outcomes_resolve_pending(
    req: &JsonRpcMessage,
    state: &ServerState,
) -> Result<Value, String> {
    let params: OutcomesResolvePendingParams =
        serde_json::from_value(req.params.clone()).map_err(|e| format!("invalid params: {e}"))?;
    let engine = get_inference_engine(state);
    let mut tracker = engine.outcome_tracker.write().await;
    let inferred = tracker.infer_outcomes_from_action_sequence(&params.action_results);
    tracker.resolve_pending_from_signals(inferred);
    Ok(serde_json::json!({ "recorded": params.action_results.len() }))
}

/// Per-session event log size.
async fn handle_events_count(session: &crate::session::ClientSession) -> Result<Value, String> {
    let n = session.runtime.log.lock().await.len();
    Ok(Value::from(n as u64))
}

/// `events.query` — structured audit query over the session event log
/// (EPIC G / G2). Params are a `car_eventlog::EventQuery`
/// (`kinds`/`action_id`/`proposal_id`/`since`/`until`/`data_matches`/`limit`);
/// returns the matching events, most-recent-first. `ActionFailed.data` exposes
/// `params_digest`, `expected_effects`, and normalized `error_class`
/// (`timeout|rejected_by_policy|tool_error|validation|unknown`) without raw
/// parameters; `ActionSucceeded.data` carries the first two. Answers "who ran
/// what tool when, and which approvals applied" against the SessionScope /
/// PermissionDecision / ApprovalRecorded / action trail.
async fn handle_events_query(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let query: car_eventlog::EventQuery = if msg.params.is_null() {
        Default::default()
    } else {
        serde_json::from_value(msg.params.clone())
            .map_err(|e| format!("invalid events.query params: {e}"))?
    };
    let log = session.runtime.log.lock().await;
    let events = log.query(&query);
    Ok(serde_json::json!({
        "count": events.len(),
        "events": events,
    }))
}

/// Which NLP primitive a `nlp.*` request selects (EPIC F / F4).
enum NlpOp {
    IdentifyLanguage,
    Tokenize,
    ExtractEntities,
}

/// `nlp.identify_language` / `nlp.tokenize` / `nlp.extract_entities` — run a
/// stateless NLP primitive over `params.text` (EPIC F / F4). Backed by Apple's
/// NaturalLanguage framework on macOS and a pure-Rust fallback elsewhere, so
/// non-macOS agents get a real (if lighter) result instead of an error. Every
/// result carries `backend` (`"apple"`|`"fallback"`).
fn handle_nlp(req: &JsonRpcMessage, op: NlpOp) -> Result<Value, String> {
    let text = req
        .params
        .get("text")
        .and_then(|v| v.as_str())
        .ok_or("missing 'text'")?;
    let json = match op {
        NlpOp::IdentifyLanguage => car_ffi_common::nlp::identify_language(text),
        NlpOp::Tokenize => car_ffi_common::nlp::tokenize_words(text),
        NlpOp::ExtractEntities => car_ffi_common::nlp::extract_named_entities(text),
    }?;
    serde_json::from_str(&json).map_err(|e| format!("nlp result parse: {e}"))
}

/// `metrics.summary` — live operational rollup of the session event stream
/// (EPIC G / G1): success/error rate, cost, tokens, avg latency, approvals,
/// gate rejections, policy violations, and the per-agent cost breakdown. One
/// call renders the whole live picture for a host dashboard.
async fn handle_metrics_summary(session: &crate::session::ClientSession) -> Result<Value, String> {
    let log = session.runtime.log.lock().await;
    // summarize_log (not a bare fold over events()) so `cumulative_cost_usd`
    // carries the monotonic counter that survives retention trims (G1).
    let summary = car_eventlog::summarize_log(&log);
    serde_json::to_value(&summary).map_err(|e| format!("serialize metrics.summary: {e}"))
}

/// `metrics.alerts` — evaluate the live summary against operational thresholds
/// (EPIC G / G1). Params are `AlertThresholds`
/// (`max_cost_usd`/`max_error_rate`/`max_avg_latency_ms`/
/// `max_goals_ungrounded`/`min_actions`).
/// Returns `{ summary, alerts }`; every fired alert is also written to the
/// operational log (`tracing::warn`) so an operator sees it out-of-band. A
/// synthetic cost overage fires the `cost_overage` alert; an ungrounded goal
/// verifier pass can fire `goal_ungrounded`.
async fn handle_metrics_alerts(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let thresholds: car_eventlog::AlertThresholds = if req.params.is_null() {
        Default::default()
    } else {
        serde_json::from_value(req.params.clone())
            .map_err(|e| format!("invalid metrics.alerts thresholds: {e}"))?
    };
    let log = session.runtime.log.lock().await;
    // The budget alert reads the monotonic cumulative cost, not a fold over
    // the retention-trimmed window — a trim must never un-fire it (G1).
    let summary = car_eventlog::summarize_log(&log);
    let alerts = car_eventlog::evaluate_alerts(&summary, &thresholds);
    for a in &alerts {
        tracing::warn!(target: "car::alerts", kind = ?a.kind, "operational alert: {}", a.message);
    }
    Ok(serde_json::json!({ "summary": summary, "alerts": alerts }))
}

/// `events.cost_by_agent` — per-agent token/cost report (EPIC G / G3),
/// folded from the session log's `InferenceMetered` events by their `agent`
/// field. Answers "how much did each agent cost this run" (e.g. Researcher
/// $2, Coordinator $0.5). Provenance (which tool/workflow) is queryable via
/// `events.query {data_matches:{agent}}`.
async fn handle_events_cost_by_agent(
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let log = session.runtime.log.lock().await;
    let report = log.cost_by_agent();
    serde_json::to_value(&report).map_err(|e| format!("serialize cost_by_agent: {e}"))
}

/// `events.retention` — get or set the session event log's auto-retention
/// policy (EPIC G / G2). With a `policy` object (`{max_events, max_age_secs}`)
/// installs it and immediately enforces the age bound, returning how many
/// events were reaped; with no `policy` returns the current policy. Bounds the
/// log by size (auto on append) and age (on this call).
async fn handle_events_retention(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let mut log = session.runtime.log.lock().await;
    if let Some(p) = msg.params.get("policy") {
        let policy: car_eventlog::RetentionPolicy = serde_json::from_value(p.clone())
            .map_err(|e| format!("invalid retention policy: {e}"))?;
        let removed = log.enforce_retention(&policy, chrono::Utc::now());
        log.set_retention(Some(policy.clone()));
        Ok(serde_json::json!({ "policy": policy, "removed": removed }))
    } else {
        Ok(serde_json::json!({ "policy": log.retention() }))
    }
}

/// `events.chain.enable` — turn on tamper-evident hash chaining for the
/// session event log (EPIC A / A9). Every event appended from now on is
/// linked to its predecessor by a content hash. Opt-in and idempotent;
/// existing events stay byte-identical.
async fn handle_events_chain_enable(
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    session.runtime.enable_event_log_hash_chaining().await;
    Ok(serde_json::json!({ "ok": true }))
}

/// `events.chain.verify` — verify the session event log's tamper-evidence
/// chain (EPIC A / A9). Returns `{verified: n}` (chained events verified) or
/// `{tampered_at: i}` naming the first event whose hash/linkage doesn't
/// match — an interior edit, deletion, or reordering. Head/tail truncation
/// is not detectable (no anchored head hash).
async fn handle_events_chain_verify(
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    match session.runtime.verify_event_log_chain().await {
        Ok(n) => Ok(serde_json::json!({ "verified": n })),
        Err(i) => Ok(serde_json::json!({ "tampered_at": i })),
    }
}

async fn handle_events_stats(session: &crate::session::ClientSession) -> Result<Value, String> {
    let stats = session.runtime.log.lock().await.stats();
    serde_json::to_value(stats).map_err(|e| e.to_string())
}

#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct EventsTruncateParams {
    #[serde(default)]
    max_events: Option<usize>,
    #[serde(default)]
    max_spans: Option<usize>,
}

async fn handle_events_truncate(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let params: EventsTruncateParams =
        serde_json::from_value(msg.params.clone()).unwrap_or(EventsTruncateParams {
            max_events: None,
            max_spans: None,
        });
    let mut log = session.runtime.log.lock().await;
    let removed_events = params
        .max_events
        .map(|max| log.truncate_events_keep_last(max))
        .unwrap_or(0);
    let removed_spans = params
        .max_spans
        .map(|max| log.truncate_spans_keep_last(max))
        .unwrap_or(0);
    let stats = log.stats();
    Ok(serde_json::json!({
        "removedEvents": removed_events,
        "removedSpans": removed_spans,
        "stats": stats,
    }))
}

async fn handle_events_clear(session: &crate::session::ClientSession) -> Result<Value, String> {
    let mut log = session.runtime.log.lock().await;
    let removed = log.clear();
    Ok(serde_json::json!({ "removed": removed, "stats": log.stats() }))
}

// ---------------------------------------------------------------------------
// Agent run tracing — run lifecycle (U1).
//
// `runs.start` brackets the beginning of an agent run: it mints a durable
// `run_id`, resolves the owning `agent_id`, tags it as the session's
// current run BEFORE responding (so the U2 per-turn recorder always reads
// the run_id the bracket set — KTD3), records `RunStarted`, and returns
// `{ run_id, agent_id }`. `runs.complete` records the terminal
// `AgentOutcome` and acks. On a mid-run disconnect with no
// `runs.complete`, `remove_session` sweeps the run to `Incomplete` after
// a short grace window (R5) so a healthy in-flight complete is not raced.
// ---------------------------------------------------------------------------

/// Resolve the owning `agent_id` for a `runs.start` call, in priority
/// order: the connection's bound agent (`session.auth {agent_id}`), the
/// `CAR_AGENT_ID` env (supervised one-shot), then a deterministic id
/// synthesized from the supplied `agent_name` (unsupervised one-shot, so
/// `run_scenarios.py` runs still record). Returns `Err` only when none of
/// these resolve — a run with no identity has no durable key and is
/// rejected rather than recorded under an ambiguous id.
async fn resolve_run_agent_id(
    session: &crate::session::ClientSession,
    req: &car_proto::RunStartRequest,
) -> Result<String, String> {
    // 1. The connection's bound agent from `session.auth {agent_id}` is
    //    AUTHORITATIVE and wins over any caller-supplied `agent_id` (FIX 5).
    //    A bound session must not be able to record a run under a DIFFERENT
    //    agent — that's trace forgery (writing into another agent's run
    //    history). A matching explicit param is fine (redundant); a
    //    mismatching one is rejected so the forgery attempt is loud rather
    //    than silently misattributed.
    if let Some(bound) = session.agent_id.lock().await.clone() {
        if let Some(id) = req.agent_id.as_deref() {
            let id = id.trim();
            if !id.is_empty() && id != bound {
                return Err(format!(
                    "runs.start `agent_id` (`{id}`) does not match this session's bound \
                     agent: a bound connection can only record runs under its own agent"
                ));
            }
        }
        return Ok(bound);
    }
    // 2. UNBOUND session only: an explicit `agent_id` param wins. This is
    //    the one-shot path that legitimately names its agent (no binding to
    //    derive from).
    if let Some(id) = req.agent_id.as_deref() {
        let id = id.trim();
        if !id.is_empty() {
            return Ok(id.to_string());
        }
    }
    // 3. The supervisor-injected env for supervised one-shot runs.
    if let Ok(env_id) = std::env::var("CAR_AGENT_ID") {
        let env_id = env_id.trim().to_string();
        if !env_id.is_empty() {
            return Ok(env_id);
        }
    }
    // 4. Unsupervised one-shot fallback: synthesize a deterministic id
    //    from the agent's name so the run still has a stable key.
    if let Some(name) = req.agent_name.as_deref() {
        if let Some(synth) = synthesize_agent_id(name) {
            return Ok(synth);
        }
    }
    Err(
        "runs.start could not resolve an agent_id: no `agent_id` param, no bound \
         session.auth {agent_id}, no CAR_AGENT_ID env, and no usable `agent_name` \
         to synthesize one from"
            .to_string(),
    )
}

/// Deterministically derive a stable agent id from a display name for
/// the unsupervised one-shot path. Lowercases, collapses any run of
/// non-alphanumeric characters to a single `-`, trims leading/trailing
/// `-`, and prefixes `name:` so a synthesized id is recognizable as a
/// name-derived fallback (and never collides with a real supervised
/// agent id, which has no `name:` prefix). Returns `None` when the name
/// has no alphanumeric content to key on.
fn synthesize_agent_id(name: &str) -> Option<String> {
    let mut slug = String::new();
    let mut prev_dash = false;
    for ch in name.chars() {
        if ch.is_ascii_alphanumeric() {
            slug.push(ch.to_ascii_lowercase());
            prev_dash = false;
        } else if !prev_dash {
            slug.push('-');
            prev_dash = true;
        }
    }
    let slug = slug.trim_matches('-');
    if slug.is_empty() {
        return None;
    }
    Some(format!("name:{slug}"))
}

async fn release_new_run_reservation_after_error(
    state: &ServerState,
    session: &crate::session::ClientSession,
    requested: &crate::session::RunMeta,
    error: String,
) -> String {
    match state
        .release_unpersisted_run_reservation(session, requested)
        .await
    {
        Ok(()) => error,
        Err(cleanup) => format!("{error}; failed to release new run reservation: {cleanup}"),
    }
}

async fn handle_runs_start(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let params: car_proto::RunStartRequest = serde_json::from_value(req.params.clone())
        .map_err(|e| format!("runs.start requires {{ intent, agent_id?, agent_name?, outcome_description?, idempotency_key? }}: {e}"))?;
    if params.intent.trim().is_empty() {
        return Err("runs.start requires a non-empty `intent`".to_string());
    }

    let agent_id = resolve_run_agent_id(session, &params).await?;
    let _run_guard = session.run_lifecycle_guard.lock().await;
    let idempotency_key = params
        .idempotency_key
        .as_deref()
        .map(str::trim)
        .filter(|k| !k.is_empty())
        .map(str::to_string);
    let run_id = idempotency_key.unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
    let current_run = session.current_run_id.lock().await.clone();
    let requested_meta = crate::session::RunMeta {
        run_id: run_id.clone(),
        agent_id: agent_id.clone(),
        client_id: session.client_id.clone(),
        active_client_id: session.client_id.clone(),
        resume_predecessor_client_id: None,
        resume_lease: None,
        intent: params.intent.clone(),
        outcome_description: params.outcome_description.clone(),
        started_at: chrono::Utc::now(),
        termination: None,
        ended_at: None,
        turns: Vec::new(),
        start_committed: false,
        pending_terminal: None,
        cancellation_pending: None,
        cancellation_receipt: None,
        trace_corruption: None,
        durability_generation: 0,
    };
    if let Some(current) = current_run.as_deref() {
        if let Some(pending) = state
            .run_store
            .pending_proposal(current)
            .map_err(|error| proposal_durability_quarantine(current, "finalization", &error))?
        {
            return Err(format!(
                "proposal finalization pending for run_id `{current}` / original submission `{}`",
                pending.original_proposal_id
            ));
        }
        if let Some(marker) = state
            .run_store
            .execution_marker(current)
            .map_err(|error| proposal_durability_quarantine(current, "execution", &error))?
        {
            return Err(format!(
                "proposal execution outcome unknown for run_id `{current}` / original submission `{}`; CAR will not replace or terminalize the quarantined run",
                marker.original_proposal_id
            ));
        }
    }
    if let Some(pending) = state
        .run_store
        .pending_proposal(&run_id)
        .map_err(|error| proposal_durability_quarantine(&run_id, "finalization", &error))?
    {
        return Err(format!(
            "proposal finalization pending for run_id `{run_id}` / original submission `{}`",
            pending.original_proposal_id
        ));
    }
    if let Some(marker) = state
        .run_store
        .execution_marker(&run_id)
        .map_err(|error| proposal_durability_quarantine(&run_id, "execution", &error))?
    {
        return Err(format!(
            "proposal execution outcome unknown for run_id `{run_id}` / original submission `{}`; CAR will not reopen or redispatch automatically",
            marker.original_proposal_id
        ));
    }
    // Reserve first so a stale/conflicting target is rejected without
    // terminalizing the current run. Every later error before the candidate
    // owns a journal/RunStore boundary releases a New reservation exactly.
    let reservation = state.reserve_run(requested_meta.clone()).await?;
    let reservation_is_new = matches!(&reservation, crate::session::RunReservation::New);

    if let crate::session::RunReservation::Existing(existing) = &reservation {
        if let Some(error) = &existing.trace_corruption {
            return Err(error.clone());
        }
        if existing.is_terminal() {
            return Err(format!(
                "{} run `{run_id}` is already terminal",
                car_proto::RUN_OWNERSHIP_CONFLICT_MESSAGE_PREFIX
            ));
        }
    }

    let current_resolution: Result<Option<Value>, String> = async {
        if let Some(current) = current_run.as_deref() {
            if current == run_id {
                let (owner, terminal, committed, pending) = state
                    .run_lifecycle_state(current)
                    .await
                    .ok_or_else(|| {
                        format!("reserved run `{current}` is absent from CAR registry")
                    })?;
                if owner != session.client_id || terminal {
                    return Err(format!(
                        "{} run `{current}` is not resumable by this client",
                        car_proto::RUN_OWNERSHIP_CONFLICT_MESSAGE_PREFIX
                    ));
                }
                session.require_run_journal_binding(current).await?;
                if pending {
                    let ended = state
                        .prepare_run_incomplete(current)
                        .await
                        .ok_or_else(|| {
                            format!("active run `{current}` could not resume its pending terminal")
                        })?;
                    session.append_run_terminal_event(&ended).await?;
                    state.commit_run_completion(&ended).await?;
                    session.clear_run_journal_binding(current).await?;
                    *session.current_run_id.lock().await = None;
                    return Err(format!(
                        "{} run `{current}` is already terminal",
                        car_proto::RUN_OWNERSHIP_CONFLICT_MESSAGE_PREFIX
                    ));
                }
                if committed {
                    return serde_json::to_value(car_proto::RunStartResponse {
                        run_id: current.to_string(),
                        agent_id: agent_id.clone(),
                        client_id: session.client_id.clone(),
                    })
                    .map(Some)
                    .map_err(|e| e.to_string());
                }
            } else {
                let (owner, terminal, committed, _pending) = state
                    .run_lifecycle_state(current)
                    .await
                    .ok_or_else(|| {
                        format!("active run `{current}` is absent from CAR registry")
                    })?;
                if owner != session.client_id {
                    return Err(format!(
                        "{} active run `{current}` belongs to another client",
                        car_proto::RUN_OWNERSHIP_CONFLICT_MESSAGE_PREFIX
                    ));
                }
                session.require_run_journal_binding(current).await?;
                if !terminal {
                    if !committed {
                        return Err(format!(
                            "{} active run `{current}` has an unacknowledged durable start; retry its exact idempotency key and occurrence-defining payload before starting `{run_id}`",
                            car_proto::RUN_OWNERSHIP_CONFLICT_MESSAGE_PREFIX
                        ));
                    }
                    // Reuse an already prepared terminal so a retry finishes
                    // its exact outcome rather than overwriting it.
                    let ended = state
                        .prepare_run_incomplete(current)
                        .await
                        .ok_or_else(|| {
                            format!("active run `{current}` could not be terminalized")
                        })?;
                    session.append_run_terminal_event(&ended).await?;
                    state.commit_run_completion(&ended).await?;
                }
                session.clear_run_journal_binding(current).await?;
                *session.current_run_id.lock().await = None;
            }
        }
        Ok(None)
    }
    .await;
    match current_resolution {
        Ok(Some(response)) => return Ok(response),
        Ok(None) => {}
        Err(error) => {
            if reservation_is_new {
                return Err(release_new_run_reservation_after_error(
                    state,
                    session,
                    &requested_meta,
                    error,
                )
                .await);
            }
            return Err(error);
        }
    }

    let binding_preexisting = current_run.as_deref() == Some(run_id.as_str());
    if !binding_preexisting {
        if let Err(error) = session.bind_run_journal(&run_id).await {
            if reservation_is_new {
                return Err(release_new_run_reservation_after_error(
                    state,
                    session,
                    &requested_meta,
                    error,
                )
                .await);
            }
            return Err(error);
        }
    }

    *session.current_run_id.lock().await = Some(run_id.clone());
    let start_result = async {
        let started = state.persist_run_start(&run_id).await?;
        session.append_run_started_event(&started).await?;
        state.commit_run_start(&run_id).await
    }
    .await;
    if let Err(error) = start_result {
        match state.run_store.run_started(&run_id) {
            Ok(None) => {
                match state
                    .reconcile_or_release_unacknowledged_start(session, &run_id)
                    .await
                {
                    Ok(true) => return Err(error),
                    Ok(false) => {
                        return Err(format!(
                            "{error}; run `{run_id}` became durable during rollback; retry the exact idempotency key and occurrence-defining payload"
                        ));
                    }
                    Err(cleanup) => {
                        return Err(format!(
                            "{error}; failed to release rejected start reservation: {cleanup}"
                        ));
                    }
                }
            }
            Ok(Some(_)) => {
                return Err(format!(
                    "{error}; {} run `{run_id}` has an unacknowledged durable start; retry the exact idempotency key and occurrence-defining payload",
                    car_proto::RUN_OWNERSHIP_CONFLICT_MESSAGE_PREFIX
                ));
            }
            Err(read_error) => {
                return Err(format!(
                    "{error}; durable start state for run `{run_id}` is unreadable ({read_error}); retry only the exact idempotency key and occurrence-defining payload"
                ));
            }
        }
    }

    serde_json::to_value(car_proto::RunStartResponse {
        run_id,
        agent_id,
        client_id: session.client_id.clone(),
    })
    .map_err(|e| e.to_string())
}

async fn handle_runs_resume(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    if !session_has_capability(session, car_proto::RUNS_RESUME_CAPABILITY) {
        return Err(format!(
            "runs.resume requires negotiated capability `{}`",
            car_proto::RUNS_RESUME_CAPABILITY
        ));
    }
    let params: car_proto::RunResumeRequest = serde_json::from_value(req.params.clone())
        .map_err(|error| format!("runs.resume requires exactly {{ run_id }}: {error}"))?;
    if params.run_id.trim().is_empty() {
        return Err("runs.resume run_id must be non-empty".into());
    }
    if !session.authenticated.load(Ordering::Acquire) {
        return Err("runs.resume requires an authenticated agent session".into());
    }
    let agent_id = session
        .agent_id
        .lock()
        .await
        .clone()
        .ok_or_else(|| "runs.resume requires session.auth with an agent_id".to_string())?;

    let _run_guard = session.run_lifecycle_guard.lock().await;
    let current = session.current_run_id.lock().await.clone();
    if current
        .as_deref()
        .is_some_and(|current| current != params.run_id)
    {
        return Err(format!(
            "runs.resume cannot replace this socket's active run `{}`",
            current.expect("checked as present")
        ));
    }

    let binding_preexisting = current.as_deref() == Some(params.run_id.as_str());
    if !binding_preexisting {
        session.bind_run_journal(&params.run_id).await?;
    }
    let resumed = match state
        .resume_run(&params.run_id, &agent_id, &session.client_id)
        .await
    {
        Ok(binding) => binding,
        Err(error) => {
            if !binding_preexisting {
                let _ = session.clear_run_journal_binding(&params.run_id).await;
            }
            return Err(error);
        }
    };
    *session.current_run_id.lock().await = Some(params.run_id.clone());

    serde_json::to_value(car_proto::RunResumeResponse {
        run_id: resumed.run_id,
        agent_id: resumed.agent_id,
        client_id: resumed.active_client_id,
        resumed_from_client_id: resumed.resumed_from_client_id,
    })
    .map_err(|error| error.to_string())
}

async fn handle_runs_complete(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let params: car_proto::RunCompleteRequest = serde_json::from_value(req.params.clone())
        .map_err(|e| format!("runs.complete requires {{ run_id, outcome }}: {e}"))?;

    let _run_guard = session.run_lifecycle_guard.lock().await;
    let current = session.current_run_id.lock().await.clone();
    if current.as_deref() != Some(params.run_id.as_str()) {
        return Err(format!(
            "runs.complete run_id `{}` is not this client's active run",
            params.run_id
        ));
    }
    let (owner_client, _terminal, start_committed, _completion_pending) = state
        .run_lifecycle_state(&params.run_id)
        .await
        .ok_or_else(|| format!("unknown run_id `{}`", params.run_id))?;
    let (durable_client, active_client) = state
        .run_owner_binding(&params.run_id)
        .await
        .ok_or_else(|| format!("unknown run_id `{}`", params.run_id))?;
    if owner_client != session.client_id || !start_committed {
        return Err("runs.complete client/run binding mismatch".into());
    }
    if active_client != session.client_id {
        return Err("runs.complete active owner mismatch".into());
    }
    session.require_run_journal_binding(&params.run_id).await?;
    if let Some(pending) = state
        .run_store
        .pending_proposal(&params.run_id)
        .map_err(|error| proposal_durability_quarantine(&params.run_id, "finalization", &error))?
    {
        return Err(format!(
            "proposal finalization pending for run_id `{}` / original submission `{}`",
            params.run_id, pending.original_proposal_id
        ));
    }
    if let Some(marker) = state
        .run_store
        .execution_marker(&params.run_id)
        .map_err(|error| proposal_durability_quarantine(&params.run_id, "execution", &error))?
    {
        return Err(format!(
            "proposal execution outcome unknown for run_id `{}` / original submission `{}`; runs.complete is quarantined",
            params.run_id, marker.original_proposal_id
        ));
    }

    let termination = car_proto::RunTermination::Outcome {
        status: params.outcome.status,
        outcome: params.outcome.clone(),
    };
    let ended = state
        .prepare_run_completion_for_active_owner(
            &params.run_id,
            termination,
            Some(&session.client_id),
        )
        .await?;
    if durable_client == session.client_id {
        session.append_run_terminal_event(&ended).await?;
    } else {
        session
            .append_resumed_run_terminal_event(&ended, &durable_client)
            .await?;
    }
    state.commit_run_completion(&ended).await?;
    let completion_digest = ended
        .completion_digest
        .clone()
        .ok_or_else(|| "terminal run is missing completion_digest".to_string())?;

    // Both durable surfaces are now acknowledged. Only at this point may the
    // authenticated journal/session binding be released; every earlier error
    // leaves it intact so the owner can retry the same prepared terminal.
    session.clear_run_journal_binding(&params.run_id).await?;
    *session.current_run_id.lock().await = None;

    serde_json::to_value(car_proto::RunCompleteResponse {
        run_id: params.run_id,
        ok: true,
        completion_digest,
    })
    .map_err(|e| e.to_string())
}

#[derive(Serialize)]
struct RunCancelReceiptPreimage<'a> {
    receipt_version: u32,
    run_id: &'a str,
    idempotency_key: &'a str,
    reason_digest: &'a str,
    principal: &'a str,
    status: car_proto::RunCancellationStatus,
    terminal_digest: &'a Option<String>,
    action_id: &'a Option<String>,
    request_id: &'a Option<String>,
}

fn run_cancel_receipt(
    requested: &car_proto::RunCancellationRequested,
    status: car_proto::RunCancellationStatus,
    terminal_digest: Option<String>,
) -> Result<car_proto::RunCancelResponse, String> {
    let preimage = RunCancelReceiptPreimage {
        receipt_version: requested.receipt_version,
        run_id: &requested.run_id,
        idempotency_key: &requested.idempotency_key,
        reason_digest: &requested.reason_digest,
        principal: &requested.principal,
        status,
        terminal_digest: &terminal_digest,
        action_id: &requested.action_id,
        request_id: &requested.request_id,
    };
    let receipt_digest = car_proto::canonical_sha256(&preimage)?;
    Ok(car_proto::RunCancelResponse {
        receipt_version: requested.receipt_version,
        run_id: requested.run_id.clone(),
        idempotency_key: requested.idempotency_key.clone(),
        reason_digest: requested.reason_digest.clone(),
        principal: requested.principal.clone(),
        status,
        terminal_digest,
        action_id: requested.action_id.clone(),
        request_id: requested.request_id.clone(),
        receipt_digest,
    })
}

fn run_cancel_terminal_receipt(
    params: &car_proto::RunCancelRequest,
    reason_digest: &str,
    principal: &str,
    ended: &car_proto::RunEnded,
) -> Result<car_proto::RunCancelResponse, String> {
    let terminal_digest = ended
        .completion_digest
        .clone()
        .ok_or_else(|| "terminal run is missing completion_digest".to_string())?;
    let (requested, status) = match &ended.termination {
        car_proto::RunTermination::Cancelled { cancellation }
            if cancellation.idempotency_key == params.idempotency_key
                && cancellation.reason_digest == reason_digest
                && cancellation.principal == principal =>
        {
            (
                car_proto::RunCancellationRequested {
                    receipt_version: cancellation.receipt_version,
                    run_id: cancellation.run_id.clone(),
                    idempotency_key: cancellation.idempotency_key.clone(),
                    reason_digest: cancellation.reason_digest.clone(),
                    principal: cancellation.principal.clone(),
                    action_id: cancellation.action_id.clone(),
                    request_id: cancellation.request_id.clone(),
                },
                car_proto::RunCancellationStatus::CancelledConfirmed,
            )
        }
        car_proto::RunTermination::Cancelled { cancellation } => (
            car_proto::RunCancellationRequested {
                receipt_version: 1,
                run_id: params.run_id.clone(),
                idempotency_key: params.idempotency_key.clone(),
                reason_digest: reason_digest.to_string(),
                principal: principal.to_string(),
                action_id: cancellation.action_id.clone(),
                request_id: cancellation.request_id.clone(),
            },
            car_proto::RunCancellationStatus::AlreadyTerminal,
        ),
        _ => (
            car_proto::RunCancellationRequested {
                receipt_version: 1,
                run_id: params.run_id.clone(),
                idempotency_key: params.idempotency_key.clone(),
                reason_digest: reason_digest.to_string(),
                principal: principal.to_string(),
                action_id: None,
                request_id: None,
            },
            car_proto::RunCancellationStatus::AlreadyTerminal,
        ),
    };
    run_cancel_receipt(&requested, status, Some(terminal_digest))
}

async fn handle_runs_cancel(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    if !session_has_capability(session, car_proto::RUNS_CANCEL_CAPABILITY) {
        return Err(format!(
            "runs.cancel requires negotiated capability `{}`",
            car_proto::RUNS_CANCEL_CAPABILITY
        ));
    }
    let params: car_proto::RunCancelRequest =
        serde_json::from_value(req.params.clone()).map_err(|error| {
            format!("runs.cancel requires exactly {{ run_id, idempotency_key, reason }}: {error}")
        })?;
    if params.run_id.trim().is_empty()
        || params.idempotency_key.trim().is_empty()
        || params.reason.trim().is_empty()
    {
        return Err("runs.cancel fields must be non-empty".into());
    }
    if params.idempotency_key.len() > 128 {
        return Err("runs.cancel idempotency_key exceeds 128 bytes".into());
    }
    if params.reason.len() > 1024 {
        return Err("runs.cancel reason exceeds 1024 bytes".into());
    }

    let meta = state.run_meta(&params.run_id).await;
    let owning_agent = meta
        .as_ref()
        .map(|meta| meta.agent_id.clone())
        .or_else(|| state.run_store.agent_for_run(&params.run_id));
    let Some(owning_agent) = owning_agent else {
        return Err("run not found or not authorized".into());
    };
    if authorize_run_access(session, state, &owning_agent)
        .await
        .is_err()
    {
        return Err("run not found or not authorized".into());
    }
    let principal = if session.is_host.load(Ordering::Acquire) {
        "host".to_string()
    } else {
        format!("agent:{owning_agent}")
    };
    let reason_digest = format!("{:x}", Sha256::digest(params.reason.as_bytes()));

    let records = state
        .run_store
        .get_run_trace_for_checked(&owning_agent, &params.run_id)
        .map_err(|error| format!("runs.cancel trace read failed: {error}"))?
        .ok_or_else(|| "run not found or not authorized".to_string())?;
    let existing_result = records.iter().find_map(|record| match record {
        car_proto::RunRecord::CancellationResult(result) => Some(result),
        _ => None,
    });
    if let Some(existing) = existing_result {
        if existing.idempotency_key != params.idempotency_key
            || existing.reason_digest != reason_digest
            || existing.principal != principal
        {
            return Err("run already has a different cancellation request".into());
        }
    }
    if let Some(ended) = records.iter().find_map(|record| match record {
        car_proto::RunRecord::Ended(ended) => Some(ended),
        _ => None,
    }) {
        return serde_json::to_value(run_cancel_terminal_receipt(
            &params,
            &reason_digest,
            &principal,
            ended,
        )?)
        .map_err(|error| error.to_string());
    }

    let existing_requested = records.iter().find_map(|record| match record {
        car_proto::RunRecord::CancellationRequested(requested) => Some(requested),
        _ => None,
    });
    if let Some(existing) = existing_result {
        let owner_session = match meta.as_ref() {
            Some(meta) => state.sessions.lock().await.get(&meta.client_id).cloned(),
            None => None,
        };
        match owner_session {
            Some(owner_session) => {
                state
                    .persist_run_cancellation_result(&owner_session, existing)
                    .await?;
            }
            None => {
                state
                    .persist_recovered_run_cancellation_result(&owning_agent, existing)
                    .await?;
            }
        }
        return serde_json::to_value(existing).map_err(|error| error.to_string());
    }
    let Some(meta) = meta else {
        let Some(requested) = existing_requested else {
            return Err("run cancellation control is unavailable".into());
        };
        if requested.idempotency_key != params.idempotency_key
            || requested.reason_digest != reason_digest
            || requested.principal != principal
        {
            return Err("run already has a different cancellation request".into());
        }
        let response = run_cancel_receipt(
            requested,
            car_proto::RunCancellationStatus::TerminationUnconfirmed,
            None,
        )?;
        state
            .persist_recovered_run_cancellation_result(&owning_agent, &response)
            .await?;
        return serde_json::to_value(response).map_err(|error| error.to_string());
    };
    let owner_session = state.sessions.lock().await.get(&meta.client_id).cloned();
    let Some(owner_session) = owner_session else {
        let Some(requested) = existing_requested else {
            return Err("run cancellation control is unavailable".into());
        };
        if requested.idempotency_key != params.idempotency_key
            || requested.reason_digest != reason_digest
            || requested.principal != principal
        {
            return Err("run already has a different cancellation request".into());
        }
        let response = run_cancel_receipt(
            requested,
            car_proto::RunCancellationStatus::TerminationUnconfirmed,
            None,
        )?;
        state
            .persist_recovered_run_cancellation_result(&owning_agent, &response)
            .await?;
        return serde_json::to_value(response).map_err(|error| error.to_string());
    };

    // Serialize against runs.complete for the opening session. Re-read the
    // durable trace after acquiring the guard: a completion that won before
    // cancellation must return the closed already_terminal vocabulary, while
    // a cancellation that wins keeps completion blocked until its durable
    // terminal or quarantine receipt is committed.
    let _run_guard = owner_session.run_lifecycle_guard.lock().await;
    let guarded_records = state
        .run_store
        .get_run_trace_for_checked(&owning_agent, &params.run_id)
        .map_err(|error| format!("runs.cancel guarded trace read failed: {error}"))?
        .ok_or_else(|| "run not found or not authorized".to_string())?;
    if let Some(ended) = guarded_records.iter().find_map(|record| match record {
        car_proto::RunRecord::Ended(ended) => Some(ended),
        _ => None,
    }) {
        return serde_json::to_value(run_cancel_terminal_receipt(
            &params,
            &reason_digest,
            &principal,
            ended,
        )?)
        .map_err(|error| error.to_string());
    }

    let mut active: Vec<(String, String)> = owner_session
        .channel
        .active_actions
        .lock()
        .await
        .iter()
        .map(|(request_id, action_id)| (request_id.clone(), action_id.clone()))
        .collect();
    active.sort();
    let active_inferences = owner_session
        .inference_control
        .active_for_run(&params.run_id);
    let (request_id, action_id) = active
        .first()
        .map(|(request_id, action_id)| (Some(request_id.clone()), Some(action_id.clone())))
        .or_else(|| {
            active_inferences.first().map(|(inference_id, request_id)| {
                (
                    request_id.clone().or_else(|| Some(inference_id.clone())),
                    None,
                )
            })
        })
        .unwrap_or((None, None));
    let requested = if let Some(existing) = existing_requested {
        if existing.idempotency_key != params.idempotency_key
            || existing.reason_digest != reason_digest
            || existing.principal != principal
        {
            return Err("run already has a different cancellation request".into());
        }
        existing.clone()
    } else {
        car_proto::RunCancellationRequested {
            receipt_version: 1,
            run_id: params.run_id.clone(),
            idempotency_key: params.idempotency_key.clone(),
            reason_digest,
            principal,
            action_id,
            request_id,
        }
    };
    state
        .persist_run_cancellation_requested(&owner_session, &requested)
        .await?;

    for (request_id, action_id) in &active {
        crate::session::write_tool_cancel(
            &owner_session.channel,
            request_id.clone(),
            action_id.clone(),
            params.reason.clone(),
        )
        .await;
    }
    let mut inference_stopped = true;
    for (inference_id, _) in &active_inferences {
        let _pending = owner_session
            .inference_control
            .try_acquire_control()
            .map_err(|error| format!("runs.cancel inference control rejected: {error:?}"))?;
        let status = owner_session
            .inference_control
            .control(
                inference_id,
                crate::inference_control::ControlCause::Cancel,
                exact_backend_termination_ack(inference_id),
            )
            .await;
        if !matches!(
            status,
            car_proto::InferenceControlStatus::CancelledConfirmed
                | car_proto::InferenceControlStatus::AlreadyTerminal
        ) {
            inference_stopped = false;
        }
    }
    let callbacks_stopped = if active.is_empty() {
        true
    } else {
        tokio::time::timeout(std::time::Duration::from_secs(5), async {
            loop {
                let pending = owner_session.channel.pending.lock().await;
                let any_active = active
                    .iter()
                    .any(|(request_id, _)| pending.contains_key(request_id));
                drop(pending);
                if !any_active {
                    break;
                }
                tokio::time::sleep(std::time::Duration::from_millis(10)).await;
            }
        })
        .await
        .is_ok()
    };
    let stopped = callbacks_stopped && inference_stopped;

    if !stopped {
        let response = run_cancel_receipt(
            &requested,
            car_proto::RunCancellationStatus::TerminationUnconfirmed,
            None,
        )?;
        state
            .persist_run_cancellation_result(&owner_session, &response)
            .await?;
        return serde_json::to_value(response).map_err(|error| error.to_string());
    }

    let cancellation = car_proto::RunCancellationIdentity {
        receipt_version: requested.receipt_version,
        run_id: requested.run_id.clone(),
        idempotency_key: requested.idempotency_key.clone(),
        reason_digest: requested.reason_digest.clone(),
        principal: requested.principal.clone(),
        action_id: requested.action_id.clone(),
        request_id: requested.request_id.clone(),
    };
    let ended = state
        .prepare_run_completion(
            &params.run_id,
            car_proto::RunTermination::Cancelled { cancellation },
        )
        .await?;
    owner_session.append_run_terminal_event(&ended).await?;
    state.commit_run_completion(&ended).await?;
    let terminal_digest = ended
        .completion_digest
        .clone()
        .ok_or_else(|| "cancelled terminal is missing completion_digest".to_string())?;
    let response = run_cancel_receipt(
        &requested,
        car_proto::RunCancellationStatus::CancelledConfirmed,
        Some(terminal_digest),
    )?;
    owner_session
        .append_run_cancellation_result_event(&response)
        .await?;
    owner_session
        .clear_run_journal_binding(&params.run_id)
        .await?;
    let mut current = owner_session.current_run_id.lock().await;
    if current.as_deref() == Some(params.run_id.as_str()) {
        *current = None;
    }
    serde_json::to_value(response).map_err(|error| error.to_string())
}

/// Daemon-owned size invariants for `runs.record_turns` (R8a). The daemon
/// owns turn size the way it owns the turn index (`record_run_turns`,
/// session.rs FIX 6) and the way `A2uiLimits` owns surface size — it never
/// trusts the client's truncation for data that lands on disk.

/// Per-string-field byte cap. Each turn's `prompt` and `output` text and
/// any oversized `parameters` string is truncated to this with a marker
/// before the turn is appended. Sized to match U3's client-side cap with
/// headroom (the client caps at ~8 KB; the daemon's 16 KB ceiling catches
/// a misbehaving or older client without trimming healthy turns).
const RECORD_TURN_FIELD_CAP_BYTES: usize = 16 * 1024;

/// Marker appended to a daemon-truncated field so a reader can tell the
/// value was cut, not merely short.
const RECORD_TURN_TRUNC_MARKER: &str = "…[truncated]";

/// Aggregate per-turn byte cap. The per-field 16 KiB cap bounds each leaf
/// string, but a turn can carry MANY leaves (e.g. a `parameters` array of
/// thousands of sub-cap strings), so the per-field cap alone does not
/// bound the persisted JSONL line. After the typed decode each candidate
/// turn is serialized; one whose encoded form exceeds this cap gets its
/// heavy free-form fields (`parameters`, `output`, `prompt`) replaced
/// whole with [`RECORD_TURN_OVERSIZE_MARKER`] — see
/// [`enforce_turn_byte_cap`].
const RECORD_TURN_MAX_BYTES: usize = 256 * 1024;

/// Replacement value for a free-form field dropped whole by the aggregate
/// per-turn cap ([`RECORD_TURN_MAX_BYTES`]) — distinct from the per-field
/// marker so a reader can tell WHICH invariant fired.
const RECORD_TURN_OVERSIZE_MARKER: &str = "…[truncated: turn exceeded 256 KiB]";

/// Max turns in a single `runs.record_turns` batch. A larger batch is a
/// client bug (the agent flushes a bounded queue per cycle); reject it
/// loudly rather than admit an unbounded append under one lock.
const RECORD_TURNS_MAX_BATCH: usize = 256;

/// Per-run turn ceiling — a runaway-loop backstop sized well above any
/// healthy main-agent-only cycle (tens of turns), never a trimmer. This is
/// a true hard cap: a batch that would take the run PAST this many
/// recorded turns is refused whole with `dropped: "run_turn_limit"`, which
/// the agent treats as stop-sending. (Losing the straddling batch is
/// correct — at this depth the run is a runaway, not a healthy cycle.)
///
/// The AUTHORITATIVE enforcement lives in
/// [`crate::session::ServerState::record_run_turns`], under the `runs` lock,
/// because the dispatcher spawns a task per frame and the handler's
/// pre-check below reads a lock-free snapshot that pipelined batches all
/// pass before any append lands (ADV-1). The handler pre-check is kept only
/// as a fast path that avoids a doomed decode+append for the obvious
/// already-over case. We alias the single source of truth here.
const RECORD_TURNS_RUN_CEILING: usize = crate::session::RECORD_TURNS_RUN_CEILING;

/// Truncate one string in place to the daemon field-byte cap, appending
/// [`RECORD_TURN_TRUNC_MARKER`] when it was cut. Cuts on a UTF-8 char
/// boundary at or below the cap so the result is always valid.
fn truncate_turn_string(s: &mut String) {
    if s.len() > RECORD_TURN_FIELD_CAP_BYTES {
        // Find the largest char boundary ≤ the cap.
        let mut end = RECORD_TURN_FIELD_CAP_BYTES;
        while end > 0 && !s.is_char_boundary(end) {
            end -= 1;
        }
        s.truncate(end);
        s.push_str(RECORD_TURN_TRUNC_MARKER);
    }
}

/// Truncate a JSON string value in place to the daemon field-byte cap,
/// appending [`RECORD_TURN_TRUNC_MARKER`] when it was cut. Non-string
/// values are recursively walked (arrays/objects) so a large blob nested
/// inside `parameters`/`output` is still bounded; numbers/bools are left
/// as-is.
fn truncate_turn_value(value: &mut Value) {
    match value {
        Value::String(s) => truncate_turn_string(s),
        Value::Array(items) => {
            for item in items.iter_mut() {
                truncate_turn_value(item);
            }
        }
        Value::Object(map) => {
            for (_k, v) in map.iter_mut() {
                truncate_turn_value(v);
            }
        }
        _ => {}
    }
}

/// Headroom (bytes) subtracted from [`RECORD_TURN_MAX_BYTES`] when MEASURING
/// a turn, to cover the re-stamp slack (ADV-4). The cap is enforced here with
/// the turn's placeholder `index: 0`, but `record_run_turns` re-stamps the
/// index to the live append position under the `runs` lock — up to a
/// 4-digit-plus number near the run ceiling. So `"index":0` (9 bytes) can
/// grow to e.g. `"index":1999` (12 bytes): a turn measured at exactly the cap
/// would persist a few bytes OVER it. 16 bytes is comfortably above the
/// worst-case index-digit growth (the ceiling is 2000 → 4 digits → +3 bytes),
/// with margin to spare.
const RECORD_TURN_REINDEX_HEADROOM: usize = 16;

/// Effective measurement cap: a turn is treated as "within the persisted
/// cap" only when its encoded length (with the placeholder index) is at or
/// below this, leaving [`RECORD_TURN_REINDEX_HEADROOM`] for the live re-stamp.
const RECORD_TURN_MEASURE_CAP: usize = RECORD_TURN_MAX_BYTES - RECORD_TURN_REINDEX_HEADROOM;

/// Encoded size of a turn as it would persist (one JSONL line, minus the
/// trailing newline). A turn that fails to serialize reports `usize::MAX`
/// so the cap path treats it as oversized rather than waving it through.
fn turn_encoded_len(turn: &car_proto::RunTurn) -> usize {
    serde_json::to_vec(turn).map_or(usize::MAX, |v| v.len())
}

/// Enforce the aggregate per-turn byte cap ([`RECORD_TURN_MAX_BYTES`]) on
/// a decoded turn — the invariant the per-field pass cannot give: the
/// per-field cap bounds each leaf string, but not how many leaves a turn
/// carries, so a `parameters` array of thousands of sub-cap strings (or a
/// multi-MB `tool` scalar the per-field pass never visits) would still
/// produce an unbounded JSONL line.
///
/// When the encoded turn exceeds the cap, the heavy free-form fields
/// (`parameters`, `output`, `prompt`) are replaced WHOLE with
/// [`RECORD_TURN_OVERSIZE_MARKER`] (no partial salvage — at this size the
/// content is a misbehaving client, not signal). If the turn is somehow
/// STILL over cap, the remaining string scalars the per-field pass never
/// truncates (`tool`, `policy_rejected.rule`/`param`) are field-capped too.
///
/// Returns `true` when the turn is within the persisted cap (keep it) and
/// `false` when it is STILL over cap after both passes (ADV-5: reject/drop
/// it — a serialize failure or a future free-form field this pass doesn't
/// bound). The caller drops a rejected turn with a logged reason and a
/// structured drop rather than appending an over-cap line. The measurement
/// uses [`RECORD_TURN_MEASURE_CAP`] (ADV-4 re-stamp headroom).
pub(crate) fn enforce_turn_byte_cap(turn: &mut car_proto::RunTurn) -> bool {
    // ADV-5: exhaustively destructure so a future new `RunTurn` field is a
    // COMPILE error here, not a silently-unbounded persisted line. Every
    // field below is either a free-form string/JSON we bound, or a
    // number/C-like enum that is bounded by construction.
    let car_proto::RunTurn {
        index: _,               // usize — bounded; daemon re-stamps it anyway
        proposal_id: _,         // semantic identity — never truncate; reject if oversized
        action_id: _,           // semantic identity — never truncate; reject if oversized
        action_status: _,       // closed enum — bounded by construction
        action_duration_ms: _,  // f64 — bounded by construction
        action_completed_at: _, // timestamp — bounded by construction
        depends_on: _,          // semantic graph — never truncate; reject if oversized
        state_dependencies: _,  // semantic graph — never truncate; reject if oversized
        prompt: _,              // bounded below (replaced whole when oversize)
        tool: _,                // bounded below (field-capped when oversize)
        parameters: _,          // bounded below (replaced whole when oversize)
        output: _,              // bounded below (replaced whole when oversize)
        cli_outcome: _,         // C-like enum + i64 — bounded
        verifier_verdict: _,    // C-like enum — bounded
        policy_rejected: _,     // bounded below (field-capped when oversize)
    } = turn;

    if turn_encoded_len(turn) <= RECORD_TURN_MEASURE_CAP {
        return true;
    }
    // Replace the big three free-form fields whole.
    if !turn.parameters.is_null() {
        turn.parameters = Value::String(RECORD_TURN_OVERSIZE_MARKER.to_string());
    }
    if turn.output.is_some() {
        turn.output = Some(Value::String(RECORD_TURN_OVERSIZE_MARKER.to_string()));
    }
    if turn.prompt.is_some() {
        turn.prompt = Some(RECORD_TURN_OVERSIZE_MARKER.to_string());
    }
    if turn_encoded_len(turn) <= RECORD_TURN_MEASURE_CAP {
        return true;
    }
    // Still over cap: the bytes live in the scalars the per-field pass
    // never visits. Field-cap them.
    if let Some(tool) = turn.tool.as_mut() {
        truncate_turn_string(tool);
    }
    if let Some(pr) = turn.policy_rejected.as_mut() {
        truncate_turn_string(&mut pr.rule);
        if let Some(param) = pr.param.as_mut() {
            truncate_turn_string(param);
        }
    }
    // ADV-5: if the turn is STILL over cap, every free-form field has already
    // been replaced/capped, so the only ways to land here are a serialize
    // failure (`turn_encoded_len` → usize::MAX) or a future free-form field
    // the exhaustive destructure above will have forced us to handle. Reject
    // the turn (hard, not a release-compiled-out `debug_assert`) so an
    // unbounded line never reaches disk.
    turn_encoded_len(turn) <= RECORD_TURN_MEASURE_CAP
}

/// Bound a proposal-produced turn without changing its authenticated action
/// parameters. Output/prompt may be compacted, but if the immutable proposal
/// metadata itself cannot fit the durable line cap, finalization fails closed.
pub(crate) fn enforce_proposal_turn_byte_cap(turn: &mut car_proto::RunTurn) -> bool {
    let parameters = turn.parameters.clone();
    if !enforce_turn_byte_cap(turn) {
        return false;
    }
    turn.parameters = parameters;
    turn_encoded_len(turn) <= RECORD_TURN_MEASURE_CAP
}

/// Build a non-fatal `runs.record_turns` rejection: `ok: false`, nothing
/// appended, with the machine-readable `dropped` reason the agent treats
/// as "stop sending for this run".
fn record_turns_dropped(run_id: &str, reason: &str) -> Result<Value, String> {
    serde_json::to_value(car_proto::RunRecordTurnsResponse {
        run_id: run_id.to_string(),
        base_index: 0,
        count: 0,
        ok: false,
        dropped: Some(reason.to_string()),
    })
    .map_err(|e| e.to_string())
}

/// `runs.record_turns {run_id, turns}` — WS-only batch append of
/// client-narrated turns (feedback-agent A2UI/runs plan, U1).
///
/// The turn source is an out-of-pipeline agent whose work happens inside
/// its own subprocess (e.g. a `claude -p` resolver), invisible to the
/// proposal-path recorder. It builds full `RunTurn`s itself and pushes
/// them here in batches; the daemon appends them through the SAME
/// [`ServerState::record_run_turns`] the proposal recorder uses, so the
/// index re-stamp (FIX 6), JSONL persist, and `runs.trace.event` fanout
/// are byte-identical — this handler never re-implements locking, append,
/// or fanout.
///
/// Authorization (KTD): write access is the OWNING-agent binding only. The
/// read path's host-token gate must NOT apply here — a host-token or
/// unbound session writing another agent's turns is trace forgery. An
/// unknown run AND an unauthorized run collapse to the same uniform
/// `dropped: "run_not_found"` (mirroring `handle_runs_subscribe`'s FIX 3
/// not-found), so the response is never an existence/owner oracle.
///
/// Daemon-owned size invariants (R8a): per-field truncation, an aggregate
/// per-turn byte cap ([`enforce_turn_byte_cap`]), a batch-size cap (hard
/// error above), and a per-run turn ceiling (`run_turn_limit` — a hard
/// cap: no batch is accepted that would take the run past the ceiling).
/// Run existence/terminality is pre-checked to return a distinguishable
/// `ok: false` + reason rather than `record_run_turns`'s silent
/// zero-count drop; the benign TOCTOU (a run going terminal between the
/// check and the append) still drops silently inside `record_run_turns`,
/// matching existing recorder semantics.
async fn handle_runs_record_turns(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    // Parse leniently: the wire `RunTurn` may omit `verifier_verdict`
    // (client-narrated turns default it to `not_run`) and carries a
    // client-supplied `index` we ignore. We deserialize each turn from a
    // generic object so we can inject the verdict default before the typed
    // `RunTurn` deserialize, without adding a serde default to the shared
    // proto type (the proposal recorder always sets the field).
    let raw_run_id = req
        .params
        .get("run_id")
        .and_then(Value::as_str)
        .map(str::to_string);
    let run_id = match raw_run_id {
        Some(id) if !id.trim().is_empty() => id,
        _ => return Err("runs.record_turns requires { run_id, turns: [RunTurn] }".to_string()),
    };

    let raw_turns =
        match req.params.get("turns").and_then(Value::as_array) {
            Some(arr) => arr,
            None => return Err(
                "runs.record_turns requires { run_id, turns: [RunTurn] }: `turns` must be an array"
                    .to_string(),
            ),
        };
    if raw_turns.is_empty() {
        return Err("runs.record_turns requires a non-empty `turns` array".to_string());
    }
    if raw_turns.len() > RECORD_TURNS_MAX_BATCH {
        return Err(format!(
            "runs.record_turns batch too large: {} turns exceeds the per-call cap of {}",
            raw_turns.len(),
            RECORD_TURNS_MAX_BATCH
        ));
    }

    // Decode each wire turn into a typed RunTurn, defaulting an absent
    // `verifier_verdict` to `not_run` and truncating its oversized string
    // fields to the daemon cap (R8a) — the daemon does not trust client
    // truncation for data that lands on disk.
    let mut turns: Vec<car_proto::RunTurn> = Vec::with_capacity(raw_turns.len());
    for (i, raw) in raw_turns.iter().enumerate() {
        let mut obj = raw.clone();
        match obj.as_object_mut() {
            Some(map) => {
                // The daemon owns the index (re-stamped under the `runs`
                // lock in `record_run_turns`), so a client-narrated turn's
                // `index` is genuinely IGNORED — the protocol doc says so.
                // ADV-6: overwrite it UNCONDITIONALLY with a placeholder `0`
                // (not `entry().or_insert`), so a present-but-invalid value
                // (`-1`, `"5"`, `1.5`) can't fail the typed `usize` decode and
                // reject the whole batch. The placeholder is re-stamped to the
                // live append position on append regardless.
                map.insert("index".to_string(), Value::Number(0.into()));
                map.entry("verifier_verdict")
                    .or_insert_with(|| Value::String("not_run".to_string()));
                // Truncate the heavy free-text / blob fields before the
                // typed decode so the bounded values are what gets stored.
                if let Some(p) = map.get_mut("prompt") {
                    truncate_turn_value(p);
                }
                if let Some(o) = map.get_mut("output") {
                    truncate_turn_value(o);
                }
                if let Some(params) = map.get_mut("parameters") {
                    truncate_turn_value(params);
                }
            }
            None => {
                return Err(format!(
                    "runs.record_turns requires {{ run_id, turns: [RunTurn] }}: \
                     turn {i} is not an object"
                ));
            }
        }
        let mut turn: car_proto::RunTurn = serde_json::from_value(obj).map_err(|e| {
            format!("runs.record_turns requires {{ run_id, turns: [RunTurn] }}: turn {i}: {e}")
        })?;
        // Aggregate cap (R8a): the per-field pass bounds each leaf, not the
        // sum of leaves — bound the whole encoded turn before it is stored.
        // ADV-5: a turn that is STILL over cap after the replace+field-cap
        // pass (a serialize failure, or a future free-form field) is REJECTED,
        // not waved through. Drop the whole batch with a structured reason and
        // log it server-side — an unbounded line must never reach disk.
        if !enforce_turn_byte_cap(&mut turn) {
            tracing::warn!(
                run_id = %run_id,
                turn = i,
                "runs.record_turns: turn could not be bounded under the per-turn byte cap; dropping batch"
            );
            return record_turns_dropped(&run_id, "turn_too_large");
        }
        turns.push(turn);
    }

    // Resolve the run's owning agent: in-memory registry (live run) first,
    // disk fallback for a run whose RunMeta isn't in this process — the
    // `handle_runs_subscribe` pattern. Unknown run → uniform not-found.
    //
    // ADV-2: read the run HEADER only — agent, terminal, count, corruption —
    // not the whole `RunMeta`. The previous `run_meta` clone copied the
    // entire `turns` buffer (full prompts + CLI output) under the global
    // `runs` lock on every batch RPC; the handler needs only those three
    // facts.
    let header = state.run_header(&run_id).await;
    let owning_agent = match &header {
        Some((agent_id, _terminal, _len, _corruption)) => agent_id.clone(),
        None => match state.run_store.agent_for_run(&run_id) {
            Some(a) => a,
            // FIX 3 uniform not-found: an unknown run and an unauthorized
            // run are indistinguishable to the caller.
            None => return record_turns_dropped(&run_id, "run_not_found"),
        },
    };

    // WRITE authz (KTD): owning-agent binding ONLY. A host-token or unbound
    // session must NOT be able to write another agent's turns — that is
    // forgery, the inverse of the read path's host-token allowance. An
    // unauthorized write collapses to the SAME `run_not_found` as an
    // unknown run (no existence/owner oracle); logged server-side only.
    let bound = session.agent_id.lock().await.clone();
    if bound.as_deref() != Some(owning_agent.as_str()) {
        tracing::debug!(
            run_id = %run_id,
            owning_agent = %owning_agent,
            client_id = %session.client_id,
            "runs.record_turns denied (not the owning agent); returning uniform not-found"
        );
        return record_turns_dropped(&run_id, "run_not_found");
    }

    if let Some((_agent_id, _terminal, _len, Some(error))) = &header {
        return Err(error.clone());
    }

    // Pre-check terminality and the ceiling as a FAST PATH only. These read
    // the lock-free `run_header` snapshot, so a write against an obviously
    // closed / already-over-ceiling run skips the decode+append. They are
    // NOT authoritative: the dispatcher spawns a task per frame, so pipelined
    // batches can each pass this snapshot before any of them appends (ADV-1).
    // The authoritative terminal+ceiling enforcement is under the `runs` lock
    // inside `record_run_turns`, whose `RecordRunTurnsOutcome` we map below.
    if let Some((_agent_id, terminal, len, _corruption)) = &header {
        if *terminal {
            return record_turns_dropped(&run_id, "run_terminal");
        }
        // Per-run turn ceiling (R8a) fast path: a runaway-loop backstop and a
        // TRUE hard cap — refuse any batch that would take the run PAST the
        // ceiling, whole, and tell the agent to stop sending. (Healthy
        // cycles are tens of turns; losing the straddling batch of a
        // 2000-turn runaway is correct, not data loss.) The under-lock check
        // in `record_run_turns` is the one that actually bounds the run; this
        // only short-circuits the common already-over case.
        if *len + turns.len() > RECORD_TURNS_RUN_CEILING {
            return record_turns_dropped(&run_id, "run_turn_limit");
        }
    }

    // Append through the shared path — index re-stamp, JSONL persist,
    // `runs.trace.event` fanout, AND the authoritative under-lock ceiling all
    // happen inside `record_run_turns` under its own lock discipline. It
    // returns a `RecordRunTurnsOutcome` that distinguishes a healthy append
    // from a ceiling refusal and from an unknown/terminal run (ADV-1) — we
    // must NOT let an under-lock ceiling refusal masquerade as `run_terminal`.
    let count = turns.len();
    let records: Vec<car_proto::RunRecord> =
        turns.into_iter().map(car_proto::RunRecord::Turn).collect();
    let new_total = match state
        .record_run_turns_for_active_owner(&run_id, &session.client_id, records)
        .await
    {
        crate::session::RecordRunTurnsOutcome::Appended { new_total } => new_total,
        crate::session::RecordRunTurnsOutcome::RefusedCeiling => {
            // A pipelined batch crossed the ceiling under the lock even
            // though our fast-path snapshot was sub-ceiling — the runaway
            // backstop fired authoritatively. Tell the agent to stop.
            return record_turns_dropped(&run_id, "run_turn_limit");
        }
        crate::session::RecordRunTurnsOutcome::UnknownOrTerminal => {
            // `record_run_turns` appended nothing because the run is unknown
            // or went terminal. We resolved the run above, so the benign
            // cause is the TOCTOU: the run went terminal between our
            // fast-path check and the append. Surface a non-fatal drop.
            return record_turns_dropped(&run_id, "run_terminal");
        }
        crate::session::RecordRunTurnsOutcome::PersistenceFailed(error) => {
            if error.starts_with(car_proto::RUN_TRACE_CORRUPTION_MESSAGE_PREFIX) {
                return Err(error);
            }
            return Err(format!(
                "runs.record_turns persistence failed; retry exact batch safely: {error}"
            ));
        }
    };

    serde_json::to_value(car_proto::RunRecordTurnsResponse {
        run_id,
        base_index: new_total - count,
        count,
        ok: true,
        dropped: None,
    })
    .map_err(|e| e.to_string())
}

/// Authorize the calling connection to read/subscribe a run owned by
/// `agent_id` (R16 / KTD10 / Parslee-ai/car#254). A connection is
/// entitled when:
///
/// 1. It **owns** the agent — its `session.auth {agent_id}` binding
///    matches the run's owning `agent_id` (the supervised agent reading
///    its own trace), or
/// 2. It holds the **host-management role** — it authenticated via
///    `session.auth { host_token }` with the per-launch host token
///    (`ClientSession::is_host`).
///
/// What this gate buys, and its bound (be honest):
///
/// - It distinguishes agent-bound sessions, so one supervised agent's
///   connection cannot read a *different* agent's runs by guessing ids.
/// - Host-role is gated by the **host token**, NOT by `host.subscribe`
///   membership. This is the #254 fix: `host.subscribe` has no authz, so
///   keying on `is_subscribed` let ANY authenticated connection
///   self-elevate and read every agent's traces. The host token is read
///   only from the `0600` `host-token` file (never served over
///   `GET /auth-token`), so a different local user — or a client that
///   scraped the auth token off the HTTP endpoint — cannot obtain it.
/// - It is therefore a real confidentiality boundary against *another
///   local user* (multi-user / CI / remote daemon). It is NOT an
///   isolation boundary against a *malicious same-user process*: that
///   process can read the `0600` host-token (and the `0600` run files)
///   directly. Closing same-user isolation would need DPAPI/Keychain or
///   process-cred (SO_PEERCRED) auth — tracked separately, out of scope.
///
/// NOTE: lower-sensitivity host *metadata* — the agent roster, approvals,
/// and host events delivered by `host.subscribe` / `host.agents` /
/// `host.approvals` — is intentionally still available to any
/// authenticated connection (the local UI consumes it). Only run-trace
/// *content* (prompts, CLI output) requires host-role. Tightening that
/// metadata surface is a separate decision from #254.
async fn authorize_run_access(
    session: &crate::session::ClientSession,
    _state: &Arc<ServerState>,
    owning_agent_id: &str,
) -> Result<(), String> {
    // 1. The connection owns the agent (its own run).
    if let Some(bound) = session.agent_id.lock().await.clone() {
        if bound == owning_agent_id {
            return Ok(());
        }
    }
    // 2. The connection authenticated as the host-management client by
    //    presenting the per-launch host token (Parslee-ai/car#254).
    //    NOTE: this is deliberately NOT `host.is_subscribed(...)` — that
    //    check let any authenticated connection self-elevate just by
    //    calling `host.subscribe` (which has no authz), reading every
    //    agent's run traces. host.subscribe still works for host *events*;
    //    it just no longer grants the cross-agent run-trace read.
    if session.is_host.load(std::sync::atomic::Ordering::Acquire) {
        return Ok(());
    }
    // Do NOT name the owning `agent_id` in the error (FIX 3): a caller-
    // supplied or resolved id is not a transparent key, and echoing it back
    // turns a rejection into an existence/owner oracle. Log it server-side
    // for diagnosis; keep the wire message agent-agnostic.
    tracing::debug!(
        owning_agent = %owning_agent_id,
        client_id = %session.client_id,
        "run access denied: connection neither owns the agent nor is the host client"
    );
    Err(
        "not authorized to access this run: this connection neither owns the \
         owning agent (via session.auth) nor is the host management client"
            .to_string(),
    )
}

/// `runs.subscribe {run_id,cursor,limit}` — return one bounded catch-up page
/// and register for `runs.trace.event` only when the page reaches live (U4).
///
/// Authorizes the caller against the run's owning `agent_id` (R16), then
/// atomically pages the run's turns and, on the final page, registers the
/// subscriber under the `runs` lock (invariant #1, in
/// [`ServerState::subscribe_run_page`]).
///
/// FIX 3 (existence/owner oracle): an unknown `run_id` and an
/// exists-but-unauthorized `run_id` must be INDISTINGUISHABLE. Both return
/// the same uniform not-found marker (`{ run_id, not_found: true }`,
/// mirroring [`handle_runs_get_trace`]) — never an error frame that varies
/// by case, and never the owning `agent_id`. Otherwise an unentitled caller
/// could probe which `run_id`s exist (and learn the owning agent) by
/// telling "unknown" apart from "not authorized".
async fn handle_runs_subscribe(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    const MAX_LIMIT: usize = 500;
    #[derive(Deserialize)]
    struct LegacyRequest {
        run_id: String,
    }
    let paginated = session_has_capability(session, car_proto::RUNS_PAGINATION_CAPABILITY);
    let (run_id, cursor, limit) = if paginated {
        let params: car_proto::RunSubscribeRequest = serde_json::from_value(req.params.clone())
            .map_err(|e| format!("runs.subscribe requires {{ run_id, cursor, limit }}: {e}"))?;
        (params.run_id, params.cursor, params.limit)
    } else {
        let params: LegacyRequest = serde_json::from_value(req.params.clone())
            .map_err(|e| format!("runs.subscribe requires {{ run_id }}: {e}"))?;
        (params.run_id, 0, crate::session::RECORD_TURNS_RUN_CEILING)
    };
    if !(1..=MAX_LIMIT).contains(&limit) && paginated {
        return Err(format!(
            "runs.subscribe limit must be between 1 and {MAX_LIMIT}"
        ));
    }

    // Uniform not-found marker shared by the unknown-run and unauthorized
    // cases so the two are indistinguishable to the caller (FIX 3).
    let not_found = || {
        serde_json::to_value(serde_json::json!({
            "run_id": run_id,
            "not_found": true,
        }))
        .map_err(|e| e.to_string())
    };

    // Resolve the run's owning agent_id. Prefer the in-memory registry
    // (live run); fall back to the disk store (a run that exists but whose
    // RunMeta isn't in this process). Unknown run → uniform not-found.
    let owning_agent = match state.run_header(&run_id).await {
        Some((agent_id, _, _, _)) => agent_id,
        None => {
            let run_store = state.run_store.clone();
            let durable_run_id = run_id.clone();
            match run_store_blocking("runs.subscribe owner lookup", move || {
                Ok(run_store.agent_for_run(&durable_run_id))
            })
            .await?
            {
                Some(agent_id) => agent_id,
                None => return not_found(),
            }
        }
    };

    // R16/KTD10: gate before snapshotting. An unauthorized caller gets the
    // SAME uniform not-found as an unknown run — no distinguishable outcome,
    // no leaked owning `agent_id` (logged server-side only).
    if authorize_run_access(session, state, &owning_agent)
        .await
        .is_err()
    {
        tracing::debug!(
            run_id = %run_id,
            owning_agent = %owning_agent,
            client_id = %session.client_id,
            "runs.subscribe denied (unauthorized); returning uniform not-found"
        );
        return not_found();
    }

    let page = match state
        .subscribe_run_page(
            &run_id,
            &session.client_id,
            session.channel.clone(),
            cursor,
            limit,
        )
        .await?
    {
        Some(crate::session::RunSubscribePageResult::Ready(page)) => page,
        Some(crate::session::RunSubscribePageResult::Durable { agent_id, status }) => {
            let run_store = state.run_store.clone();
            let durable_run_id = run_id.clone();
            let page = strict_run_trace_read_blocking(
                "runs.subscribe durable page",
                state,
                run_id.clone(),
                move || run_store.get_run_turn_page_for(&agent_id, &durable_run_id, cursor, limit),
            )
            .await?;
            let Some((turns, next_cursor, live_cursor, durable_status)) = page else {
                return not_found();
            };
            let status = match durable_status {
                crate::run_store::RunStatus::InProgress => status,
                crate::run_store::RunStatus::Completed => car_proto::RunLiveStatus::Completed,
                crate::run_store::RunStatus::Incomplete => car_proto::RunLiveStatus::Incomplete,
                crate::run_store::RunStatus::CancellationPending => {
                    car_proto::RunLiveStatus::CancellationPending
                }
                crate::run_store::RunStatus::Cancelled => car_proto::RunLiveStatus::Cancelled,
            };
            car_proto::RunSubscribeResponse {
                run_id: run_id.clone(),
                agent_id: owning_agent.clone(),
                turns,
                cursor,
                limit,
                next_cursor,
                live_cursor,
                subscribed: next_cursor.is_none(),
                status,
            }
        }
        // A restart has no in-memory RunMeta for retained terminal history.
        // The owner lookup above already proved the durable file exists, so
        // page it directly instead of turning a valid replay subscription into
        // a false not-found (and, critically, run the strict corruption scan).
        None => {
            let run_store = state.run_store.clone();
            let durable_run_id = run_id.clone();
            let durable_agent = owning_agent.clone();
            let page = strict_run_trace_read_blocking(
                "runs.subscribe retained durable page",
                state,
                run_id.clone(),
                move || {
                    run_store.get_run_turn_page_for(&durable_agent, &durable_run_id, cursor, limit)
                },
            )
            .await?;
            if let Some((turns, next_cursor, live_cursor, durable_status)) = page {
                let status = match durable_status {
                    crate::run_store::RunStatus::InProgress => car_proto::RunLiveStatus::InProgress,
                    crate::run_store::RunStatus::Completed => car_proto::RunLiveStatus::Completed,
                    crate::run_store::RunStatus::Incomplete => car_proto::RunLiveStatus::Incomplete,
                    crate::run_store::RunStatus::CancellationPending => {
                        car_proto::RunLiveStatus::CancellationPending
                    }
                    crate::run_store::RunStatus::Cancelled => car_proto::RunLiveStatus::Cancelled,
                };
                car_proto::RunSubscribeResponse {
                    run_id: run_id.clone(),
                    agent_id: owning_agent.clone(),
                    turns,
                    cursor,
                    limit,
                    next_cursor,
                    live_cursor,
                    subscribed: next_cursor.is_none(),
                    status,
                }
            } else if !paginated {
                // Pre-v3 durable traces have no summary sidecar. The legacy
                // no-capability lane intentionally preserves v2's complete,
                // unbounded snapshot semantics, so recover the turns and
                // status from the strict JSONL read instead of hiding valid
                // persisted user history behind a false not-found.
                let run_store = state.run_store.clone();
                let durable_run_id = run_id.clone();
                let durable_agent = owning_agent.clone();
                let records = strict_run_trace_read_blocking(
                    "runs.subscribe pre-v3 durable trace",
                    state,
                    run_id.clone(),
                    move || run_store.get_run_trace_for_checked(&durable_agent, &durable_run_id),
                )
                .await?;
                let Some(records) = records else {
                    return not_found();
                };
                let mut status = car_proto::RunLiveStatus::InProgress;
                let mut turns = Vec::new();
                for record in records {
                    match record {
                        turn @ car_proto::RunRecord::Turn(_) => turns.push(turn),
                        car_proto::RunRecord::CancellationRequested(_)
                        | car_proto::RunRecord::CancellationResult(_) => {
                            if status == car_proto::RunLiveStatus::InProgress {
                                status = car_proto::RunLiveStatus::CancellationPending;
                            }
                        }
                        car_proto::RunRecord::Ended(ended) => {
                            status = match ended.termination {
                                car_proto::RunTermination::Outcome { .. } => {
                                    car_proto::RunLiveStatus::Completed
                                }
                                car_proto::RunTermination::Incomplete => {
                                    car_proto::RunLiveStatus::Incomplete
                                }
                                car_proto::RunTermination::Cancelled { .. } => {
                                    car_proto::RunLiveStatus::Cancelled
                                }
                            };
                        }
                        car_proto::RunRecord::Started(_) => {}
                    }
                }
                let live_cursor = turns.len();
                car_proto::RunSubscribeResponse {
                    run_id: run_id.clone(),
                    agent_id: owning_agent.clone(),
                    turns,
                    cursor: 0,
                    limit,
                    next_cursor: None,
                    live_cursor,
                    subscribed: false,
                    status,
                }
            } else {
                return not_found();
            }
        }
    };
    if paginated {
        serde_json::to_value(page).map_err(|e| e.to_string())
    } else {
        serde_json::to_value(serde_json::json!({
            "run_id": page.run_id,
            "agent_id": page.agent_id,
            "turns_so_far": page.turns,
            "cursor": page.live_cursor,
            "status": page.status,
        }))
        .map_err(|e| e.to_string())
    }
}

/// `runs.unsubscribe {run_id}` — drop this connection's live run-trace
/// subscription for `run_id` (U4). Idempotent: returns `removed: false`
/// if there was nothing to remove. No authorization gate is needed —
/// removing your own subscription leaks nothing.
async fn handle_runs_unsubscribe(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let params: car_proto::RunUnsubscribeRequest = serde_json::from_value(req.params.clone())
        .map_err(|e| format!("runs.unsubscribe requires {{ run_id }}: {e}"))?;
    let removed = state
        .unsubscribe_run(&params.run_id, &session.client_id)
        .await;
    serde_json::to_value(car_proto::RunUnsubscribeResponse {
        run_id: params.run_id,
        removed,
    })
    .map_err(|e| e.to_string())
}

/// `runs.list {agent_id,cursor,limit}` — list one bounded page of an agent's
/// runs newest-first for replay (U5). Reads the disk store's durable summary
/// index ([`RunStore::list_runs_page`]), so it works
/// across daemon restart / `client_id` churn — `agent_id` is the durable
/// key, not the connection.
///
/// R16/KTD10: the `agent_id` is **not** a transparent key. We authorize
/// the caller for it FIRST — it must own the agent (`session.auth
/// {agent_id}`) or be the CarHost host-client — so an unentitled caller
/// can't enumerate other agents' run lists. An authorized caller for an
/// agent with no runs gets an empty list (the empty state, R13).
async fn handle_runs_list(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    #[derive(Deserialize)]
    struct LegacyRequest {
        agent_id: String,
    }
    let paginated = session_has_capability(session, car_proto::RUNS_PAGINATION_CAPABILITY);
    let (agent_id, page) = if paginated {
        let params: car_proto::RunListRequest = serde_json::from_value(req.params.clone())
            .map_err(|e| format!("runs.list requires {{ agent_id, cursor, limit }}: {e}"))?;
        (params.agent_id, Some((params.cursor, params.limit)))
    } else {
        let params: LegacyRequest = serde_json::from_value(req.params.clone())
            .map_err(|e| format!("runs.list requires {{ agent_id }}: {e}"))?;
        (params.agent_id, None)
    };

    // Gate before reading — the param is an authorization subject, not a
    // lookup key. An unentitled caller is rejected, never served a list.
    authorize_run_access(session, state, &agent_id).await?;

    const MAX_LIMIT: usize = 200;
    if let Some((_, limit)) = page {
        if !(1..=MAX_LIMIT).contains(&limit) {
            return Err(format!("runs.list limit must be between 1 and {MAX_LIMIT}"));
        }
    }
    let run_store = state.run_store.clone();
    let durable_agent_id = agent_id.clone();
    let Some((cursor, limit)) = page else {
        let runs = run_store_blocking("runs.list legacy complete read", move || {
            Ok(run_store.list_runs(&durable_agent_id))
        })
        .await?;
        return Ok(serde_json::json!({"agent_id": agent_id, "runs": runs}));
    };
    let (runs, next_cursor) = run_store_blocking("runs.list page", move || {
        run_store
            .list_runs_page(&durable_agent_id, cursor, limit)
            .map_err(|error| format!("runs.list durable index read failed: {error}"))
    })
    .await?;
    let mut response = serde_json::json!({
        "agent_id": agent_id,
        "runs": runs,
        "cursor": cursor,
        "limit": limit,
    });
    if let Some(next_cursor) = next_cursor {
        response["next_cursor"] = serde_json::json!(next_cursor);
    }
    Ok(response)
}

/// `runs.get_trace {run_id,cursor,limit}` — fetch one bounded page of a
/// run's ordered trace from the disk store for replay (U5). Sequential pages
/// replay identically to what the live stream delivered, including after a
/// fresh daemon restart with empty memory.
///
/// R16/KTD10: resolve the run's owning `agent_id` from disk and authorize
/// the caller against it before serving any record — a `run_id` is not a
/// transparent key. An unknown `run_id` (no file on disk) returns a clear
/// not-found marker (`{ run_id, not_found: true }`), not an error frame,
/// so a UI can distinguish "no such run" from a transport failure.
///
/// A `timeout`/`Incomplete` run is **not** an error: its persisted trail
/// (the turns recorded so far plus the terminal `Ended`/`Incomplete`
/// marker) is returned, so the dashboard renders the partial run.
async fn handle_runs_get_trace(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    #[derive(Deserialize)]
    struct LegacyRequest {
        run_id: String,
        #[serde(default)]
        cursor: Option<usize>,
    }
    let paginated = session_has_capability(session, car_proto::RUNS_PAGINATION_CAPABILITY);
    let (run_id, cursor, limit) = if paginated {
        let params: car_proto::RunGetTraceRequest = serde_json::from_value(req.params.clone())
            .map_err(|e| format!("runs.get_trace requires {{ run_id, cursor, limit }}: {e}"))?;
        (params.run_id, params.cursor, Some(params.limit))
    } else {
        let params: LegacyRequest = serde_json::from_value(req.params.clone())
            .map_err(|e| format!("runs.get_trace requires {{ run_id }}: {e}"))?;
        (params.run_id, params.cursor.unwrap_or(0), None)
    };
    const MAX_LIMIT: usize = 500;
    if let Some(limit) = limit {
        if !(1..=MAX_LIMIT).contains(&limit) {
            return Err(format!(
                "runs.get_trace limit must be between 1 and {MAX_LIMIT}"
            ));
        }
    }

    // Resolve the owning agent from disk (the durable key path — works
    // after a restart). An unknown run_id has no owner: not-found, and we
    // never reach the store read. We don't reveal whether the id exists to
    // an unauthorized caller — authorization is checked against the
    // resolved owner, and resolution failure is the same not-found either
    // way.
    let run_store = state.run_store.clone();
    let durable_run_id = run_id.clone();
    let owning_agent = run_store_blocking("runs.get_trace owner lookup", move || {
        Ok(run_store.agent_for_run(&durable_run_id))
    })
    .await?;
    let Some(owning_agent) = owning_agent else {
        return serde_json::to_value(serde_json::json!({
            "run_id": run_id,
            "not_found": true,
        }))
        .map_err(|e| e.to_string());
    };

    // R16/KTD10: gate before serving any record.
    authorize_run_access(session, state, &owning_agent).await?;

    // Stream one bounded page from disk. `agent_for_run` just resolved the
    // file, so this is the cheaper keyed read.
    let run_store = state.run_store.clone();
    let durable_agent = owning_agent.clone();
    let durable_run_id = run_id.clone();
    if limit.is_none() {
        let records = strict_run_trace_read_blocking(
            "runs.get_trace legacy complete read",
            state,
            run_id.clone(),
            move || run_store.get_run_trace_for_checked(&durable_agent, &durable_run_id),
        )
        .await?;
        let Some(records) = records else {
            return Ok(serde_json::json!({"run_id": run_id, "not_found": true}));
        };
        let records = records.into_iter().skip(cursor).collect::<Vec<_>>();
        return Ok(serde_json::json!({
            "run_id": run_id,
            "agent_id": owning_agent,
            "records": records,
            "cursor": cursor,
        }));
    }
    let limit = limit.expect("paginated path has a limit");
    let page =
        strict_run_trace_read_blocking("runs.get_trace page", state, run_id.clone(), move || {
            run_store.get_run_trace_page_for(&durable_agent, &durable_run_id, cursor, limit)
        })
        .await?;
    let Some((paged, next_cursor)) = page else {
        return serde_json::to_value(serde_json::json!({
            "run_id": run_id,
            "not_found": true,
        }))
        .map_err(|e| e.to_string());
    };

    let mut response = serde_json::json!({
        "run_id": run_id,
        "agent_id": owning_agent,
        "records": paged,
        "cursor": cursor,
        "limit": limit,
    });
    if let Some(next_cursor) = next_cursor {
        response["next_cursor"] = serde_json::json!(next_cursor);
    }
    Ok(response)
}

fn run_trace_read_error(run_id: &str, error: std::io::Error) -> String {
    if crate::run_store::is_trace_corruption_error(&error) {
        format!(
            "{} run `{run_id}`: {error}",
            car_proto::RUN_TRACE_CORRUPTION_MESSAGE_PREFIX
        )
    } else {
        format!("run trace read failed for `{run_id}`: {error}")
    }
}

/// Update the per-session replan config. Wire shape mirrors the
/// FFI's positional `set_replan_config` arguments — the engine
/// crate's `ReplanConfig` struct doesn't derive Serialize, so we
/// reconstruct it from a flat object here.
async fn handle_replan_set_config(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let max_replans = msg
        .params
        .get("max_replans")
        .and_then(|v| v.as_u64())
        .unwrap_or(0) as u32;
    let delay_ms = msg
        .params
        .get("delay_ms")
        .and_then(|v| v.as_u64())
        .unwrap_or(0);
    let verify_before_execute = msg
        .params
        .get("verify_before_execute")
        .and_then(|v| v.as_bool())
        .unwrap_or(true);
    let replan_on_rejected = msg
        .params
        .get("replan_on_rejected")
        .and_then(|v| v.as_bool())
        .unwrap_or(false);
    let cfg = car_engine::ReplanConfig {
        max_replans,
        delay_ms,
        verify_before_execute,
        replan_on_rejected,
    };
    session.runtime.set_replan_config(cfg).await;
    Ok(Value::Null)
}

async fn handle_skills_list(
    msg: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let domain = msg.params.get("domain").and_then(|v| v.as_str());
    let engine = session.memgine.lock().await;
    let skills: Vec<serde_json::Value> = engine
        .graph
        .inner
        .node_indices()
        .filter_map(|nix| {
            let node = engine.graph.inner.node_weight(nix)?;
            if node.kind != car_memgine::MemKind::Skill {
                return None;
            }
            let meta = car_memgine::SkillMeta::from_node(node)?;
            if let Some(d) = domain {
                match &meta.scope {
                    car_memgine::SkillScope::Global => {}
                    car_memgine::SkillScope::Domain(sd) if sd == d => {}
                    _ => return None,
                }
            }
            Some(serde_json::to_value(&meta).unwrap_or_default())
        })
        .collect();
    serde_json::to_value(&skills).map_err(|e| e.to_string())
}

#[derive(serde::Deserialize)]
struct SecretParams {
    #[serde(default)]
    service: Option<String>,
    key: String,
    #[serde(default)]
    value: Option<String>,
    /// Set only by the local CLI reader after it loaded the owner-only host
    /// token. This is authorization intent, not identity; the authenticated
    /// session remains the proof.
    #[serde(default)]
    operator_broker: bool,
}

fn canonical_secret_key(key: &str) -> &str {
    if key.eq_ignore_ascii_case("openrouter") {
        car_inference::openrouter::API_KEY_ENV
    } else {
        key
    }
}

fn reject_reserved_oauth_secret(service: Option<&str>, key: &str) -> Result<(), String> {
    if car_inference::openrouter::is_reserved_oauth_secret(service, key) {
        Err("reserved_private_secret: the OpenRouter OAuth credential is managed only by openrouter.auth_start/openrouter.disconnect".to_string())
    } else {
        Ok(())
    }
}

fn is_openrouter_pasted_authority_slot(service: Option<&str>, key: &str) -> bool {
    let is_default_service = service.is_none() || service == Some(car_secrets::DEFAULT_SERVICE);
    is_default_service && key == car_inference::openrouter::API_KEY_ENV
}

async fn handle_secret_put(req: &JsonRpcMessage) -> Result<Value, String> {
    let p: SecretParams = serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let value = p.value.ok_or_else(|| "missing 'value'".to_string())?;
    let key = canonical_secret_key(&p.key);
    reject_reserved_oauth_secret(p.service.as_deref(), key)?;
    if !is_openrouter_pasted_authority_slot(p.service.as_deref(), key) {
        return car_ffi_common::secrets::put(p.service.as_deref(), key, &value);
    }
    let (result, final_status) = crate::openrouter_auth::mutate_pasted_credential(true, || {
        car_ffi_common::secrets::put(p.service.as_deref(), key, &value)
    })
    .await;
    result.map(|value| with_openrouter_authority_generation(value, &final_status))
}

async fn handle_secret_get(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
    state: &crate::session::ServerState,
) -> Result<Value, String> {
    let p: SecretParams = serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let key = canonical_secret_key(&p.key);
    let agent_id = session.agent_id.lock().await.clone();

    if p.operator_broker {
        // The auth gate has already validated this session. Host authority is
        // backed by the owner-only local token file (the ordinary token is
        // exposed to dashboard clients), which is the same-UID proof. Requiring
        // auth-enabled state closes `--no-auth`; rejecting a bound agent keeps
        // it from self-promoting past policy.
        if state.auth_token.get().is_none()
            || !session
                .authenticated
                .load(std::sync::atomic::Ordering::Acquire)
            || !session.is_host.load(std::sync::atomic::Ordering::Acquire)
            || agent_id.is_some()
        {
            return Err(
                "operator_broker_denied: secret.get operator broker requires an authenticated local host session"
                    .to_string(),
            );
        }
        let service = p.service.as_deref().unwrap_or(car_secrets::DEFAULT_SERVICE);
        let action = car_ir::Action::tool_call("secret.get")
            .with_param("service", Value::String(service.to_string()))
            .with_param("key", Value::String(key.to_string()))
            .with_param("caller_role", Value::String("operator".to_string()));
        let result =
            car_ffi_common::secrets::get_for_daemon_operator_broker(p.service.as_deref(), key);
        let (kind, outcome) = if result.is_ok() {
            (car_eventlog::EventKind::ActionSucceeded, "read")
        } else {
            (car_eventlog::EventKind::ActionFailed, "secret_store_error")
        };
        session.runtime.log.lock().await.append(
            kind,
            Some(&action.id),
            None,
            operator_secret_read_audit_data(service, key, outcome),
        );
        return result;
    }

    reject_reserved_oauth_secret(p.service.as_deref(), key)?;

    let Some(agent_id) = agent_id else {
        // Hosts and user-run standalone clients keep the existing generic
        // secret.get contract. The broker boundary applies to authenticated
        // supervised-agent sessions, whose identity the daemon can enforce and
        // audit rather than trusting a caller-supplied label.
        return car_ffi_common::secrets::get(p.service.as_deref(), key);
    };
    let service = p.service.as_deref().unwrap_or(car_secrets::DEFAULT_SERVICE);
    let action = car_ir::Action::tool_call("secret.get")
        .with_param("service", Value::String(service.to_string()))
        .with_param("key", Value::String(key.to_string()))
        .with_param("agent_id", Value::String(agent_id.clone()));
    let violations = session
        .runtime
        .policies
        .read()
        .await
        .check(&action, &session.runtime.state);
    if !violations.is_empty() {
        let policies: Vec<Value> = violations
            .iter()
            .map(|violation| Value::String(violation.policy_name.clone()))
            .collect();
        let mut data = secret_read_audit_data(service, key, &agent_id, "policy_denied");
        data.insert("policies".to_string(), Value::Array(policies.clone()));
        session.runtime.log.lock().await.append(
            car_eventlog::EventKind::PolicyViolation,
            Some(&action.id),
            None,
            data,
        );
        return Err(serde_json::json!({
            "code": "policy_denied",
            "message": "secret.get was denied by the daemon policy engine",
            "context": {"service": service, "key": key, "agent_id": agent_id},
            "policies": policies,
        })
        .to_string());
    }

    let result = car_ffi_common::secrets::get(p.service.as_deref(), key);
    let (kind, outcome) = if result.is_ok() {
        (car_eventlog::EventKind::ActionSucceeded, "read")
    } else {
        (car_eventlog::EventKind::ActionFailed, "secret_store_error")
    };
    session.runtime.log.lock().await.append(
        kind,
        Some(&action.id),
        None,
        secret_read_audit_data(service, key, &agent_id, outcome),
    );
    result
}

fn secret_read_audit_data(
    service: &str,
    key: &str,
    agent_id: &str,
    outcome: &str,
) -> HashMap<String, Value> {
    HashMap::from([
        ("tool".to_string(), Value::String("secret.get".to_string())),
        ("service".to_string(), Value::String(service.to_string())),
        ("key".to_string(), Value::String(key.to_string())),
        ("agent_id".to_string(), Value::String(agent_id.to_string())),
        ("outcome".to_string(), Value::String(outcome.to_string())),
    ])
}

fn operator_secret_read_audit_data(
    service: &str,
    key: &str,
    outcome: &str,
) -> HashMap<String, Value> {
    HashMap::from([
        ("tool".to_string(), Value::String("secret.get".to_string())),
        ("service".to_string(), Value::String(service.to_string())),
        ("key".to_string(), Value::String(key.to_string())),
        (
            "caller_role".to_string(),
            Value::String("operator".to_string()),
        ),
        ("outcome".to_string(), Value::String(outcome.to_string())),
    ])
}

async fn handle_secret_delete(req: &JsonRpcMessage) -> Result<Value, String> {
    let p: SecretParams = serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let key = canonical_secret_key(&p.key);
    reject_reserved_oauth_secret(p.service.as_deref(), key)?;
    if !is_openrouter_pasted_authority_slot(p.service.as_deref(), key) {
        return car_ffi_common::secrets::delete(p.service.as_deref(), key);
    }
    let (result, final_status) = crate::openrouter_auth::mutate_pasted_credential(false, || {
        car_ffi_common::secrets::delete(p.service.as_deref(), key)
    })
    .await;
    result.map(|value| with_openrouter_authority_generation(value, &final_status))
}

fn with_openrouter_authority_generation(
    mut value: Value,
    status: &crate::openrouter_auth::Status,
) -> Value {
    if let Value::Object(fields) = &mut value {
        fields.insert(
            "authority_generation".to_string(),
            Value::from(status.authority_generation),
        );
        return value;
    }
    serde_json::json!({
        "ok": true,
        "authority_generation": status.authority_generation,
        "result": value,
    })
}

fn handle_secret_status(req: &JsonRpcMessage) -> Result<Value, String> {
    let p: SecretParams = serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    car_ffi_common::secrets::status(p.service.as_deref(), canonical_secret_key(&p.key))
}

#[cfg(test)]
mod openrouter_secret_service_authority_tests {
    use super::{handle_secret_delete, handle_secret_put, handle_secret_status, JsonRpcMessage};
    use serde_json::{json, Value};

    static ENV_LOCK: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());

    struct FileSecretEnvironment(Option<std::ffi::OsString>);

    impl FileSecretEnvironment {
        fn install(path: &std::path::Path) -> Self {
            let previous = std::env::var_os("CAR_SECRETS_FILE_DIR");
            unsafe { std::env::set_var("CAR_SECRETS_FILE_DIR", path) };
            Self(previous)
        }
    }

    impl Drop for FileSecretEnvironment {
        fn drop(&mut self) {
            match self.0.take() {
                Some(previous) => unsafe { std::env::set_var("CAR_SECRETS_FILE_DIR", previous) },
                None => unsafe { std::env::remove_var("CAR_SECRETS_FILE_DIR") },
            }
        }
    }

    fn req(params: Value) -> JsonRpcMessage {
        JsonRpcMessage {
            jsonrpc: "2.0".into(),
            method: None,
            params,
            id: json!(1),
            result: None,
            error: None,
        }
    }

    #[tokio::test(flavor = "current_thread")]
    async fn non_default_service_put_is_generic_and_does_not_publish_pasted_authority() {
        let _env_lock = ENV_LOCK.lock().await;
        let temp = tempfile::TempDir::new().unwrap();
        let _environment = FileSecretEnvironment::install(temp.path());
        let authority_before = serde_json::to_value(crate::openrouter_auth::status()).unwrap();

        let result = handle_secret_put(&req(json!({
            "service": "integration-test-vault",
            "key": "openrouter",
            "value": "custom-service-only"
        })))
        .await
        .unwrap();
        assert_eq!(result["service"], "integration-test-vault");
        assert_eq!(result["key"], car_inference::openrouter::API_KEY_ENV);
        assert!(
            result.get("authority_generation").is_none(),
            "a generic service write must not claim it changed OpenRouter authority: {result}"
        );
        let generic_status = handle_secret_status(&req(json!({
            "service": "integration-test-vault",
            "key": "openrouter"
        })))
        .unwrap();
        assert_eq!(generic_status["exists"], true);
        assert_eq!(
            serde_json::to_value(crate::openrouter_auth::status()).unwrap(),
            authority_before,
            "a non-default service cannot supersede OAuth/default-service resolution"
        );
    }

    #[tokio::test(flavor = "current_thread")]
    async fn non_default_service_delete_is_generic_and_does_not_publish_false_absence() {
        let _env_lock = ENV_LOCK.lock().await;
        let temp = tempfile::TempDir::new().unwrap();
        let _environment = FileSecretEnvironment::install(temp.path());
        car_ffi_common::secrets::put(
            Some("integration-test-vault-delete"),
            car_inference::openrouter::API_KEY_ENV,
            "custom-service-only",
        )
        .unwrap();
        let authority_before = serde_json::to_value(crate::openrouter_auth::status()).unwrap();

        let result = handle_secret_delete(&req(json!({
            "service": "integration-test-vault-delete",
            "key": "openrouter"
        })))
        .await
        .unwrap();
        assert_eq!(result["service"], "integration-test-vault-delete");
        assert!(
            result.get("authority_generation").is_none(),
            "a generic service delete must not claim it changed OpenRouter authority: {result}"
        );
        let generic_status = handle_secret_status(&req(json!({
            "service": "integration-test-vault-delete",
            "key": "openrouter"
        })))
        .unwrap();
        assert_eq!(generic_status["exists"], false);
        assert_eq!(
            serde_json::to_value(crate::openrouter_auth::status()).unwrap(),
            authority_before,
            "deleting another service's key cannot publish false default-service absence"
        );
    }
}

#[derive(serde::Deserialize)]
struct PermParams {
    domain: String,
    #[serde(default)]
    target_bundle_id: Option<String>,
}

fn handle_perm_status(req: &JsonRpcMessage) -> Result<Value, String> {
    let p: PermParams = serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    car_ffi_common::permissions::status(&p.domain, p.target_bundle_id.as_deref())
}

fn handle_perm_request(req: &JsonRpcMessage) -> Result<Value, String> {
    let p: PermParams = serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    car_ffi_common::permissions::request(&p.domain, p.target_bundle_id.as_deref())
}

fn handle_perm_explain(req: &JsonRpcMessage) -> Result<Value, String> {
    let p: PermParams = serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    car_ffi_common::permissions::explain(&p.domain, p.target_bundle_id.as_deref())
}

fn handle_calendar_events(req: &JsonRpcMessage) -> Result<Value, String> {
    #[derive(serde::Deserialize)]
    struct P {
        start: String,
        end: String,
        #[serde(default)]
        calendar_ids: Vec<String>,
    }
    let p: P = serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let start = chrono::DateTime::parse_from_rfc3339(&p.start)
        .map_err(|e| format!("parse start: {}", e))?
        .with_timezone(&chrono::Utc);
    let end = chrono::DateTime::parse_from_rfc3339(&p.end)
        .map_err(|e| format!("parse end: {}", e))?
        .with_timezone(&chrono::Utc);
    car_ffi_common::integrations::calendar_events(start, end, &p.calendar_ids)
}

fn handle_calendar_create_event(req: &JsonRpcMessage) -> Result<Value, String> {
    let raw = req.params.to_string();
    car_ffi_common::integrations::calendar_create_event(&raw)
}

fn handle_calendar_update_event(req: &JsonRpcMessage) -> Result<Value, String> {
    let raw = req.params.to_string();
    car_ffi_common::integrations::calendar_update_event(&raw)
}

fn handle_calendar_delete_event(req: &JsonRpcMessage) -> Result<Value, String> {
    #[derive(serde::Deserialize)]
    struct P {
        event_id: String,
    }
    let p: P = serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    car_ffi_common::integrations::calendar_delete_event(&p.event_id)
}

fn handle_contacts_find(req: &JsonRpcMessage) -> Result<Value, String> {
    #[derive(serde::Deserialize)]
    struct P {
        query: String,
        #[serde(default = "default_limit")]
        limit: usize,
        #[serde(default)]
        container_ids: Vec<String>,
    }
    fn default_limit() -> usize {
        50
    }
    let p: P = serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    car_ffi_common::integrations::contacts_list(&p.query, &p.container_ids, p.limit)
}

fn handle_mail_inbox(req: &JsonRpcMessage) -> Result<Value, String> {
    #[derive(serde::Deserialize, Default)]
    struct P {
        #[serde(default)]
        account_ids: Vec<String>,
    }
    let p: P = serde_json::from_value(req.params.clone()).unwrap_or_default();
    car_ffi_common::integrations::mail_inbox(&p.account_ids)
}

fn handle_mail_mailboxes(req: &JsonRpcMessage) -> Result<Value, String> {
    #[derive(serde::Deserialize, Default)]
    struct P {
        #[serde(default)]
        account_ids: Vec<String>,
    }
    let p: P = serde_json::from_value(req.params.clone()).unwrap_or_default();
    car_ffi_common::integrations::mail_mailboxes(&p.account_ids)
}

/// The params ARE the `MessageQuery`, so they go through verbatim — every
/// field defaults, and `{}` reads the INBOX exactly as `mail.inbox` does.
/// Omitted params deserialize as `Value::Null`, which is not a `MessageQuery`;
/// treat that as the all-defaults query rather than a parse error.
fn handle_mail_messages(req: &JsonRpcMessage) -> Result<Value, String> {
    let raw = if req.params.is_null() {
        "{}".to_string()
    } else {
        req.params.to_string()
    };
    car_ffi_common::integrations::mail_messages(&raw)
}

fn handle_mail_message_body(req: &JsonRpcMessage) -> Result<Value, String> {
    #[derive(serde::Deserialize)]
    struct P {
        message_id: String,
    }
    let p: P = serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    car_ffi_common::integrations::mail_message_body(&p.message_id)
}

fn handle_mail_send(req: &JsonRpcMessage) -> Result<Value, String> {
    let raw = req.params.to_string();
    car_ffi_common::integrations::mail_send(&raw)
}

fn handle_messages_chats(req: &JsonRpcMessage) -> Result<Value, String> {
    #[derive(serde::Deserialize)]
    struct P {
        #[serde(default = "default_limit")]
        limit: usize,
    }
    fn default_limit() -> usize {
        50
    }
    let p: P = serde_json::from_value(req.params.clone()).unwrap_or(P { limit: 50 });
    car_ffi_common::integrations::messages_chats(p.limit)
}

/// The params object is the all-optional MessagesReadQuery. As with
/// `mail.messages`, omitted JSON-RPC params mean the default `{}` query.
fn handle_messages_read(req: &JsonRpcMessage) -> Result<Value, String> {
    let raw = if req.params.is_null() {
        "{}".to_string()
    } else {
        req.params.to_string()
    };
    car_ffi_common::integrations::messages_read(&raw)
}

fn handle_messages_send(req: &JsonRpcMessage) -> Result<Value, String> {
    let raw = req.params.to_string();
    car_ffi_common::integrations::messages_send(&raw)
}

fn handle_notes_find(req: &JsonRpcMessage) -> Result<Value, String> {
    #[derive(serde::Deserialize)]
    struct P {
        query: String,
        #[serde(default = "default_limit")]
        limit: usize,
    }
    fn default_limit() -> usize {
        50
    }
    let p: P = serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    car_ffi_common::integrations::notes_find(&p.query, p.limit)
}

fn handle_reminders_items(req: &JsonRpcMessage) -> Result<Value, String> {
    #[derive(serde::Deserialize)]
    struct P {
        #[serde(default = "default_limit")]
        limit: usize,
    }
    fn default_limit() -> usize {
        50
    }
    let p: P = serde_json::from_value(req.params.clone()).unwrap_or(P { limit: 50 });
    car_ffi_common::integrations::reminders_items(p.limit)
}

fn handle_bookmarks_list(req: &JsonRpcMessage) -> Result<Value, String> {
    #[derive(serde::Deserialize)]
    struct P {
        #[serde(default = "default_limit")]
        limit: usize,
    }
    fn default_limit() -> usize {
        100
    }
    let p: P = serde_json::from_value(req.params.clone()).unwrap_or(P { limit: 100 });
    car_ffi_common::integrations::bookmarks_list(p.limit)
}

fn handle_health_sleep(req: &JsonRpcMessage) -> Result<Value, String> {
    #[derive(serde::Deserialize)]
    struct P {
        start: String,
        end: String,
    }
    let p: P = serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let s = chrono::DateTime::parse_from_rfc3339(&p.start)
        .map_err(|e| format!("parse start: {}", e))?
        .with_timezone(&chrono::Utc);
    let e = chrono::DateTime::parse_from_rfc3339(&p.end)
        .map_err(|e| format!("parse end: {}", e))?
        .with_timezone(&chrono::Utc);
    car_ffi_common::health::sleep_windows(s, e)
}

fn handle_health_workouts(req: &JsonRpcMessage) -> Result<Value, String> {
    #[derive(serde::Deserialize)]
    struct P {
        start: String,
        end: String,
    }
    let p: P = serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let s = chrono::DateTime::parse_from_rfc3339(&p.start)
        .map_err(|e| format!("parse start: {}", e))?
        .with_timezone(&chrono::Utc);
    let e = chrono::DateTime::parse_from_rfc3339(&p.end)
        .map_err(|e| format!("parse end: {}", e))?
        .with_timezone(&chrono::Utc);
    car_ffi_common::health::workouts(s, e)
}

fn handle_health_activity(req: &JsonRpcMessage) -> Result<Value, String> {
    #[derive(serde::Deserialize)]
    struct P {
        start: String,
        end: String,
    }
    let p: P = serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let s = chrono::NaiveDate::parse_from_str(&p.start, "%Y-%m-%d")
        .map_err(|e| format!("parse start: {}", e))?;
    let e = chrono::NaiveDate::parse_from_str(&p.end, "%Y-%m-%d")
        .map_err(|e| format!("parse end: {}", e))?;
    car_ffi_common::health::activity(s, e)
}

async fn handle_browser_close(session: &crate::session::ClientSession) -> Result<Value, String> {
    let closed = session.browser.close().await?;
    Ok(serde_json::json!({"closed": closed}))
}

async fn handle_browser_run(
    req: &JsonRpcMessage,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    #[derive(serde::Deserialize)]
    struct BrowserRunParams {
        /// Inline JSON string (CLI-compatible), OR the structured object.
        script: Value,
        #[serde(default)]
        width: Option<u32>,
        #[serde(default)]
        height: Option<u32>,
        /// When true, launches a visible Chromium window for interactive
        /// flows (first-time auth, 2FA, supervised runs). Only honored on
        /// the call that first launches the browser session — subsequent
        /// calls reuse the existing browser regardless.
        #[serde(default)]
        headed: Option<bool>,
        /// Extra Chromium command-line flags appended verbatim at
        /// launch (#112). Honoured only on the launch call.
        #[serde(default)]
        extra_args: Option<Vec<String>>,
    }
    let params: BrowserRunParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;

    // Validate before launching Chromium. The wire contract accepts an inline
    // JSON string or a structured object, not arbitrary JSON scalars/arrays.
    // Launching first made malformed calls wait on browser startup before the
    // script parser could reject them.
    let script_json = browser_script_json(params.script)?;

    let browser_session = session
        .browser
        .get_or_launch(car_ffi_common::browser::BrowserLaunchOptions {
            width: params.width.unwrap_or(1280),
            height: params.height.unwrap_or(720),
            headless: !params.headed.unwrap_or(false),
            extra_args: params.extra_args.unwrap_or_default(),
            // `browser.run` is a per-CONNECTION browser and stays fully
            // independent of the drawer's and the agents': no persistent
            // profile, so nothing it does can collide with theirs, and
            // nothing they do can repoint it.
            profile_dir: None,
        })
        .await?;

    let trace_json = browser_session.run(&script_json).await?;
    serde_json::from_str(&trace_json).map_err(|e| e.to_string())
}

fn browser_script_json(script: Value) -> Result<String, String> {
    match script {
        Value::String(script) => Ok(script),
        script @ Value::Object(_) => Ok(script.to_string()),
        _ => Err("browser.run script must be a string or object".to_string()),
    }
}

#[cfg(test)]
mod browser_run_script_tests {
    use super::browser_script_json;
    use serde_json::{json, Value};

    #[test]
    fn accepts_only_the_documented_script_shapes_before_browser_launch() {
        assert_eq!(
            browser_script_json(Value::String(r#"{"operations":[]}"#.to_string()))
                .expect("inline JSON string"),
            r#"{"operations":[]}"#
        );
        assert_eq!(
            serde_json::from_str::<Value>(
                &browser_script_json(json!({"operations": []})).expect("structured object")
            )
            .expect("serialized object"),
            json!({"operations": []})
        );

        for unsupported in [Value::Null, json!(1), json!(true), json!([])] {
            assert_eq!(
                browser_script_json(unsupported).expect_err("unsupported JSON shape"),
                "browser.run script must be a string or object"
            );
        }
    }
}

// ---------------------------------------------------------------------------
// Voice streaming JSON-RPC methods
//
// Events are pushed back to the originating client as JSON-RPC notifications:
//   { "jsonrpc": "2.0", "method": "voice.event",
//     "params": { "session_id": "...", "event": {...} } }
//
// The session registry is process-wide (ServerState.voice_sessions); per-call
// WsVoiceEventSink instances bind each session to its originating WS so a
// client only ever sees events for sessions it started.
// ---------------------------------------------------------------------------

#[derive(Deserialize)]
struct VoiceStartParams {
    session_id: String,
    audio_source: Value,
    #[serde(default)]
    options: Option<Value>,
}

async fn handle_voice_transcribe_stream_start(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    session: &Arc<crate::session::ClientSession>,
) -> Result<Value, String> {
    let params: VoiceStartParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let audio_source_json =
        serde_json::to_string(&params.audio_source).map_err(|e| e.to_string())?;
    let options_json = params
        .options
        .as_ref()
        .map(|v| serde_json::to_string(v).map_err(|e| e.to_string()))
        .transpose()?;
    let sink: Arc<dyn car_voice::VoiceEventSink> = Arc::new(crate::session::WsVoiceEventSink {
        channel: session.channel.clone(),
    });
    let json = car_ffi_common::voice::transcribe_stream_start(
        &params.session_id,
        &audio_source_json,
        options_json.as_deref(),
        state.voice_sessions.clone(),
        sink,
    )
    .await?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

#[derive(Deserialize)]
struct VoiceStopParams {
    session_id: String,
}

async fn handle_voice_transcribe_stream_stop(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let params: VoiceStopParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let json = car_ffi_common::voice::transcribe_stream_stop(
        &params.session_id,
        state.voice_sessions.clone(),
    )
    .await?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

#[derive(Deserialize)]
struct VoicePushParams {
    session_id: String,
    /// Base64-encoded 16-bit signed PCM frame. JSON-RPC is text, so binary
    /// audio frames have to be encoded; clients in WS-binary contexts that
    /// want to skip the round trip can call the FFI directly.
    pcm_b64: String,
}

async fn handle_voice_transcribe_stream_push(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    use base64::Engine;
    let params: VoicePushParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let pcm = base64::engine::general_purpose::STANDARD
        .decode(&params.pcm_b64)
        .map_err(|e| format!("invalid pcm_b64: {}", e))?;
    let json = car_ffi_common::voice::transcribe_stream_push(
        &params.session_id,
        &pcm,
        state.voice_sessions.clone(),
    )
    .await?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

fn handle_voice_sessions_list(state: &Arc<ServerState>) -> Value {
    let json = car_ffi_common::voice::list_voice_sessions(state.voice_sessions.clone());
    serde_json::from_str(&json).unwrap_or(Value::Null)
}

#[derive(Deserialize)]
struct VoiceTtsStreamStartParams {
    /// Caller-chosen opaque id for this stream. Used both as the
    /// session_id wrapped onto each `voice.event` notification AND as
    /// the key for `voice.tts_stream.cancel`.
    stream_id: String,
    /// Text to synthesize. Splitting into multiple synth calls (for
    /// long-form narration) is the caller's responsibility.
    text: String,
    /// Optional [`car_ffi_common::voice::TtsStreamOptions`] as a raw
    /// JSON value (provider, voice_id, binary_frames).
    #[serde(default)]
    options: Option<Value>,
}

async fn handle_voice_tts_stream_start(
    req: &JsonRpcMessage,
    session: &Arc<crate::session::ClientSession>,
) -> Result<Value, String> {
    let params: VoiceTtsStreamStartParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let opts_str = params
        .options
        .as_ref()
        .map(|v| v.to_string())
        .filter(|s| !s.is_empty());
    let sink: Arc<dyn car_voice::VoiceEventSink> = Arc::new(crate::session::WsVoiceEventSink {
        channel: session.channel.clone(),
    });
    let json = car_ffi_common::voice::tts_stream_start(
        &params.stream_id,
        &params.text,
        opts_str.as_deref(),
        sink,
    )
    .await?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

#[derive(Deserialize)]
struct VoiceTtsStreamCancelParams {
    stream_id: String,
}

async fn handle_voice_tts_stream_cancel(req: &JsonRpcMessage) -> Result<Value, String> {
    let params: VoiceTtsStreamCancelParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let json = car_ffi_common::voice::tts_stream_cancel(&params.stream_id).await?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

fn handle_voice_tts_stream_list() -> Value {
    let json = car_ffi_common::voice::list_tts_streams();
    serde_json::from_str(&json).unwrap_or(Value::Null)
}

async fn handle_voice_dispatch_turn(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    session: &Arc<crate::session::ClientSession>,
) -> Result<Value, String> {
    let req_value = req.params.clone();
    let request: crate::voice_turn::DispatchVoiceTurnRequest =
        serde_json::from_value(req_value).map_err(|e| e.to_string())?;
    let engine = get_inference_engine(state).clone();
    let sink: Arc<dyn car_voice::VoiceEventSink> = Arc::new(crate::session::WsVoiceEventSink {
        channel: session.channel.clone(),
    });
    let resp = crate::voice_turn::dispatch(engine, request, sink).await?;
    serde_json::to_value(resp).map_err(|e| e.to_string())
}

async fn handle_voice_cancel_turn() -> Result<Value, String> {
    crate::voice_turn::cancel().await;
    Ok(serde_json::json!({"cancelled": true}))
}

async fn handle_voice_prewarm_turn(state: &Arc<ServerState>) -> Result<Value, String> {
    let engine = get_inference_engine(state).clone();
    crate::voice_turn::prewarm(engine).await;
    Ok(serde_json::json!({"prewarmed": true}))
}

// ---------------------------------------------------------------------------
// Inference runner over WebSocket — closes Parslee-ai/car-releases#24
//
// Bidirectional protocol shape:
//   1. Client → server: `inference.register_runner` (no params). The
//      session that calls this becomes the host for delegated models.
//   2. Server → client: `inference.runner.invoke` notification with
//      {call_id, request} when CAR needs to dispatch a delegated turn.
//   3. Client → server: `inference.runner.event` with {call_id, event}
//      for each chunk; `inference.runner.complete` with {call_id, result}
//      on success; `inference.runner.fail` with {call_id, error} on
//      failure.
//
// The server-side data is process-wide because only one inference
// runner can be registered at a time (matches the FFI bindings'
// constraint). The per-call mailboxes live in dedicated DashMaps.
// ---------------------------------------------------------------------------

/// Runners keyed by the `client_id` of the session that registered them.
///
/// Replaces a single process-global slot that the last registrant overwrote —
/// so two hosts sharing one daemon dispatched each other's delegated calls, and
/// the loser saw `no bridge context for <uuid>` (Parslee-ai/car-releases#77).
///
/// This is ROUTING only. It is deliberately NOT a concurrency control: bounding
/// how many generations run at once is `crate::admission`'s job, which sizes
/// permits from host RAM. The old singleton conflated the two, and as a resource
/// guard it was both redundant and worse than admission — a hard global 1
/// regardless of how much memory the machine actually had.
fn ws_runner_sessions() -> &'static dashmap::DashMap<String, Arc<crate::session::WsChannel>> {
    static MAP: std::sync::OnceLock<dashmap::DashMap<String, Arc<crate::session::WsChannel>>> =
        std::sync::OnceLock::new();
    MAP.get_or_init(dashmap::DashMap::new)
}

/// The runner that serves calls whose originator registered none of its own.
///
/// Preserves the pre-#77 use case: a dedicated runner process serving calls that
/// originate elsewhere (a CLI invocation, a scheduled agent). Last registrant
/// wins here, as before — but now only for unclaimed traffic, not for calls a
/// host made itself.
fn ws_runner_fallback() -> &'static std::sync::RwLock<Option<Arc<crate::session::WsChannel>>> {
    static SLOT: std::sync::OnceLock<std::sync::RwLock<Option<Arc<crate::session::WsChannel>>>> =
        std::sync::OnceLock::new();
    SLOT.get_or_init(|| std::sync::RwLock::new(None))
}

/// Resolve the channel for a delegated call: the caller's own runner when it has
/// one, else the fallback.
fn resolve_runner_channel(caller: Option<&str>) -> Option<Arc<crate::session::WsChannel>> {
    if let Some(id) = caller {
        if let Some(entry) = ws_runner_sessions().get(id) {
            return Some(entry.value().clone());
        }
    }
    ws_runner_fallback().read().ok().and_then(|g| g.clone())
}

fn ws_runner_calls() -> &'static dashmap::DashMap<String, car_inference::EventEmitter> {
    static MAP: std::sync::OnceLock<dashmap::DashMap<String, car_inference::EventEmitter>> =
        std::sync::OnceLock::new();
    MAP.get_or_init(dashmap::DashMap::new)
}

fn ws_runner_completions() -> &'static dashmap::DashMap<
    String,
    tokio::sync::oneshot::Sender<std::result::Result<car_inference::RunnerResult, String>>,
> {
    static MAP: std::sync::OnceLock<
        dashmap::DashMap<
            String,
            tokio::sync::oneshot::Sender<std::result::Result<car_inference::RunnerResult, String>>,
        >,
    > = std::sync::OnceLock::new();
    MAP.get_or_init(dashmap::DashMap::new)
}

struct WsInferenceRunner;

#[async_trait::async_trait]
impl car_inference::InferenceRunner for WsInferenceRunner {
    async fn run(
        &self,
        request: car_inference::tasks::generate::GenerateRequest,
        emitter: car_inference::EventEmitter,
    ) -> std::result::Result<car_inference::RunnerResult, car_inference::RunnerError> {
        // Route to the runner the ORIGINATING session registered; fall back to
        // the global one only when it registered none (car-releases#77).
        let channel = resolve_runner_channel(request.caller.as_deref()).ok_or_else(|| {
            car_inference::RunnerError::Declined(
                "no WebSocket inference runner registered — call inference.register_runner first"
                    .into(),
            )
        })?;

        let call_id = uuid::Uuid::new_v4().to_string();
        let request_json = serde_json::to_value(&request)
            .map_err(|e| car_inference::RunnerError::Failed(e.to_string()))?;
        let (tx, rx) = tokio::sync::oneshot::channel();
        ws_runner_calls().insert(call_id.clone(), emitter);
        ws_runner_completions().insert(call_id.clone(), tx);

        // Fire the invoke notification.
        use futures::SinkExt;
        let notification = serde_json::json!({
            "jsonrpc": "2.0",
            "method": "inference.runner.invoke",
            "params": {
                "call_id": call_id,
                "request": request_json,
            },
        });
        let text = serde_json::to_string(&notification)
            .map_err(|e| car_inference::RunnerError::Failed(e.to_string()))?;
        let _ = channel
            .write
            .lock()
            .await
            .send(tokio_tungstenite::tungstenite::Message::Text(text.into()))
            .await;

        let result = rx.await.map_err(|_| {
            car_inference::RunnerError::Failed("runner completion channel dropped".into())
        })?;
        ws_runner_calls().remove(&call_id);
        result.map_err(car_inference::RunnerError::Failed)
    }
}

async fn handle_inference_register_runner(
    session: &Arc<crate::session::ClientSession>,
) -> Result<Value, String> {
    ws_runner_sessions().insert(session.client_id.clone(), session.channel.clone());
    // Also the fallback for calls whose originator registered no runner. Last
    // registrant wins here, as before — but that now only affects unclaimed
    // traffic, not another host's own calls.
    let mut guard = ws_runner_fallback()
        .write()
        .map_err(|e| format!("ws runner slot poisoned: {e}"))?;
    let displaced = guard.is_some();
    *guard = Some(session.channel.clone());
    drop(guard);
    car_inference::set_inference_runner(Some(Arc::new(WsInferenceRunner)));
    // Report what happened. A bare `{"registered": true}` to a second registrant
    // was indistinguishable from being the only one, which is how two hosts
    // silently stole each other's calls (car-releases#77).
    Ok(serde_json::json!({
        "registered": true,
        "scope": "session",
        "runners_registered": ws_runner_sessions().len(),
        "became_fallback": true,
        "displaced_fallback": displaced,
    }))
}

#[derive(serde::Deserialize)]
struct InferenceRunnerEventParams {
    call_id: String,
    event: Value,
}

async fn handle_inference_runner_event(req: &JsonRpcMessage) -> Result<Value, String> {
    let params: InferenceRunnerEventParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let stream_event = match parse_runner_event_value(&params.event) {
        Some(e) => e,
        None => return Err("unrecognised runner event shape".into()),
    };
    if let Some(entry) = ws_runner_calls().get(&params.call_id) {
        let emitter = entry.value().clone();
        tokio::spawn(async move { emitter.emit(stream_event).await });
    }
    Ok(serde_json::json!({"emitted": true}))
}

#[derive(serde::Deserialize)]
struct InferenceRunnerCompleteParams {
    call_id: String,
    result: Value,
}

async fn handle_inference_runner_complete(req: &JsonRpcMessage) -> Result<Value, String> {
    let params: InferenceRunnerCompleteParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let result: std::result::Result<car_inference::RunnerResult, String> =
        serde_json::from_value(params.result)
            .map_err(|e| format!("invalid RunnerResult JSON: {e}"));
    if let Some((_, tx)) = ws_runner_completions().remove(&params.call_id) {
        let _ = tx.send(result);
    }
    Ok(serde_json::json!({"completed": true}))
}

#[derive(serde::Deserialize)]
struct InferenceRunnerFailParams {
    call_id: String,
    error: String,
}

async fn handle_inference_runner_fail(req: &JsonRpcMessage) -> Result<Value, String> {
    let params: InferenceRunnerFailParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    if let Some((_, tx)) = ws_runner_completions().remove(&params.call_id) {
        let _ = tx.send(Err(params.error));
    }
    Ok(serde_json::json!({"failed": true}))
}

fn parse_runner_event_value(v: &Value) -> Option<car_inference::StreamEvent> {
    let ty = v.get("type").and_then(|t| t.as_str())?;
    match ty {
        "text" => Some(car_inference::StreamEvent::TextDelta(
            v.get("data")?.as_str()?.to_string(),
        )),
        "tool_start" => Some(car_inference::StreamEvent::ToolCallStart {
            name: v.get("name")?.as_str()?.to_string(),
            index: v.get("index")?.as_u64()? as usize,
            id: v.get("id").and_then(|i| i.as_str()).map(str::to_string),
        }),
        "tool_delta" => Some(car_inference::StreamEvent::ToolCallDelta {
            index: v.get("index")?.as_u64()? as usize,
            arguments_delta: v.get("data")?.as_str()?.to_string(),
        }),
        "usage" => Some(car_inference::StreamEvent::Usage {
            input_tokens: v.get("input_tokens")?.as_u64()?,
            output_tokens: v.get("output_tokens")?.as_u64()?,
            cache_read_input_tokens: v
                .get("cache_read_input_tokens")
                .and_then(|x| x.as_u64())
                .unwrap_or(0),
            cache_creation_input_tokens: v
                .get("cache_creation_input_tokens")
                .and_then(|x| x.as_u64())
                .unwrap_or(0),
        }),
        "provider_output_item" => Some(car_inference::StreamEvent::ProviderOutputItem(
            v.get("item")?.clone(),
        )),
        "error" => Some(car_inference::StreamEvent::Error(
            v.get("message")?.as_str()?.to_string(),
        )),
        "done" => Some(car_inference::StreamEvent::Done {
            text: v.get("text")?.as_str()?.to_string(),
            tool_calls: v
                .get("tool_calls")
                .and_then(|tc| serde_json::from_value(tc.clone()).ok())
                .unwrap_or_default(),
        }),
        _ => None,
    }
}

#[derive(Deserialize)]
struct EnrollSpeakerParams {
    label: String,
    audio: Value,
}

async fn handle_enroll_speaker(req: &JsonRpcMessage) -> Result<Value, String> {
    let params: EnrollSpeakerParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let audio_json = serde_json::to_string(&params.audio).map_err(|e| e.to_string())?;
    let json = car_ffi_common::voice::enroll_speaker(&params.label, &audio_json).await?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

#[derive(Deserialize)]
struct RemoveEnrollmentParams {
    label: String,
}

fn handle_remove_enrollment(req: &JsonRpcMessage) -> Result<Value, String> {
    let params: RemoveEnrollmentParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let json = car_ffi_common::voice::remove_enrollment(&params.label)?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

#[derive(Deserialize)]
struct WorkflowRunParams {
    workflow: Value,
    /// Optional state map seeded into workflow state before the run starts —
    /// the inter-workflow chaining hook (hand a prior run's `final_state` to
    /// the next workflow). Omitted = prior behavior.
    #[serde(default)]
    initial_state: Option<std::collections::HashMap<String, Value>>,
}

async fn handle_workflow_run(
    req: &JsonRpcMessage,
    session: &Arc<crate::session::ClientSession>,
) -> Result<Value, String> {
    let params: WorkflowRunParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let workflow_json = serde_json::to_string(&params.workflow).map_err(|e| e.to_string())?;
    let runner: Arc<dyn car_multi::AgentRunner> = Arc::new(WsAgentRunner {
        channel: session.channel.clone(),
        host: session.host.clone(),
        client_id: session.client_id.clone(),
    });
    let json = car_ffi_common::workflow::run_workflow(&workflow_json, params.initial_state, runner)
        .await?;
    let result: Value = serde_json::from_str(&json).map_err(|e| e.to_string())?;
    // If the run parked at an approval gate, persist the checkpoint durably so
    // it survives a daemon restart and can be resumed by run_id.
    persist_if_paused(&result)?;
    Ok(result)
}

#[derive(Deserialize)]
struct WorkflowChainParams {
    /// Workflow definitions run sequentially: each next workflow's initial
    /// state is the previous result's `final_state` merged over
    /// `initial_state`.
    workflows: Vec<Value>,
    /// Optional base state seeded into every workflow in the chain (the first
    /// workflow gets exactly this; later ones get it merged under the
    /// predecessor's `final_state`).
    #[serde(default)]
    initial_state: Option<std::collections::HashMap<String, Value>>,
}

/// `workflow.chain` — run workflows sequentially, threading each result's
/// `final_state` into the next workflow's initial state. Every workflow is
/// statically pre-validated before any executes (structural garbage rejects
/// the chain up front, as an error). Stops at the first non-`completed`
/// result, returning the results so far plus the stopping status; a paused
/// intermediate persists its checkpoint durably exactly like `workflow.run`
/// (resume it via `workflow.resume` by `run_id`, then re-chain the remainder
/// if desired) and is named by `paused_at_index`. A mid-chain *runtime*
/// engine error (e.g. cycle limit) does not discard the chain: the response
/// still carries `results` so far (delivery evidence included) plus
/// top-level `error` and `failed_at_index`.
async fn handle_workflow_chain(
    req: &JsonRpcMessage,
    session: &Arc<crate::session::ClientSession>,
) -> Result<Value, String> {
    let params: WorkflowChainParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let workflows_json = serde_json::to_string(&params.workflows).map_err(|e| e.to_string())?;
    let runner: Arc<dyn car_multi::AgentRunner> = Arc::new(WsAgentRunner {
        channel: session.channel.clone(),
        host: session.host.clone(),
        client_id: session.client_id.clone(),
    });
    let json =
        car_ffi_common::workflow::chain_workflows(&workflows_json, params.initial_state, runner)
            .await?;
    let result: Value = serde_json::from_str(&json).map_err(|e| e.to_string())?;
    // Only the stopping workflow can be paused (the chain halts there);
    // persist its checkpoint durably so workflow.resume can pick it up.
    if let Some(last) = result
        .get("results")
        .and_then(|r| r.as_array())
        .and_then(|r| r.last())
    {
        persist_if_paused(last)?;
    }
    Ok(result)
}

/// Re-arm workflow runs orphaned by a crash between an approval `claim` and its
/// `complete`. Call **once at daemon startup**, before serving connections, so a
/// restart mid-approval doesn't bury paused runs. Best-effort: logs and returns
/// on any error rather than failing boot.
pub fn recover_workflow_checkpoints() {
    let dir = match workflow_runs_dir() {
        Ok(d) => d,
        Err(e) => {
            tracing::debug!(error = %e, "no workflow checkpoint dir; skipping recovery");
            return;
        }
    };
    match car_workflow::CheckpointStore::open(&dir).and_then(|s| s.recover_orphaned()) {
        Ok(0) => {}
        Ok(n) => tracing::info!(rearmed = n, "recovered orphaned workflow checkpoints"),
        Err(e) => tracing::warn!(error = %e, "workflow checkpoint recovery failed"),
    }
}

/// Directory holding durable workflow checkpoints: `workflow-runs` under the
/// CAR state root — `CAR_HOME` when set, otherwise `~/.car/workflow-runs`.
fn workflow_runs_dir() -> Result<std::path::PathBuf, String> {
    let root = car_home::root()
        .ok_or_else(|| "cannot resolve home directory for workflow checkpoints".to_string())?;
    Ok(root.join("workflow-runs"))
}

/// If `result` is a paused WorkflowResult, save its checkpoint to the store.
fn persist_if_paused(result: &Value) -> Result<(), String> {
    if result.get("status").and_then(|s| s.as_str()) != Some("paused") {
        return Ok(());
    }
    let Some(paused_value) = result.get("paused") else {
        return Err("paused result missing checkpoint".to_string());
    };
    let paused: car_workflow::PausedWorkflow =
        serde_json::from_value(paused_value.clone()).map_err(|e| e.to_string())?;
    let store =
        car_workflow::CheckpointStore::open(workflow_runs_dir()?).map_err(|e| e.to_string())?;
    store.save(&paused).map_err(|e| e.to_string())
}

#[derive(Deserialize)]
struct WorkflowResumeParams {
    run_id: String,
    #[serde(default)]
    input: Value,
}

/// `workflow.list_paused` — list resumable workflow runs with their pause
/// metadata (EPIC H / H1). The discovery half of durable resume: after a daemon
/// restart a client no longer holds the paused `run_id`s, so it enumerates them
/// here (each `{run_id, paused_stage_id, prompt, created_at}`) and resumes by
/// `run_id` via `workflow.resume`. In-flight and corrupt checkpoints are
/// omitted — only genuinely resumable runs are returned.
async fn handle_workflow_list_paused() -> Result<Value, String> {
    let store =
        car_workflow::CheckpointStore::open(workflow_runs_dir()?).map_err(|e| e.to_string())?;
    let summaries = store.list_summaries().map_err(|e| e.to_string())?;
    serde_json::to_value(&summaries).map_err(|e| format!("serialize list_paused: {e}"))
}

async fn handle_workflow_resume(
    req: &JsonRpcMessage,
    session: &Arc<crate::session::ClientSession>,
) -> Result<Value, String> {
    let params: WorkflowResumeParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;

    let store =
        car_workflow::CheckpointStore::open(workflow_runs_dir()?).map_err(|e| e.to_string())?;
    // Atomic claim: a duplicate/racing resume of the same run gets nothing,
    // so a side-effecting downstream stage never runs twice.
    let paused = store
        .claim(&params.run_id)
        .map_err(|e| e.to_string())?
        .ok_or_else(|| {
            format!(
                "no paused workflow run '{}' (already resumed or unknown)",
                params.run_id
            )
        })?;
    let paused_json = serde_json::to_string(&paused).map_err(|e| e.to_string())?;
    let input_json = if params.input.is_null() {
        "{}".to_string()
    } else {
        serde_json::to_string(&params.input).map_err(|e| e.to_string())?
    };

    let runner: Arc<dyn car_multi::AgentRunner> = Arc::new(WsAgentRunner {
        channel: session.channel.clone(),
        host: session.host.clone(),
        client_id: session.client_id.clone(),
    });

    let json = car_ffi_common::workflow::resume_workflow(&paused_json, &input_json, runner).await;
    let result = match json {
        Ok(j) => serde_json::from_str::<Value>(&j).map_err(|e| e.to_string())?,
        Err(e) => {
            // Resume failed (e.g. invalid input) — release the in-flight marker
            // so the run can be resumed again with corrected input.
            let _ = store.save(&paused);
            let _ = store.complete(&params.run_id);
            return Err(e);
        }
    };
    // Re-paused at another gate → persist the fresh checkpoint; either way drop
    // the in-flight marker from the claim.
    persist_if_paused(&result)?;
    store.complete(&params.run_id).map_err(|e| e.to_string())?;
    Ok(result)
}

#[derive(Deserialize)]
struct BuilderBuildParams {
    goal: String,
    #[serde(default)]
    existing: Value,
    #[serde(default = "default_builder_attempts")]
    max_attempts: u32,
}

fn default_builder_attempts() -> u32 {
    3
}

/// `builder.build` — natural language → validated workflow. Runs on the daemon so
/// the catalog is authoritative: tools come from this session's registered tool
/// schemas and models from the inference registry, making the builder's
/// tool-existence cross-check meaningful.
async fn handle_builder_build(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    session: &Arc<crate::session::ClientSession>,
) -> Result<Value, String> {
    let params: BuilderBuildParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    if params.goal.trim().is_empty() {
        return Err("missing 'goal'".to_string());
    }

    let engine = get_inference_engine(state).clone();

    let tools: Vec<car_builder::ToolInfo> = session
        .runtime
        .registry
        .schemas()
        .await
        .into_iter()
        .map(|s| car_builder::ToolInfo {
            name: s.name,
            description: s.description,
        })
        .collect();
    let models: Vec<String> = engine
        .list_models_unified()
        .into_iter()
        .map(|m| m.id)
        .collect();
    let catalog = car_builder::ToolCatalog {
        tools,
        models,
        agents: Vec::new(),
    };

    let existing = if params.existing.is_null() {
        None
    } else {
        serde_json::from_value::<car_workflow::Workflow>(params.existing.clone()).ok()
    };

    let build_req = car_builder::BuildRequest {
        goal: params.goal,
        catalog,
        existing,
        feedback: None,
        max_attempts: params.max_attempts,
    };

    let result = car_builder::build_workflow(
        |prompt: String| {
            let engine = engine.clone();
            async move {
                let greq = car_inference::GenerateRequest {
                    prompt,
                    model: None,
                    expected_row_digest: None,
                    expected_catalog_revision: None,
                    params: car_inference::GenerateParams {
                        temperature: 0.2,
                        max_tokens: 4096,
                        ..Default::default()
                    },
                    context: None,
                    context_stable_prefix: None,
                    tools: None,
                    images: None,
                    messages: None,
                    cache_control: false,
                    response_format: None,
                    intent: None,
                    client_ref: None,
                    caller: None,
                };
                engine
                    .generate_tracked(greq)
                    .await
                    .map(|r| r.text)
                    .map_err(|e| e.to_string())
            }
        },
        &build_req,
    )
    .await;

    Ok(serde_json::json!({
        "valid": result.valid,
        "workflow": result.workflow,
        "issues": result.issues,
        "warnings": result.warnings,
        "attempts": result.attempts,
    }))
}

#[derive(Deserialize)]
struct WorkflowVerifyParams {
    workflow: Value,
}

fn handle_workflow_verify(req: &JsonRpcMessage) -> Result<Value, String> {
    let params: WorkflowVerifyParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let workflow_json = serde_json::to_string(&params.workflow).map_err(|e| e.to_string())?;
    let json = car_ffi_common::workflow::verify_workflow(&workflow_json)?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

#[derive(Deserialize)]
struct WorkflowBuildAutomationParams {
    spec: Value,
}

/// Lower an external-item `AutomationSpec` (poll → dedup → per-item agent →
/// deliver) into a runnable workflow definition. Stateless; the caller hands the
/// returned workflow back to `workflow.run` (typically on a schedule).
fn handle_workflow_build_automation(req: &JsonRpcMessage) -> Result<Value, String> {
    let params: WorkflowBuildAutomationParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let spec_json = serde_json::to_string(&params.spec).map_err(|e| e.to_string())?;
    let json = car_ffi_common::workflow::build_automation_workflow(&spec_json)?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

// ---------------------------------------------------------------------------
// Meeting JSON-RPC methods
// ---------------------------------------------------------------------------

async fn handle_meeting_start(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    session: &Arc<crate::session::ClientSession>,
) -> Result<Value, String> {
    // We need the meeting id BEFORE handing the upstream sink to
    // start_meeting so the WsMemgineIngestSink stamps transcripts with
    // the correct `meeting/<id>/<source>` speaker. Parse the request
    // here, mint an id if none was provided, and pass the same id
    // through to start_meeting via the request JSON.
    let mut req_value = req.params.clone();
    let meeting_id = req_value
        .get("id")
        .and_then(|v| v.as_str())
        .map(str::to_string)
        .unwrap_or_else(|| uuid::Uuid::new_v4().simple().to_string());
    if let Some(map) = req_value.as_object_mut() {
        map.insert("id".into(), Value::String(meeting_id.clone()));
    }
    let request_json = serde_json::to_string(&req_value).map_err(|e| e.to_string())?;

    let ws_upstream: Arc<dyn car_voice::VoiceEventSink> =
        Arc::new(crate::session::WsVoiceEventSink {
            channel: session.channel.clone(),
        });

    // Wrap the WS upstream with a memgine-ingest fanout that uses the
    // tokio::sync::Mutex-wrapped session memgine. We pass `None` for
    // the FFI-common `start_meeting` memgine arg to avoid the
    // sync-mutex contract there — ingest happens here instead.
    let upstream: Arc<dyn car_voice::VoiceEventSink> =
        Arc::new(crate::session::WsMemgineIngestSink {
            meeting_id,
            engine: session.memgine.clone(),
            upstream: ws_upstream,
        });

    let cwd = std::env::current_dir().ok();
    let json = crate::meeting::start_meeting(
        &request_json,
        state.meetings.clone(),
        state.voice_sessions.clone(),
        upstream,
        None,
        cwd,
    )
    .await?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

#[derive(Deserialize)]
struct MeetingStopParams {
    meeting_id: String,
    #[serde(default = "default_summarize")]
    summarize: bool,
}

fn default_summarize() -> bool {
    true
}

async fn handle_meeting_stop(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    _session: &Arc<crate::session::ClientSession>,
) -> Result<Value, String> {
    let params: MeetingStopParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let inference = if params.summarize {
        Some(state.inference.get().cloned()).flatten()
    } else {
        None
    };
    let json = crate::meeting::stop_meeting(
        &params.meeting_id,
        params.summarize,
        state.meetings.clone(),
        state.voice_sessions.clone(),
        inference,
    )
    .await?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

#[derive(Deserialize, Default)]
struct MeetingListParams {
    #[serde(default)]
    root: Option<std::path::PathBuf>,
}

fn handle_meeting_list(req: &JsonRpcMessage) -> Result<Value, String> {
    let params: MeetingListParams = serde_json::from_value(req.params.clone()).unwrap_or_default();
    let cwd = std::env::current_dir().ok();
    let json = crate::meeting::list_meetings(params.root, cwd)?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

#[derive(Deserialize)]
struct MeetingGetParams {
    meeting_id: String,
    #[serde(default)]
    root: Option<std::path::PathBuf>,
}

fn handle_meeting_get(req: &JsonRpcMessage) -> Result<Value, String> {
    let params: MeetingGetParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let cwd = std::env::current_dir().ok();
    let json = crate::meeting::get_meeting(&params.meeting_id, params.root, cwd)?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

// ---------------------------------------------------------------------------
// Agent registry — file-based cross-process discovery (#111)
// ---------------------------------------------------------------------------

#[derive(Deserialize, Default)]
struct RegistryRegisterParams {
    /// Caller serializes their AgentEntry as a JSON value; we
    /// re-serialize it so the ffi-common helper can validate the
    /// shape with the same parser used by the bindings.
    entry: Value,
    #[serde(default)]
    registry_path: Option<std::path::PathBuf>,
}

fn handle_registry_register(req: &JsonRpcMessage) -> Result<Value, String> {
    let params: RegistryRegisterParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let entry_json = serde_json::to_string(&params.entry).map_err(|e| e.to_string())?;
    car_ffi_common::registry::register_agent(&entry_json, params.registry_path)?;
    Ok(Value::Null)
}

#[derive(Deserialize, Default)]
struct RegistryNameParams {
    name: String,
    #[serde(default)]
    registry_path: Option<std::path::PathBuf>,
}

fn handle_registry_heartbeat(req: &JsonRpcMessage) -> Result<Value, String> {
    let params: RegistryNameParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let json = car_ffi_common::registry::agent_heartbeat(&params.name, params.registry_path)?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

fn handle_registry_unregister(req: &JsonRpcMessage) -> Result<Value, String> {
    let params: RegistryNameParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    car_ffi_common::registry::unregister_agent(&params.name, params.registry_path)?;
    Ok(Value::Null)
}

#[derive(Deserialize, Default)]
struct RegistryListParams {
    #[serde(default)]
    registry_path: Option<std::path::PathBuf>,
}

fn handle_registry_list(req: &JsonRpcMessage) -> Result<Value, String> {
    let params: RegistryListParams = serde_json::from_value(req.params.clone()).unwrap_or_default();
    let json = car_ffi_common::registry::list_agents(params.registry_path)?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

#[derive(Deserialize, Default)]
struct RegistryReapParams {
    /// Heartbeats older than this many seconds are reaped. Default
    /// 60 — two missed 20s heartbeats trigger removal.
    #[serde(default = "default_reap_age")]
    max_age_secs: u64,
    #[serde(default)]
    registry_path: Option<std::path::PathBuf>,
}

fn default_reap_age() -> u64 {
    60
}

fn handle_registry_reap(req: &JsonRpcMessage) -> Result<Value, String> {
    let params: RegistryReapParams = serde_json::from_value(req.params.clone()).unwrap_or_default();
    let json =
        car_ffi_common::registry::reap_stale_agents(params.max_age_secs, params.registry_path)?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

// ---------------------------------------------------------------------------
// car-a2a server lifecycle (mirrors NAPI startA2AServer / stopA2AServer /
// a2AServerStatus and PyO3 start_a2a_server / stop_a2a_server /
// a2a_server_status — closes the binding gap noted in #126).
// ---------------------------------------------------------------------------

async fn handle_a2a_start(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let params_json = serde_json::to_string(&req.params).map_err(|e| e.to_string())?;
    // Always hand the session's runtime through. start_a2a uses it
    // only when `share_session_runtime: true` is set in params;
    // otherwise it falls back to the legacy fresh-Runtime + agent_basics
    // path. Passing it unconditionally keeps the FFI layer ignorant of
    // the flag's plumbing.
    //
    // Also hand through a chat responder bound to THIS session so a
    // conversational (text-only) `message/send` to the A2A listener routes back
    // to this host agent's `agent.chat` handler (car-releases#65). start_a2a
    // wires it only when `share_session_runtime: true` — without the shared
    // runtime there's no host loop to route to.
    let responder: Arc<dyn car_a2a::ChatResponder> = Arc::new(WsChatResponder {
        state: Arc::downgrade(state),
        host_client_id: session.client_id.clone(),
    });
    let json =
        crate::a2a::start_a2a(&params_json, Some(session.runtime.clone()), Some(responder)).await?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

fn handle_a2a_stop() -> Result<Value, String> {
    let json = crate::a2a::stop_a2a()?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

fn handle_a2a_status() -> Result<Value, String> {
    let json = crate::a2a::a2a_status()?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

// a2a.peers.* — registry of remote A2A peers CAR can discover/call. Reachable
// from the language bindings via the generic `a2a_dispatch` proxy.

#[derive(serde::Deserialize)]
struct A2aPeerAddParams {
    url: String,
    #[serde(default)]
    label: Option<String>,
    /// Opt-in to register a non-loopback peer (see the gate below).
    #[serde(default)]
    allow_untrusted: bool,
}

fn handle_a2a_peers_add(req: &JsonRpcMessage) -> Result<Value, String> {
    let params: A2aPeerAddParams =
        serde_json::from_value(req.params.clone()).map_err(|e| format!("invalid params: {e}"))?;
    // `discovery.resolve` will issue an outbound GET to this URL's agent card,
    // so registering a non-loopback peer is a deliberate trust decision — gate
    // it the same way `a2a.send` gates its endpoint (SSRF guard: otherwise any
    // registered URL, incl. internal/metadata endpoints, becomes a daemon GET).
    if !params.allow_untrusted && !is_loopback_http_endpoint(&params.url) {
        return Err(
            "a2a.peers.add endpoint must be loopback unless allowUntrusted is true".to_string(),
        );
    }
    let reg = car_a2a::peers::PeerRegistry::user_default()?;
    let entry = reg.add(&params.url, params.label)?;
    serde_json::to_value(entry).map_err(|e| e.to_string())
}

fn handle_a2a_peers_list() -> Result<Value, String> {
    let reg = car_a2a::peers::PeerRegistry::user_default()?;
    Ok(serde_json::json!({ "peers": reg.list() }))
}

#[derive(serde::Deserialize)]
struct A2aPeerRemoveParams {
    slug: String,
}

fn handle_a2a_peers_remove(req: &JsonRpcMessage) -> Result<Value, String> {
    let params: A2aPeerRemoveParams =
        serde_json::from_value(req.params.clone()).map_err(|e| format!("invalid params: {e}"))?;
    let reg = car_a2a::peers::PeerRegistry::user_default()?;
    Ok(serde_json::json!({ "removed": reg.remove(&params.slug)? }))
}

#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct A2aSendParams {
    endpoint: String,
    message: car_a2a::Message,
    #[serde(default)]
    blocking: bool,
    #[serde(default = "default_true")]
    ingest_a2ui: bool,
    #[serde(default)]
    route_auth: Option<A2aRouteAuth>,
    #[serde(default)]
    allow_untrusted_endpoint: bool,
}

fn default_true() -> bool {
    true
}

/// In-core A2A dispatcher entry point. Forwards the JSON-RPC method
/// + params to the lazy-initialized [`car_a2a::A2aDispatcher`] held
/// on `ServerState`. Closes Parslee-ai/car-releases#28.
///
/// Streaming methods (`message/stream`, `tasks/resubscribe` and their
/// PascalCase aliases) return `MethodNotFound` from the dispatcher's
/// transport-neutral surface — the standalone `start_a2a_listener`
/// HTTP path serves SSE for those, but the in-core WS surface is
/// JSON-RPC only. Same trade as the dispatcher itself.
async fn handle_a2a_dispatch(
    method: &str,
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let dispatcher = state.a2a_dispatcher().await;
    dispatcher
        .dispatch(method, req.params.clone())
        .await
        .map_err(|e| e.to_string())
}

async fn handle_a2a_send(req: &JsonRpcMessage, state: &Arc<ServerState>) -> Result<Value, String> {
    let params: A2aSendParams =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let endpoint = trusted_route_endpoint(
        Some(params.endpoint.clone()),
        params.allow_untrusted_endpoint,
    )
    .ok_or_else(|| {
        "`a2a.send` endpoint must be loopback unless allowUntrustedEndpoint is true".to_string()
    })?;
    let client = match params.route_auth.clone() {
        Some(auth) => {
            car_a2a::A2aClient::new(endpoint.clone()).with_auth(client_auth_from_route_auth(auth))
        }
        None => car_a2a::A2aClient::new(endpoint.clone()),
    };
    let result = client
        .send_message(params.message, params.blocking)
        .await
        .map_err(|e| e.to_string())?;
    let result_value = serde_json::to_value(&result).map_err(|e| e.to_string())?;
    let mut applied = Vec::new();
    if params.ingest_a2ui {
        state
            .a2ui
            .validate_payload(&result_value)
            .map_err(|e| e.to_string())?;
        let routed_endpoint = Some(endpoint.clone());
        for envelope in car_a2ui::envelopes_from_value(&result_value).map_err(|e| e.to_string())? {
            let owner = car_a2ui::owner_from_value(&result_value).map(|owner| {
                if owner.endpoint.is_none() {
                    owner.with_endpoint(routed_endpoint.clone())
                } else {
                    owner
                }
            });
            applied.push(
                apply_a2ui_envelope(state, envelope, owner, params.route_auth.clone()).await?,
            );
        }
    }
    Ok(serde_json::json!({
        "result": result,
        "a2ui": {
            "applied": applied,
        }
    }))
}

// ---------------------------------------------------------------------------
// macOS automation — AppleScript + Shortcuts (car-automation), Vision OCR
// (car-vision). Mirrors NAPI runApplescript / listShortcuts / runShortcut /
// visionOcr and PyO3 run_applescript / list_shortcuts / run_shortcut /
// vision_ocr.
// ---------------------------------------------------------------------------

async fn handle_run_applescript(req: &JsonRpcMessage) -> Result<Value, String> {
    let args_json = serde_json::to_string(&req.params).map_err(|e| e.to_string())?;
    let json = car_ffi_common::automation::run_applescript(&args_json).await?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

async fn handle_run_powershell(req: &JsonRpcMessage) -> Result<Value, String> {
    let args_json = serde_json::to_string(&req.params).map_err(|e| e.to_string())?;
    let json = car_ffi_common::automation::run_powershell(&args_json).await?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

async fn handle_list_shortcuts(req: &JsonRpcMessage) -> Result<Value, String> {
    let args_json = serde_json::to_string(&req.params).map_err(|e| e.to_string())?;
    let json = car_ffi_common::automation::list_shortcuts(&args_json).await?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

async fn handle_run_shortcut(req: &JsonRpcMessage) -> Result<Value, String> {
    let args_json = serde_json::to_string(&req.params).map_err(|e| e.to_string())?;
    let json = car_ffi_common::automation::run_shortcut(&args_json).await?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

async fn handle_local_notification(req: &JsonRpcMessage) -> Result<Value, String> {
    let args_json = serde_json::to_string(&req.params).map_err(|e| e.to_string())?;
    let json = car_ffi_common::notifications::local(&args_json).await?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

async fn handle_vision_ocr(req: &JsonRpcMessage) -> Result<Value, String> {
    let args_json = serde_json::to_string(&req.params).map_err(|e| e.to_string())?;
    let json = car_ffi_common::vision::ocr(&args_json).await?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

// ---------------------------------------------------------------------------
// Lifecycle-managed agents (car_registry::supervisor) — Parslee-ai/car-releases#27
// ---------------------------------------------------------------------------

/// Serialize a `ManagedAgent` for the wire, WITHOUT its per-agent token.
///
/// `AgentSpec::token` is the credential `session.auth { agent_id, token }`
/// checks, and `ManagedAgent` flattens the spec — so serializing one verbatim
/// published every supervised agent's credential to any authenticated caller.
/// That made the bound-identity rules in this file decorative rather than wrong:
/// an agent could read another's token, authenticate AS it, and then every
/// identity check would pass because the bound identity genuinely was the
/// victim. A spoofing rule cannot hold while the impersonation credential is a
/// public read.
///
/// Redacted in the PROJECTION rather than with `skip_serializing` on the field:
/// `AgentSpec` is also the on-disk `agents.json` format, so skipping it there
/// would silently blank every token on the next manifest write.
fn agent_to_wire(agent: &car_registry::supervisor::ManagedAgent) -> Result<Value, String> {
    let mut v = serde_json::to_value(agent).map_err(|e| e.to_string())?;
    if let Some(map) = v.as_object_mut() {
        map.remove("token");
    }
    Ok(v)
}

async fn handle_agents_list(state: &Arc<ServerState>) -> Result<Value, String> {
    // Observe-only mode (Parslee-ai/car-releases#44): a second
    // car-server on the host can't take the supervisor lock, so it
    // can't drive `Supervisor::list` — but it can still answer
    // `agents.list` by reading the on-disk manifest directly. The
    // `attached` decoration is local to whichever daemon the caller
    // is talking to, so observer-mode entries return `attached:
    // false` (this daemon hasn't received `session.auth` from those
    // children; the primary one has).
    let (agents, manifest_path, log_dir) = match state.observer_manifest_path() {
        Some(p) => {
            let agents = car_registry::supervisor::Supervisor::list_from_manifest(p)
                .map_err(|e| e.to_string())?;
            let log_dir = p
                .parent()
                .map(|parent| parent.join("logs"))
                .unwrap_or_else(|| std::path::PathBuf::from("logs"));
            (agents, p.clone(), log_dir)
        }
        None => {
            let supervisor = state.supervisor()?;
            let agents = supervisor.list().await;
            (
                agents,
                supervisor.manifest_path().to_path_buf(),
                supervisor.log_dir().to_path_buf(),
            )
        }
    };
    let agents_dir = manifest_path
        .parent()
        .map(|parent| parent.join("agents"))
        .unwrap_or_else(|| std::path::PathBuf::from("agents"));
    // Decorate each entry with `attached` + `session_id` so operators
    // see whether the supervised process has actually called
    // `session.auth { agent_id }` and bound a WS connection (#169) —
    // the lifecycle status (`Running`, etc.) only reports the
    // process-level view, which can't tell "alive but never
    // attached" from "alive and attached".
    let attached = state.attached_agents.lock().await.clone();
    let mut decorated: Vec<Value> = Vec::with_capacity(agents.len());
    for a in agents {
        let mut v = agent_to_wire(&a)?;
        let session_id = attached.get(&a.spec.id).cloned();
        if let Some(map) = v.as_object_mut() {
            map.insert("attached".to_string(), Value::Bool(session_id.is_some()));
            map.insert(
                "manifest_path".to_string(),
                Value::String(
                    agents_dir
                        .join(&a.spec.id)
                        .join("manifest.toml")
                        .to_string_lossy()
                        .into_owned(),
                ),
            );
            map.insert(
                "log_path".to_string(),
                Value::String(
                    log_dir
                        .join(format!("{}.stdout.log", a.spec.id))
                        .to_string_lossy()
                        .into_owned(),
                ),
            );
            map.insert(
                "stderr_log_path".to_string(),
                Value::String(
                    log_dir
                        .join(format!("{}.stderr.log", a.spec.id))
                        .to_string_lossy()
                        .into_owned(),
                ),
            );
            if let Some(sid) = session_id {
                map.insert("session_id".to_string(), Value::String(sid));
            }
        }
        decorated.push(v);
    }
    // Merge in declarative (in-daemon) agents the coder→agent loop built. They
    // carry `kind:"declarative"` + `enabled` instead of process status, and
    // never travel through the supervisor's command-validation path.
    decorated.extend(crate::coder::rpc::declarative_agent_rows(state).await);
    Ok(Value::Array(decorated))
}

async fn handle_agents_upsert(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    require_host_lifecycle_authority(session, state).await?;
    let mut params = req.params.clone();
    // Optional `interpreter` sugar (#171). When present, the
    // supervisor resolves the bare program name (`"node"`,
    // `"python"`, …) against `$PATH` and writes the absolute path
    // into `command` *before* validation. This keeps the strict
    // no-PATH-lookup rule at upsert time while letting callers
    // stop hand-coding `/opt/homebrew/bin/node` into every
    // agents.json entry. Resolution happens once; subsequent PATH
    // changes do not silently rewire the binding.
    if let Some(name) = params
        .get("interpreter")
        .and_then(|v| v.as_str())
        .map(str::to_string)
    {
        let resolved =
            car_registry::supervisor::resolve_interpreter(&name).map_err(|e| e.to_string())?;
        params["command"] = Value::String(resolved.to_string_lossy().into_owned());
    }
    let spec: car_registry::supervisor::AgentSpec =
        serde_json::from_value(params).map_err(|e| e.to_string())?;
    let supervisor = state.supervisor()?;
    let agent = supervisor.upsert(spec).await.map_err(|e| e.to_string())?;
    agent_to_wire(&agent)
}

/// `agents.install` — install a contributed-agent manifest
/// (Parslee-ai/car#182 phase 3). Caller passes the parsed
/// `AgentManifest` JSON; the daemon runs install-time validation
/// (`car_min_version`, capability negotiation against the daemon's
/// own advertisement) and adopts the manifest. Returns
/// `{ report, agent? }` where `agent` is the spawnable
/// `ManagedAgent` for `external_process` transports and absent for
/// `pure_data` / health_url-only manifests.
///
/// The host capability advertisement comes from
/// `HostCapabilities::daemon_default(car_version)` — operators that
/// want a tighter advertisement go through a future config phase;
/// this MVP uses the runtime's natural surface.
async fn handle_agents_install(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    require_host_lifecycle_authority(session, state).await?;
    let manifest: car_registry::manifest::AgentManifest =
        serde_json::from_value(req.params.clone()).map_err(|e| e.to_string())?;
    let host = car_registry::install::HostCapabilities::daemon_default(env!("CARGO_PKG_VERSION"));
    let supervisor = state.supervisor()?;
    let (report, managed) = supervisor
        .install_manifest(manifest, &host)
        .await
        .map_err(|e| e.to_string())?;
    Ok(serde_json::json!({
        "report": {
            "missingOptional": report
                .missing_optional
                .iter()
                .map(|(ns, feat)| serde_json::json!({ "namespace": ns, "feature": feat }))
                .collect::<Vec<_>>(),
        },
        "agent": managed,
    }))
}

async fn handle_agents_health(state: &Arc<ServerState>) -> Result<Value, String> {
    // Observe-only mode (Parslee-ai/car-releases#44) — see
    // `handle_agents_list` for the rationale. The health view is a
    // pure function of each entry's `command` plus the on-disk
    // sandbox rules, so reading from the manifest is equivalent to
    // calling the live supervisor's `health()`.
    let entries = match state.observer_manifest_path() {
        Some(p) => car_registry::supervisor::Supervisor::health_from_manifest(p)
            .map_err(|e| e.to_string())?,
        None => {
            let supervisor = state.supervisor()?;
            supervisor.health().await
        }
    };
    serde_json::to_value(entries).map_err(|e| e.to_string())
}

fn extract_agent_id(req: &JsonRpcMessage) -> Result<String, String> {
    req.params
        .get("id")
        .and_then(Value::as_str)
        .map(str::to_string)
        .ok_or_else(|| "missing required `id` parameter".to_string())
}

async fn handle_agents_remove(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    require_host_lifecycle_authority(session, state).await?;
    let id = extract_agent_id(req)?;
    let supervisor = state.supervisor()?;
    let removed = supervisor.remove(&id).await.map_err(|e| e.to_string())?;
    Ok(serde_json::json!({ "removed": removed }))
}

async fn handle_agents_start(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let id = extract_agent_id(req)?;
    require_own_agent_or_host(session, state, "agents.start", &id).await?;
    let supervisor = state.supervisor()?;
    let agent = supervisor.start(&id).await.map_err(|e| e.to_string())?;
    agent_to_wire(&agent)
}

async fn handle_agents_stop(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let id = extract_agent_id(req)?;
    require_own_agent_or_host(session, state, "agents.stop", &id).await?;
    let signal: car_registry::supervisor::StopSignal = req
        .params
        .get("signal")
        .map(|v| serde_json::from_value(v.clone()))
        .transpose()
        .map_err(|e| e.to_string())?
        .unwrap_or_default();
    let supervisor = state.supervisor()?;
    let agent = supervisor
        .stop(&id, signal)
        .await
        .map_err(|e| e.to_string())?;
    agent_to_wire(&agent)
}

async fn handle_agents_restart(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    session: &crate::session::ClientSession,
) -> Result<Value, String> {
    let id = extract_agent_id(req)?;
    require_own_agent_or_host(session, state, "agents.restart", &id).await?;
    let supervisor = state.supervisor()?;
    let agent = supervisor.restart(&id).await.map_err(|e| e.to_string())?;
    agent_to_wire(&agent)
}

/// Block until a managed agent reaches one of the target statuses, or the
/// timeout elapses. Params: `{ id, targets?: string[] = ["running"],
/// Ceiling for `agents.wait { timeout_secs }`. Far longer than any real
/// start or stop, and finite — an unbounded caller-supplied wait is a hold on
/// daemon resources for as long as the caller likes.
const MAX_AGENT_WAIT_SECS: f64 = 600.0;

/// timeout_secs?: number = 30, poll_ms?: number = 200 }`. Returns the matching
/// `ManagedAgent`, or an error on timeout / unknown id.
async fn handle_agents_wait(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    bound_agent: Option<&str>,
) -> Result<Value, String> {
    let id = extract_agent_id(req)?;
    require_own_agent(bound_agent, "agents.wait", &id)?;
    let targets: Vec<car_registry::supervisor::AgentStatus> = match req.params.get("targets") {
        Some(v) => serde_json::from_value(v.clone())
            .map_err(|e| format!("invalid 'targets' (expected status string array): {e}"))?,
        None => vec![car_registry::supervisor::AgentStatus::Running],
    };
    let targets = if targets.is_empty() {
        vec![car_registry::supervisor::AgentStatus::Running]
    } else {
        targets
    };
    let timeout = std::time::Duration::from_secs_f64(
        req.params
            .get("timeout_secs")
            .and_then(Value::as_f64)
            .unwrap_or(30.0)
            // Bounded at both ends. Only the floor was enforced, so a caller
            // could ask the daemon to hold a supervisor poll open for an
            // arbitrary duration; ten minutes is far longer than any real
            // start/stop and still terminates.
            .clamp(0.0, MAX_AGENT_WAIT_SECS),
    );
    let poll = std::time::Duration::from_millis(
        req.params
            .get("poll_ms")
            .and_then(Value::as_u64)
            .unwrap_or(200)
            .max(10),
    );
    let supervisor = state.supervisor()?;
    let agent = supervisor
        .wait_for(&id, &targets, timeout, poll)
        .await
        .map_err(|e| e.to_string())?;
    agent_to_wire(&agent)
}

async fn handle_agents_tail_log(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    bound_agent: Option<&str>,
) -> Result<Value, String> {
    let id = extract_agent_id(req)?;
    require_own_agent(bound_agent, "agents.tail_log", &id)?;
    // Honor `n` OR `lines` for the count — the CarHost UI historically
    // sent `lines: 200` while the daemon only read `n`, so the count
    // was silently ignored and the modal title lied (Parslee-ai/car#273).
    let n = req
        .params
        .get("n")
        .or_else(|| req.params.get("lines"))
        .and_then(Value::as_u64)
        .unwrap_or(100) as usize;
    let offset = req
        .params
        .get("offset")
        .and_then(Value::as_u64)
        .unwrap_or(0) as usize;
    let stream = car_registry::supervisor::LogStream::from_wire(
        req.params.get("stream").and_then(Value::as_str),
    );
    let supervisor = state.supervisor()?;
    let tail = supervisor
        .read_log(&id, stream, n, offset)
        .await
        .map_err(|e| e.to_string())?;
    serde_json::to_value(tail).map_err(|e| e.to_string())
}

// ---------------------------------------------------------------------------
// External-agent detection (Phase 1 of docs/proposals/external-agent-detection.md)
//
// Discovery surface for agentic CLIs the user has already installed and
// authenticated (Claude Code, Codex, Gemini). Read-only — no invocation
// path yet; agents.invoke_external lands in Phase 2 alongside the JSON
// stdio adapter. The cache lives in car_ffi_common::external_agents so
// the in-process FFI singletons share the same snapshot.
// ---------------------------------------------------------------------------

async fn handle_agents_list_external(req: &JsonRpcMessage) -> Result<Value, String> {
    let include_health = req
        .params
        .get("include_health")
        .and_then(Value::as_bool)
        .unwrap_or(false);
    let json = car_ffi_common::external_agents::list(include_health).await?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

async fn handle_agents_detect_external(req: &JsonRpcMessage) -> Result<Value, String> {
    let include_health = req
        .params
        .get("include_health")
        .and_then(Value::as_bool)
        .unwrap_or(false);
    let json = car_ffi_common::external_agents::detect(include_health).await?;
    serde_json::from_str(&json).map_err(|e| e.to_string())
}

#[derive(Debug, Deserialize)]
struct AssistantInvokeParams {
    capability: String,
    #[serde(default)]
    agent_hint: Option<String>,
    payload_json: String,
}

const ASSISTANT_INVOKE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);

/// Daemon-owned invocation for ready-to-use assistants. This mirrors the
/// UniFFI `invoke_capability` contract, but brackets the model call in the
/// durable run trace store so CarHost's Activity tab can explain what ran.
async fn handle_assistants_invoke(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    host_session: &Arc<crate::session::ClientSession>,
) -> Result<Value, String> {
    let params: AssistantInvokeParams =
        serde_json::from_value(req.params.clone()).map_err(|e| {
            format!("assistants.invoke requires {{ capability, agent_hint?, payload_json }}: {e}")
        })?;
    let capability = params.capability.trim();
    if capability.is_empty() {
        return Err("assistants.invoke requires a non-empty `capability`".to_string());
    }

    let registry = car_engine::AgentCapabilityRegistry::new();
    car_engine::register_builtins(&registry);
    let agent = registry
        .select(capability, params.agent_hint.as_deref())
        .ok_or_else(|| format!("no ready-to-use assistant supports capability `{capability}`"))?;
    let task = car_engine::format_capability_payload(capability, &params.payload_json)
        .map_err(|e| e.to_string())?;
    let system_prompt = car_engine::agent_metadata(&agent)
        .map(|m| m.system_prompt.to_string())
        .unwrap_or_else(|| "You are a helpful assistant. Carry out the user's task.".into());

    let run_id = uuid::Uuid::new_v4().to_string();
    let started_at = chrono::Utc::now();
    state
        .start_run(crate::session::RunMeta {
            run_id: run_id.clone(),
            agent_id: agent.clone(),
            client_id: host_session.client_id.clone(),
            active_client_id: host_session.client_id.clone(),
            resume_predecessor_client_id: None,
            resume_lease: None,
            intent: task.clone(),
            outcome_description: Some(format!("Run {capability} with a ready-to-use assistant")),
            started_at,
            termination: None,
            ended_at: None,
            turns: Vec::new(),
            start_committed: false,
            pending_terminal: None,
            cancellation_pending: None,
            cancellation_receipt: None,
            trace_corruption: None,
            durability_generation: 0,
        })
        .await?;

    let req = car_inference::GenerateRequest {
        prompt: task.clone(),
        context: Some(system_prompt),
        intent: Some(car_inference::IntentHint {
            prefer_fast: true,
            ..Default::default()
        }),
        ..Default::default()
    };
    let engine = get_inference_engine(state);
    let generated: Result<String, String> = match assistant_model_setup_message(engine, &req).await
    {
        Some(message) => Err(message),
        None => match tokio::time::timeout(ASSISTANT_INVOKE_TIMEOUT, engine.generate(req)).await {
            Ok(Ok(result)) => Ok(result),
            Ok(Err(e)) => Err(format!("Assistant failed: {e}")),
            Err(_) => Err(format!(
                "Assistant timed out after {} seconds. Choose a faster model in Models, or try again after model setup finishes.",
                ASSISTANT_INVOKE_TIMEOUT.as_secs()
            )),
        },
    };

    match generated {
        Ok(result) => {
            registry.note_used(capability, &agent);
            let _ = state
                .record_run_turns(
                    &run_id,
                    vec![car_proto::RunRecord::Turn(car_proto::RunTurn {
                        index: 0,
                        proposal_id: None,
                        action_id: None,
                        action_status: None,
                        action_duration_ms: None,
                        action_completed_at: None,
                        depends_on: None,
                        state_dependencies: None,
                        prompt: Some(task),
                        tool: Some(capability.to_string()),
                        parameters: serde_json::from_str(&params.payload_json).unwrap_or_else(
                            |_| serde_json::json!({ "payload_json": params.payload_json }),
                        ),
                        output: Some(serde_json::json!({ "text": result })),
                        cli_outcome: None,
                        verifier_verdict: car_proto::VerifierVerdict::NotRun,
                        policy_rejected: None,
                    })],
                )
                .await;
            state
                .complete_run(
                    &run_id,
                    car_proto::RunTermination::Outcome {
                        status: car_ir::OutcomeStatus::Success,
                        outcome: car_ir::AgentOutcome {
                            status: car_ir::OutcomeStatus::Success,
                            summary: "Assistant completed successfully.".to_string(),
                            evidence: Vec::new(),
                            metrics: Default::default(),
                            timestamp: chrono::Utc::now(),
                        },
                    },
                )
                .await?;
            Ok(serde_json::json!({
                "agent": agent,
                "result": result,
                "run_id": run_id,
            }))
        }
        Err(message) => {
            let _ = state
                .record_run_turns(
                    &run_id,
                    vec![car_proto::RunRecord::Turn(car_proto::RunTurn {
                        index: 0,
                        proposal_id: None,
                        action_id: None,
                        action_status: None,
                        action_duration_ms: None,
                        action_completed_at: None,
                        depends_on: None,
                        state_dependencies: None,
                        prompt: Some(task),
                        tool: Some(capability.to_string()),
                        parameters: serde_json::from_str(&params.payload_json).unwrap_or_else(
                            |_| serde_json::json!({ "payload_json": params.payload_json }),
                        ),
                        output: Some(serde_json::json!({ "error": message.clone() })),
                        cli_outcome: None,
                        verifier_verdict: car_proto::VerifierVerdict::NotRun,
                        policy_rejected: None,
                    })],
                )
                .await;
            state
                .complete_run(
                    &run_id,
                    car_proto::RunTermination::Outcome {
                        status: car_ir::OutcomeStatus::Failure,
                        outcome: car_ir::AgentOutcome {
                            status: car_ir::OutcomeStatus::Failure,
                            summary: message.clone(),
                            evidence: Vec::new(),
                            metrics: Default::default(),
                            timestamp: chrono::Utc::now(),
                        },
                    },
                )
                .await?;
            Err(message)
        }
    }
}

async fn assistant_model_setup_message(
    engine: &car_inference::InferenceEngine,
    req: &car_inference::GenerateRequest,
) -> Option<String> {
    let decision = engine
        .route_adaptive_with_intent(&req.prompt, req.intent.clone())
        .await;
    match engine
        .unified_registry
        .ready_without_download(&decision.model_id)
    {
        Some(true) => None,
        Some(false) => Some(format!(
            "Assistant needs model setup before it can run. Open Models and install {}, then try again.",
            decision.model_name
        )),
        None => Some(format!(
            "Assistant selected {}, but that model is not registered. Open Models and choose an available model.",
            decision.model_name
        )),
    }
}

/// Per-task invocation of an external CLI agent. Required params:
/// `id` (adapter, e.g. `"claude-code"`) and `task` (the prompt).
/// Optional: `cwd`, `allowed_tools`, `max_turns`, `timeout_secs`.
///
/// Phase 2 stage 3 ships with `claude-code` only. Other adapter
/// ids return `is_error: true` with a structured `error` so hosts
/// can surface the gap without a separate error code.
///
/// Phase 2 stage 4a (governance): every invocation appends a
/// structured audit record to `~/.car/external-agents.jsonl`. The
/// record captures id, task, options, result, and the full
/// `tool_uses` list the assistant emitted — so even though the
/// agent executes its built-in tools in-process (which we can't
/// gate via stream-json), there's a complete after-the-fact audit
/// trail. Full policy gating (proposing each tool_use to CAR's
/// validator + getting a yes/no) requires the MCP server route in
/// stage 4b.
async fn handle_agents_invoke_external(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    host_session: &Arc<crate::session::ClientSession>,
) -> Result<Value, String> {
    let id = req
        .params
        .get("id")
        .and_then(Value::as_str)
        .ok_or_else(|| "missing required `id` parameter".to_string())?
        .to_string();
    let task = req
        .params
        .get("task")
        .and_then(Value::as_str)
        .ok_or_else(|| "missing required `task` parameter".to_string())?
        .to_string();
    let stream = req
        .params
        .get("stream")
        .and_then(Value::as_bool)
        .unwrap_or(false);
    let session_id = req
        .params
        .get("session_id")
        .and_then(Value::as_str)
        .map(str::to_string)
        .unwrap_or_else(|| format!("ext-{}", uuid::Uuid::new_v4().simple()));

    // Build the options sub-object directly from req.params so
    // hosts can pass `cwd` / `allowed_tools` / `max_turns` /
    // `timeout_secs` as siblings of `id`/`task`. Strip the
    // dispatch + streaming fields so they don't pollute the
    // options serde.
    let mut options_value = req.params.clone();
    if let Some(obj) = options_value.as_object_mut() {
        obj.remove("id");
        obj.remove("task");
        obj.remove("stream");
        obj.remove("session_id");
        // Auto-fill `mcp_endpoint` from the bound MCP URL when the
        // caller didn't supply one. This is the load-bearing
        // wiring of MCP-4: external agents get CAR's tools (memory,
        // skills, verify) routed through the daemon's policy +
        // shared memgine without any per-call host configuration.
        // Callers who want to opt out can pass `"mcp_endpoint": ""`
        // (empty string) — the runner skips the temp-file write
        // when the value isn't a non-empty URL.
        let has_explicit_mcp = obj.contains_key("mcp_endpoint");
        if !has_explicit_mcp {
            if let Some(url) = state.mcp_url.get() {
                obj.insert("mcp_endpoint".to_string(), Value::String(url.clone()));
            }
        }
    }

    if !stream {
        // Legacy one-shot path. Unchanged shape for FFI consumers
        // and any caller that hasn't opted into streaming.
        let options_json = options_value.to_string();
        let json = car_ffi_common::external_agents::invoke(&id, &task, &options_json).await?;
        let result: Value = serde_json::from_str(&json).map_err(|e| e.to_string())?;
        append_external_agent_audit(&id, &task, &options_value, &result);
        return Ok(result);
    }

    // Streaming path. Returns an ack ({accepted, session_id})
    // immediately and streams `agents.chat.event` notifications
    // to the host's WS as the runner emits StreamEvents. Reuses
    // the chat_sessions routing infrastructure supervised agents
    // use — host UIs render both kinds through the same path.
    let opts: car_external_agents::InvokeOptions = serde_json::from_value(options_value.clone())
        .map_err(|e| format!("invalid options: {e}"))?;

    // Register the chat session BEFORE spawning so the host's
    // subscriber is correctly bound to this session_id by the
    // time the first event arrives. Reusing the supervised
    // agent chat infrastructure means `agents.chat.cancel`
    // routes to chat_sessions[session_id] and can flip the same
    // local cancellation flag the external runner races against.
    let local_cancel = Arc::new(AtomicBool::new(false));
    let owns_chat_session = {
        // If a chat session is already registered for this id (the
        // typical proxy shape: host → agents.chat → supervised agent
        // → agents.invoke_external with the same session_id), DO NOT
        // overwrite it. The existing entry owns the routing to the
        // original host; clobbering it with our caller's client_id
        // would send streaming events to the proxying agent instead
        // of back to the host that issued agents.chat. Only register
        // a fresh entry when the slot is empty (a direct
        // host-to-invoke_external call without a prior agents.chat).
        let mut chats = state.chat_sessions.lock().await;
        if let Some(chat) = chats.get_mut(&session_id) {
            if chat.local_cancel.is_none() {
                chat.local_cancel = Some(local_cancel.clone());
            }
            false
        } else {
            let created_at = std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map(|d| d.as_secs())
                .unwrap_or(0);
            chats.insert(
                session_id.clone(),
                crate::session::ChatSession {
                    agent_id: id.clone(),
                    host_client_id: host_session.client_id.clone(),
                    created_at,
                    local_cancel: Some(local_cancel.clone()),
                },
            );
            true
        }
    };

    // Single drain task pulls StreamEvents off an unbounded
    // channel and serializes WS sends to the host. Per-event
    // tokio::spawn would let sends race (which token arrives
    // first depends on lock acquisition order). The channel
    // is unbounded because claude's event volume is bounded
    // by user turn count — typically <50 events per invocation.
    use tokio::sync::mpsc;
    let (tx, mut rx) = mpsc::unbounded_channel::<car_external_agents::StreamEvent>();

    let drain_state = state.clone();
    let drain_session_id = session_id.clone();
    let drain_agent_id = id.clone();
    tokio::spawn(async move {
        while let Some(event) = rx.recv().await {
            emit_external_chat_event(&drain_state, &drain_session_id, &drain_agent_id, event).await;
        }
    });

    let emitter_tx = tx.clone();
    let emitter: car_external_agents::StreamEventEmitter = Arc::new(move |event| {
        // Send failure (rx dropped) means the drain task has
        // exited — usually because the host disconnected. The
        // runner will keep going; let it finish so the audit
        // log captures the full result.
        let _ = emitter_tx.send(event);
    });

    // Run the invocation in a separate task so this handler
    // can return the ack right away. The runner's child-process
    // future owns the spawn lifetime; if the host disconnects
    // mid-stream, the runner still completes (its events fall
    // on the floor at the drain layer) so the audit log lands.
    let spawn_state = state.clone();
    let spawn_session_id = session_id.clone();
    let spawn_id = id.clone();
    let spawn_task = task.clone();
    let spawn_options = options_value.clone();
    tokio::spawn(async move {
        let outcome = car_external_agents::invoke_with_emitter_and_cancel(
            &spawn_id,
            &spawn_task,
            opts,
            Some(emitter),
            Some(local_cancel.clone()),
        )
        .await;
        drop(tx); // signal drain task to exit after queue empties

        // Synthesize a terminal agents.chat.event so the host's
        // bubble finalizes. The runner doesn't emit a "done" event
        // itself — the result is the aggregate InvokeResult. We
        // translate it here.
        let terminal_params: Value;
        let result_value: Value;
        match outcome {
            Ok(res) => {
                // Pack the metadata into `finish_reason` as a
                // human-readable summary so the host's existing
                // ChatEvent decoder surfaces it without a schema
                // change. Hosts that want structured data can
                // re-issue `agents.invoke_external` with
                // `stream: false` and read the InvokeResult.
                let mut parts: Vec<String> = Vec::new();
                if res.turns > 0 {
                    parts.push(format!(
                        "{} turn{}",
                        res.turns,
                        if res.turns == 1 { "" } else { "s" }
                    ));
                }
                if res.tool_calls > 0 {
                    parts.push(format!(
                        "{} tool{}",
                        res.tool_calls,
                        if res.tool_calls == 1 { "" } else { "s" }
                    ));
                }
                if res.duration_ms > 0 {
                    parts.push(format!("{:.1}s", res.duration_ms as f64 / 1000.0));
                }
                if res.dropped_attachments > 0 {
                    parts.push(format!(
                        "{} image{} skipped",
                        res.dropped_attachments,
                        if res.dropped_attachments == 1 {
                            ""
                        } else {
                            "s"
                        }
                    ));
                }
                let summary = if parts.is_empty() {
                    "stop".to_string()
                } else {
                    parts.join(" · ")
                };
                if res.is_error {
                    terminal_params = serde_json::json!({
                        "session_id": spawn_session_id,
                        "agent_id": spawn_id,
                        "kind": "error",
                        "error": res.error.clone().unwrap_or_else(|| "external agent reported error".to_string()),
                    });
                } else {
                    terminal_params = serde_json::json!({
                        "session_id": spawn_session_id,
                        "agent_id": spawn_id,
                        "kind": "done",
                        "finish_reason": summary,
                        // Structured count so the host can warn distinctly
                        // from the human-readable summary. Omitted when 0.
                        "dropped_attachments": res.dropped_attachments,
                    });
                }
                result_value = serde_json::to_value(&res).unwrap_or(Value::Null);
            }
            Err(e) => {
                let message = format!("{e}");
                terminal_params = serde_json::json!({
                    "session_id": spawn_session_id,
                    "agent_id": spawn_id,
                    "kind": "error",
                    "error": message.clone(),
                });
                result_value = serde_json::json!({ "is_error": true, "error": message });
            }
        }
        send_external_chat_frame(&spawn_state, &spawn_session_id, terminal_params).await;
        remove_owned_external_chat_session(&spawn_state, &spawn_session_id, owns_chat_session)
            .await;
        append_external_agent_audit(&spawn_id, &spawn_task, &spawn_options, &result_value);
    });

    Ok(serde_json::json!({
        "accepted": true,
        "session_id": session_id,
    }))
}

async fn remove_owned_external_chat_session(
    state: &Arc<ServerState>,
    session_id: &str,
    owns_chat_session: bool,
) {
    if owns_chat_session {
        state.chat_sessions.lock().await.remove(session_id);
    }
}

/// Translate one [`StreamEvent`] from the running external CLI
/// into an `agents.chat.event` notification on the originating
/// host's WS. Same wire shape supervised agents emit, so host
/// UIs render both kinds with one decoder.
///
/// Mapping:
/// - `Assistant` events with `text` content blocks → `kind: "token"`
///   per text block. Each block carries the full text the
///   assistant emitted in that turn (claude doesn't expose
///   word-level deltas via stream-json — it emits per-turn or
///   per-content-block chunks).
/// - `Assistant` events with `tool_use` blocks → `kind: "tool_call"`
///   per block (tool name in `detail`).
/// - `System` / `User` / `Result` / others → dropped (Result's
///   metadata is folded into the terminal `done` event the
///   outer task emits when the invocation finishes).
async fn emit_external_chat_event(
    state: &Arc<ServerState>,
    session_id: &str,
    agent_id: &str,
    event: car_external_agents::StreamEvent,
) {
    use car_external_agents::StreamEvent;
    match event {
        StreamEvent::Assistant(a) => {
            if let Some(content) = a.message.get("content").and_then(|v| v.as_array()) {
                for block in content {
                    let block_type = block.get("type").and_then(|v| v.as_str()).unwrap_or("");
                    match block_type {
                        "text" => {
                            if let Some(text) = block.get("text").and_then(|v| v.as_str()) {
                                if !text.is_empty() {
                                    let params = serde_json::json!({
                                        "session_id": session_id,
                                        "agent_id": agent_id,
                                        "kind": "token",
                                        "delta": text,
                                    });
                                    send_external_chat_frame(state, session_id, params).await;
                                }
                            }
                        }
                        "tool_use" => {
                            let name = block
                                .get("name")
                                .and_then(|v| v.as_str())
                                .unwrap_or("(unknown tool)");
                            // Emit the host-protocol.md `tool` + `params`
                            // shape so the host renders a structured
                            // tool-call card (name + args). `detail` is
                            // kept as a legacy alias for older hosts that
                            // only read it.
                            let mut frame = serde_json::json!({
                                "session_id": session_id,
                                "agent_id": agent_id,
                                "kind": "tool_call",
                                "tool": name,
                                "detail": name,
                            });
                            if let Some(input) = block.get("input") {
                                if !input.is_null() {
                                    frame["params"] = input.clone();
                                }
                            }
                            send_external_chat_frame(state, session_id, frame).await;
                        }
                        _ => {}
                    }
                }
            }
        }
        _ => {
            // System (session id init), User (tool result echo),
            // Result (final aggregate — folded into terminal
            // `done` event by the outer task), RateLimitEvent,
            // Other: not surfaced to host.
        }
    }
}

/// Send a single `agents.chat.event` notification to the host
/// session bound by `session_id`. Best-effort: a missing route
/// or a closed WS is silently dropped, the runner continues so
/// the audit log lands.
async fn send_external_chat_frame(state: &Arc<ServerState>, session_id: &str, params: Value) {
    use futures::SinkExt;
    use tokio_tungstenite::tungstenite::Message;

    update_chat_goal_from_event(state, session_id, &params).await;

    let host_client_id = state
        .chat_sessions
        .lock()
        .await
        .get(session_id)
        .map(|s| s.host_client_id.clone());
    let Some(host_client_id) = host_client_id else {
        return;
    };
    let host_channel = {
        let sessions = state.sessions.lock().await;
        sessions.get(&host_client_id).map(|s| s.channel.clone())
    };
    let Some(channel) = host_channel else {
        return;
    };
    let frame = serde_json::json!({
        "jsonrpc": "2.0",
        "method": "agents.chat.event",
        "params": params,
    });
    if let Ok(text) = serde_json::to_string(&frame) {
        let _ = channel
            .write
            .lock()
            .await
            .send(Message::Text(text.into()))
            .await;
    }
}

/// Append one JSONL audit record to `external-agents.jsonl` under the CAR state
/// root (`~/.car/external-agents.jsonl` unless `CAR_HOME` moves the root).
/// Best-effort: a failure to open the journal must NOT fail the
/// invocation; the in-memory result already returned is the
/// authoritative answer. Logs at warn level when the write fails so
/// operators notice repeated failures. An unresolvable root is the same
/// best-effort miss — no root, no journal, no failed invocation.
fn append_external_agent_audit(id: &str, task: &str, options: &Value, result: &Value) {
    use std::io::Write;
    let car_dir = match car_home::root() {
        Some(root) => root,
        None => return,
    };
    if std::fs::create_dir_all(&car_dir).is_err() {
        return;
    }
    let path = car_dir.join("external-agents.jsonl");
    let record = serde_json::json!({
        "ts": chrono::Utc::now().to_rfc3339(),
        "adapter_id": id,
        "task": task,
        "options": options,
        "result": result,
    });
    let line = match serde_json::to_string(&record) {
        Ok(s) => s,
        Err(_) => return,
    };
    if let Ok(mut f) = std::fs::OpenOptions::new()
        .create(true)
        .append(true)
        .open(&path)
    {
        let _ = writeln!(f, "{}", line);
    } else {
        tracing::warn!(
            path = %path.display(),
            "failed to append external-agent audit record"
        );
    }
}

/// Ground-truth health check. Optional `id` param picks one tool;
/// without it, every detected adapter is checked. `force: true`
/// bypasses the 30s per-tool TTL cache. Replaces the Phase 1
/// credential-file shape heuristic as the load-bearing signal for
/// "is this tool ready to invoke."
async fn handle_agents_health_external(req: &JsonRpcMessage) -> Result<Value, String> {
    let force = req
        .params
        .get("force")
        .and_then(Value::as_bool)
        .unwrap_or(false);
    if let Some(id) = req.params.get("id").and_then(Value::as_str) {
        let json = car_ffi_common::external_agents::health_one(id, force).await?;
        serde_json::from_str(&json).map_err(|e| e.to_string())
    } else {
        let json = car_ffi_common::external_agents::health(force).await?;
        serde_json::from_str(&json).map_err(|e| e.to_string())
    }
}

// ---------------------------------------------------------------------------
// agents.chat — unified chat surface (docs/proposals/agent-chat-surface.md)
// ---------------------------------------------------------------------------
//
// Host calls `agents.chat { agent_id, prompt, session_id?, stream? }`.
// The server looks up the target agent's attached WS connection,
// reverse-calls `agent.chat { session_id, prompt, context }` on it
// (same pattern as `tools.execute`), and returns once the agent acks.
// The agent then streams `agent.chat.event` notifications back, which
// the dispatcher intercepts (see `try_forward_agent_chat_event`) and
// rewrites as `agents.chat.event` notifications on the originating
// host's channel.

/// Timeout the server waits for the agent to ack `agent.chat`. The
/// streamed tokens come later as separate notifications and have no
/// bearing on this — this is just "did the agent receive the prompt
/// and accept it." Five seconds is generous for a local IPC ack.
const AGENT_CHAT_ACK_TIMEOUT_SECS: u64 = 5;

/// `agents.chat` — host issues a chat turn to a named agent. Returns
/// `{ accepted: true, session_id }` once the agent acks; streamed
/// tokens arrive on the host's channel as `agents.chat.event`
/// notifications keyed by the same `session_id`.
/// Validate and extract the optional `attachments` array from an
/// `agents.chat` request's params. Returns `Ok(None)` when absent or
/// null; `Err` on a malformed shape (a non-array, or any entry lacking
/// an image-`ContentBlock` `type`). Pulled out so the validation is
/// unit-testable without the full session machinery.
fn extract_chat_attachments(params: &Value) -> Result<Option<Value>, String> {
    const ALLOWED_MEDIA: [&str; 4] = ["image/png", "image/jpeg", "image/gif", "image/webp"];
    let items = match params.get("attachments") {
        None | Some(Value::Null) => return Ok(None),
        Some(Value::Array(items)) => items,
        Some(_) => return Err("`agents.chat` `attachments` must be an array".to_string()),
    };
    // Validate each entry's content, not just its `type` tag — we
    // forward this verbatim to the agent and on to a provider, so a
    // malformed/hostile entry (missing data, a non-image media type, a
    // `file://` URL) must not pass through.
    for item in items {
        let ty = item.get("type").and_then(Value::as_str).ok_or_else(|| {
            "`agents.chat` `attachments` entries must have a string `type`".to_string()
        })?;
        match ty {
            "image_base64" => {
                if item.get("data").and_then(Value::as_str).is_none() {
                    return Err("`image_base64` attachment requires a string `data`".to_string());
                }
                let media = item.get("media_type").and_then(Value::as_str).unwrap_or("");
                if !ALLOWED_MEDIA.contains(&media) {
                    return Err(format!(
                        "`image_base64` attachment `media_type` must be one of {ALLOWED_MEDIA:?}"
                    ));
                }
            }
            "image_url" => {
                let url = item.get("url").and_then(Value::as_str).unwrap_or("");
                if !(url.starts_with("https://") || url.starts_with("http://")) {
                    return Err("`image_url` attachment `url` must be http(s)".to_string());
                }
            }
            other => {
                return Err(format!(
                    "`agents.chat` `attachments` entries must be image ContentBlocks \
                     (`image_base64` or `image_url`), got `{other}`"
                ));
            }
        }
    }
    Ok(Some(Value::Array(items.clone())))
}

/// Validate and extract an optional deterministic goal check for an
/// `agents.chat` turn. When present, the served assistant runs the prompt as a
/// goal loop and streams `goal_evaluated` after each verifier pass.
fn extract_chat_goal(params: &Value) -> Result<Option<Value>, String> {
    let Some(goal) = params.get("goal") else {
        return Ok(None);
    };
    if goal.is_null() {
        return Ok(None);
    }
    let obj = goal
        .as_object()
        .ok_or_else(|| "`agents.chat` `goal` must be an object".to_string())?;
    let check = obj
        .get("check")
        .and_then(Value::as_str)
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .ok_or_else(|| "`agents.chat` `goal.check` must be a non-empty string".to_string())?;
    let max_iterations = obj
        .get("max_iterations")
        .and_then(Value::as_u64)
        .unwrap_or(8)
        .clamp(1, 50);
    Ok(Some(serde_json::json!({
        "check": check,
        "max_iterations": max_iterations,
    })))
}

/// Validate the optional explicit inference model for a native chat turn.
/// Omitted/null/blank preserves the target agent's own model or adaptive
/// routing default. A non-empty value uses the same `model` selector carried
/// by CAR's typed inference requests.
fn extract_chat_model(params: &Value) -> Result<Option<String>, String> {
    match params.get("model") {
        None | Some(Value::Null) => Ok(None),
        Some(Value::String(model)) => {
            Ok((!model.trim().is_empty()).then(|| model.trim().to_string()))
        }
        Some(_) => Err("`agents.chat` `model` must be a string".to_string()),
    }
}

fn unix_secs_now() -> u64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0)
}

fn chat_goal_value_to_state(session_id: &str, goal: &Value) -> Result<ChatGoalState, String> {
    let obj = goal
        .as_object()
        .ok_or_else(|| "`goal` must be an object".to_string())?;
    let check = obj
        .get("check")
        .and_then(Value::as_str)
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .ok_or_else(|| "`goal.check` must be a non-empty string".to_string())?;
    let max_iterations = obj
        .get("max_iterations")
        .and_then(Value::as_u64)
        .unwrap_or(8)
        .clamp(1, 50) as u32;
    Ok(ChatGoalState {
        session_id: session_id.to_string(),
        check: check.to_string(),
        max_iterations,
        status: "active".to_string(),
        last_iteration: None,
        last_met: None,
        last_grounded: None,
        last_reason: None,
        terminal_kind: None,
        terminal_message: None,
        updated_at: unix_secs_now(),
    })
}

fn chat_goal_state_to_value(goal: &ChatGoalState) -> Result<Value, String> {
    serde_json::to_value(goal).map_err(|e| e.to_string())
}

fn chat_goal_state_to_wire_goal(goal: &ChatGoalState) -> Value {
    serde_json::json!({
        "check": goal.check,
        "max_iterations": goal.max_iterations,
    })
}

async fn ensure_chat_goal_running(
    state: &Arc<ServerState>,
    session_id: &str,
    goal_value: &Value,
) -> Result<(), String> {
    let mut inserted = false;
    {
        let mut goals = state.chat_goals.lock().await;
        if let Some(stored) = goals.get_mut(session_id) {
            stored.status = "running".to_string();
            stored.terminal_kind = None;
            stored.terminal_message = None;
            stored.updated_at = unix_secs_now();
        } else {
            let mut goal = chat_goal_value_to_state(session_id, goal_value)?;
            goal.status = "running".to_string();
            goals.insert(session_id.to_string(), goal);
            inserted = true;
        }
    }
    state.persist_chat_goals().await?;
    if inserted {
        tracing::debug!(
            session_id,
            "created durable chat goal status for inline goal"
        );
    }
    Ok(())
}

async fn handle_goal_suggest(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let prompt = req
        .params
        .get("prompt")
        .or_else(|| req.params.get("objective"))
        .and_then(Value::as_str)
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .ok_or_else(|| "`goal.suggest` requires `prompt` or `objective`".to_string())?;
    let cwd = req
        .params
        .get("working_dir")
        .or_else(|| req.params.get("cwd"))
        .and_then(Value::as_str)
        .map(std::path::PathBuf::from);
    let mut result = crate::goal_suggest::synthesize_goal_check(prompt, cwd.as_deref());

    let should_set = req
        .params
        .get("set")
        .and_then(Value::as_bool)
        .unwrap_or(false);
    if should_set {
        let session_id = req
            .params
            .get("session_id")
            .and_then(Value::as_str)
            .map(str::trim)
            .filter(|s| !s.is_empty())
            .ok_or_else(|| "`goal.suggest` with `set: true` requires `session_id`".to_string())?;
        let goal_value = result.get("goal").cloned().unwrap_or(Value::Null);
        if goal_value.is_null() {
            return Err("`goal.suggest` could not infer a goal to set".to_string());
        }
        let goal = chat_goal_value_to_state(session_id, &goal_value)?;
        state
            .chat_goals
            .lock()
            .await
            .insert(session_id.to_string(), goal.clone());
        state.persist_chat_goals().await?;
        if let Some(obj) = result.as_object_mut() {
            obj.insert("set".to_string(), Value::Bool(true));
            obj.insert(
                "session_id".to_string(),
                Value::String(session_id.to_string()),
            );
            obj.insert("stored_goal".to_string(), chat_goal_state_to_value(&goal)?);
        }
    }

    Ok(result)
}

async fn handle_goal_set(req: &JsonRpcMessage, state: &Arc<ServerState>) -> Result<Value, String> {
    let session_id = req
        .params
        .get("session_id")
        .and_then(Value::as_str)
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .ok_or_else(|| "`goal.set` requires `session_id`".to_string())?;
    let goal_value = if let Some(goal) = req.params.get("goal") {
        goal.clone()
    } else {
        serde_json::json!({
            "check": req.params.get("check").cloned().unwrap_or(Value::Null),
            "max_iterations": req.params.get("max_iterations").cloned().unwrap_or(Value::Null),
        })
    };
    let goal = chat_goal_value_to_state(session_id, &goal_value)?;
    state
        .chat_goals
        .lock()
        .await
        .insert(session_id.to_string(), goal.clone());
    state.persist_chat_goals().await?;
    Ok(serde_json::json!({
        "set": true,
        "goal": chat_goal_state_to_value(&goal)?,
    }))
}

async fn handle_goal_status(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let goals = state.chat_goals.lock().await;
    if let Some(session_id) = req.params.get("session_id").and_then(Value::as_str) {
        let goal = goals.get(session_id).cloned();
        return Ok(serde_json::json!({
            "session_id": session_id,
            "goal": goal
                .as_ref()
                .map(chat_goal_state_to_value)
                .transpose()?
                .unwrap_or(Value::Null),
        }));
    }
    let mut values = Vec::with_capacity(goals.len());
    for goal in goals.values() {
        values.push(chat_goal_state_to_value(goal)?);
    }
    Ok(serde_json::json!({ "goals": values }))
}

async fn handle_goal_clear(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> Result<Value, String> {
    let Some(session_id) = req.params.get("session_id").and_then(Value::as_str) else {
        let mut goals = state.chat_goals.lock().await;
        let removed = goals.len();
        goals.clear();
        drop(goals);
        state.persist_chat_goals().await?;
        return Ok(serde_json::json!({ "cleared": removed }));
    };
    let removed = state.chat_goals.lock().await.remove(session_id).is_some();
    state.persist_chat_goals().await?;
    Ok(serde_json::json!({
        "cleared": removed,
        "session_id": session_id,
    }))
}

/// Build the `params` object for the reverse `agent.chat` call. The
/// `attachments` key is inserted only when present, so agents that
/// don't read it see no change to the request shape. Pulled out so the
/// attachment-forwarding is unit-testable.
fn build_agent_chat_params(
    session_id: &str,
    prompt: &str,
    stream: bool,
    host_client_id: &str,
    voice_input: bool,
    model: Option<String>,
    attachments: Option<Value>,
    goal: Option<Value>,
) -> Value {
    let mut params = serde_json::json!({
        "session_id": session_id,
        "prompt": prompt,
        "stream": stream,
        "context": {
            "host_client_id": host_client_id,
            "voice_input": voice_input,
        },
    });
    if let Some(model) = model {
        if let Some(obj) = params.as_object_mut() {
            obj.insert("model".to_string(), Value::String(model));
        }
    }
    if let Some(att) = attachments {
        if let Some(obj) = params.as_object_mut() {
            obj.insert("attachments".to_string(), att);
        }
    }
    if let Some(goal) = goal {
        if let Some(obj) = params.as_object_mut() {
            obj.insert("goal".to_string(), goal);
        }
    }
    params
}

/// Resolve a caller-supplied `agent_id` against the flagship assistant's
/// canonical/legacy id pair (car#1107). If `agent_id` names the assistant
/// under either spelling (`parslee-core` or `car-assistant`) and the daemon
/// only has the *other* spelling attached, return the attached one; otherwise
/// return `agent_id` unchanged. Keeps macOS (hardcoded `car-assistant`) and
/// mobile (hardcoded `parslee-core`) both working against a daemon that
/// attaches the flagship under one spelling at a time.
async fn resolve_assistant_agent_alias(agent_id: String, state: &Arc<ServerState>) -> String {
    if !crate::assistant::register::is_assistant_alias(&agent_id) {
        return agent_id;
    }
    let attached = state.attached_agents.lock().await;
    if attached.contains_key(&agent_id) {
        return agent_id;
    }
    for alias in [
        crate::assistant::register::ASSISTANT_AGENT_ID,
        crate::assistant::register::LEGACY_ASSISTANT_AGENT_ID,
    ] {
        if alias != agent_id && attached.contains_key(alias) {
            return alias.to_string();
        }
    }
    agent_id
}

async fn handle_agents_chat(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    host_session: &Arc<crate::session::ClientSession>,
) -> Result<Value, String> {
    use futures::SinkExt;
    use tokio::sync::oneshot;
    use tokio_tungstenite::tungstenite::Message;

    let agent_id = req
        .params
        .get("agent_id")
        .and_then(Value::as_str)
        .ok_or_else(|| "`agents.chat` requires `agent_id`".to_string())?
        .to_string();
    // Resolve `car-assistant` / `parslee-core` to whichever spelling the
    // flagship assistant actually attached under (car#1107). This is the
    // single call site: `agents.chat.approve` / `.cancel` read the resolved
    // id back out of `chat_sessions` (see `ChatSession::agent_id` below),
    // so they need no resolution of their own.
    let agent_id = resolve_assistant_agent_alias(agent_id, state).await;
    let prompt = req
        .params
        .get("prompt")
        .and_then(Value::as_str)
        .ok_or_else(|| "`agents.chat` requires `prompt`".to_string())?
        .to_string();
    let session_id = req
        .params
        .get("session_id")
        .and_then(Value::as_str)
        .map(str::to_string)
        .unwrap_or_else(|| format!("chat-{}", uuid::Uuid::new_v4().simple()));
    let stream = req
        .params
        .get("stream")
        .and_then(Value::as_bool)
        .unwrap_or(true);
    let voice_input = req
        .params
        .get("voice_input")
        .and_then(Value::as_bool)
        .unwrap_or(false);
    let model = extract_chat_model(&req.params)?;

    // Optional image attachments (ContentBlock image variants). The
    // daemon is a pass-through here — it validates the shape lightly and
    // forwards them verbatim to the agent's `agent.chat` handler, which
    // hands them to inference as `imagesJson`.
    let attachments = extract_chat_attachments(&req.params)?;
    let inline_goal = extract_chat_goal(&req.params)?;
    let stored_goal = if inline_goal.is_none() {
        state
            .chat_goals
            .lock()
            .await
            .get(&session_id)
            .map(chat_goal_state_to_wire_goal)
    } else {
        None
    };
    let goal = inline_goal.or(stored_goal);
    if goal.is_some() && attachments.is_some() {
        return Err(
            "`agents.chat` `goal` currently cannot be combined with `attachments`".to_string(),
        );
    }
    let has_attached_agent = state.attached_agents.lock().await.contains_key(&agent_id);
    let declarative_spec = if has_attached_agent {
        None
    } else {
        state.declagents().ok().and_then(|reg| reg.get(&agent_id))
    };

    // Same admission `agents.message` applies. Without it this method was the
    // way around that one: an agent denied at the read-only tier could reach
    // another agent by calling `agents.chat` instead, and two agents could
    // answer each other with nothing to terminate the loop. The host is exempt
    // inside the helper — it is the operator's own client.
    //
    // Placed AFTER the agent is known to exist, and that ordering is
    // load-bearing twice over. The guard records the (sender, body) pair on
    // admit, so admitting first meant an unroutable `agent_id` burned the
    // dedupe window and the caller's honest retry came back "already
    // delivered" — false, and it points away from the only thing that would
    // work. It also meant every caller-supplied string minted a permanent
    // `DeliveryGuard` in a map only a disconnecting bound agent ever prunes.
    // `handle_agents_message` never had either problem because it resolves the
    // directory before the guard; this now matches it.
    if !has_attached_agent && declarative_spec.is_none() {
        return Err(format!(
            "`{agent_id}` is not attached to this daemon and is not a declarative agent"
        ));
    }
    let chat_principal = session_principal_for_peers(host_session).await;
    {
        let sender_agent = host_session.agent_id.lock().await.clone();
        let is_host = host_session
            .is_host
            .load(std::sync::atomic::Ordering::Acquire);
        crate::peers::admit_turn(
            &state.clone(),
            &chat_principal,
            sender_agent,
            is_host,
            &agent_id,
            &prompt,
        )
        .await?;
    }

    if !has_attached_agent {
        if let Some(spec) = declarative_spec {
            return handle_declarative_agents_chat(
                state,
                host_session,
                spec,
                prompt,
                session_id,
                stream,
                model,
                attachments,
                goal,
            )
            .await;
        }
    }
    // Resolve the agent's attached WS channel via `attached_agents` →
    // `sessions` → `channel`. Both lookups must hit; a missing entry on
    // either side means the agent is registered in `agents.json` but
    // hasn't `session.auth`'d (or has disconnected), so refuse with a
    // structured error rather than silently parking the chat.
    // A turn admitted above but not delivered here must give back its dedupe
    // record: the agent was attached when we checked and is gone now, so the
    // caller's immediate retry is a legitimate retry, not the loop the dedupe
    // window exists to break. The rate budget is deliberately not refunded —
    // the attempt did cost the channel something.
    let resolved = async {
        let agent_client_id = state
            .attached_agents
            .lock()
            .await
            .get(&agent_id)
            .cloned()
            .ok_or_else(|| {
                format!(
                    "agent `{}` is not attached to this daemon — supervisor may have it stopped, or it hasn't called session.auth yet",
                    agent_id
                )
            })?;
        let sessions = state.sessions.lock().await;
        sessions
            .get(&agent_client_id)
            .map(|s| s.channel.clone())
            .ok_or_else(|| {
                format!(
                    "agent `{}` client_id `{}` not found in session registry (raced with disconnect)",
                    agent_id, agent_client_id
                )
            })
    }
    .await;
    let agent_channel = match resolved {
        Ok(ch) => ch,
        Err(e) => {
            crate::peers::forget_synchronous_turn(state, &chat_principal, &agent_id, &prompt).await;
            return Err(e);
        }
    };

    // Record who drove this turn. See `crate::peers::append_agent_chat_audit`
    // for why this lands here in the same change as `agents.message`.
    crate::peers::append_agent_chat_audit(
        state,
        &session_principal(host_session).await,
        &agent_id,
        &session_id,
    );

    if let Some(goal_value) = &goal {
        ensure_chat_goal_running(state, &session_id, goal_value).await?;
    }

    // Register the chat session BEFORE sending the reverse call so any
    // `agent.chat.event` notifications the agent sends as part of
    // accepting the chat (e.g. an immediate `token` delta) route
    // correctly. Indexed by session_id so the notification interceptor
    // can locate the originating host without scanning.
    {
        let created_at = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_secs())
            .unwrap_or(0);
        state.chat_sessions.lock().await.insert(
            session_id.clone(),
            crate::session::ChatSession {
                agent_id: agent_id.clone(),
                host_client_id: host_session.client_id.clone(),
                created_at,
                local_cancel: None,
            },
        );
    }

    // Reverse-callback: register a oneshot for the ack, send the
    // `agent.chat` JSON-RPC request on the agent's channel, await up
    // to AGENT_CHAT_ACK_TIMEOUT_SECS. Uses the same `pending` map the
    // tool-callback path uses (`WsToolExecutor`) — the dispatcher's
    // response demuxer at the top of `run_dispatch` already routes
    // `result` / `error` frames keyed by request id back through it.
    let request_id = agent_channel.next_request_id();
    let (tx, rx) = oneshot::channel();
    agent_channel
        .pending
        .lock()
        .await
        .insert(request_id.clone(), tx);

    let chat_params = build_agent_chat_params(
        &session_id,
        &prompt,
        stream,
        &host_session.client_id,
        voice_input,
        model,
        attachments,
        goal,
    );
    let rpc_request = serde_json::json!({
        "jsonrpc": "2.0",
        "method": "agent.chat",
        "params": chat_params,
        "id": request_id,
    });
    let msg = Message::Text(
        serde_json::to_string(&rpc_request)
            .map_err(|e| e.to_string())?
            .into(),
    );
    if let Err(e) = agent_channel.write.lock().await.send(msg).await {
        // Send failed — drop the pending waiter and the chat session
        // entry so a retry can take a fresh session_id without
        // colliding.
        agent_channel.pending.lock().await.remove(&request_id);
        state.chat_sessions.lock().await.remove(&session_id);
        update_chat_goal_from_event(
            state,
            &session_id,
            &serde_json::json!({
                "kind": "error",
                "error": format!("failed to deliver agent.chat to `{}`: {}", agent_id, e),
            }),
        )
        .await;
        return Err(format!(
            "failed to deliver agent.chat to `{}`: {}",
            agent_id, e
        ));
    }

    // Await the agent's ack. The dispatcher's response demuxer routes
    // the result/error back via the oneshot. Timeout means the agent
    // is alive but unresponsive — clean up routing state and surface a
    // structured error so the host UI doesn't hang.
    let ack = match tokio::time::timeout(
        std::time::Duration::from_secs(AGENT_CHAT_ACK_TIMEOUT_SECS),
        rx,
    )
    .await
    {
        Ok(Ok(resp)) => resp,
        Ok(Err(_)) => {
            // Channel closed — agent disconnected mid-call.
            state.chat_sessions.lock().await.remove(&session_id);
            update_chat_goal_from_event(
                state,
                &session_id,
                &serde_json::json!({
                    "kind": "error",
                    "error": format!("agent `{}` disconnected before acking agents.chat", agent_id),
                }),
            )
            .await;
            return Err(format!(
                "agent `{}` disconnected before acking agents.chat",
                agent_id
            ));
        }
        Err(_) => {
            // Timeout — agent didn't respond in time. Don't keep the
            // chat session around: any later events from the agent
            // would route to a host that already returned an error.
            agent_channel.pending.lock().await.remove(&request_id);
            state.chat_sessions.lock().await.remove(&session_id);
            update_chat_goal_from_event(
                state,
                &session_id,
                &serde_json::json!({
                    "kind": "error",
                    "error": format!(
                        "agent `{}` did not ack agents.chat within {}s",
                        agent_id, AGENT_CHAT_ACK_TIMEOUT_SECS
                    ),
                }),
            )
            .await;
            return Err(format!(
                "agent `{}` did not ack agents.chat within {}s",
                agent_id, AGENT_CHAT_ACK_TIMEOUT_SECS
            ));
        }
    };

    if let Some(err) = ack.error {
        // Agent explicitly rejected — drop the session and propagate.
        state.chat_sessions.lock().await.remove(&session_id);
        update_chat_goal_from_event(
            state,
            &session_id,
            &serde_json::json!({
                "kind": "error",
                "error": format!("agent `{}` rejected chat: {}", agent_id, err),
            }),
        )
        .await;
        return Err(format!("agent `{}` rejected chat: {}", agent_id, err));
    }

    Ok(serde_json::json!({
        "accepted": true,
        "session_id": session_id,
    }))
}

async fn handle_declarative_agents_chat(
    state: &Arc<ServerState>,
    host_session: &Arc<crate::session::ClientSession>,
    spec: car_registry::declarative::DeclarativeAgentSpec,
    prompt: String,
    session_id: String,
    _stream: bool,
    model: Option<String>,
    attachments: Option<Value>,
    goal: Option<Value>,
) -> Result<Value, String> {
    if attachments.is_some() {
        return Err("declarative agents do not support `agents.chat` attachments".to_string());
    }
    if goal.is_some() {
        return Err(
            "`agents.chat` inline/standing goals are only supported by attached chat agents; \
             declarative agents use their manifest `goal`"
                .to_string(),
        );
    }
    if !spec.enabled {
        return Err(format!("agent '{}' is disabled", spec.id));
    }

    let local_cancel = Arc::new(AtomicBool::new(false));
    {
        let created_at = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_secs())
            .unwrap_or(0);
        state.chat_sessions.lock().await.insert(
            session_id.clone(),
            crate::session::ChatSession {
                agent_id: spec.id.clone(),
                host_client_id: host_session.client_id.clone(),
                created_at,
                local_cancel: Some(local_cancel.clone()),
            },
        );
    }

    let state_for_task = state.clone();
    let sid = session_id.clone();
    tokio::spawn(async move {
        let result = crate::coder::rpc::run_declarative_with_cancel_and_model(
            &spec,
            &prompt,
            &state_for_task,
            Some(local_cancel.clone()),
            model,
        )
        .await;
        match result {
            Ok(run) => {
                if local_cancel.load(Ordering::SeqCst) {
                    send_external_chat_frame(
                        &state_for_task,
                        &sid,
                        serde_json::json!({
                            "session_id": sid.clone(),
                            "agent_id": spec.id.clone(),
                            "kind": "error",
                            "error": "cancelled",
                            "result": crate::coder::rpc::run_result_json(&run),
                        }),
                    )
                    .await;
                    state_for_task.chat_sessions.lock().await.remove(&sid);
                    return;
                }
                crate::coder::rpc::record_routing_outcome(&state_for_task, &spec.id, &run);
                if let Some(goal) = &run.goal {
                    send_external_chat_frame(
                        &state_for_task,
                        &sid,
                        serde_json::json!({
                            "session_id": sid.clone(),
                            "agent_id": spec.id.clone(),
                            "kind": "goal_evaluated",
                            "iteration": goal.iterations,
                            "met": goal.met,
                            "grounded": goal.grounded,
                            "reason": goal.last_reason,
                        }),
                    )
                    .await;
                }
                let result_json = crate::coder::rpc::run_result_json(&run);
                if let Some(err) = run.error.clone() {
                    send_external_chat_frame(
                        &state_for_task,
                        &sid,
                        serde_json::json!({
                            "session_id": sid.clone(),
                            "agent_id": spec.id.clone(),
                            "kind": "error",
                            "error": err,
                            "result": result_json,
                        }),
                    )
                    .await;
                } else {
                    let text = run.output.clone();
                    if !text.is_empty() {
                        send_external_chat_frame(
                            &state_for_task,
                            &sid,
                            serde_json::json!({
                                "session_id": sid.clone(),
                                "agent_id": spec.id.clone(),
                                "kind": "token",
                                "delta": text,
                            }),
                        )
                        .await;
                    }
                    send_external_chat_frame(
                        &state_for_task,
                        &sid,
                        serde_json::json!({
                            "session_id": sid.clone(),
                            "agent_id": spec.id.clone(),
                            "kind": "done",
                            "text": text,
                            "finish_reason": "declarative agent completed",
                            "result": result_json,
                        }),
                    )
                    .await;
                }
            }
            Err(e) => {
                send_external_chat_frame(
                    &state_for_task,
                    &sid,
                    serde_json::json!({
                        "session_id": sid.clone(),
                        "agent_id": spec.id.clone(),
                        "kind": "error",
                        "error": e,
                    }),
                )
                .await;
            }
        }
        state_for_task.chat_sessions.lock().await.remove(&sid);
    });

    Ok(serde_json::json!({
        "accepted": true,
        "session_id": session_id,
        "in_daemon": true,
    }))
}

/// Overall deadline for an A2A conversational turn: how long [`chat_collect`]
/// waits for the host agent to finish streaming after it acks. Generous (the
/// host may run several tool round-trips) but bounded so an A2A task can't hang
/// forever on a wedged agent.
const A2A_CHAT_TIMEOUT_SECS: u64 = 180;

/// Reverse-call `agent.chat` on `host_channel` and aggregate the streamed
/// `agent.chat.event` deltas into a single reply string. The A2A conversational
/// bridge uses this — it has no host UI to stream to, so it registers an
/// in-process collector (keyed by a fresh `session_id`) that
/// [`try_forward_agent_chat_event`] feeds, then accumulates `token` deltas until
/// the terminal `done`/`error`. Always removes its collector on the way out.
/// Principal recorded for a conversational A2A message routed to the host
/// agent's loop. One bucket, not one per remote caller: the `a2a.start`
/// listener is `NoAuth`, so there is no verified caller to name — and inventing
/// a per-request identity from unauthenticated input would put a forgeable
/// string in the audit journal, which is worse than an honest single bucket.
pub(crate) const A2A_CONVERSATIONAL_PRINCIPAL: &str = "a2a:conversational";

pub(crate) async fn chat_collect(
    state: &Arc<ServerState>,
    host_channel: &Arc<crate::session::WsChannel>,
    host_client_id: &str,
    prompt: &str,
) -> Result<String, String> {
    use futures::SinkExt;
    use tokio::sync::{mpsc, oneshot};
    use tokio_tungstenite::tungstenite::Message;

    // This sends the same `agent.chat` frame as `handle_agents_chat` and had
    // none of its admission — no guard, no policy, no audit — while being
    // reachable from the `a2a.start` listener, which serves NO authentication.
    // Gating the *bind* (loopback unless `allow_non_loopback_bind`) bounds who
    // can reach it; this bounds what they can do once they have. There is no
    // agent principal to grade — the caller is a remote party the operator
    // deliberately exposed with `share_session_runtime` — so the channel guard
    // is the whole admission here, which is what stops a remote peer looping or
    // flooding the host agent's turns.
    crate::peers::admit_turn(
        state,
        A2A_CONVERSATIONAL_PRINCIPAL,
        None,
        false,
        host_client_id,
        prompt,
    )
    .await?;

    let session_id = format!("a2a-chat-{}", uuid::Uuid::new_v4().simple());
    let (chunk_tx, mut chunk_rx) = mpsc::unbounded_channel::<crate::session::ChatStreamChunk>();
    state.chat_collectors.lock().await.insert(
        session_id.clone(),
        crate::session::ChatCollector {
            tx: chunk_tx,
            host_client_id: host_client_id.to_string(),
        },
    );

    // Ack round-trip reuses the tools.execute pending-response demuxer.
    let request_id = host_channel.next_request_id();
    let (ack_tx, ack_rx) = oneshot::channel();
    host_channel
        .pending
        .lock()
        .await
        .insert(request_id.clone(), ack_tx);

    let req = serde_json::json!({
        "jsonrpc": "2.0",
        "method": "agent.chat",
        "params": {
            "session_id": session_id,
            "prompt": prompt,
            "stream": true,
            "context": { "source": "a2a" },
        },
        "id": request_id,
    });
    if let Err(e) = host_channel
        .write
        .lock()
        .await
        .send(Message::Text(
            serde_json::to_string(&req).unwrap_or_default().into(),
        ))
        .await
    {
        host_channel.pending.lock().await.remove(&request_id);
        state.chat_collectors.lock().await.remove(&session_id);
        return Err(format!("failed to deliver agent.chat to host: {e}"));
    }

    // Wait for the host to ack (same 5s budget as agents.chat).
    let ack = tokio::time::timeout(
        std::time::Duration::from_secs(AGENT_CHAT_ACK_TIMEOUT_SECS),
        ack_rx,
    )
    .await;
    match ack {
        Ok(Ok(resp)) => {
            if let Some(err) = resp.error {
                state.chat_collectors.lock().await.remove(&session_id);
                return Err(format!("host agent rejected chat: {err}"));
            }
        }
        Ok(Err(_)) => {
            state.chat_collectors.lock().await.remove(&session_id);
            return Err("host agent disconnected before acking agent.chat".to_string());
        }
        Err(_) => {
            host_channel.pending.lock().await.remove(&request_id);
            state.chat_collectors.lock().await.remove(&session_id);
            return Err(format!(
                "host agent did not ack agent.chat within {AGENT_CHAT_ACK_TIMEOUT_SECS}s"
            ));
        }
    }

    // Aggregate streamed deltas until the terminal event or the overall timeout.
    let collect = async {
        let mut text = String::new();
        while let Some(chunk) = chunk_rx.recv().await {
            match chunk.kind.as_str() {
                "token" => {
                    if let Some(d) = chunk.delta {
                        text.push_str(&d);
                    }
                }
                "done" => return Ok(text),
                "error" => {
                    return Err(chunk
                        .error
                        .unwrap_or_else(|| "host agent error".to_string()));
                }
                _ => {}
            }
        }
        Err("agent.chat stream ended before completion".to_string())
    };
    let result = tokio::time::timeout(
        std::time::Duration::from_secs(A2A_CHAT_TIMEOUT_SECS),
        collect,
    )
    .await;
    state.chat_collectors.lock().await.remove(&session_id);
    match result {
        Ok(r) => r,
        Err(_) => Err(format!(
            "host agent did not complete the reply within {A2A_CHAT_TIMEOUT_SECS}s"
        )),
    }
}

/// [`car_a2a::ChatResponder`] backed by the WS session that started the A2A
/// listener: a conversational A2A `message/send` reverse-calls `agent.chat` on
/// that session and returns the host agent's aggregated reply. Holds a `Weak`
/// to `ServerState` so a dropped daemon doesn't keep it alive, and resolves the
/// host channel fresh each call so a reconnect/disconnect surfaces as an error.
pub(crate) struct WsChatResponder {
    pub state: std::sync::Weak<ServerState>,
    pub host_client_id: String,
}

#[async_trait::async_trait]
impl car_a2a::ChatResponder for WsChatResponder {
    async fn respond(&self, prompt: &str) -> Result<String, String> {
        let state = self
            .state
            .upgrade()
            .ok_or_else(|| "daemon is shutting down".to_string())?;
        let host_channel = {
            let sessions = state.sessions.lock().await;
            sessions
                .get(&self.host_client_id)
                .map(|s| s.channel.clone())
        }
        .ok_or_else(|| "host session for the A2A listener has disconnected".to_string())?;
        chat_collect(&state, &host_channel, &self.host_client_id, prompt).await
    }
}

/// `agents.chat.cancel` — host aborts an in-flight chat. Forwards
/// `agent.chat.cancel` to the bound agent so the agent can short-
/// circuit its inference stream + free upstream resources
/// (`inference.stream.cancel`). The chat session is dropped from
/// routing state immediately whether or not the agent acks the cancel
/// — further `agent.chat.event` notifications for this session_id
/// fall on the floor by design.
async fn handle_agents_chat_cancel(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    caller_client_id: &str,
    caller_is_host: bool,
) -> Result<Value, String> {
    use futures::SinkExt;
    use tokio_tungstenite::tungstenite::Message;

    let session_id = req
        .params
        .get("session_id")
        .and_then(Value::as_str)
        .ok_or_else(|| "`agents.chat.cancel` requires `session_id`".to_string())?
        .to_string();

    // Same ownership check `agents.chat.approve` applies one arm over. Without
    // it any authenticated session could abort any live turn by guessing or
    // observing a `session_id` — the caller was authenticated, and that was
    // taken to settle what it may do. Look up before removing, so a caller that
    // fails the check does not destroy the routing entry on its way out.
    {
        let chat = state.chat_sessions.lock().await.get(&session_id).cloned();
        if let Some(chat) = chat {
            if !caller_is_host && caller_client_id != chat.host_client_id {
                return Err(
                    "`agents.chat.cancel` requires the originating host session or \
                     host-management role"
                        .to_string(),
                );
            }
        }
    }

    let chat = state.chat_sessions.lock().await.remove(&session_id);
    let chat = match chat {
        Some(c) => c,
        None => {
            // Already cancelled or never existed — idempotent.
            return Ok(serde_json::json!({ "cancelled": false, "reason": "unknown session_id" }));
        }
    };
    if let Some(flag) = &chat.local_cancel {
        flag.store(true, Ordering::SeqCst);
    }
    update_chat_goal_from_event(
        state,
        &session_id,
        &serde_json::json!({
            "kind": "error",
            "error": "cancelled",
        }),
    )
    .await;

    // Best-effort fire-and-forget to the agent. We've already removed
    // the routing entry, so no need to await any agent response.
    let agent_client_id = state
        .attached_agents
        .lock()
        .await
        .get(&chat.agent_id)
        .cloned();
    if let Some(client_id) = agent_client_id {
        let channel_opt = {
            let sessions = state.sessions.lock().await;
            sessions.get(&client_id).map(|s| s.channel.clone())
        };
        if let Some(channel) = channel_opt {
            let notification = serde_json::json!({
                "jsonrpc": "2.0",
                "method": "agent.chat.cancel",
                "params": { "session_id": session_id },
            });
            if let Ok(text) = serde_json::to_string(&notification) {
                let _ = channel
                    .write
                    .lock()
                    .await
                    .send(Message::Text(text.into()))
                    .await;
            }
        }
    }

    Ok(serde_json::json!({ "cancelled": true, "session_id": session_id }))
}

/// Resolve a chat-surface human-in-the-loop approval (`agents.chat.approve`).
///
/// The mirror of [`handle_agents_chat_cancel`], but for the `approval_pending`
/// round-trip: an agent parked a gated action awaiting a decision (emitting an
/// `approval_pending` event with an `approval_id`); a host renders Approve/Deny
/// and calls this. We route the decision to the agent's own
/// `agent.chat.approve` handler (which resolves the parked oneshot so the turn
/// resumes), keyed by the live `chat_sessions` map — the SAME routing
/// `agents.chat`/`agents.chat.cancel` use. Unlike cancel, we do NOT drop the
/// chat session: the turn continues after the approval.
///
/// Params: `session_id` (required, routes to the agent), `approval_id`
/// (required, identifies the parked action), `decision` (bool, or one of
/// `"approve"`/`"approved"`/`"yes"` vs anything else). Forwarded verbatim.
///
/// This is a reverse *request* (not fire-and-forget like cancel): the agent's
/// handler returns `{ resolved: bool }`, which we await (bounded) and relay so
/// the host gets a definitive answer rather than guessing from the stream.
async fn handle_agents_chat_approve(
    req: &JsonRpcMessage,
    state: &Arc<ServerState>,
    caller_client_id: &str,
    caller_is_host: bool,
) -> Result<Value, String> {
    use futures::SinkExt;
    use tokio::sync::oneshot;
    use tokio_tungstenite::tungstenite::Message;

    let session_id = req
        .params
        .get("session_id")
        .and_then(Value::as_str)
        .ok_or_else(|| "`agents.chat.approve` requires `session_id`".to_string())?
        .to_string();
    let approval_id = req
        .params
        .get("approval_id")
        .and_then(Value::as_str)
        .ok_or_else(|| "`agents.chat.approve` requires `approval_id`".to_string())?
        .to_string();
    // `decision` is forwarded verbatim — the agent-side handler accepts a bool
    // or a string (`"approve"`/`"approved"`/`"yes"` → approved). Default to a
    // negative bool if omitted so an unspecified decision can never approve.
    let decision = req
        .params
        .get("decision")
        .cloned()
        .unwrap_or(Value::Bool(false));

    // Look up (do NOT remove) the chat session so the turn keeps routing after
    // the approval resolves.
    let chat = state.chat_sessions.lock().await.get(&session_id).cloned();
    let chat = chat.ok_or_else(|| {
        format!("`agents.chat.approve`: unknown or already-finished session_id `{session_id}`")
    })?;
    if !caller_is_host && caller_client_id != chat.host_client_id {
        return Err(
            "`agents.chat.approve` requires the originating host session or host-management role"
                .to_string(),
        );
    }

    // Resolve the agent's attached WS channel, same as agents.chat.
    let agent_client_id = state
        .attached_agents
        .lock()
        .await
        .get(&chat.agent_id)
        .cloned()
        .ok_or_else(|| {
            format!(
                "agent `{}` is not attached to this daemon (raced with disconnect)",
                chat.agent_id
            )
        })?;
    let agent_channel = {
        let sessions = state.sessions.lock().await;
        sessions
            .get(&agent_client_id)
            .map(|s| s.channel.clone())
            .ok_or_else(|| {
                format!(
                    "agent `{}` client_id `{}` not found in session registry",
                    chat.agent_id, agent_client_id
                )
            })?
    };

    // Reverse-request `agent.chat.approve` and await the agent's `{resolved}`
    // reply via the same `pending` demuxer the ack path uses.
    let request_id = agent_channel.next_request_id();
    let (tx, rx) = oneshot::channel();
    agent_channel
        .pending
        .lock()
        .await
        .insert(request_id.clone(), tx);

    let rpc_request = serde_json::json!({
        "jsonrpc": "2.0",
        "method": "agent.chat.approve",
        "params": { "approval_id": approval_id, "decision": decision },
        "id": request_id,
    });
    let msg = Message::Text(
        serde_json::to_string(&rpc_request)
            .map_err(|e| e.to_string())?
            .into(),
    );
    if let Err(e) = agent_channel.write.lock().await.send(msg).await {
        agent_channel.pending.lock().await.remove(&request_id);
        return Err(format!(
            "failed to deliver agent.chat.approve to `{}`: {}",
            chat.agent_id, e
        ));
    }

    let ack = match tokio::time::timeout(
        std::time::Duration::from_secs(AGENT_CHAT_ACK_TIMEOUT_SECS),
        rx,
    )
    .await
    {
        Ok(Ok(resp)) => resp,
        Ok(Err(_)) => {
            return Err(format!(
                "agent `{}` disconnected before acking agents.chat.approve",
                chat.agent_id
            ));
        }
        Err(_) => {
            agent_channel.pending.lock().await.remove(&request_id);
            return Err(format!(
                "agent `{}` did not ack agents.chat.approve within {}s",
                chat.agent_id, AGENT_CHAT_ACK_TIMEOUT_SECS
            ));
        }
    };
    if let Some(err) = ack.error {
        return Err(format!(
            "agent `{}` rejected agents.chat.approve: {}",
            chat.agent_id, err
        ));
    }

    // Relay the agent's `{resolved: bool}` result; default false if the agent
    // returned an unexpected shape.
    let resolved = ack
        .output
        .as_ref()
        .and_then(|r| r.get("resolved"))
        .and_then(Value::as_bool)
        .unwrap_or(false);
    Ok(serde_json::json!({ "resolved": resolved, "session_id": session_id }))
}

async fn update_chat_goal_from_event(state: &Arc<ServerState>, session_id: &str, params: &Value) {
    let Some(kind) = params.get("kind").and_then(Value::as_str) else {
        return;
    };
    let changed = {
        let mut goals = state.chat_goals.lock().await;
        let Some(goal) = goals.get_mut(session_id) else {
            return;
        };
        match kind {
            "goal_evaluated" => {
                goal.last_iteration = params
                    .get("iteration")
                    .and_then(Value::as_u64)
                    .and_then(|n| u32::try_from(n).ok());
                goal.last_met = params.get("met").and_then(Value::as_bool);
                goal.last_grounded = params.get("grounded").and_then(Value::as_bool);
                goal.last_reason = params
                    .get("reason")
                    .and_then(Value::as_str)
                    .map(str::to_string);
                goal.status = if goal.last_met == Some(true) && goal.last_grounded == Some(true) {
                    "met".to_string()
                } else {
                    "running".to_string()
                };
                goal.updated_at = unix_secs_now();
                true
            }
            "done" | "error" => {
                goal.terminal_kind = Some(kind.to_string());
                goal.terminal_message = params
                    .get("finish_reason")
                    .or_else(|| params.get("error"))
                    .and_then(Value::as_str)
                    .map(str::to_string);
                // car#1113 review: a fail-open `done` (the goal check never
                // got the chance to run — see `chat::goal_turn_terminal_event`
                // / `GoalHalt::EvaluationTimeout`) must not be recorded as
                // `"met"`. `finish_reason` alone isn't enough to prevent that
                // — it lands in `terminal_message`, a secondary prose field,
                // while `status` is the one `docs/websocket-protocol.md`
                // documents as what a `goal.status` poller actually reads.
                // `goal_unevaluated` is the machine-readable marker
                // `goal_turn_terminal_event` sets for exactly this case.
                let unevaluated = params
                    .get("goal_unevaluated")
                    .and_then(Value::as_bool)
                    .unwrap_or(false);
                goal.status = if kind == "error" {
                    "error".to_string()
                } else if unevaluated {
                    "unevaluated".to_string()
                } else {
                    "met".to_string()
                };
                goal.updated_at = unix_secs_now();
                true
            }
            _ => false,
        }
    };
    if changed {
        if let Err(e) = state.persist_chat_goals().await {
            tracing::warn!(
                session_id,
                error = %e,
                "failed to persist chat goal status update"
            );
        }
    }
}

/// Forward an `agent.chat.event` notification from an agent's
/// connection to the originating host's connection, rewritten as an
/// `agents.chat.event` notification. Returns `true` if the inbound
/// frame was a chat-event we routed (so the dispatcher can `continue`
/// past the normal method dispatch and skip the wasted "unknown
/// method" response), `false` otherwise.
///
/// Terminal events (`kind: "done"` / `"error"`) also drop the routing
/// entry from `state.chat_sessions` so a later stray notification can
/// be rejected as orphaned without leaking memory.
pub(crate) async fn try_forward_agent_chat_event(
    parsed: &JsonRpcMessage,
    state: &Arc<ServerState>,
) -> bool {
    use futures::SinkExt;
    use tokio_tungstenite::tungstenite::Message;

    // Notification predicate: method is `agent.chat.event`, id is
    // missing/null (per JSON-RPC, notifications have no id), and
    // params carry a session_id.
    let Some(method) = parsed.method.as_deref() else {
        return false;
    };
    if method != "agent.chat.event" {
        return false;
    }
    if !parsed.id.is_null() {
        // Has an id → it's a request, not a notification. Let the
        // normal dispatcher handle it (and reply with method-not-found).
        return false;
    }
    let Some(session_id) = parsed.params.get("session_id").and_then(Value::as_str) else {
        return false;
    };
    let session_id = session_id.to_string();

    // In-process collector path (the A2A conversational bridge has no host UI
    // to stream to). If a collector is registered for this session, feed it the
    // normalized chunk and consume the event — the collecting task owns the
    // collector's lifetime, so we don't touch chat_sessions or remove it here.
    let collector = state
        .chat_collectors
        .lock()
        .await
        .get(&session_id)
        .map(|c| c.tx.clone());
    if let Some(tx) = collector {
        let kind = parsed
            .params
            .get("kind")
            .and_then(Value::as_str)
            .map(str::to_string)
            .unwrap_or_else(|| {
                if parsed.params.get("error").is_some() {
                    "error".to_string()
                } else if parsed.params.get("finish_reason").is_some() {
                    "done".to_string()
                } else {
                    "token".to_string()
                }
            });
        let delta = parsed
            .params
            .get("delta")
            .and_then(Value::as_str)
            .map(str::to_string);
        let error = parsed
            .params
            .get("error")
            .and_then(Value::as_str)
            .map(str::to_string);
        let _ = tx.send(crate::session::ChatStreamChunk { kind, delta, error });
        return true;
    }

    // Look up the routing entry. If gone (cancelled, agent dropped,
    // disconnect cleanup), drop the event silently — late frames from
    // a respawned agent for a stale session are not the host's
    // problem.
    let chat = state.chat_sessions.lock().await.get(&session_id).cloned();
    let Some(chat) = chat else {
        return true; // recognized the method, but routing has dropped — consumed.
    };

    // Pull the kind early so terminal-event cleanup runs even if the
    // host's send fails. Agents may omit `kind` and signal terminal
    // state via `finish_reason` / `error` instead (car#222) — derive
    // it from the frame shape so both the cleanup below AND the host
    // see a correct, host-protocol-compliant kind. The old code
    // defaulted a `finish_reason`-only "done" frame to "token", so
    // terminal cleanup never ran and the host (which requires `kind`)
    // dropped every frame silently.
    let kind = parsed
        .params
        .get("kind")
        .and_then(Value::as_str)
        .map(str::to_string)
        .unwrap_or_else(|| {
            if parsed.params.get("error").is_some() {
                "error".to_string()
            } else if parsed.params.get("finish_reason").is_some() {
                "done".to_string()
            } else {
                "token".to_string()
            }
        });
    update_chat_goal_from_event(
        state,
        &session_id,
        &serde_json::json!({
            "kind": kind.clone(),
            "finish_reason": parsed.params.get("finish_reason").cloned().unwrap_or(Value::Null),
            "error": parsed.params.get("error").cloned().unwrap_or(Value::Null),
            "iteration": parsed.params.get("iteration").cloned().unwrap_or(Value::Null),
            "met": parsed.params.get("met").cloned().unwrap_or(Value::Null),
            "grounded": parsed.params.get("grounded").cloned().unwrap_or(Value::Null),
            "reason": parsed.params.get("reason").cloned().unwrap_or(Value::Null),
        }),
    )
    .await;

    // Forward to the host. Rewrites the method name to the host-facing
    // form and attaches `agent_id` so the host doesn't have to remember
    // which agent owns each session.
    let host_channel = {
        let sessions = state.sessions.lock().await;
        sessions
            .get(&chat.host_client_id)
            .map(|s| s.channel.clone())
    };
    if let Some(channel) = host_channel {
        let mut params = parsed.params.clone();
        if let Some(obj) = params.as_object_mut() {
            obj.insert("agent_id".to_string(), Value::String(chat.agent_id.clone()));
            // host-protocol.md requires a top-level `kind` on every
            // agents.chat.event. Agents that omit it (signalling via
            // finish_reason/error) were dropped wholesale by the host
            // decoder — normalize here so the contract holds. car#222.
            obj.entry("kind")
                .or_insert_with(|| Value::String(kind.clone()));
        }
        let forward = serde_json::json!({
            "jsonrpc": "2.0",
            "method": "agents.chat.event",
            "params": params,
        });
        if let Ok(text) = serde_json::to_string(&forward) {
            let send_result = channel
                .write
                .lock()
                .await
                .send(Message::Text(text.into()))
                .await;
            if let Err(e) = send_result {
                tracing::warn!(
                    session_id = %session_id,
                    agent_id = %chat.agent_id,
                    host_client_id = %chat.host_client_id,
                    kind = %kind,
                    error = %e,
                    "agent.chat.event forward to host failed at the WS send step"
                );
            }
        }
    } else {
        // Host disconnected mid-stream — chat_sessions still holds
        // the routing entry but the originating client_id no longer
        // resolves to a session. Pre-#233 this was silent and the
        // operator had no way to tell whether the event was dropped
        // here or never emitted by the agent. Log + drop the
        // routing entry so subsequent stray events are no-ops.
        tracing::warn!(
            session_id = %session_id,
            agent_id = %chat.agent_id,
            host_client_id = %chat.host_client_id,
            kind = %kind,
            "agent.chat.event from supervised agent had no host channel \
             (host disconnected since `agents.chat`); dropping routing entry"
        );
        state.chat_sessions.lock().await.remove(&session_id);
        return true;
    }

    // Terminal-kind cleanup. The host_channel branch above already
    // forwarded the terminal event; we just remove the routing entry
    // here so subsequent stray frames are no-ops.
    if matches!(kind.as_str(), "done" | "error") {
        state.chat_sessions.lock().await.remove(&session_id);
    }

    true
}

#[cfg(test)]
mod credential_event_lag_regression {
    use super::{credential_fanout_test_gate, credential_handoff_test_gate, run_dispatch};
    use futures::{Sink, SinkExt, StreamExt};
    use std::pin::Pin;
    use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
    use std::sync::Arc;
    use std::task::{Context, Poll};
    use tokio_tungstenite::tungstenite::{Error as WsError, Message};

    const HOST_TOKEN: &str = "lag-test-host-token-cccccccccccccccccccc";

    struct StallAfterTwoWrites {
        outbound: futures::channel::mpsc::UnboundedSender<Message>,
        sends: Arc<AtomicUsize>,
        stalled: Arc<AtomicBool>,
    }

    impl Sink<Message> for StallAfterTwoWrites {
        type Error = WsError;

        fn poll_ready(
            self: Pin<&mut Self>,
            _context: &mut Context<'_>,
        ) -> Poll<Result<(), Self::Error>> {
            if self.sends.load(Ordering::SeqCst) >= 2 {
                self.stalled.store(true, Ordering::SeqCst);
                Poll::Pending
            } else {
                Poll::Ready(Ok(()))
            }
        }

        fn start_send(self: Pin<&mut Self>, message: Message) -> Result<(), Self::Error> {
            self.outbound
                .unbounded_send(message)
                .map_err(|_| WsError::ConnectionClosed)?;
            self.sends.fetch_add(1, Ordering::SeqCst);
            Ok(())
        }

        fn poll_flush(
            self: Pin<&mut Self>,
            _context: &mut Context<'_>,
        ) -> Poll<Result<(), Self::Error>> {
            Poll::Ready(Ok(()))
        }

        fn poll_close(
            self: Pin<&mut Self>,
            _context: &mut Context<'_>,
        ) -> Poll<Result<(), Self::Error>> {
            Poll::Ready(Ok(()))
        }
    }

    fn request(id: &str, method: &str, params: serde_json::Value) -> Message {
        Message::Text(
            serde_json::json!({
                "jsonrpc": "2.0",
                "id": id,
                "method": method,
                "params": params,
            })
            .to_string()
            .into(),
        )
    }

    #[tokio::test]
    async fn credential_event_queue_overflow_terminates_host_dispatch() {
        const SENTINEL: &str = "CAR_CREDENTIAL_EVENT_LAG_CHILD";
        if std::env::var_os(SENTINEL).is_none() {
            let status = std::process::Command::new(std::env::current_exe().unwrap())
                .arg("--exact")
                .arg(
                    "handler::credential_event_lag_regression::credential_event_queue_overflow_terminates_host_dispatch",
                )
                .arg("--nocapture")
                .env(SENTINEL, "1")
                .env("CAR_NO_INFERENCE_WORKER", "1")
                .status()
                .expect("spawn isolated credential-event lag contract");
            assert!(
                status.success(),
                "isolated credential-event lag contract failed"
            );
            return;
        }

        let temp = tempfile::TempDir::new().unwrap();
        let secrets = tempfile::TempDir::new().unwrap();
        std::env::set_var("CAR_SECRETS_FILE_DIR", secrets.path());
        std::env::set_var(car_home::ENV_VAR, temp.path());
        car_auth::commit_login(
            "https://api.example.test",
            &car_auth::TokenSet {
                access_token: "lag-test-access".into(),
                refresh_token: "lag-test-refresh".into(),
                expires_in: 3_600,
                token_type: "Bearer".into(),
            },
            r#"{"Account":{"Id":"lag-account","Email":"lag@example.test"}}"#,
            None,
        )
        .await
        .unwrap();

        let state = Arc::new(crate::session::ServerState::standalone(
            temp.path().join("journal"),
        ));
        state
            .install_host_token(HOST_TOKEN.to_string())
            .expect("install host token");

        let (inbound_tx, inbound_rx) =
            futures::channel::mpsc::unbounded::<Result<Message, WsError>>();
        let (outbound_tx, mut outbound_rx) = futures::channel::mpsc::unbounded::<Message>();
        let sends = Arc::new(AtomicUsize::new(0));
        let credential_write_stalled = Arc::new(AtomicBool::new(false));
        let sink = StallAfterTwoWrites {
            outbound: outbound_tx,
            sends: Arc::clone(&sends),
            stalled: Arc::clone(&credential_write_stalled),
        };
        let write: crate::session::WsSink = Box::pin(sink);
        let dispatch_state = Arc::clone(&state);
        let mut dispatch = tokio::spawn(async move {
            run_dispatch(
                inbound_rx,
                write,
                "credential-lag-test".to_string(),
                dispatch_state,
            )
            .await
            .map_err(|error| error.to_string())
        });

        inbound_tx
            .unbounded_send(Ok(request(
                "auth",
                "session.auth",
                serde_json::json!({ "host_token": HOST_TOKEN }),
            )))
            .unwrap();
        let auth_response = outbound_rx.next().await.expect("host auth response");
        assert!(auth_response
            .into_text()
            .unwrap()
            .contains("\"role\":\"host\""));

        inbound_tx
            .unbounded_send(Ok(request(
                "handshake",
                "server.handshake",
                serde_json::json!({ "protocol_version": car_proto::PROTOCOL_VERSION }),
            )))
            .unwrap();
        let handshake_response = outbound_rx.next().await.expect("handshake response");
        assert!(handshake_response.into_text().unwrap().contains(&format!(
            "\"protocol_version\":{}",
            car_proto::PROTOCOL_VERSION
        )));

        car_auth::resolve_credential(car_auth::CredentialReadMode::Retry)
            .await
            .expect("credential generation should resolve");
        for _ in 0..100 {
            if credential_write_stalled.load(Ordering::SeqCst) {
                break;
            }
            tokio::task::yield_now().await;
        }
        assert!(
            credential_write_stalled.load(Ordering::SeqCst),
            "the real host fanout must be stalled on its credential-event write"
        );
        for _ in 0..3 {
            car_auth::resolve_credential(car_auth::CredentialReadMode::Retry)
                .await
                .expect("credential generation should resolve while host fanout is stalled");
        }

        let result = tokio::time::timeout(std::time::Duration::from_millis(500), &mut dispatch)
            .await
            .expect("credential-event overflow must cancel the owning host connection")
            .expect("dispatcher task should join");
        assert!(result.is_ok(), "dispatcher cleanup failed: {result:?}");
        assert!(
            state.sessions.lock().await.is_empty(),
            "a lagged host cannot remain connected but silently unsubscribed"
        );
    }

    #[tokio::test]
    async fn preauth_activity_cannot_disconnect_a_later_eligible_host() {
        const SENTINEL: &str = "CAR_CREDENTIAL_EVENT_PREAUTH_CHILD";
        if std::env::var_os(SENTINEL).is_none() {
            let status = std::process::Command::new(std::env::current_exe().unwrap())
                .arg("--exact")
                .arg(
                    "handler::credential_event_lag_regression::preauth_activity_cannot_disconnect_a_later_eligible_host",
                )
                .arg("--nocapture")
                .env(SENTINEL, "1")
                .env("CAR_NO_INFERENCE_WORKER", "1")
                .env("CAR_TEST_PAUSE_CREDENTIAL_FANOUT", "1")
                .status()
                .expect("spawn isolated pre-auth credential-event contract");
            assert!(status.success(), "isolated pre-auth contract failed");
            return;
        }

        let temp = tempfile::TempDir::new().unwrap();
        let secrets = tempfile::TempDir::new().unwrap();
        std::env::set_var("CAR_SECRETS_FILE_DIR", secrets.path());
        std::env::set_var(car_home::ENV_VAR, temp.path());
        car_auth::commit_login(
            "https://api.example.test",
            &car_auth::TokenSet {
                access_token: "preauth-test-access".into(),
                refresh_token: "preauth-test-refresh".into(),
                expires_in: 3_600,
                token_type: "Bearer".into(),
            },
            r#"{"Account":{"Id":"preauth-account","Email":"preauth@example.test"}}"#,
            None,
        )
        .await
        .unwrap();

        let state = Arc::new(crate::session::ServerState::standalone(
            temp.path().join("journal"),
        ));
        state
            .install_host_token(HOST_TOKEN.to_string())
            .expect("install host token");

        let (inbound_tx, inbound_rx) =
            futures::channel::mpsc::unbounded::<Result<Message, WsError>>();
        let (outbound_tx, mut outbound_rx) = futures::channel::mpsc::unbounded::<Message>();
        let write: crate::session::WsSink = Box::pin(
            outbound_tx.sink_map_err(|_| tokio_tungstenite::tungstenite::Error::ConnectionClosed),
        );
        let dispatch_state = Arc::clone(&state);
        let mut dispatch = tokio::spawn(async move {
            run_dispatch(
                inbound_rx,
                write,
                "credential-preauth-test".to_string(),
                dispatch_state,
            )
            .await
            .map_err(|error| error.to_string())
        });

        credential_fanout_test_gate().ready.notified().await;
        for _ in 0..3 {
            car_auth::resolve_credential(car_auth::CredentialReadMode::Retry)
                .await
                .expect("pre-auth credential generation should resolve");
        }

        inbound_tx
            .unbounded_send(Ok(request(
                "auth",
                "session.auth",
                serde_json::json!({ "host_token": HOST_TOKEN }),
            )))
            .unwrap();
        let auth_response = outbound_rx.next().await.expect("host auth response");
        assert!(auth_response
            .into_text()
            .unwrap()
            .contains("\"role\":\"host\""));

        inbound_tx
            .unbounded_send(Ok(request(
                "handshake",
                "server.handshake",
                serde_json::json!({ "protocol_version": car_proto::PROTOCOL_VERSION }),
            )))
            .unwrap();
        let mut negotiated = false;
        for _ in 0..100 {
            negotiated = state.sessions.lock().await.values().any(|session| {
                session.negotiated_protocol_version.load(Ordering::Acquire)
                    == car_proto::PROTOCOL_VERSION
            });
            if negotiated {
                break;
            }
            tokio::task::yield_now().await;
        }
        assert!(
            negotiated,
            "host protocol negotiation must complete while fanout is paused"
        );

        credential_fanout_test_gate().release.notify_one();
        let mut saw_handshake = false;
        let mut saw_reconciled = false;
        for _ in 0..2 {
            let frame =
                tokio::time::timeout(std::time::Duration::from_millis(500), outbound_rx.next())
                    .await
                    .expect("eligible host should receive handshake and reconciled snapshot")
                    .expect("eligible host connection must remain open")
                    .into_text()
                    .unwrap();
            saw_handshake |= frame.contains(&format!(
                "\"protocol_version\":{}",
                car_proto::PROTOCOL_VERSION
            ));
            saw_reconciled |= frame.contains("\"method\":\"auth.credential.event\"")
                && frame.contains("\"state\":\"configured\"");
        }
        assert!(saw_handshake, "host must receive handshake success");
        assert!(
            saw_reconciled,
            "host must receive the retained credential snapshot"
        );

        inbound_tx
            .unbounded_send(Ok(request(
                "still-connected",
                "auth.authority_hint",
                serde_json::json!({}),
            )))
            .unwrap();
        let response =
            tokio::time::timeout(std::time::Duration::from_millis(500), outbound_rx.next())
                .await
                .expect("host should remain responsive after pre-auth activity")
                .expect("host connection should remain open")
                .into_text()
                .unwrap();
        assert!(response.contains("\"id\":\"still-connected\""));
        assert!(!dispatch.is_finished());

        inbound_tx.unbounded_send(Ok(Message::Close(None))).unwrap();
        let result = tokio::time::timeout(std::time::Duration::from_millis(500), &mut dispatch)
            .await
            .expect("dispatcher should stop after close")
            .expect("dispatcher task should join");
        assert!(result.is_ok(), "dispatcher cleanup failed: {result:?}");
    }

    #[tokio::test]
    async fn handoff_cannot_send_terminal_before_queued_pending() {
        const SENTINEL: &str = "CAR_CREDENTIAL_EVENT_HANDOFF_CHILD";
        if std::env::var_os(SENTINEL).is_none() {
            let status = std::process::Command::new(std::env::current_exe().unwrap())
                .arg("--exact")
                .arg(
                    "handler::credential_event_lag_regression::handoff_cannot_send_terminal_before_queued_pending",
                )
                .arg("--nocapture")
                .env(SENTINEL, "1")
                .env("CAR_NO_INFERENCE_WORKER", "1")
                .env("CAR_TEST_PAUSE_CREDENTIAL_HANDOFF", "1")
                .status()
                .expect("spawn isolated credential handoff contract");
            assert!(status.success(), "isolated credential handoff failed");
            return;
        }

        let temp = tempfile::TempDir::new().unwrap();
        let secrets = tempfile::TempDir::new().unwrap();
        std::env::set_var("CAR_SECRETS_FILE_DIR", secrets.path());
        std::env::set_var(car_home::ENV_VAR, temp.path());
        car_auth::commit_login(
            "https://api.example.test",
            &car_auth::TokenSet {
                access_token: "handoff-test-access".into(),
                refresh_token: "handoff-test-refresh".into(),
                expires_in: 3_600,
                token_type: "Bearer".into(),
            },
            r#"{"Account":{"Id":"handoff-account","Email":"handoff@example.test"}}"#,
            None,
        )
        .await
        .unwrap();

        let state = Arc::new(crate::session::ServerState::standalone(
            temp.path().join("journal"),
        ));
        state
            .install_host_token(HOST_TOKEN.to_string())
            .expect("install host token");

        let (inbound_tx, inbound_rx) =
            futures::channel::mpsc::unbounded::<Result<Message, WsError>>();
        let (outbound_tx, mut outbound_rx) = futures::channel::mpsc::unbounded::<Message>();
        let write: crate::session::WsSink = Box::pin(
            outbound_tx.sink_map_err(|_| tokio_tungstenite::tungstenite::Error::ConnectionClosed),
        );
        let dispatch_state = Arc::clone(&state);
        let mut dispatch = tokio::spawn(async move {
            run_dispatch(
                inbound_rx,
                write,
                "credential-handoff-test".to_string(),
                dispatch_state,
            )
            .await
            .map_err(|error| error.to_string())
        });

        inbound_tx
            .unbounded_send(Ok(request(
                "auth",
                "session.auth",
                serde_json::json!({ "host_token": HOST_TOKEN }),
            )))
            .unwrap();
        let auth_response = outbound_rx.next().await.expect("host auth response");
        assert!(auth_response
            .into_text()
            .unwrap()
            .contains("\"role\":\"host\""));

        inbound_tx
            .unbounded_send(Ok(request(
                "handshake",
                "server.handshake",
                serde_json::json!({ "protocol_version": car_proto::PROTOCOL_VERSION }),
            )))
            .unwrap();
        credential_handoff_test_gate().ready.notified().await;

        car_auth::resolve_credential(car_auth::CredentialReadMode::Retry)
            .await
            .expect("interleaved credential generation should resolve");
        credential_handoff_test_gate().release.notify_one();

        let mut saw_handshake = false;
        let mut states = Vec::new();
        while !saw_handshake || states.len() < 2 {
            let frame =
                tokio::time::timeout(std::time::Duration::from_millis(500), outbound_rx.next())
                    .await
                    .expect("handoff must deliver handshake and exact credential lifecycle")
                    .expect("eligible host connection must remain open")
                    .into_text()
                    .unwrap();
            let value: serde_json::Value =
                serde_json::from_str(&frame).expect("credential handoff frame JSON");
            saw_handshake |= value["id"] == "handshake";
            if value["method"] == "auth.credential.event" {
                states.push(value["params"]["state"].as_str().unwrap().to_string());
            }
        }
        assert_eq!(states, ["pending", "configured"]);

        inbound_tx.unbounded_send(Ok(Message::Close(None))).unwrap();
        let result = tokio::time::timeout(std::time::Duration::from_millis(500), &mut dispatch)
            .await
            .expect("dispatcher should stop after close")
            .expect("dispatcher task should join");
        assert!(result.is_ok(), "dispatcher cleanup failed: {result:?}");
    }
}

#[cfg(test)]
mod fd_leak_regression {
    //! car#209 regression: an abrupt transport error must still run
    //! the connection cleanup. Before the fix, `let msg = msg?;`
    //! propagated the read error out of `run_dispatch`, skipping
    //! `remove_session`, so `state.sessions` (holding the
    //! `Arc<ClientSession>` -> `Arc<WsChannel>` -> socket FD) leaked
    //! forever on every peer reset / crash-loop disconnect.
    use super::run_dispatch;
    use futures::SinkExt;
    use std::sync::Arc;
    use tokio_tungstenite::tungstenite::{Error as WsError, Message};

    #[tokio::test]
    async fn abrupt_read_error_still_runs_session_cleanup() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(crate::session::ServerState::standalone(
            tmp.path().to_path_buf(),
        ));

        // Read stream that immediately yields a transport error (peer
        // reset), then ends -- the exact shape of an ungraceful
        // client disconnect.
        let read = futures::stream::iter(vec![Err::<Message, WsError>(WsError::ConnectionClosed)]);
        let write: crate::session::WsSink =
            Box::pin(futures::sink::drain().sink_map_err(|_| WsError::ConnectionClosed));

        let result = run_dispatch(read, write, "test-peer".to_string(), state.clone()).await;
        assert!(
            result.is_ok(),
            "run_dispatch must return Ok after cleanup, got {result:?}"
        );

        // The session (and its channel/FD) must be gone -- cleanup
        // ran despite the abrupt error.
        assert!(
            state.sessions.lock().await.is_empty(),
            "state.sessions must be empty after an abrupt disconnect (car#209)"
        );
    }
}

#[cfg(test)]
mod a2ui_action_delivery {
    //! Parslee-ai/car-releases#58: a ClientAction must reach A2UI
    //! subscribers on the `a2ui.event` channel — the same one that
    //! already carries surface updates — so an agent that created a
    //! surface receives the button click it would otherwise never see.
    use super::{handle_a2ui_action, JsonRpcMessage};
    use crate::session::{ServerState, WsChannel, WsSink};
    use futures::{SinkExt, StreamExt};
    use std::collections::HashMap;
    use std::sync::atomic::AtomicU64;
    use std::sync::Arc;
    use tokio::sync::Mutex;
    use tokio_tungstenite::tungstenite::{Error as WsError, Message};

    #[tokio::test]
    async fn client_action_broadcasts_to_a2ui_subscribers() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));

        // Capturing subscriber channel: a futures mpsc whose sink half is
        // erased into the WsSink the server writes to, receiver kept here.
        let (tx, mut rx) = futures::channel::mpsc::unbounded::<Message>();
        let sink: WsSink = Box::pin(tx.sink_map_err(|_| WsError::ConnectionClosed));
        let channel = Arc::new(WsChannel {
            write: Mutex::new(sink),
            pending: Mutex::new(HashMap::new()),
            active_actions: Mutex::new(HashMap::new()),
            next_id: AtomicU64::new(0),
        });
        state
            .a2ui_subscribers
            .lock()
            .await
            .insert("test-sub".to_string(), channel);

        // Send the action under the `action` key (not `name`) to also
        // exercise the serde alias — the web renderer forwards
        // `@a2ui/web_core`'s object verbatim.
        let req: JsonRpcMessage = serde_json::from_value(serde_json::json!({
            "jsonrpc": "2.0",
            "method": "a2ui.action",
            "id": 1,
            "params": {
                "action": "trader:pause",
                "surfaceId": "surf-1",
                "sourceComponentId": "b1",
                "timestamp": "2026-06-03T00:00:00Z"
            }
        }))
        .unwrap();

        let out = handle_a2ui_action(&req, &state).await;
        assert!(out.is_ok(), "handle_a2ui_action failed: {out:?}");

        let msg = rx.next().await.expect("subscriber received no frame");
        let text = match msg {
            Message::Text(t) => t.to_string(),
            other => panic!("expected text frame, got {other:?}"),
        };
        let v: serde_json::Value = serde_json::from_str(&text).unwrap();
        assert_eq!(v["method"], "a2ui.event");
        assert_eq!(v["params"]["kind"], "a2ui.action");
        // Alias resolved `action` -> `name`.
        assert_eq!(
            v["params"]["result"]["action"]["name"], "trader:pause",
            "ClientAction.name should accept the `action` alias"
        );
        assert_eq!(v["params"]["result"]["surfaceId"], "surf-1");
    }
}

#[cfg(test)]
mod a2a_chat_collector {
    //! car-releases#65 part 2: when an A2A conversational turn registers an
    //! in-process collector, `try_forward_agent_chat_event` feeds it the
    //! normalized stream chunks instead of forwarding to a host UI channel.
    use super::{try_forward_agent_chat_event, JsonRpcMessage};
    use crate::session::{ChatCollector, ServerState};
    use std::sync::Arc;
    use tokio::sync::mpsc;

    fn event(session_id: &str, extra: serde_json::Value) -> JsonRpcMessage {
        let mut params = serde_json::Map::new();
        params.insert("session_id".into(), session_id.into());
        if let Some(obj) = extra.as_object() {
            for (k, v) in obj {
                params.insert(k.clone(), v.clone());
            }
        }
        serde_json::from_value(serde_json::json!({
            "jsonrpc": "2.0",
            "method": "agent.chat.event",
            "params": params,
        }))
        .unwrap()
    }

    #[tokio::test]
    async fn collector_receives_normalized_chunks() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        let (tx, mut rx) = mpsc::unbounded_channel();
        state.chat_collectors.lock().await.insert(
            "a2a-chat-xyz".into(),
            ChatCollector {
                tx,
                host_client_id: "host-1".into(),
            },
        );

        // Explicit token delta.
        assert!(
            try_forward_agent_chat_event(
                &event(
                    "a2a-chat-xyz",
                    serde_json::json!({ "kind": "token", "delta": "Hello " })
                ),
                &state,
            )
            .await
        );
        // kind omitted, has delta → derived "token".
        try_forward_agent_chat_event(
            &event("a2a-chat-xyz", serde_json::json!({ "delta": "world" })),
            &state,
        )
        .await;
        // kind omitted, finish_reason present → derived terminal "done".
        try_forward_agent_chat_event(
            &event(
                "a2a-chat-xyz",
                serde_json::json!({ "finish_reason": "1 turn" }),
            ),
            &state,
        )
        .await;

        let c1 = rx.recv().await.unwrap();
        assert_eq!(c1.kind, "token");
        assert_eq!(c1.delta.as_deref(), Some("Hello "));
        let c2 = rx.recv().await.unwrap();
        assert_eq!(c2.delta.as_deref(), Some("world"));
        let c3 = rx.recv().await.unwrap();
        assert_eq!(c3.kind, "done");

        // The collector is left in place for the collecting task to drain/remove.
        assert!(state
            .chat_collectors
            .lock()
            .await
            .contains_key("a2a-chat-xyz"));
    }

    #[tokio::test]
    async fn error_event_carries_error_text() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        let (tx, mut rx) = mpsc::unbounded_channel();
        state.chat_collectors.lock().await.insert(
            "a2a-chat-err".into(),
            ChatCollector {
                tx,
                host_client_id: "h".into(),
            },
        );
        try_forward_agent_chat_event(
            &event(
                "a2a-chat-err",
                serde_json::json!({ "error": "model exploded" }),
            ),
            &state,
        )
        .await;
        let c = rx.recv().await.unwrap();
        assert_eq!(c.kind, "error"); // derived from `error` presence
        assert_eq!(c.error.as_deref(), Some("model exploded"));
    }
}

#[cfg(test)]
mod scheduler_stateful_dedup {
    //! The WS `scheduler.run` path deserializes a fresh `Task` from client
    //! params on every call and used to run it through a throwaway `Executor`
    //! without persisting the mutated task. Because the executor's
    //! deterministic occurrence guard lives in `task.executions`, that history
    //! was empty on every call and a replayed Interval/Once occurrence ran
    //! twice. `run_scheduler_task_once` now seeds the task from a `TaskStore`
    //! and saves it back, so the guard survives the JSON-RPC boundary.
    use super::run_scheduler_task_once;
    use car_multi::{AgentOutput, AgentRunner, AgentSpec, Mailbox, MultiError};
    use car_scheduler::{Task, TaskStore, TaskTrigger};
    use std::sync::atomic::{AtomicU32, Ordering};
    use std::sync::Arc;

    /// Runner that counts how many times the runtime actually invoked it.
    struct CountingRunner {
        runs: Arc<AtomicU32>,
    }

    #[async_trait::async_trait]
    impl AgentRunner for CountingRunner {
        async fn run(
            &self,
            spec: &AgentSpec,
            _task: &str,
            _runtime: &car_engine::Runtime,
            _mailbox: &Mailbox,
        ) -> Result<AgentOutput, MultiError> {
            self.runs.fetch_add(1, Ordering::SeqCst);
            Ok(AgentOutput {
                name: spec.name.clone(),
                answer: "done".to_string(),
                turns: 1,
                tool_calls: 0,
                duration_ms: 1.0,
                error: None,
                outcome: None,
                tokens: None,
                tools_used: Vec::new(),
            })
        }
    }

    #[tokio::test]
    async fn second_run_dedups_across_the_jsonrpc_boundary() {
        let dir = tempfile::TempDir::new().unwrap();
        let store = TaskStore::new(dir.path());
        let runs = Arc::new(AtomicU32::new(0));

        // The same Task JSON a client would post twice: an Interval trigger on a
        // long schedule (both calls land in slot 0) with an empty execution
        // history each time. Serializing/deserializing models the JSON-RPC hop.
        let task =
            Task::new("dedup_task", "do the thing").with_trigger(TaskTrigger::Interval, "1h");
        let task_json = serde_json::to_value(&task).unwrap();

        // First call: runs and persists the occurrence.
        let mut t1: Task = serde_json::from_value(task_json.clone()).unwrap();
        assert!(t1.executions.is_empty());
        let runner1: Arc<dyn AgentRunner> = Arc::new(CountingRunner { runs: runs.clone() });
        run_scheduler_task_once(&mut t1, runner1, &store).await;

        // Second call: a fresh deserialized Task (empty executions again), but
        // the store seeds the prior occurrence so the guard dedups it.
        let mut t2: Task = serde_json::from_value(task_json).unwrap();
        assert!(t2.executions.is_empty());
        let runner2: Arc<dyn AgentRunner> = Arc::new(CountingRunner { runs: runs.clone() });
        run_scheduler_task_once(&mut t2, runner2, &store).await;

        assert_eq!(
            runs.load(Ordering::SeqCst),
            1,
            "the runner must be invoked exactly once across two stateless calls"
        );

        // The persisted task carries the single occurrence.
        let persisted = store.load(&task.id).expect("task should be persisted");
        assert_eq!(persisted.run_count, 1);
        assert_eq!(persisted.executions.len(), 1);
    }
}

#[cfg(test)]
mod a2ui_apply_delivery {
    //! Parslee-ai/car-releases#29: applying an A2UI envelope must reach
    //! every WS subscriber on the `a2ui.event` channel. A `createSurface`
    //! apply broadcasts `a2ui.surface_updated`; a `deleteSurface` apply
    //! broadcasts `a2ui.surface_deleted`. Reuses the fake
    //! WsChannel-over-mpsc harness from `a2ui_action_delivery`.
    use super::apply_a2ui_envelope;
    use crate::session::{ServerState, WsChannel, WsSink};
    use futures::{SinkExt, StreamExt};
    use std::collections::HashMap;
    use std::sync::atomic::AtomicU64;
    use std::sync::Arc;
    use tokio::sync::Mutex;
    use tokio_tungstenite::tungstenite::{Error as WsError, Message};

    fn fake_subscriber() -> (
        Arc<WsChannel>,
        futures::channel::mpsc::UnboundedReceiver<Message>,
    ) {
        let (tx, rx) = futures::channel::mpsc::unbounded::<Message>();
        let sink: WsSink = Box::pin(tx.sink_map_err(|_| WsError::ConnectionClosed));
        let channel = Arc::new(WsChannel {
            write: Mutex::new(sink),
            pending: Mutex::new(HashMap::new()),
            active_actions: Mutex::new(HashMap::new()),
            next_id: AtomicU64::new(0),
        });
        (channel, rx)
    }

    fn envelope(value: serde_json::Value) -> car_a2ui::A2uiEnvelope {
        serde_json::from_value(value).expect("valid envelope")
    }

    #[tokio::test]
    async fn apply_create_broadcasts_surface_updated() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        let (channel, mut rx) = fake_subscriber();
        state
            .a2ui_subscribers
            .lock()
            .await
            .insert("test-sub".to_string(), channel);

        apply_a2ui_envelope(
            &state,
            envelope(serde_json::json!({
                "version": "v0.9",
                "createSurface": { "surfaceId": "surf-a" }
            })),
            None,
            None,
        )
        .await
        .expect("apply must succeed");

        let msg = rx.next().await.expect("subscriber received no frame");
        let text = match msg {
            Message::Text(t) => t.to_string(),
            other => panic!("expected text frame, got {other:?}"),
        };
        let v: serde_json::Value = serde_json::from_str(&text).unwrap();
        assert_eq!(v["method"], "a2ui.event");
        assert_eq!(v["params"]["kind"], "a2ui.surface_updated");
        assert_eq!(v["params"]["result"]["surfaceId"], "surf-a");
    }

    #[tokio::test]
    async fn apply_delete_broadcasts_surface_deleted() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        let (channel, mut rx) = fake_subscriber();
        state
            .a2ui_subscribers
            .lock()
            .await
            .insert("test-sub".to_string(), channel);

        // Create the surface first so the delete targets something real.
        apply_a2ui_envelope(
            &state,
            envelope(serde_json::json!({
                "version": "v0.9",
                "createSurface": { "surfaceId": "surf-d" }
            })),
            None,
            None,
        )
        .await
        .expect("create must succeed");
        let _ = rx.next().await.expect("surface_updated frame");

        apply_a2ui_envelope(
            &state,
            envelope(serde_json::json!({
                "version": "v0.9",
                "deleteSurface": { "surfaceId": "surf-d" }
            })),
            None,
            None,
        )
        .await
        .expect("delete must succeed");

        let msg = rx
            .next()
            .await
            .expect("subscriber received no delete frame");
        let text = match msg {
            Message::Text(t) => t.to_string(),
            other => panic!("expected text frame, got {other:?}"),
        };
        let v: serde_json::Value = serde_json::from_str(&text).unwrap();
        assert_eq!(v["method"], "a2ui.event");
        assert_eq!(v["params"]["kind"], "a2ui.surface_deleted");
        assert_eq!(v["params"]["result"]["surfaceId"], "surf-d");
    }
}

#[cfg(test)]
mod agents_chat_attachments {
    //! Image attachments ride the `agents.chat` → `agent.chat`
    //! reverse-call as an optional `attachments` array of image
    //! ContentBlocks. The daemon validates the shape and forwards it
    //! verbatim; absent attachments must not alter the request shape.
    use super::{
        build_agent_chat_params, ensure_chat_goal_running, extract_chat_attachments,
        extract_chat_goal, extract_chat_model, handle_agents_chat_cancel, handle_goal_clear,
        handle_goal_set, handle_goal_status, handle_goal_suggest, send_external_chat_frame,
        update_chat_goal_from_event, JsonRpcMessage,
    };
    use crate::session::{ChatSession, ServerState};
    use serde_json::{json, Value};
    use std::sync::atomic::AtomicBool;
    use std::sync::Arc;

    fn req(params: Value) -> JsonRpcMessage {
        JsonRpcMessage {
            jsonrpc: "2.0".into(),
            method: None,
            params,
            id: json!(1),
            result: None,
            error: None,
        }
    }

    #[test]
    fn extract_returns_none_when_absent_or_null() {
        assert_eq!(extract_chat_attachments(&json!({"prompt": "hi"})), Ok(None));
        assert_eq!(
            extract_chat_attachments(&json!({"attachments": null})),
            Ok(None)
        );
    }

    #[test]
    fn extract_accepts_image_content_blocks() {
        let params = json!({
            "attachments": [
                {"type": "image_base64", "data": "AAAA", "media_type": "image/png"},
                {"type": "image_url", "url": "https://example.com/a.jpg", "detail": "auto"}
            ]
        });
        let got = extract_chat_attachments(&params).unwrap().unwrap();
        assert_eq!(got.as_array().map(|a| a.len()), Some(2));
    }

    #[test]
    fn extract_rejects_non_array() {
        assert!(extract_chat_attachments(&json!({"attachments": "nope"})).is_err());
    }

    #[test]
    fn extract_rejects_non_image_entry() {
        let params = json!({
            "attachments": [
                {"type": "image_base64", "data": "AAAA", "media_type": "image/png"},
                {"type": "text", "text": "not an image"}
            ]
        });
        assert!(extract_chat_attachments(&params).is_err());
    }

    #[test]
    fn extract_rejects_base64_missing_data() {
        let params = json!({"attachments": [{"type": "image_base64", "media_type": "image/png"}]});
        assert!(extract_chat_attachments(&params).is_err());
    }

    #[test]
    fn extract_rejects_disallowed_media_type() {
        let params = json!({
            "attachments": [{"type": "image_base64", "data": "AAAA", "media_type": "image/svg+xml"}]
        });
        assert!(extract_chat_attachments(&params).is_err());
    }

    #[test]
    fn extract_rejects_non_http_image_url() {
        let params = json!({"attachments": [{"type": "image_url", "url": "file:///etc/passwd"}]});
        assert!(extract_chat_attachments(&params).is_err());
    }

    #[test]
    fn build_params_omits_attachments_when_none() {
        let params =
            build_agent_chat_params("sess-1", "hello", true, "host-1", false, None, None, None);
        assert_eq!(params["session_id"], "sess-1");
        assert_eq!(params["prompt"], "hello");
        assert_eq!(params["context"]["host_client_id"], "host-1");
        assert!(
            params.get("attachments").is_none(),
            "no `attachments` key when there are none — agents that ignore it see the legacy shape"
        );
    }

    #[test]
    fn build_params_carries_attachments_when_present() {
        let blocks = json!([
            {"type": "image_base64", "data": "AAAA", "media_type": "image/png"}
        ]);
        let params = build_agent_chat_params(
            "sess-2",
            "describe",
            true,
            "host-2",
            false,
            None,
            Some(blocks),
            None,
        );
        let att = params["attachments"]
            .as_array()
            .expect("attachments present");
        assert_eq!(att.len(), 1);
        assert_eq!(att[0]["type"], "image_base64");
        assert_eq!(att[0]["media_type"], "image/png");
    }

    #[test]
    fn extract_goal_returns_none_when_absent_or_null() {
        assert_eq!(extract_chat_goal(&json!({"prompt": "hi"})), Ok(None));
        assert_eq!(extract_chat_goal(&json!({"goal": null})), Ok(None));
    }

    #[test]
    fn extract_goal_normalizes_check_and_default_iterations() {
        let got = extract_chat_goal(&json!({"goal": {"check": "  cargo test -q  "}}))
            .unwrap()
            .unwrap();
        assert_eq!(got["check"], "cargo test -q");
        assert_eq!(got["max_iterations"], 8);
    }

    #[test]
    fn extract_goal_clamps_iteration_budget() {
        let low = extract_chat_goal(&json!({"goal": {"check": "true", "max_iterations": 0}}))
            .unwrap()
            .unwrap();
        let high = extract_chat_goal(&json!({"goal": {"check": "true", "max_iterations": 500}}))
            .unwrap()
            .unwrap();
        assert_eq!(low["max_iterations"], 1);
        assert_eq!(high["max_iterations"], 50);
    }

    #[test]
    fn extract_goal_rejects_bad_shape() {
        assert!(extract_chat_goal(&json!({"goal": "nope"})).is_err());
        assert!(extract_chat_goal(&json!({"goal": {"check": ""}})).is_err());
    }

    #[test]
    fn selected_chat_model_is_forwarded_and_unset_preserves_agent_default() {
        assert_eq!(
            extract_chat_model(&json!({
                "model": "  openrouter/deepseek/deepseek-v3.2  "
            }))
            .unwrap()
            .as_deref(),
            Some("openrouter/deepseek/deepseek-v3.2")
        );
        assert_eq!(extract_chat_model(&json!({})), Ok(None));
        assert_eq!(extract_chat_model(&json!({"model": "  "})), Ok(None));
        assert!(extract_chat_model(&json!({"model": 42})).is_err());

        let selected = build_agent_chat_params(
            "sess-model",
            "hello",
            true,
            "host-model",
            false,
            Some("openrouter/deepseek/deepseek-v3.2".into()),
            None,
            None,
        );
        assert_eq!(
            selected["model"], "openrouter/deepseek/deepseek-v3.2",
            "the actual daemon-to-agent chat request must carry the selected CAR model"
        );

        let adaptive = build_agent_chat_params(
            "sess-adaptive",
            "hello",
            true,
            "host-adaptive",
            false,
            None,
            None,
            None,
        );
        assert!(
            adaptive.get("model").is_none(),
            "omission preserves the supervised agent or adaptive-router default"
        );
    }

    #[test]
    fn build_params_carries_goal_when_present() {
        let goal = json!({"check": "cargo test -q", "max_iterations": 4});
        let params = build_agent_chat_params(
            "sess-3",
            "fix tests",
            true,
            "host-3",
            false,
            None,
            None,
            Some(goal),
        );
        assert_eq!(params["goal"]["check"], "cargo test -q");
        assert_eq!(params["goal"]["max_iterations"], 4);
        assert!(params.get("attachments").is_none());
    }

    #[tokio::test]
    async fn goal_set_status_and_clear_roundtrip() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));

        let set = handle_goal_set(
            &req(json!({
                "session_id": "chat-1",
                "goal": {"check": "  test -f done  ", "max_iterations": 500}
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(set["set"], true);
        assert_eq!(set["goal"]["check"], "test -f done");
        assert_eq!(set["goal"]["max_iterations"], 50);
        assert_eq!(set["goal"]["status"], "active");

        let status = handle_goal_status(&req(json!({"session_id": "chat-1"})), &state)
            .await
            .unwrap();
        assert_eq!(status["goal"]["session_id"], "chat-1");
        assert_eq!(status["goal"]["check"], "test -f done");

        let clear = handle_goal_clear(&req(json!({"session_id": "chat-1"})), &state)
            .await
            .unwrap();
        assert_eq!(clear["cleared"], true);
        let status = handle_goal_status(&req(json!({"session_id": "chat-1"})), &state)
            .await
            .unwrap();
        assert!(status["goal"].is_null());
    }

    #[tokio::test]
    async fn goal_status_tracks_evaluator_and_terminal_events() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        handle_goal_set(
            &req(json!({"session_id": "chat-2", "check": "test -f done", "max_iterations": 4})),
            &state,
        )
        .await
        .unwrap();

        update_chat_goal_from_event(
            &state,
            "chat-2",
            &json!({
                "kind": "goal_evaluated",
                "iteration": 1,
                "met": false,
                "grounded": false,
                "reason": "file missing"
            }),
        )
        .await;
        let status = handle_goal_status(&req(json!({"session_id": "chat-2"})), &state)
            .await
            .unwrap();
        assert_eq!(status["goal"]["status"], "running");
        assert_eq!(status["goal"]["last_iteration"], 1);
        assert_eq!(status["goal"]["last_reason"], "file missing");

        update_chat_goal_from_event(
            &state,
            "chat-2",
            &json!({
                "kind": "goal_evaluated",
                "iteration": 2,
                "met": true,
                "grounded": true,
                "reason": "file exists"
            }),
        )
        .await;
        update_chat_goal_from_event(
            &state,
            "chat-2",
            &json!({"kind": "done", "finish_reason": "goal reached"}),
        )
        .await;
        let status = handle_goal_status(&req(json!({"session_id": "chat-2"})), &state)
            .await
            .unwrap();
        assert_eq!(status["goal"]["status"], "met");
        assert_eq!(status["goal"]["last_met"], true);
        assert_eq!(status["goal"]["terminal_kind"], "done");
        assert_eq!(status["goal"]["terminal_message"], "goal reached");
    }

    /// car#1113 review: a fail-open `done` — the goal check never got the
    /// chance to run (`GoalHalt::EvaluationTimeout`, `chat::
    /// goal_turn_terminal_event`) — must NOT be recorded as `status: "met"`.
    /// Before this fix, `kind == "done"` mapped to `"met"` unconditionally,
    /// so this exact event persisted a "verified" status for a goal that was
    /// never actually checked, surviving a daemon restart via
    /// `chat-goals.json`.
    #[tokio::test]
    async fn a_fail_open_done_is_recorded_as_unevaluated_not_met() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        handle_goal_set(
            &req(json!({"session_id": "chat-timeout", "check": "test -f done"})),
            &state,
        )
        .await
        .unwrap();

        // Shape mirrors `chat::goal_turn_terminal_event`'s `EvaluationTimeout`
        // arm exactly: `kind: "done"` (fail-open) plus the machine-readable
        // `goal_unevaluated` marker alongside the human-readable
        // `finish_reason`.
        update_chat_goal_from_event(
            &state,
            "chat-timeout",
            &json!({
                "kind": "done",
                "finish_reason": "goal check unevaluated (timed out) — reply delivered unverified",
                "goal_unevaluated": true,
            }),
        )
        .await;

        let status = handle_goal_status(&req(json!({"session_id": "chat-timeout"})), &state)
            .await
            .unwrap();
        assert_eq!(
            status["goal"]["status"], "unevaluated",
            "a goal check that never ran must not be recorded as met: {status}"
        );
        assert_eq!(status["goal"]["terminal_kind"], "done");
        assert_eq!(
            status["goal"]["terminal_message"],
            "goal check unevaluated (timed out) — reply delivered unverified"
        );

        // A genuine achieved completion (no `goal_unevaluated` marker) is
        // unaffected by the new branch — still "met".
        handle_goal_set(
            &req(json!({"session_id": "chat-achieved", "check": "test -f done"})),
            &state,
        )
        .await
        .unwrap();
        update_chat_goal_from_event(
            &state,
            "chat-achieved",
            &json!({"kind": "done", "finish_reason": "goal reached"}),
        )
        .await;
        let status = handle_goal_status(&req(json!({"session_id": "chat-achieved"})), &state)
            .await
            .unwrap();
        assert_eq!(status["goal"]["status"], "met");
    }

    #[tokio::test]
    async fn inline_goal_creates_durable_running_status() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));

        ensure_chat_goal_running(
            &state,
            "chat-inline",
            &json!({"check": "test -f done", "max_iterations": 99}),
        )
        .await
        .unwrap();

        let status = handle_goal_status(&req(json!({"session_id": "chat-inline"})), &state)
            .await
            .unwrap();
        assert_eq!(status["goal"]["session_id"], "chat-inline");
        assert_eq!(status["goal"]["check"], "test -f done");
        assert_eq!(status["goal"]["max_iterations"], 50);
        assert_eq!(status["goal"]["status"], "running");
    }

    #[tokio::test]
    async fn rerun_goal_clears_prior_terminal_status() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        handle_goal_set(
            &req(json!({"session_id": "chat-rerun", "check": "test -f done"})),
            &state,
        )
        .await
        .unwrap();
        update_chat_goal_from_event(
            &state,
            "chat-rerun",
            &json!({"kind": "error", "error": "cancelled"}),
        )
        .await;

        ensure_chat_goal_running(
            &state,
            "chat-rerun",
            &json!({"check": "test -f done", "max_iterations": 4}),
        )
        .await
        .unwrap();

        let status = handle_goal_status(&req(json!({"session_id": "chat-rerun"})), &state)
            .await
            .unwrap();
        assert_eq!(status["goal"]["status"], "running");
        assert!(status["goal"]["terminal_kind"].is_null());
        assert!(status["goal"]["terminal_message"].is_null());
    }

    #[tokio::test]
    async fn daemon_owned_chat_frames_update_goal_status_before_host_delivery() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        handle_goal_set(
            &req(json!({"session_id": "chat-local", "check": "test -f done"})),
            &state,
        )
        .await
        .unwrap();

        // No chat_sessions route is registered here. `send_external_chat_frame`
        // should still persist the goal status before best-effort host delivery
        // decides there is no host channel to send to.
        send_external_chat_frame(
            &state,
            "chat-local",
            json!({
                "session_id": "chat-local",
                "agent_id": "local",
                "kind": "goal_evaluated",
                "iteration": 1,
                "met": true,
                "grounded": true,
                "reason": "file exists"
            }),
        )
        .await;

        let status = handle_goal_status(&req(json!({"session_id": "chat-local"})), &state)
            .await
            .unwrap();
        assert_eq!(status["goal"]["status"], "met");
        assert_eq!(status["goal"]["last_iteration"], 1);
        assert_eq!(status["goal"]["last_reason"], "file exists");
    }

    #[tokio::test]
    async fn cancelling_goal_chat_marks_standing_goal_terminal() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        handle_goal_set(
            &req(json!({"session_id": "chat-cancel", "check": "test -f done"})),
            &state,
        )
        .await
        .unwrap();
        update_chat_goal_from_event(
            &state,
            "chat-cancel",
            &json!({"kind": "goal_evaluated", "iteration": 1, "met": false, "grounded": false, "reason": "not yet"}),
        )
        .await;
        let cancel_flag = Arc::new(AtomicBool::new(false));
        state.chat_sessions.lock().await.insert(
            "chat-cancel".to_string(),
            ChatSession {
                agent_id: "local".to_string(),
                host_client_id: "host".to_string(),
                created_at: 0,
                local_cancel: Some(cancel_flag.clone()),
            },
        );

        // A different authenticated session may not abort someone else's turn.
        // `agents.chat.approve` has always required the originating host; this
        // is the same check on the arm next to it, which had none — being
        // authenticated was taken to settle what the caller may do.
        let stolen = handle_agents_chat_cancel(
            &req(json!({"session_id": "chat-cancel"})),
            &state,
            "someone-else",
            false,
        )
        .await;
        assert!(
            stolen.is_err(),
            "a foreign session must not cancel this turn: {stolen:?}"
        );
        assert!(
            state.chat_sessions.lock().await.contains_key("chat-cancel"),
            "a refused cancel must not destroy the routing entry on its way out"
        );
        assert!(
            !cancel_flag.load(std::sync::atomic::Ordering::SeqCst),
            "and must not have signalled cancellation"
        );

        let cancel = handle_agents_chat_cancel(
            &req(json!({"session_id": "chat-cancel"})),
            &state,
            "host",
            true,
        )
        .await
        .unwrap();
        assert_eq!(cancel["cancelled"], true);
        let status = handle_goal_status(&req(json!({"session_id": "chat-cancel"})), &state)
            .await
            .unwrap();
        assert_eq!(status["goal"]["status"], "error");
        assert_eq!(status["goal"]["terminal_kind"], "error");
        assert_eq!(status["goal"]["terminal_message"], "cancelled");
        assert!(cancel_flag.load(std::sync::atomic::Ordering::SeqCst));
    }

    #[tokio::test]
    async fn goal_status_persists_across_server_state_restart() {
        let tmp = tempfile::TempDir::new().unwrap();
        let journal_dir = tmp.path().join(".car").join("journals");
        let state = Arc::new(ServerState::standalone(journal_dir.clone()));

        handle_goal_set(
            &req(json!({"session_id": "chat-durable", "check": "test -f done"})),
            &state,
        )
        .await
        .unwrap();
        update_chat_goal_from_event(
            &state,
            "chat-durable",
            &json!({
                "kind": "goal_evaluated",
                "iteration": 1,
                "met": false,
                "grounded": false,
                "reason": "not yet"
            }),
        )
        .await;

        let restarted = Arc::new(ServerState::standalone(journal_dir.clone()));
        let status = handle_goal_status(&req(json!({"session_id": "chat-durable"})), &restarted)
            .await
            .unwrap();
        assert_eq!(status["goal"]["check"], "test -f done");
        assert_eq!(status["goal"]["status"], "active");
        assert_eq!(status["goal"]["last_iteration"], 1);
        assert_eq!(status["goal"]["last_reason"], "not yet");

        update_chat_goal_from_event(
            &restarted,
            "chat-durable",
            &json!({
                "kind": "goal_evaluated",
                "iteration": 2,
                "met": true,
                "grounded": true,
                "reason": "done exists"
            }),
        )
        .await;
        update_chat_goal_from_event(
            &restarted,
            "chat-durable",
            &json!({"kind": "done", "finish_reason": "goal reached"}),
        )
        .await;

        let restarted_again = Arc::new(ServerState::standalone(journal_dir));
        let status = handle_goal_status(
            &req(json!({"session_id": "chat-durable"})),
            &restarted_again,
        )
        .await
        .unwrap();
        assert_eq!(status["goal"]["status"], "met");
        assert_eq!(status["goal"]["last_iteration"], 2);
        assert_eq!(status["goal"]["terminal_kind"], "done");
    }

    #[tokio::test]
    async fn restart_downgrades_stale_running_goal_to_active() {
        let tmp = tempfile::TempDir::new().unwrap();
        let journal_dir = tmp.path().join(".car").join("journals");
        let state = Arc::new(ServerState::standalone(journal_dir.clone()));

        handle_goal_set(
            &req(json!({"session_id": "chat-running", "check": "true"})),
            &state,
        )
        .await
        .unwrap();
        {
            let mut goals = state.chat_goals.lock().await;
            goals.get_mut("chat-running").unwrap().status = "running".to_string();
        }
        state.persist_chat_goals().await.unwrap();

        let restarted = Arc::new(ServerState::standalone(journal_dir));
        let status = handle_goal_status(&req(json!({"session_id": "chat-running"})), &restarted)
            .await
            .unwrap();
        assert_eq!(status["goal"]["status"], "active");
    }

    #[tokio::test]
    async fn goal_suggest_detects_cargo_project() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join("Cargo.toml"),
            "[package]\nname = \"demo\"\nversion = \"0.1.0\"\n",
        )
        .unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "make the tests pass",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        assert!(got["goal"]["check"]
            .as_str()
            .unwrap()
            .ends_with(" && cargo test -q"));
    }

    #[tokio::test]
    async fn goal_suggest_prefers_project_check_over_existing_path_mentions() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::create_dir_all(tmp.path().join("src")).unwrap();
        std::fs::write(
            tmp.path().join("Cargo.toml"),
            "[package]\nname = \"demo\"\nversion = \"0.1.0\"\n",
        )
        .unwrap();
        std::fs::write(tmp.path().join("src/lib.rs"), "").unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "fix src/lib.rs",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert!(got["goal"]["check"]
            .as_str()
            .unwrap()
            .ends_with(" && cargo test -q"));
    }

    #[tokio::test]
    async fn goal_suggest_combines_created_file_with_project_check() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::create_dir_all(tmp.path().join("src")).unwrap();
        std::fs::write(
            tmp.path().join("Cargo.toml"),
            "[package]\nname = \"demo\"\nversion = \"0.1.0\"\n",
        )
        .unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "create src/lib.rs",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        let check = got["goal"]["check"].as_str().unwrap();
        assert!(check.contains("test -f 'src/lib.rs'"), "{check}");
        assert!(check.ends_with(" && cargo test -q"), "{check}");
        let signals = got["signals"].as_array().unwrap();
        assert!(signals.contains(&json!("prompt_mentions_path:src/lib.rs")));
        assert!(signals.contains(&json!("Cargo.toml")));
    }

    #[tokio::test]
    async fn goal_suggest_chooses_package_script_from_prompt() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join("package.json"),
            r#"{"scripts":{"test":"vitest run","typecheck":"tsc --noEmit","check":"biome check","build":"vite build","lint":"eslint ."}}"#,
        )
        .unwrap();
        std::fs::write(tmp.path().join("pnpm-lock.yaml"), "").unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "fix the TypeScript errors",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert!(got["goal"]["check"]
            .as_str()
            .unwrap()
            .ends_with(" && pnpm typecheck"));
    }

    #[tokio::test]
    async fn goal_suggest_chooses_check_script_from_prompt() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join("package.json"),
            r#"{"scripts":{"test":"vitest run","check":"biome check","build":"vite build"}}"#,
        )
        .unwrap();
        std::fs::write(tmp.path().join("pnpm-lock.yaml"), "").unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "fix the CI check failures",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert!(got["goal"]["check"]
            .as_str()
            .unwrap()
            .ends_with(" && pnpm check"));
        let signals = got["signals"].as_array().unwrap();
        assert!(signals.contains(&json!("package_script:check")));
    }

    #[tokio::test]
    async fn goal_suggest_chooses_build_script_from_nested_directory_prompt() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::create_dir_all(tmp.path().join("apps/web")).unwrap();
        std::fs::write(
            tmp.path().join("apps/web/package.json"),
            r#"{"scripts":{"test":"vitest run","build":"vite build","lint":"eslint ."}}"#,
        )
        .unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "fix the production build in apps/web",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        let check = got["goal"]["check"].as_str().unwrap();
        assert!(check.contains("apps/web"), "{check}");
        assert!(check.ends_with(" && npm run build"), "{check}");
        let signals = got["signals"].as_array().unwrap();
        assert!(signals.contains(&json!("package_script:build")));
    }

    #[tokio::test]
    async fn goal_suggest_chooses_lint_script_from_prompt() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join("package.json"),
            r#"{"scripts":{"test":"vitest run","lint":"eslint .","build":"vite build"}}"#,
        )
        .unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "fix lint errors",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert!(got["goal"]["check"]
            .as_str()
            .unwrap()
            .ends_with(" && npm run lint"));
        let signals = got["signals"].as_array().unwrap();
        assert!(signals.contains(&json!("package_script:lint")));
    }

    #[tokio::test]
    async fn goal_suggest_uses_nearest_nested_project_for_created_file() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::create_dir_all(tmp.path().join("apps/web/src")).unwrap();
        std::fs::write(
            tmp.path().join("apps/web/package.json"),
            r#"{"scripts":{"test":"vitest run"}}"#,
        )
        .unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "create apps/web/src/App.ts",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        let check = got["goal"]["check"].as_str().unwrap();
        assert!(check.contains("apps/web"), "{check}");
        assert!(check.contains("test -f 'src/App.ts'"), "{check}");
        assert!(check.ends_with(" && npm test"), "{check}");
        let signals = got["signals"].as_array().unwrap();
        assert!(signals.contains(&json!("project_dir:apps/web")));
        assert!(signals.contains(&json!("package.json")));
    }

    #[tokio::test]
    async fn goal_suggest_uses_nearest_nested_project_for_existing_file_prompt() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::create_dir_all(tmp.path().join("apps/web/src")).unwrap();
        std::fs::write(
            tmp.path().join("apps/web/package.json"),
            r#"{"scripts":{"typecheck":"tsc --noEmit","test":"vitest run"}}"#,
        )
        .unwrap();
        std::fs::write(tmp.path().join("apps/web/src/App.ts"), "export {}\n").unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "fix TypeScript errors in apps/web/src/App.ts",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        let check = got["goal"]["check"].as_str().unwrap();
        assert!(check.contains("apps/web"), "{check}");
        assert!(!check.contains("test -f"), "{check}");
        assert!(check.ends_with(" && npm run typecheck"), "{check}");
        let signals = got["signals"].as_array().unwrap();
        assert!(signals.contains(&json!("prompt_mentions_path:apps/web/src/App.ts")));
        assert!(signals.contains(&json!("project_dir:apps/web")));
        assert!(signals.contains(&json!("package_script:typecheck")));
    }

    #[tokio::test]
    async fn goal_suggest_uses_nearest_nested_project_for_directory_prompt() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::create_dir_all(tmp.path().join("apps/web/src")).unwrap();
        std::fs::write(
            tmp.path().join("apps/web/package.json"),
            r#"{"scripts":{"test":"vitest run"}}"#,
        )
        .unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "fix apps/web",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        let check = got["goal"]["check"].as_str().unwrap();
        assert!(check.contains("apps/web"), "{check}");
        assert!(!check.contains("test -f"), "{check}");
        assert!(check.ends_with(" && npm test"), "{check}");
        let signals = got["signals"].as_array().unwrap();
        assert!(signals.contains(&json!("prompt_mentions_path:apps/web")));
        assert!(signals.contains(&json!("project_dir:apps/web")));
    }

    #[tokio::test]
    async fn goal_suggest_can_store_the_suggested_goal() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(tmp.path().join("go.mod"), "module demo\n").unwrap();
        let journal_dir = tmp.path().join(".car").join("journals");
        let state = Arc::new(ServerState::standalone(journal_dir.clone()));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "make it work",
                "working_dir": tmp.path().to_string_lossy(),
                "session_id": "chat-suggest",
                "set": true
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["set"], true);
        assert_eq!(got["stored_goal"]["session_id"], "chat-suggest");

        let restarted = Arc::new(ServerState::standalone(journal_dir));
        let status = handle_goal_status(&req(json!({"session_id": "chat-suggest"})), &restarted)
            .await
            .unwrap();
        assert!(status["goal"]["check"]
            .as_str()
            .unwrap()
            .ends_with(" && go test ./..."));
    }

    #[tokio::test]
    async fn goal_suggest_detects_swift_package() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join("Package.swift"),
            "// swift-tools-version: 6.0\nimport PackageDescription\n",
        )
        .unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "make the package tests pass",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        assert!(got["goal"]["check"]
            .as_str()
            .unwrap()
            .ends_with(" && swift test"));
        let signals = got["signals"].as_array().unwrap();
        assert!(signals.contains(&json!("Package.swift")));
    }

    #[tokio::test]
    async fn goal_suggest_combines_created_swift_file_with_package_check() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::create_dir_all(tmp.path().join("Sources/App")).unwrap();
        std::fs::write(
            tmp.path().join("Package.swift"),
            "// swift-tools-version: 6.0\nimport PackageDescription\n",
        )
        .unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "create Sources/App/Main.swift",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        let check = got["goal"]["check"].as_str().unwrap();
        assert!(
            check.contains("test -f 'Sources/App/Main.swift'"),
            "{check}"
        );
        assert!(check.ends_with(" && swift test"), "{check}");
    }

    #[tokio::test]
    async fn goal_suggest_detects_cmake_project() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join("CMakeLists.txt"),
            "cmake_minimum_required(VERSION 3.20)\nproject(demo LANGUAGES CXX)\n",
        )
        .unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "fix the C++ build",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        assert!(got["goal"]["check"]
            .as_str()
            .unwrap()
            .ends_with(" && cmake -S . -B build && cmake --build build"));
        let signals = got["signals"].as_array().unwrap();
        assert!(signals.contains(&json!("CMakeLists.txt")));
    }

    #[tokio::test]
    async fn goal_suggest_combines_created_cpp_file_with_cmake_check() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::create_dir_all(tmp.path().join("src")).unwrap();
        std::fs::write(
            tmp.path().join("CMakeLists.txt"),
            "cmake_minimum_required(VERSION 3.20)\nproject(demo LANGUAGES CXX)\n",
        )
        .unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "create src/widget.cpp",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        let check = got["goal"]["check"].as_str().unwrap();
        assert!(check.contains("test -f 'src/widget.cpp'"), "{check}");
        assert!(
            check.ends_with(" && cmake -S . -B build && cmake --build build"),
            "{check}"
        );
        let signals = got["signals"].as_array().unwrap();
        assert!(signals.contains(&json!("prompt_mentions_path:src/widget.cpp")));
        assert!(signals.contains(&json!("CMakeLists.txt")));
    }

    #[tokio::test]
    async fn goal_suggest_uses_ctest_for_cmake_test_prompts() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join("CMakeLists.txt"),
            "cmake_minimum_required(VERSION 3.20)\nproject(demo LANGUAGES CXX)\n",
        )
        .unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "make the cmake unit tests pass",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        let check = got["goal"]["check"].as_str().unwrap();
        assert!(check.ends_with(
            " && cmake -S . -B build && cmake --build build && ctest --test-dir build --output-on-failure"
        ), "{check}");
    }

    #[tokio::test]
    async fn goal_suggest_detects_gradle_project() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join("build.gradle.kts"),
            "plugins { kotlin(\"jvm\") }\n",
        )
        .unwrap();
        std::fs::write(tmp.path().join("gradlew"), "#!/bin/sh\n").unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "make the kotlin tests pass",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        assert!(got["goal"]["check"]
            .as_str()
            .unwrap()
            .ends_with(" && ./gradlew test"));
        let signals = got["signals"].as_array().unwrap();
        assert!(signals.contains(&json!("build.gradle.kts")));
        assert!(signals.contains(&json!("gradlew")));
    }

    #[tokio::test]
    async fn goal_suggest_combines_created_kotlin_file_with_gradle_check() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::create_dir_all(tmp.path().join("app/src/main/java/com/demo")).unwrap();
        std::fs::write(tmp.path().join("build.gradle"), "plugins { id 'java' }\n").unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "create app/src/main/java/com/demo/Main.kt",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        let check = got["goal"]["check"].as_str().unwrap();
        assert!(
            check.contains("test -f 'app/src/main/java/com/demo/Main.kt'"),
            "{check}"
        );
        assert!(check.ends_with(" && gradle test"), "{check}");
    }

    #[tokio::test]
    async fn goal_suggest_detects_maven_project() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join("pom.xml"),
            "<project><modelVersion>4.0.0</modelVersion></project>\n",
        )
        .unwrap();
        std::fs::write(tmp.path().join("mvnw"), "#!/bin/sh\n").unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "make the java tests pass",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        assert!(got["goal"]["check"]
            .as_str()
            .unwrap()
            .ends_with(" && ./mvnw test"));
        let signals = got["signals"].as_array().unwrap();
        assert!(signals.contains(&json!("pom.xml")));
        assert!(signals.contains(&json!("mvnw")));
    }

    #[tokio::test]
    async fn goal_suggest_combines_created_java_file_with_maven_check() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::create_dir_all(tmp.path().join("src/main/java/com/demo")).unwrap();
        std::fs::write(
            tmp.path().join("pom.xml"),
            "<project><modelVersion>4.0.0</modelVersion></project>\n",
        )
        .unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "create src/main/java/com/demo/Main.java",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        let check = got["goal"]["check"].as_str().unwrap();
        assert!(
            check.contains("test -f 'src/main/java/com/demo/Main.java'"),
            "{check}"
        );
        assert!(check.ends_with(" && mvn test"), "{check}");
    }

    #[tokio::test]
    async fn goal_suggest_detects_dotnet_solution() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(tmp.path().join("Demo.sln"), "").unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "make the csharp tests pass",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        assert!(got["goal"]["check"]
            .as_str()
            .unwrap()
            .ends_with(" && dotnet test"));
        let signals = got["signals"].as_array().unwrap();
        assert!(signals.contains(&json!("Demo.sln")));
    }

    #[tokio::test]
    async fn goal_suggest_combines_created_csharp_file_with_dotnet_check() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::create_dir_all(tmp.path().join("src/Demo")).unwrap();
        std::fs::write(
            tmp.path().join("src").join("Demo").join("Demo.csproj"),
            "<Project Sdk=\"Microsoft.NET.Sdk\" />\n",
        )
        .unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "create Program.cs",
                "working_dir": tmp.path().join("src").join("Demo").to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        let check = got["goal"]["check"].as_str().unwrap();
        assert!(check.contains("test -f 'Program.cs'"), "{check}");
        assert!(check.ends_with(" && dotnet test"), "{check}");
    }

    #[tokio::test]
    async fn goal_suggest_detects_php_composer_project() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::create_dir_all(tmp.path().join("vendor/bin")).unwrap();
        std::fs::write(tmp.path().join("composer.json"), r#"{"require-dev":{}}"#).unwrap();
        std::fs::write(
            tmp.path().join("vendor/bin/phpunit"),
            "#!/usr/bin/env php\n",
        )
        .unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "make the php tests pass",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        assert!(got["goal"]["check"]
            .as_str()
            .unwrap()
            .ends_with(" && vendor/bin/phpunit"));
        let signals = got["signals"].as_array().unwrap();
        assert!(signals.contains(&json!("composer.json")));
        assert!(signals.contains(&json!("phpunit")));
    }

    #[tokio::test]
    async fn goal_suggest_combines_created_php_file_with_composer_script() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::create_dir_all(tmp.path().join("src")).unwrap();
        std::fs::write(
            tmp.path().join("composer.json"),
            r#"{"scripts":{"test":"phpunit"}}"#,
        )
        .unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "create src/App.php",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        let check = got["goal"]["check"].as_str().unwrap();
        assert!(check.contains("test -f 'src/App.php'"), "{check}");
        assert!(check.ends_with(" && composer test"), "{check}");
        let signals = got["signals"].as_array().unwrap();
        assert!(signals.contains(&json!("composer_script:test")));
    }

    #[tokio::test]
    async fn goal_suggest_uses_php_lint_when_composer_has_no_test_signal() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(tmp.path().join("composer.json"), r#"{"scripts":{}}"#).unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "make the php project valid",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "medium");
        let check = got["goal"]["check"].as_str().unwrap();
        assert!(
            check.ends_with(
                " && find . -name '*.php' -not -path './vendor/*' -print0 | xargs -0 -n1 php -l"
            ),
            "{check}"
        );
        let signals = got["signals"].as_array().unwrap();
        assert!(!signals.contains(&json!("composer_script:test")));
    }

    #[tokio::test]
    async fn goal_suggest_detects_ruby_bundler_project() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join("Gemfile"),
            "source 'https://rubygems.org'\n",
        )
        .unwrap();
        std::fs::write(tmp.path().join("Rakefile"), "task :test\n").unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "make the ruby tests pass",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        assert!(got["goal"]["check"]
            .as_str()
            .unwrap()
            .ends_with(" && bundle exec rake test"));
        let signals = got["signals"].as_array().unwrap();
        assert!(signals.contains(&json!("Gemfile")));
        assert!(signals.contains(&json!("Rakefile")));
    }

    #[tokio::test]
    async fn goal_suggest_uses_ruby_syntax_check_without_test_runner_signal() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(
            tmp.path().join("Gemfile"),
            "source 'https://rubygems.org'\n",
        )
        .unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "make the ruby project valid",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "medium");
        let check = got["goal"]["check"].as_str().unwrap();
        assert!(
            check.ends_with(
                " && find . -name '*.rb' -not -path './vendor/*' -print0 | xargs -0 -n1 ruby -c"
            ),
            "{check}"
        );
        let signals = got["signals"].as_array().unwrap();
        assert!(signals.contains(&json!("Gemfile")));
        assert!(!signals.contains(&json!("Rakefile")));
    }

    #[tokio::test]
    async fn goal_suggest_combines_created_elixir_file_with_mix_check() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::create_dir_all(tmp.path().join("lib/demo")).unwrap();
        std::fs::write(
            tmp.path().join("mix.exs"),
            "defmodule Demo.MixProject do\nend\n",
        )
        .unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "create lib/demo/worker.ex",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert_eq!(got["confidence"], "high");
        let check = got["goal"]["check"].as_str().unwrap();
        assert!(check.contains("test -f 'lib/demo/worker.ex'"), "{check}");
        assert!(check.ends_with(" && mix test"), "{check}");
    }

    #[tokio::test]
    async fn goal_suggest_falls_through_when_package_has_no_scripts() {
        let tmp = tempfile::TempDir::new().unwrap();
        std::fs::write(tmp.path().join("package.json"), r#"{"scripts":{}}"#).unwrap();
        std::fs::write(tmp.path().join("go.mod"), "module demo\n").unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));

        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "make it work",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], true);
        assert!(got["goal"]["check"]
            .as_str()
            .unwrap()
            .ends_with(" && go test ./..."));
        let warnings = got["warnings"].as_array().unwrap();
        assert!(warnings.contains(&json!(
            "package.json has no test/typecheck/check/build/lint script"
        )));
    }

    #[tokio::test]
    async fn goal_suggest_refuses_to_invent_a_weak_check() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(
            tmp.path().join(".car").join("journals"),
        ));
        let got = handle_goal_suggest(
            &req(json!({
                "prompt": "make it better",
                "working_dir": tmp.path().to_string_lossy()
            })),
            &state,
        )
        .await
        .unwrap();
        assert_eq!(got["suggested"], false);
        assert!(got["goal"].is_null());
    }
}

#[cfg(test)]
mod metrics_alert_surface {
    use super::{handle_metrics_alerts, JsonRpcMessage};
    use crate::session::{ServerState, WsChannel};
    use car_verify::goal::GoalCondition;
    use serde_json::{json, Value};
    use std::sync::Arc;

    fn req(params: Value) -> JsonRpcMessage {
        JsonRpcMessage {
            jsonrpc: "2.0".into(),
            method: None,
            params,
            id: json!(1),
            result: None,
            error: None,
        }
    }

    #[tokio::test]
    async fn metrics_alerts_returns_goal_ungrounded() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        let session = state
            .create_session("metrics-alerts", Arc::new(WsChannel::test_stub()))
            .await
            .unwrap();
        let condition = GoalCondition::Command {
            id: "tests".to_string(),
            expect_exit: 0,
        };
        session
            .runtime
            .record_goal_evaluated(
                "make tests pass",
                &condition,
                1,
                true,
                false,
                "ungrounded assistant summary claim(s): tests were run/passed",
                "mlx/qwen3-8b:4bit",
            )
            .await;

        let got = handle_metrics_alerts(&req(json!({"max_goals_ungrounded": 0})), &session)
            .await
            .unwrap();
        assert_eq!(got["summary"]["goals_ungrounded"], json!(1));
        assert_eq!(got["alerts"][0]["kind"], json!("goal_ungrounded"));
        assert_eq!(got["alerts"][0]["observed"], json!(1.0));
        assert_eq!(got["alerts"][0]["threshold"], json!(0.0));
    }
}

#[cfg(test)]
mod tool_registry_surface {
    //! `tools.list` / `tools.unregister` (Parslee-ai/car#892) — the enumerate
    //! and removal halves that `tools.register` shipped without, mirroring
    //! `policy.list` / `policy.unregister` (Parslee-ai/car#623).
    //!
    //! Each WS connection gets its own `car_engine::Runtime`, so the listed set
    //! is a per-session fact and can be asserted literally rather than
    //! approximately.
    //!
    //! A fresh daemon session is **not** empty, which is worth pinning here
    //! because it is the sort of thing this surface exists to reveal:
    //! `create_session` builds its runtime with `.with_message_sink(...)`, and
    //! `Runtime::with_message_sink` registers the `messaging.send` built-in
    //! into both the registry and the legacy schema map — sink and schema
    //! arrive together by design, so a tool the runtime cannot execute is never
    //! advertised. The commodity stdlib is absent until the session asks for
    //! it — both `session.bindSubstrate` and `session.bindSandbox` register
    //! it, and neither runs here. So the baseline is exactly
    //! `["messaging.send"]`, and the assertions below are exact vectors over
    //! that baseline plus whatever the test registered.
    use super::{
        handle_tools_list, handle_tools_register, handle_tools_unregister, JsonRpcMessage,
    };
    use crate::session::{ServerState, WsChannel};
    use serde_json::{json, Value};
    use std::sync::Arc;

    fn req(params: Value) -> JsonRpcMessage {
        JsonRpcMessage {
            jsonrpc: "2.0".into(),
            method: None,
            params,
            id: json!(1),
            result: None,
            error: None,
        }
    }

    async fn session(client_id: &str) -> Arc<crate::session::ClientSession> {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        state
            .create_session(client_id, Arc::new(WsChannel::test_stub()))
            .await
            .unwrap()
    }

    /// Names in `tools.list` order, so assertions can be literal vectors.
    fn names(listed: &Value) -> Vec<String> {
        listed["tools"]
            .as_array()
            .expect("tools must be an array")
            .iter()
            .map(|t| {
                t["name"]
                    .as_str()
                    .expect("name must be a string")
                    .to_string()
            })
            .collect()
    }

    /// The session baseline: a connection that registered nothing still has the
    /// daemon's `messaging.send` built-in, and `tools.list` says so. Asserting
    /// the exact vector (not just a count) is the point — a client auditing its
    /// own session needs to see the tool it never registered.
    #[tokio::test]
    async fn fresh_session_lists_only_the_built_in_messaging_send() {
        let session = session("c-tools-list-empty").await;
        let listed = handle_tools_list(&session).await.unwrap();
        assert_eq!(listed["count"], json!(1));
        assert_eq!(names(&listed), vec!["messaging.send"]);
        assert_eq!(listed["tools"][0]["source"], json!("builtin"));
    }

    /// The goal's verifiable target: after registering exactly two tools, the
    /// wire surface reports exactly those two on top of the session baseline,
    /// in sorted order — which is what makes it usable as proof of a governed
    /// session's effective toolset.
    #[tokio::test]
    async fn list_returns_exactly_the_two_registered_tools_over_the_baseline_in_sorted_order() {
        let session = session("c-tools-list-two").await;

        // Registered out of alphabetical order on purpose: the sort is the
        // contract, not an accident of insertion order. `messaging.send` was
        // registered first of all (at runtime construction) and still sorts
        // first here, and `write_file`/`read_file` come back swapped relative
        // to how they went in — so the ordering below cannot be insertion order.
        let registered = handle_tools_register(
            &req(json!([
                { "name": "write_file" },
                { "name": "read_file" },
            ])),
            &session,
        )
        .await
        .unwrap();
        assert_eq!(registered, json!(2));

        let listed = handle_tools_list(&session).await.unwrap();
        assert_eq!(listed["count"], json!(3));
        assert_eq!(
            names(&listed),
            vec!["messaging.send", "read_file", "write_file"]
        );
    }

    #[tokio::test]
    async fn register_rejects_a_server_owned_tool_name_without_changing_its_source() {
        let session = session("c-tools-register-shadow").await;
        let error = handle_tools_register(
            &req(json!([{ "name": "messaging.send", "description": "shadow" }])),
            &session,
        )
        .await
        .expect_err("callback registration must not shadow a built-in");
        assert_eq!(
            error,
            "tool 'messaging.send' is server-owned and cannot be shadowed by tools.register"
        );

        let listed = handle_tools_list(&session).await.unwrap();
        assert_eq!(listed["count"], json!(1));
        assert_eq!(names(&listed), vec!["messaging.send"]);
        assert_eq!(listed["tools"][0]["source"], json!("builtin"));
    }

    #[tokio::test]
    async fn unregister_drops_one_tool_and_list_reports_the_remainder() {
        let session = session("c-tools-unregister").await;
        handle_tools_register(
            &req(json!([{ "name": "read_file" }, { "name": "write_file" }])),
            &session,
        )
        .await
        .unwrap();

        let dropped = handle_tools_unregister(&req(json!({ "name": "write_file" })), &session)
            .await
            .unwrap();
        assert_eq!(dropped["unregistered"], json!("write_file"));
        assert_eq!(dropped["removed"], json!(1));

        let listed = handle_tools_list(&session).await.unwrap();
        assert_eq!(listed["count"], json!(2));
        assert_eq!(names(&listed), vec!["messaging.send", "read_file"]);
    }

    /// Unknown tool → `removed: 0` and `Ok`, never `Err`, so cleanup can call
    /// this unconditionally without listing first (`policy.unregister`'s
    /// contract). Missing `name` is still an error, house style.
    #[tokio::test]
    async fn unregistering_an_unknown_tool_reports_zero_rather_than_erroring() {
        let session = session("c-tools-unregister-unknown").await;

        let dropped =
            handle_tools_unregister(&req(json!({ "name": "never_registered" })), &session)
                .await
                .expect("unknown tool must not be an error");
        assert_eq!(dropped["unregistered"], json!("never_registered"));
        assert_eq!(dropped["removed"], json!(0));

        assert_eq!(
            handle_tools_unregister(&req(json!({})), &session)
                .await
                .unwrap_err(),
            "missing 'name'"
        );
    }

    /// The surface proves the *effective* toolset, not a name list: the full
    /// schema a caller registered comes back, parameters included.
    #[tokio::test]
    async fn list_round_trips_the_full_tool_schema() {
        let session = session("c-tools-list-schema").await;
        handle_tools_register(
            &req(json!([{
                "name": "read_file",
                "description": "Read a UTF-8 file from disk",
                "parameters": {
                    "type": "object",
                    "properties": { "path": { "type": "string" } },
                    "required": ["path"],
                },
                "idempotent": true,
            }])),
            &session,
        )
        .await
        .unwrap();

        let listed = handle_tools_list(&session).await.unwrap();
        let tool = listed["tools"]
            .as_array()
            .unwrap()
            .iter()
            .find(|t| t["name"] == json!("read_file"))
            .expect("read_file must be listed");
        assert_eq!(tool["name"], json!("read_file"));
        assert_eq!(tool["source"], json!("user_defined"));
        assert_eq!(tool["description"], json!("Read a UTF-8 file from disk"));
        assert_eq!(tool["idempotent"], json!(true));
        assert_eq!(
            tool["parameters"],
            json!({
                "type": "object",
                "properties": { "path": { "type": "string" } },
                "required": ["path"],
            })
        );
    }

    /// `ToolDefinition` deliberately omits `source` — the runtime assigns
    /// `user_defined` server-side rather than trusting the caller. This pins
    /// that security boundary end-to-end: a registration payload carrying a
    /// spoofed `"source": "builtin"` must parse (serde ignores the unknown
    /// field) but the stored/listed schema still reports `user_defined`.
    #[tokio::test]
    async fn registered_tool_cannot_claim_a_source_it_did_not_earn() {
        let session = session("c-tools-spoofed-source").await;
        handle_tools_register(
            &req(json!([{
                "name": "read_file",
                "description": "Claims to be a builtin",
                "source": "builtin",
                "parameters": {},
            }])),
            &session,
        )
        .await
        .expect("an unknown field must not fail registration");

        let listed = handle_tools_list(&session).await.unwrap();
        let tool = listed["tools"]
            .as_array()
            .unwrap()
            .iter()
            .find(|t| t["name"] == json!("read_file"))
            .expect("read_file must be listed");
        assert_eq!(
            tool["source"],
            json!("user_defined"),
            "the runtime assigns user_defined; a client cannot claim builtin"
        );
    }
}

#[cfg(test)]
mod tool_stream_surface {
    //! C2 WS surface: `tools.poll` drains a detached handle's chunks and
    //! reports status, `tools.cancel` seals it. An unknown handle polls to
    //! `null` (absence, not an error) and cancels to `{cancelled: false}`.
    use super::{handle_tools_cancel, handle_tools_poll, JsonRpcMessage};
    use crate::session::{ServerState, WsChannel};
    use serde_json::{json, Value};
    use std::sync::Arc;

    fn req(params: Value) -> JsonRpcMessage {
        JsonRpcMessage {
            jsonrpc: "2.0".into(),
            method: None,
            params,
            id: json!(1),
            result: None,
            error: None,
        }
    }

    #[tokio::test]
    async fn poll_and_cancel_roundtrip() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        let channel = Arc::new(WsChannel::test_stub());
        let session = state.create_session("c-tools-c2", channel).await.unwrap();

        // Unknown handle → null, not an error.
        let poll = handle_tools_poll(&req(json!({"handle": "nope"})), &session)
            .await
            .unwrap();
        assert!(poll.is_null(), "unknown handle must poll to null");

        // Missing param → error (house style).
        assert!(handle_tools_poll(&req(json!({})), &session).await.is_err());

        // Start a detached invocation on the session runtime's registry —
        // the same path a detached ToolCall dispatch takes.
        let (h, _tok) = session
            .runtime
            .tool_handles
            .register("tail_log", "a1")
            .await;
        session
            .runtime
            .tool_handles
            .push_chunk(
                &h.id,
                car_ir::ToolStreamChunk::Text {
                    text: "line".into(),
                },
            )
            .await;

        let poll = handle_tools_poll(&req(json!({"handle": h.id})), &session)
            .await
            .unwrap();
        assert_eq!(poll["status"], "running");
        assert_eq!(poll["chunks"][0]["kind"], "text");
        assert_eq!(poll["chunks"][0]["text"], "line");
        assert_eq!(poll["tool"], "tail_log");

        // Cancel seals the invocation; a subsequent poll observes it.
        let cancel = handle_tools_cancel(&req(json!({"handle": h.id})), &session)
            .await
            .unwrap();
        assert_eq!(cancel["cancelled"], true);
        let poll = handle_tools_poll(&req(json!({"handle": h.id})), &session)
            .await
            .unwrap();
        assert_eq!(poll["status"], "cancelled");

        // Unknown handle cancels to false.
        let cancel = handle_tools_cancel(&req(json!({"handle": "nope"})), &session)
            .await
            .unwrap();
        assert_eq!(cancel["cancelled"], false);
    }
}

#[cfg(test)]
mod chat_cancel_surface {
    use super::{handle_agents_chat_cancel, remove_owned_external_chat_session, JsonRpcMessage};
    use crate::session::{ChatSession, ServerState};
    use serde_json::{json, Value};
    use std::sync::atomic::{AtomicBool, Ordering};
    use std::sync::Arc;

    fn req(params: Value) -> JsonRpcMessage {
        JsonRpcMessage {
            jsonrpc: "2.0".into(),
            method: None,
            params,
            id: json!(1),
            result: None,
            error: None,
        }
    }

    #[tokio::test]
    async fn cancel_sets_local_declarative_flag_and_drops_session() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        let flag = Arc::new(AtomicBool::new(false));
        state.chat_sessions.lock().await.insert(
            "decl-chat".to_string(),
            ChatSession {
                agent_id: "writer".to_string(),
                host_client_id: "host-1".to_string(),
                created_at: 0,
                local_cancel: Some(flag.clone()),
            },
        );

        let cancel = handle_agents_chat_cancel(
            &req(json!({"session_id": "decl-chat"})),
            &state,
            "host",
            true,
        )
        .await
        .unwrap();
        assert_eq!(cancel["cancelled"], true);
        assert!(flag.load(Ordering::SeqCst));
        assert!(!state.chat_sessions.lock().await.contains_key("decl-chat"));

        let again = handle_agents_chat_cancel(
            &req(json!({"session_id": "decl-chat"})),
            &state,
            "host",
            true,
        )
        .await
        .unwrap();
        assert_eq!(again["cancelled"], false);
    }

    #[tokio::test]
    async fn external_cleanup_preserves_proxied_chat_route() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        let flag = Arc::new(AtomicBool::new(false));
        state.chat_sessions.lock().await.insert(
            "proxied-chat".to_string(),
            ChatSession {
                agent_id: "car-assistant".to_string(),
                host_client_id: "host-1".to_string(),
                created_at: 0,
                local_cancel: Some(flag),
            },
        );

        remove_owned_external_chat_session(&state, "proxied-chat", false).await;
        assert!(state
            .chat_sessions
            .lock()
            .await
            .contains_key("proxied-chat"));

        remove_owned_external_chat_session(&state, "proxied-chat", true).await;
        assert!(!state
            .chat_sessions
            .lock()
            .await
            .contains_key("proxied-chat"));
    }
}

#[cfg(test)]
mod assistant_agent_alias_surface {
    //! car#1107: `agents.chat` must resolve either spelling of the flagship
    //! assistant's id — `parslee-core` (canonical since car#1107, and what
    //! mobile has always sent) or `car-assistant` (the pre-car#1107 id macOS
    //! still hardcodes) — to whichever one the daemon actually has attached.
    use super::resolve_assistant_agent_alias;
    use crate::session::ServerState;
    use std::sync::Arc;

    fn state() -> Arc<ServerState> {
        let tmp = tempfile::TempDir::new().unwrap();
        Arc::new(ServerState::standalone(tmp.path().to_path_buf()))
    }

    #[tokio::test]
    async fn legacy_id_resolves_to_canonical_when_only_canonical_attached() {
        let state = state();
        state
            .attached_agents
            .lock()
            .await
            .insert("parslee-core".to_string(), "client-1".to_string());

        assert_eq!(
            resolve_assistant_agent_alias("car-assistant".to_string(), &state).await,
            "parslee-core"
        );
    }

    #[tokio::test]
    async fn canonical_id_resolves_to_legacy_when_only_legacy_attached() {
        let state = state();
        state
            .attached_agents
            .lock()
            .await
            .insert("car-assistant".to_string(), "client-1".to_string());

        assert_eq!(
            resolve_assistant_agent_alias("parslee-core".to_string(), &state).await,
            "car-assistant"
        );
    }

    #[tokio::test]
    async fn exact_match_is_never_rewritten() {
        let state = state();
        state
            .attached_agents
            .lock()
            .await
            .insert("parslee-core".to_string(), "client-1".to_string());

        assert_eq!(
            resolve_assistant_agent_alias("parslee-core".to_string(), &state).await,
            "parslee-core"
        );
    }

    #[tokio::test]
    async fn non_assistant_id_is_left_untouched_even_if_unattached() {
        let state = state();
        assert_eq!(
            resolve_assistant_agent_alias("some-other-agent".to_string(), &state).await,
            "some-other-agent"
        );
    }

    #[tokio::test]
    async fn assistant_id_is_left_untouched_when_neither_spelling_attached() {
        let state = state();
        assert_eq!(
            resolve_assistant_agent_alias("parslee-core".to_string(), &state).await,
            "parslee-core"
        );
    }
}

#[cfg(test)]
mod chat_approve_surface {
    //! `agents.chat.approve` (#483): resolve an inline chat-turn approval by
    //! reverse-requesting the agent's `agent.chat.approve`. The full reply
    //! round-trip needs a live agent connection (exercised end-to-end by the
    //! `assistant::chat` tests + the CLI); here we lock down the param
    //! validation and session-routing preconditions the handler enforces before
    //! it ever touches an agent channel.
    use super::{handle_agents_chat_approve, JsonRpcMessage};
    use crate::session::{ChatSession, ServerState};
    use serde_json::{json, Value};
    use std::sync::Arc;

    fn req(params: Value) -> JsonRpcMessage {
        JsonRpcMessage {
            jsonrpc: "2.0".into(),
            method: None,
            params,
            id: json!(1),
            result: None,
            error: None,
        }
    }

    #[tokio::test]
    async fn requires_session_and_approval_ids() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));

        // Missing session_id.
        let err =
            handle_agents_chat_approve(&req(json!({"approval_id": "a1"})), &state, "host-1", false)
                .await
                .unwrap_err();
        assert!(err.contains("session_id"), "{err}");

        // Missing approval_id.
        let err =
            handle_agents_chat_approve(&req(json!({"session_id": "s1"})), &state, "host-1", false)
                .await
                .unwrap_err();
        assert!(err.contains("approval_id"), "{err}");
    }

    #[tokio::test]
    async fn unknown_session_is_rejected() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        let err = handle_agents_chat_approve(
            &req(json!({"session_id": "ghost", "approval_id": "a1", "decision": true})),
            &state,
            "host-1",
            false,
        )
        .await
        .unwrap_err();
        assert!(err.contains("unknown or already-finished"), "{err}");
    }

    /// car#1295 / car#1296. A session that authenticated AS an agent is
    /// authoritative about who it is, so a caller-supplied id naming a
    /// different agent is a forgery attempt, not a request to honor.
    #[test]
    fn a_bound_session_may_act_only_as_itself() {
        assert!(super::require_own_agent(Some("a"), "m", "a").is_ok());
        assert!(super::require_own_agent(Some("a"), "m", "b").is_err());
        // Compared exactly: an agent id is a filename-safe key the supervisor
        // stores verbatim, not a display name to be folded or trimmed.
        assert!(super::require_own_agent(Some("a"), "m", "A").is_err());
        assert!(super::require_own_agent(Some("a"), "m", "a ").is_err());
    }

    /// An UNBOUND session passes this identity-only helper for operator reads
    /// and lease/sync calls. Mutating lifecycle handlers add host-aware gates.
    #[test]
    fn an_unbound_session_is_not_restricted_by_this_rule() {
        assert!(super::require_own_agent(None, "m", "a").is_ok());
        assert!(super::require_own_agent(None, "m", "anything-at-all").is_ok());
    }

    /// The refusal names the id the CALLER supplied, which is theirs already,
    /// and is returned before any lookup — so unlike `authorize_run_access`'s
    /// FIX 3 it cannot answer "does that agent exist?".
    #[test]
    fn the_refusal_says_which_call_was_refused_without_revealing_anything() {
        let err = super::require_own_agent(Some("a"), "agents.wait", "b").unwrap_err();
        assert!(err.contains("agents.wait"), "{err}");
        assert!(err.contains("may only act on itself"), "{err}");
        assert!(!err.contains("  "), "collapsed continuation: {err:?}");
        assert!(super::require_own_agent(Some("a"), "agents.wait", "a").is_ok());
        assert!(super::require_own_agent(None, "agents.wait", "b").is_ok());
    }

    #[tokio::test]
    async fn caller_must_be_originating_host_or_host_management() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        state.chat_sessions.lock().await.insert(
            "s1".to_string(),
            ChatSession {
                agent_id: "car-assistant".to_string(),
                host_client_id: "host-1".to_string(),
                created_at: 0,
                local_cancel: None,
            },
        );

        let err = handle_agents_chat_approve(
            &req(json!({"session_id": "s1", "approval_id": "a1", "decision": true})),
            &state,
            "agent-client",
            false,
        )
        .await
        .unwrap_err();
        assert!(
            err.contains("originating host session or host-management role"),
            "{err}"
        );
        assert!(state.chat_sessions.lock().await.contains_key("s1"));
    }

    #[tokio::test]
    async fn known_session_but_detached_agent_is_rejected() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        // Register a chat session whose agent never attached (`attached_agents`
        // has no entry), so routing must fail cleanly rather than hang.
        state.chat_sessions.lock().await.insert(
            "s1".to_string(),
            ChatSession {
                agent_id: "car-assistant".to_string(),
                host_client_id: "host-1".to_string(),
                created_at: 0,
                local_cancel: None,
            },
        );
        let err = handle_agents_chat_approve(
            &req(json!({"session_id": "s1", "approval_id": "a1", "decision": true})),
            &state,
            "host-1",
            false,
        )
        .await
        .unwrap_err();
        assert!(err.contains("not attached"), "{err}");
        // The session is NOT dropped by a failed approve (unlike cancel).
        assert!(state.chat_sessions.lock().await.contains_key("s1"));
    }

    #[tokio::test]
    async fn host_management_may_resolve_any_chat_approval() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));
        state.chat_sessions.lock().await.insert(
            "s1".to_string(),
            ChatSession {
                agent_id: "car-assistant".to_string(),
                host_client_id: "host-1".to_string(),
                created_at: 0,
                local_cancel: None,
            },
        );

        let err = handle_agents_chat_approve(
            &req(json!({"session_id": "s1", "approval_id": "a1", "decision": true})),
            &state,
            "host-admin",
            true,
        )
        .await
        .unwrap_err();
        assert!(
            err.contains("not attached"),
            "host-management should pass authorization and fail only at routing: {err}"
        );
    }
}

#[cfg(test)]
mod sync_lease_surface {
    //! The `sync.*` / `lease.*` daemon dispatch surface (B6). Drives the
    //! handlers directly against a standalone `ServerState` (rooted at a tmp dir,
    //! so the sync subsystem opens under `<tmp>/sync/`), proving the WS wiring,
    //! transcript resume, the dispatch fence, and cross-call lease visibility on
    //! the one daemon-held subsystem. The two-device convergence + fencing
    //! mechanics themselves are unit-tested in `crate::sync`.
    use super::{
        acquire_lease, check_sync_fence, handle_lease_status, handle_sync_append,
        handle_sync_record_turn, handle_sync_resume, handle_sync_status, record_sync_intent,
        release_lease, JsonRpcMessage,
    };
    use crate::session::ServerState;
    use serde_json::{json, Value};
    use std::sync::Arc;

    fn req(params: Value) -> JsonRpcMessage {
        JsonRpcMessage {
            jsonrpc: "2.0".into(),
            method: None,
            params,
            id: json!(1),
            result: None,
            error: None,
        }
    }

    #[tokio::test]
    async fn sync_and_lease_dispatch_roundtrip() {
        let tmp = tempfile::TempDir::new().unwrap();
        let state = Arc::new(ServerState::standalone(tmp.path().to_path_buf()));

        // sync.status lazily opens the subsystem and reports a real device id.
        let status = handle_sync_status(&state).await.unwrap();
        assert!(status["device_id"].as_str().unwrap().starts_with("device-"));

        // Record a knowledge op + a conversation turn through the oplog.
        handle_sync_append(
            &req(json!({"surface": "knowledge", "payload": {"id": "f1", "body": "sky"}})),
            &state,
        )
        .await
        .unwrap();
        handle_sync_record_turn(
            &req(json!({"conversation_id": "c1", "role": "user", "content": "hi", "timestamp": 1})),
            &state,
        )
        .await
        .unwrap();

        // sync.resume is real: the turn comes back as a provider-valid message.
        let resume = handle_sync_resume(&req(json!({"conversation_id": "c1"})), &state)
            .await
            .unwrap();
        let msgs = resume.as_array().unwrap();
        assert_eq!(msgs.len(), 1);
        assert_eq!(msgs[0]["role"], json!("user"));

        // lease.acquire → status reflects the same daemon-held holder. These
        // operation cores are called after the production handler's session
        // authorization; the real WS boundary is covered by
        // `bound_agent_identity_ws`.
        let lease = acquire_lease(
            &req(json!({"agent_id": "milo", "ttl_ms": 1_000_000})),
            &state,
            "milo",
        )
        .await
        .unwrap();
        assert_eq!(lease["epoch"], json!(1));
        let ls = handle_lease_status(&req(json!({"agent_id": "milo"})), &state, Some("milo"))
            .await
            .unwrap();
        assert_eq!(ls["lease"]["holder"], lease["holder"]);

        // The holder may dispatch run r1 (no prior commit).
        let fence = check_sync_fence(
            &req(json!({"agent_id": "milo", "run_id": "r1", "epoch": 1})),
            &state,
            "milo",
        )
        .await
        .unwrap();
        assert_eq!(fence["may_dispatch"], json!(true));

        // Record r1 committed; the fence now refuses re-dispatch (idempotency).
        record_sync_intent(
            &req(json!({"agent_id": "milo", "run_id": "r1", "epoch": 1, "status": "committed"})),
            &state,
            "milo",
        )
        .await
        .unwrap();
        let fence = check_sync_fence(
            &req(json!({"agent_id": "milo", "run_id": "r1", "epoch": 1})),
            &state,
            "milo",
        )
        .await
        .unwrap();
        assert_eq!(fence["decision"]["decision"], json!("already_committed"));
        assert_eq!(fence["may_dispatch"], json!(false));

        // Clean release; a bad-epoch renew/release surfaces as an error.
        release_lease(
            &req(json!({"agent_id": "milo", "epoch": 1})),
            &state,
            "milo",
        )
        .await
        .unwrap();
        assert!(release_lease(
            &req(json!({"agent_id": "milo", "epoch": 1})),
            &state,
            "milo"
        )
        .await
        .is_err());
    }
}

#[cfg(test)]
mod merged_knowledge_tests {
    use super::merge_knowledge;
    use serde_json::json;

    #[test]
    fn org_none_leaves_personal_knowledge_unchanged() {
        // The org-scope-OFF read invariant: no org subsystem → personal only.
        let personal = vec![json!({"subject": "a", "body": "1"})];
        assert_eq!(merge_knowledge(personal.clone(), None), personal);
    }

    /// Replicate the recall path's POSITIONAL newest-per-subject reduce
    /// (`car-cli reduce_newest_per_subject`): last occurrence per subject wins,
    /// trusting ascending order. This is what a `sync.knowledge` consumer applies,
    /// so it is the real semantic to assert against.
    fn reduce_last_wins(
        entries: &[serde_json::Value],
    ) -> std::collections::HashMap<String, String> {
        let mut out = std::collections::HashMap::new();
        for e in entries {
            let subject = e["subject"].as_str().unwrap().to_string();
            let body = e["body"].as_str().unwrap().to_string();
            out.insert(subject, body); // last-wins
        }
        out
    }

    #[test]
    fn shared_subject_resolves_to_personal_not_org() {
        // The precedence bug linus caught: a subject in BOTH scopes must resolve to
        // the PERSONAL body (Option-B personal-authoritative), NOT the org one.
        // merge_knowledge puts personal LAST so the positional last-wins reducer
        // keeps it.
        let personal = vec![json!({"subject": "shared", "body": "personal-newer"})];
        let org = vec![
            json!({"subject": "org-only", "body": "from-org"}),
            json!({"subject": "shared", "body": "org-staler"}),
        ];
        let reduced = reduce_last_wins(&merge_knowledge(personal, Some(org)));
        assert_eq!(
            reduced.get("shared").map(String::as_str),
            Some("personal-newer"),
            "personal must win a shared subject — a staler org fact must NOT shadow it"
        );
        assert_eq!(
            reduced.get("org-only").map(String::as_str),
            Some("from-org"),
            "an org-only subject is still surfaced"
        );
    }

    #[test]
    fn within_scope_newest_is_preserved() {
        // Ordering within a scope is unchanged: the later entry for a subject wins.
        let personal = vec![
            json!({"subject": "a", "body": "old"}),
            json!({"subject": "a", "body": "new"}),
        ];
        let reduced = reduce_last_wins(&merge_knowledge(personal, None));
        assert_eq!(reduced.get("a").map(String::as_str), Some("new"));
    }
}

/// `skill.adopt_pack`'s provenance resolution — the security-relevant half of
/// governed pack adoption, kept pure so its precedence is testable without a
/// daemon. Signature trust is *derived* against the operator keyring, never
/// asserted by the caller (arXiv 2602.12430 "Agent Skills";
/// `docs/proposals/skill-trust-governance.md`).
#[cfg(test)]
mod skill_adopt_pack_tests {
    use super::resolve_adopt_provenance;
    use car_bundle::{sign_manifest, AgentIdentity, AgentManifest, PublisherInfo, TransportSpec};
    use ed25519_dalek::SigningKey;
    use serde_json::json;

    /// A genuinely ed25519-signed manifest standing in for a skill bundle, plus
    /// the base64 `key_id` it was signed with (so a test can choose to trust
    /// it). Mirrors `car-memgine/tests/skill_trust_lifecycle.rs::signed_manifest`;
    /// the key is deterministic here because the test needs no entropy.
    fn signed_manifest(id: &str) -> (AgentManifest, String) {
        let mut m = AgentManifest {
            agent: AgentIdentity {
                id: id.into(),
                name: id.into(),
                namespace: Some("parslee".into()),
                version: Some("1.0.0".into()),
                description: None,
                license: None,
                homepage: None,
            },
            publisher: None,
            runtime: None,
            lifecycle: None,
            transport: TransportSpec::PureData,
            capabilities: None,
        };
        let key = SigningKey::from_bytes(&[7u8; 32]);
        sign_manifest(&mut m, &key).expect("sign");
        let key_id = m
            .publisher
            .as_ref()
            .and_then(|p: &PublisherInfo| p.key_id.clone())
            .expect("key_id present after signing");
        (m, key_id)
    }

    #[test]
    fn no_manifest_no_provenance_defaults_to_unsigned_and_untrusted() {
        let params = json!({ "scanned": true, "vulnerabilities": 2, "source": "community" });
        let p = resolve_adopt_provenance(&params, &[]).expect("resolves");
        assert!(!p.signed, "nothing signed it, so it is not signed");
        assert!(!p.signer_trusted);
        // The caller's own scan/source hints DO survive — only the signature
        // half is off-limits to the caller.
        assert!(p.scanned);
        assert_eq!(p.vulnerabilities, 2);
        assert_eq!(p.source, car_policy::skill_trust::SkillSource::Community);
    }

    #[test]
    fn manifest_signed_by_a_keyring_signer_is_signed_and_trusted() {
        let (m, key_id) = signed_manifest("pack-agent");
        let params = json!({ "manifest": serde_json::to_value(&m).unwrap() });
        let p = resolve_adopt_provenance(&params, &[key_id]).expect("resolves");
        assert!(p.signed);
        assert!(p.signer_trusted, "key_id is in the operator keyring");
    }

    #[test]
    fn manifest_signed_by_an_unknown_signer_is_signed_but_not_trusted() {
        let (m, _key_id) = signed_manifest("pack-agent");
        let params = json!({ "manifest": serde_json::to_value(&m).unwrap() });
        let p = resolve_adopt_provenance(&params, &[]).expect("resolves");
        assert!(p.signed, "the signature itself still verifies");
        assert!(
            !p.signer_trusted,
            "an empty keyring trusts no signer, which costs this pack Official \
             (and only Official) — signed + scanned still reaches Verified"
        );
    }

    #[test]
    fn manifest_and_provenance_together_is_an_error_not_a_precedence_choice() {
        let (m, _) = signed_manifest("pack-agent");
        let params = json!({
            "manifest": serde_json::to_value(&m).unwrap(),
            "provenance": { "signed": true, "signer_trusted": true },
        });
        let err = resolve_adopt_provenance(&params, &[]).expect_err("must refuse");
        assert!(err.contains("not both"), "unexpected message: {err}");
    }

    #[test]
    fn unrecognised_source_is_rejected_rather_than_silently_defaulted() {
        let params = json!({ "source": "bogus" });
        let err = resolve_adopt_provenance(&params, &[]).expect_err("must refuse");
        assert!(err.contains("invalid source"), "unexpected message: {err}");
    }
}

#[cfg(test)]
mod approval_requester_tests {
    use super::stamped_requester;

    /// An agent-bound session IS that agent. Its binding was proven against the
    /// supervisor-minted per-agent token in `session.auth`, so a claim to be a
    /// different agent is a forgery and must not reach the row.
    #[test]
    fn a_bound_session_cannot_claim_to_be_another_agent() {
        assert_eq!(
            stamped_requester(Some("agent-7".into()), Some("agent-9".into())),
            Some("agent-7".into())
        );
    }

    /// Nor can it launder the attribution by omitting the field — which was the
    /// cheaper evasion, because an absent `agent_id` never matched the
    /// requester-vs-resolver comparison at all.
    #[test]
    fn a_bound_session_cannot_launder_by_omitting_the_field() {
        assert_eq!(
            stamped_requester(Some("agent-7".into()), None),
            Some("agent-7".into())
        );
    }

    /// A host client — CarHost, `car-host approve`, the CLI — has no binding and
    /// legitimately raises approvals on an agent's behalf, so its claim stands.
    #[test]
    fn an_unbound_host_client_keeps_its_claim() {
        assert_eq!(
            stamped_requester(None, Some("agent-7".into())),
            Some("agent-7".into())
        );
        assert_eq!(stamped_requester(None, None), None);
    }
}