subc_daemon/

control.rs

use std::{
    collections::{BTreeMap, BTreeSet, HashMap, HashSet},
    fmt,
    path::{Path, PathBuf},
    sync::{Arc, Mutex, RwLock},
    time::{Duration, Instant as StdInstant},
};

use serde::{Deserialize, Serialize};
use subc_control::{
    ops, CapabilityRequirementStatus, CatalogEntry, ClientControlPush, ClientControlRequest,
    ClientControlResponse, ConsumerIdentity, DaemonBuildProvenance, DaemonObservedProcess,
    ModuleDeclaredProvenance, ModuleProtocol, NotReadyReason, PendingReloadVerdict, PollKind,
    ReloadPathAgreement, ReloadPathUnavailableReason, RouteCloseReason, SpawnCursor,
    StderrCaptureState, StderrTail, StderrTailEntry, SupervisorDaemonProvenance, SupervisorEntry,
    SupervisorHealthEntry, SupervisorModuleProvenance, SupervisorObservedProcess,
    SupervisorRescanResult, SupervisorRoute, SupervisorRouteConsumer, SupervisorRouteModule,
};
use subc_protocol::{
    error_codes,
    manifest::{
        validate_hello_capability_grammar, validate_hello_self_signal_declarations,
        CapabilityDeclarations, CapabilityNeed, Concurrency, ManifestProvenance, ModuleManifest,
        ProviderRole,
    },
    scope::{
        ScopeRecord, ScopeRecordOutcome, ScopeRecordResult, ScopeSelector,
        CAP_ROUTE_ROLE_VERSIONS_V1, CAP_SCOPES_V1, SCOPE_DESCRIBE_OP, SCOPE_SYNC_OP,
    },
    session::{
        validate_role_versions, HealthReport, ModuleControlPush, ModuleControlRequest,
        ModuleControlRequestFromModule, ModuleControlResponse, ModuleControlResponseToModule,
        MODULE_CONTROL_OP_HEALTH_CHECK, MODULE_TO_SUBC_OP_CATALOG_UPDATE, ROLE_VERSIONS_FIELD,
    },
    BindIdentity, ErrorBody, Flags, FrameType, ModuleHelloAckBody, ModuleHelloBody, Principal,
    Priority, RouteTarget, PROTOCOL_VERSION,
};
use tokio::time::{timeout_at, Instant};
use tracing::{debug, info, warn};

use crate::{
    capability_requirements::{
        log_duplicate_claim_events, log_requirement_events, CapabilityRequirementEvaluator,
        CapabilityVerdict, DuplicateClaimSource, RegisteredModule, RequirementStatus,
        RuntimeModule,
    },
    daemon_config::RestartRequiredSection,
    forwarding::{
        CloseReason, EndpointRoute, ForwardingError, ForwardingTable, GoodbyeTarget,
        ModuleControlRpcCompletion, ModuleControlRpcOutcome, ModuleEndpointId,
        PendingModuleControlRpc, RouteBindRelayOutcome, RoutePollSnapshot, RouteRelease,
    },
    observability::{
        ROUTE_OPEN_REFUSED_DECLARED_NOT_READY, ROUTE_OPEN_REFUSED_REQUIRED_CAPABILITY_UNPROVIDED,
    },
    provenance::{
        process_start_time, spawned_file_identity, ExecutableIdentityProbe, SpawnedFileIdentity,
    },
    registry::{ChannelState, ConnectionId, Registry, RegistryError},
    router::{RouteCtx, RouterError},
    scopes::{BoundScope, HelloLaunchNonces, ScopeTable},
    server::MAX_PENDING_ROUTE_BINDS_PER_TARGET,
    stderr_tail::{CaptureState, TailEntry},
    supervise::{
        validate_spec, ModuleProcessLiveness, ReservedHelloRejection, SpawnSubscribeRefusal,
        SupervisorHandle, SwapHelloAdmission,
    },
    ConnectedClients, DaemonCounters, Frame, ProjectRootId, Supervisor,
};

/// Lowest envelope version this subc build will negotiate.
///
/// Module HELLO negotiation is exact: peers must use the daemon's locked
/// protocol version. Older and newer peers receive `version_unsupported` and
/// are not registered.
pub const MIN_SUPPORTED_VERSION: u8 = PROTOCOL_VERSION;

const CAP_MANIFEST_REGISTRATION: &str = "manifest_registration_v1";
const CAP_CHANNEL_LIFECYCLE: &str = "channel_lifecycle_v1";
const CAP_PING_PONG: &str = "ping_pong_v1";
const CAP_SESSION_ATTACH: &str = "session_attach_v1";
const CAP_ADMISSION_FACTS_RELAY: &str = "admission_facts_relay_v1";

const SUBC_CONTROL_OPS: &[&str] = &[
    ops::SERVER_DESCRIBE,
    ops::CATALOG_LIST,
    ops::ROUTE_OPEN,
    ops::ROUTE_POLL,
    ops::ROUTE_CLOSING,
    ops::ROUTE_CLOSED,
    ops::SUPERVISOR_LIST,
    ops::SUPERVISOR_RESTART,
    ops::SUPERVISOR_SWAP,
    ops::SUPERVISOR_RELOAD,
    ops::SUPERVISOR_RESCAN,
    ops::SUPERVISOR_RELEASE_RESERVED,
    ops::SUPERVISOR_SET_ENABLED,
    ops::SUPERVISOR_HEALTH_PROBE,
    ops::SUPERVISOR_HEALTH,
    ops::SUPERVISOR_STDERR_TAIL,
    ops::SUPERVISOR_TERMINALS,
    ops::SUPERVISOR_ROUTES,
    ops::SUPERVISOR_PROVENANCE,
    ops::SUPERVISOR_SPAWN_SNAPSHOT,
    ops::SUPERVISOR_SPAWN_SUBSCRIBE,
];

const MODULE_TO_SUBC_CONTROL_OPS: &[&str] = &[
    MODULE_TO_SUBC_OP_CATALOG_UPDATE,
    "supervisor.live_roots",
    SCOPE_SYNC_OP,
    SCOPE_DESCRIBE_OP,
];

/// Module-originated ops the daemon answers but does not advertise in
/// `HELLO_ACK`. Empty today; an op is served from here while the feature it
/// belongs to is incomplete, so no module is told it works before it does.
const MODULE_TO_SUBC_UNADVERTISED_OPS: &[&str] = &[];

const MODULE_BASELINE_CONTROL_OPS: &[&str] = &["route.bind", "route.status"];

/// How long subc waits for a module to ack a relayed route.bind before returning
/// `module_timeout`. The ack waits on the module's own configure, which for AFT
/// includes a synchronous bounded project walk (up to ~20k files) plus gitignore
/// and DB-open work — on a cold page cache or a large repo that legitimately
/// exceeds a couple of seconds. The default is generous because rejecting a VALID
/// bind is far worse than waiting on a slow one; a consumer that wants a tighter
/// bound retries the bind itself (the sanctioned warm-bind-retry pattern).
pub const DEFAULT_ROUTE_BIND_RELAY_TIMEOUT: Duration = Duration::from_secs(12);

/// How many CONSECUTIVE full-budget relay timeouts against one target module
/// open that module's bind-relay breaker.
///
/// Three, so that the breaker is NOT REACHABLE INSIDE ONE CLIENT CALL. Both
/// SDKs default to a 30s request deadline and the relay budget defaults to 12s,
/// so three consecutive full-budget timeouts take ~36s to observe: every client
/// whose open contributed to opening the breaker had already given up on its
/// own. That is what makes opening the breaker unable to turn a call that would
/// have succeeded into a refusal — it can only make an already-failing module
/// fail faster.
///
/// Two would be reachable inside one default deadline. One would convict a
/// module on a single cold-cache bind, which is exactly the valid-but-slow case
/// `DEFAULT_ROUTE_BIND_RELAY_TIMEOUT`'s own doc comment exists to protect.
pub const DEFAULT_ROUTE_BIND_BREAKER_THRESHOLD: u32 = 3;

/// How long a module's bind-relay breaker stays open before exactly one
/// `route.open` is let through as a probe.
///
/// Bounded BELOW by the relay budget: a cooldown at or under the 12s budget
/// re-pays a full-budget stall almost continuously, and the breaker stops being
/// a saving worth its own state. Bounded ABOVE by the SDKs' 30s default request
/// deadline: a client that starts retrying after the module recovers has to get
/// a probe opportunity inside its own deadline, or the breaker converts a
/// recovered module into a failed call — the failure it exists to prevent,
/// pointed the other way.
///
/// 20s sits between those with room on both sides, and it caps what a wedged
/// module can cost at one full-budget wait per 20s ACROSS THE WHOLE DAEMON
/// rather than one per `route.open` per connection. The stall that motivated
/// this, with its measurements, is written up in
/// `docs/designs/route-open-head-of-line.md`: 268 opens against one module each
/// waited the whole budget out.
pub const DEFAULT_ROUTE_BIND_BREAKER_COOLDOWN: Duration = Duration::from_secs(20);

const DEFAULT_HEALTH_PROBE_TIMEOUT: Duration = Duration::from_secs(5);
const SLOW_CONTROL_DISPATCH_THRESHOLD: Duration = Duration::from_secs(1);

fn reload_verdict(
    configured: &Path,
    spawned_from: Option<&Path>,
    image: subc_control::RunningImageAgreement,
) -> PendingReloadVerdict {
    let path = match spawned_from {
        Some(spawned_from) if configured == spawned_from => ReloadPathAgreement::Match,
        Some(spawned_from) => ReloadPathAgreement::Mismatch {
            configured: configured.to_path_buf(),
            spawned_from: spawned_from.to_path_buf(),
        },
        None => ReloadPathAgreement::Unavailable {
            reason: if matches!(
                image,
                subc_control::RunningImageAgreement::Unavailable {
                    reason: subc_control::RunningImageUnavailableReason::NotRunning
                }
            ) {
                ReloadPathUnavailableReason::NotRunning
            } else {
                ReloadPathUnavailableReason::SpawnedPathUnavailable
            },
        },
    };
    PendingReloadVerdict { path, image }
}

#[derive(Clone)]
struct DaemonProvenanceFacts {
    build: DaemonBuildProvenance,
    pid: Option<u32>,
    started_at_ms: Option<u64>,
    start_clock: Option<crate::clock::StartClock>,
    executable_path: Option<PathBuf>,
    executable_identity: Option<SpawnedFileIdentity>,
    process_start_time: Option<u64>,
    probe: ExecutableIdentityProbe,
}

impl Default for DaemonProvenanceFacts {
    fn default() -> Self {
        Self {
            build: DaemonBuildProvenance {
                build_git_sha: None,
                build_lock_digest: None,
            },
            pid: None,
            started_at_ms: None,
            start_clock: None,
            executable_path: None,
            executable_identity: None,
            process_start_time: None,
            probe: ExecutableIdentityProbe::default(),
        }
    }
}

#[derive(Debug, Clone)]
struct SupervisorRescanContext {
    supervisor: Supervisor,
    config_path: PathBuf,
    configured_port: Option<u16>,
    storage_config: Option<crate::daemon_config::StorageConfig>,
    admission_facts_carrier_module_id: Option<String>,
    admission_facts_targets: Option<Vec<String>>,
    scope_authority_owners: Vec<String>,
}

/// Refusal labels passed to `observe_route_open_refusal` that mean the target
/// module is not serving right now, and so open or extend an outage in the
/// route outage tracker. Every one of them is only reachable after the target
/// was found in the registry, which is what keeps an arbitrary client-chosen
/// id from ever creating tracker state.
///
/// Deliberately absent: `not_registered` and `removed` (the id may be
/// anything a client sent, and a removed module is gone on purpose),
/// `protocol_none` (such a module never serves routes, so nothing is out),
/// `role_not_provided`, `op_not_allowed`, `bad_consumer_identity`, the
/// capability and admission-facts refusals (they refuse the caller, not a
/// module outage), and `relay_reservation_failed` (its code ranges over
/// capacity limits as well as a vanished connection). Capacity, breaker,
/// relay-timeout and module-rejection refusals do not pass through that
/// function at all; the breaker logs its own transitions.
///
/// The two not-serving refusals that bypass that function record themselves
/// at their own sites: `supervised_not_registered` and `declared_not_ready`.
/// `required_capability_unprovided` is not tracked: the module itself is up,
/// and the outage belongs to the missing provider.
const ROUTE_OPEN_NOT_SERVING_REASONS: &[&str] = &[
    "reloading",
    "supervisor_not_live",
    "registration_not_active",
    "no_forwarding_connection",
    "relay_send_failed",
];

/// Real channel-0 control handler for subc itself.
#[derive(Clone)]
pub struct ControlHandler {
    registry: Arc<Registry>,
    forwarding: Arc<ForwardingTable>,
    process_liveness: Option<Arc<dyn ModuleProcessLiveness>>,
    supervisor: SupervisorHandle,
    subc_capabilities: Arc<[String]>,
    /// Daemon-wide route.bind relay budget. Used as the fallback when the
    /// target module has no per-module override in
    /// `route_bind_relay_timeouts`.
    route_bind_relay_timeout: Duration,
    /// Per-module route.bind relay budget overrides, keyed by module id. When
    /// `handle_route_open` resolves the deadline for a target module, a
    /// per-module entry wins over the daemon-wide value above.
    route_bind_relay_timeouts: BTreeMap<String, Duration>,
    /// Per-target-module bind-relay breaker state. Shared with the forwarding
    /// table, which is where a new module connection resets it.
    route_bind_breakers: RouteBindBreakers,
    /// Live relay admissions keyed by target module. Shared through the
    /// forwarding table so cloned or separately built handlers enforce one cap.
    route_bind_concurrency: RouteBindConcurrency,
    /// Start and end of each module's not-serving period as seen by
    /// `route.open`, so an outage gets one line at each edge instead of only
    /// the per-refusal INFO lines. Taken from the forwarding table, so every
    /// handler built over one table shares it.
    route_outages: Arc<crate::route_outage::RouteOutageTracker>,
    /// Consecutive relay timeouts that open a module's breaker.
    route_bind_breaker_threshold: u32,
    /// How long a breaker stays open before one probe is admitted.
    route_bind_breaker_cooldown: Duration,
    health_probe_timeout: Duration,
    /// Central storage policy. When set, each registering module receives its
    /// resolved storage descriptor in HELLO_ACK; `None` leaves the field absent.
    storage_config: Option<crate::daemon_config::StorageConfig>,
    /// The machine id established at boot, served on every HELLO_ACK and on
    /// `server.describe`. Fixed for the daemon's lifetime: `ck machine adopt`
    /// changes the file, never this value. `None` serves no id.
    machine_id: Option<crate::machine_id::MachineId>,
    admission_facts_carrier_module_id: Option<String>,
    admission_facts_targets: Option<Vec<String>>,
    /// Scope records with their sync authorities and tombstones; see
    /// `crate::scopes`. Shared by clones of this handler, so every connection
    /// reads and writes one table.
    scopes: Arc<RwLock<ScopeTable>>,
    /// The configured `scope_authority_owners`, kept so a rescan can report a
    /// changed value as needing a daemon restart; rescan never applies it.
    scope_authority_owners: Vec<String>,
    /// The launch nonce each module connection presented at HELLO, which is how
    /// a `scope.sync` is matched to the owner's current launch.
    hello_launch_nonces: Arc<Mutex<HelloLaunchNonces>>,
    rescan: Option<SupervisorRescanContext>,
    connected_clients: ConnectedClients,
    counters: DaemonCounters,
    capability_evaluator: Arc<CapabilityRequirementEvaluator>,
    daemon_provenance: DaemonProvenanceFacts,
    #[cfg(test)]
    control_dispatch_delay: Option<Duration>,
    #[cfg(test)]
    provenance_probe_override: Option<subc_control::RunningImageAgreement>,
}

impl fmt::Debug for ControlHandler {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("ControlHandler")
            .field("registry", &self.registry)
            .field("forwarding", &self.forwarding)
            .field("process_liveness", &self.process_liveness.is_some())
            .field("supervisor", &self.supervisor)
            .field("subc_capabilities", &self.subc_capabilities)
            .finish()
    }
}

struct RouteOpenRequest {
    target: RouteTarget,
    identity: BindIdentity,
    consumer_identity: Option<ConsumerIdentity>,
    consumer_capabilities: Option<Vec<String>>,
    role_versions: Option<BTreeMap<String, String>>,
    admission_facts: Option<serde_json::Value>,
    scope: Option<ScopeSelector>,
}

struct RouteBindReservationGuard {
    forwarding: Arc<ForwardingTable>,
    endpoint: ModuleEndpointId,
    relay_corr: u64,
    armed: bool,
}

struct ModuleControlRpcGuard {
    forwarding: Arc<ForwardingTable>,
    endpoint: ModuleEndpointId,
    corr: u64,
    armed: bool,
}

impl ModuleControlRpcGuard {
    fn new(forwarding: Arc<ForwardingTable>, endpoint: ModuleEndpointId, corr: u64) -> Self {
        Self {
            forwarding,
            endpoint,
            corr,
            armed: true,
        }
    }

    fn disarm(&mut self) {
        self.armed = false;
    }
}

impl Drop for ModuleControlRpcGuard {
    fn drop(&mut self) {
        if self.armed {
            let _ = self
                .forwarding
                .cancel_module_control_rpc(self.endpoint, self.corr);
        }
    }
}

impl RouteBindReservationGuard {
    fn new(forwarding: Arc<ForwardingTable>, endpoint: ModuleEndpointId, relay_corr: u64) -> Self {
        Self {
            forwarding,
            endpoint,
            relay_corr,
            armed: true,
        }
    }

    fn release_and_disarm(&mut self) {
        if !self.armed {
            return;
        }
        if let Ok(Some(target)) = self.forwarding.abort_pending_relay(
            self.endpoint,
            self.relay_corr,
            RouteBindRelayOutcome::ModuleGone("route.open handler canceled".to_string()),
        ) {
            send_goodbye_target_best_effort(
                &self.forwarding.counters(),
                &target,
                "canceled route.bind",
            );
        }
        self.armed = false;
    }

    fn disarm(&mut self) {
        self.armed = false;
    }
}

impl Drop for RouteBindReservationGuard {
    fn drop(&mut self) {
        self.release_and_disarm();
    }
}

/// Per-target-module circuit breaker around the `route.bind` relay.
///
/// The connection reader is serial per connection, so a module whose `on_bind`
/// sits on the ack blocks every LATER frame on the connections that call it,
/// including calls to unrelated modules. This does not make any module's bind
/// fast; it stops the daemon paying the full budget again and again for a
/// condition it has already observed.
///
/// State is keyed by TARGET MODULE and shared by every connection: a wedged
/// module wedges everyone, so what one connection learned should protect the
/// rest.
///
/// THE MAP IS EMPTY WHILE THE FLEET IS HEALTHY. An entry appears only when a
/// relay to that module has actually timed out, and is removed again when a
/// relay is accepted or the module reconnects, so it cannot grow with traffic
/// or with modules that behave.
///
/// # Why a `std` mutex here is not the head-of-line defect again
///
/// Acquisition never awaits. The critical section is a hash lookup plus a few
/// integer updates, with no I/O and no `.await` inside it, so a reader task
/// cannot be descheduled behind it the way it can behind
/// `tokio::sync::Mutex::lock().await` or a semaphore permit. It is the same
/// primitive, held for the same kind of work, as the refusal counter this very
/// path already increments.
///
/// It is also NOT on the data-plane splice path: only `route.open` and module
/// registration touch it, so bound-route frames gain no state check and no
/// contention.
#[derive(Debug, Clone, Default)]
pub(crate) struct RouteBindBreakers {
    modules: Arc<Mutex<HashMap<String, ModuleBreakerState>>>,
}

#[derive(Debug, Clone, Default)]
pub(crate) struct RouteBindConcurrency {
    modules: Arc<Mutex<HashMap<String, usize>>>,
}

struct RouteBindConcurrencyGuard {
    concurrency: RouteBindConcurrency,
    module_id: String,
}

impl RouteBindConcurrency {
    /// Admit without waiting. Waiting here would move the bind stall from the
    /// module reply to a semaphore and restore reader head-of-line blocking.
    fn try_admit(&self, module_id: &str, limit: usize) -> Result<RouteBindConcurrencyGuard, usize> {
        let mut modules = self
            .modules
            .lock()
            .expect("route.bind concurrency mutex poisoned");
        let in_flight = modules.entry(module_id.to_string()).or_default();
        if *in_flight >= limit {
            return Err(*in_flight);
        }
        *in_flight += 1;
        Ok(RouteBindConcurrencyGuard {
            concurrency: self.clone(),
            module_id: module_id.to_string(),
        })
    }
}

impl Drop for RouteBindConcurrencyGuard {
    fn drop(&mut self) {
        let mut modules = self
            .concurrency
            .modules
            .lock()
            .expect("route.bind concurrency mutex poisoned");
        let remove = {
            let in_flight = modules
                .get_mut(&self.module_id)
                .expect("admitted route.bind has a concurrency entry");
            *in_flight -= 1;
            *in_flight == 0
        };
        if remove {
            modules.remove(&self.module_id);
        }
    }
}

#[derive(Debug, Default)]
struct ModuleBreakerState {
    /// Relay timeouts observed with no accepted relay in between.
    consecutive_timeouts: u32,
    /// `Some` while the breaker is open: the instant the cooldown expires and
    /// the next arrival may probe. `None` means closed.
    cooldown_until: Option<Instant>,
    /// A half-open probe has been admitted and has not settled yet. This is
    /// what makes the probe EXACTLY ONE: the flag is set under the same lock
    /// that read the cooldown, so concurrent opens arriving at the moment the
    /// cooldown expires cannot all decide that they are the probe.
    probe_in_flight: Option<Arc<()>>,
}

/// What the breaker decided for one `route.open`, before any relay work.
enum RouteBindAdmission<'a> {
    Admitted {
        guard: RouteBindBreakerGuard<'a>,
        /// This open is the single half-open probe, so the transition is worth
        /// one log line.
        probe: bool,
    },
    Refused {
        consecutive_timeouts: u32,
        /// What is left of the cooldown. Zero when the refusal is because the
        /// one probe is already in flight rather than because the cooldown has
        /// not elapsed.
        retry_in: Duration,
        probe_in_flight: bool,
    },
}

/// An outstanding admission, which must be told how its relay settled.
///
/// `Drop` settles it as inconclusive, so an early return between admission and
/// the relay -- or the whole handler being cancelled when the client
/// disconnects -- releases a half-open probe slot instead of leaving the
/// breaker wedged half-open with no further probes.
struct RouteBindBreakerGuard<'a> {
    breakers: RouteBindBreakers,
    module_id: &'a str,
    probe_token: Option<Arc<()>>,
    settled: bool,
}

impl RouteBindBreakerGuard<'_> {
    /// The module answered within the budget and took the bind. THE ONLY
    /// OUTCOME THAT CLEARS THE COUNT. Returns true when this closed an open
    /// breaker, which is a transition worth logging.
    fn record_accepted(&mut self) -> bool {
        self.settled = true;
        self.breakers.record_accepted(self.module_id)
    }

    /// The relay burned the whole budget with no answer. THE ONLY ARM THAT
    /// COUNTS TOWARD OPENING.
    fn record_timeout(&mut self, threshold: u32, cooldown: Duration) -> Option<BreakerOpened> {
        self.settled = true;
        self.breakers.record_timeout(
            self.module_id,
            self.probe_token.as_ref(),
            threshold,
            cooldown,
        )
    }

    /// Everything else: the module REJECTED the bind, its connection went away
    /// mid-relay, or the waiter was cancelled.
    ///
    /// None of these is evidence that a module is slow, and each already has
    /// its own refusal with its own code. A module that rejects a bind in
    /// microseconds is healthy and must never be convicted for it; a module
    /// that died has said nothing about the module that replaces it. So these
    /// neither increment nor reset the count -- they only release a probe slot.
    fn record_inconclusive(&mut self) {
        self.settled = true;
        self.breakers
            .record_inconclusive(self.module_id, self.probe_token.as_ref());
    }
}

impl Drop for RouteBindBreakerGuard<'_> {
    fn drop(&mut self) {
        if !self.settled {
            self.breakers
                .record_inconclusive(self.module_id, self.probe_token.as_ref());
        }
    }
}

/// The breaker moved to open, reported so the caller can log it outside the
/// lock. Opening is rare and load-bearing; the refusals that follow are
/// frequent and are counted rather than logged.
struct BreakerOpened {
    consecutive_timeouts: u32,
    /// True when a failed probe re-opened an already-open breaker, which reads
    /// very differently in a log from a first opening.
    reopened_after_probe: bool,
}

impl RouteBindBreakers {
    fn lock(&self) -> std::sync::MutexGuard<'_, HashMap<String, ModuleBreakerState>> {
        self.modules
            .lock()
            .expect("route.bind breaker mutex poisoned")
    }

    /// Decide whether this `route.open` may attempt its relay. Takes the map
    /// lock and nothing else, and never awaits.
    fn admit<'a>(&self, module_id: &'a str) -> RouteBindAdmission<'a> {
        let admitted = |probe_token: Option<Arc<()>>| RouteBindAdmission::Admitted {
            probe: probe_token.is_some(),
            guard: RouteBindBreakerGuard {
                breakers: self.clone(),
                module_id,
                probe_token,
                settled: false,
            },
        };

        let mut modules = self.lock();
        let Some(state) = modules.get_mut(module_id) else {
            return admitted(None);
        };
        let Some(cooldown_until) = state.cooldown_until else {
            return admitted(None);
        };
        if state.probe_in_flight.is_some() {
            return RouteBindAdmission::Refused {
                consecutive_timeouts: state.consecutive_timeouts,
                retry_in: Duration::ZERO,
                probe_in_flight: true,
            };
        }
        let now = Instant::now();
        if now < cooldown_until {
            return RouteBindAdmission::Refused {
                consecutive_timeouts: state.consecutive_timeouts,
                retry_in: cooldown_until - now,
                probe_in_flight: false,
            };
        }
        let token = Arc::new(());
        state.probe_in_flight = Some(Arc::clone(&token));
        admitted(Some(token))
    }

    fn record_accepted(&self, module_id: &str) -> bool {
        self.lock()
            .remove(module_id)
            .is_some_and(|state| state.cooldown_until.is_some())
    }

    fn record_timeout(
        &self,
        module_id: &str,
        probe_token: Option<&Arc<()>>,
        threshold: u32,
        cooldown: Duration,
    ) -> Option<BreakerOpened> {
        let mut modules = self.lock();
        let state = modules.entry(module_id.to_string()).or_default();
        let was_open = state.cooldown_until.is_some();
        let was_probe = Self::owns_probe(state, probe_token);
        if was_probe {
            state.probe_in_flight = None;
        }
        state.consecutive_timeouts = state.consecutive_timeouts.saturating_add(1);
        if state.consecutive_timeouts < threshold {
            return None;
        }
        state.cooldown_until = Some(Instant::now() + cooldown);
        Some(BreakerOpened {
            consecutive_timeouts: state.consecutive_timeouts,
            reopened_after_probe: was_open && was_probe,
        })
    }

    fn owns_probe(state: &ModuleBreakerState, token: Option<&Arc<()>>) -> bool {
        // A relay can finish after the breaker was reset or after it opened
        // again and started a new probe. Only the guard whose token matches the
        // active probe may release it, so a late relay never frees a newer probe.
        state
            .probe_in_flight
            .as_ref()
            .zip(token)
            .is_some_and(|(active, token)| Arc::ptr_eq(active, token))
    }

    fn record_inconclusive(&self, module_id: &str, probe_token: Option<&Arc<()>>) {
        if let Some(state) = self.lock().get_mut(module_id) {
            if Self::owns_probe(state, probe_token) {
                state.probe_in_flight = None;
            }
        }
    }

    /// Discard what was learned about a module, because the process it was
    /// learned about is gone. Returns the discarded count when it was non-zero.
    ///
    /// A BREAKER IS A CACHED VERDICT ABOUT A PROCESS, NOT ABOUT A NAME. A
    /// `module_id` is a configuration identity that outlives any particular
    /// child; what the breaker observed was the process behind the module
    /// connection of the moment. When a new connection registers under that id
    /// the verdict's subject no longer exists, so the verdict is stale by
    /// construction rather than merely likely to be wrong. Keeping it would
    /// apply a dead process's record to a live one, which is the same defect
    /// class this breaker exists to stop the daemon committing.
    ///
    /// A half-open probe in flight is discarded with the rest: it was a
    /// question about the old process.
    pub(crate) fn reset_for_new_module_connection(&self, module_id: &str) -> Option<u32> {
        self.lock()
            .remove(module_id)
            .map(|state| state.consecutive_timeouts)
            .filter(|discarded| *discarded > 0)
    }

    /// Open breakers, for the `server.describe` counters object. `None` when
    /// none is open, so the key stays absent rather than present-and-empty.
    ///
    /// This is the operator's answer to "is this module refusing instantly or
    /// is it fine?", which look identical from a client that retries and then
    /// succeeds.
    fn open_snapshot(&self) -> Option<serde_json::Value> {
        let now = Instant::now();
        let modules = self.lock();
        let open = modules
            .iter()
            .filter_map(|(module_id, state)| {
                let cooldown_until = state.cooldown_until?;
                Some((
                    module_id.clone(),
                    serde_json::json!({
                        "consecutive_timeouts": state.consecutive_timeouts,
                        "cooldown_remaining_ms":
                            cooldown_until.saturating_duration_since(now).as_millis() as u64,
                        "probe_in_flight": state.probe_in_flight.is_some(),
                    }),
                ))
            })
            .collect::<serde_json::Map<String, serde_json::Value>>();
        (!open.is_empty()).then_some(serde_json::Value::Object(open))
    }
}

impl ControlHandler {
    pub fn new(registry: Arc<Registry>) -> Self {
        Self::with_forwarding(registry, Arc::new(ForwardingTable::default()))
    }

    pub fn with_forwarding(registry: Arc<Registry>, forwarding: Arc<ForwardingTable>) -> Self {
        let counters = forwarding.counters();
        // Taken from the forwarding table rather than created here, so that the
        // breaker a `route.open` consults is the same one a module's
        // registration resets, however many handlers are built over one table.
        let route_bind_breakers = forwarding.route_bind_breakers();
        let route_bind_concurrency = forwarding.route_bind_concurrency();
        let route_outages = forwarding.route_outages();
        Self {
            registry,
            forwarding,
            process_liveness: None,
            supervisor: SupervisorHandle::new(),
            subc_capabilities: Arc::from([
                CAP_MANIFEST_REGISTRATION.to_string(),
                CAP_CHANNEL_LIFECYCLE.to_string(),
                CAP_PING_PONG.to_string(),
                CAP_SESSION_ATTACH.to_string(),
                CAP_ADMISSION_FACTS_RELAY.to_string(),
                CAP_SCOPES_V1.to_string(),
                CAP_ROUTE_ROLE_VERSIONS_V1.to_string(),
            ]),
            route_bind_relay_timeout: DEFAULT_ROUTE_BIND_RELAY_TIMEOUT,
            route_bind_relay_timeouts: BTreeMap::new(),
            route_bind_breakers,
            route_bind_concurrency,
            route_outages,
            route_bind_breaker_threshold: DEFAULT_ROUTE_BIND_BREAKER_THRESHOLD,
            route_bind_breaker_cooldown: DEFAULT_ROUTE_BIND_BREAKER_COOLDOWN,
            health_probe_timeout: DEFAULT_HEALTH_PROBE_TIMEOUT,
            storage_config: None,
            machine_id: None,
            admission_facts_carrier_module_id: None,
            admission_facts_targets: None,
            scopes: Arc::new(RwLock::new(ScopeTable::new(
                crate::daemon_config::default_scope_authority_owners(),
            ))),
            scope_authority_owners: crate::daemon_config::default_scope_authority_owners(),
            hello_launch_nonces: Arc::new(Mutex::new(HelloLaunchNonces::default())),
            rescan: None,
            connected_clients: ConnectedClients::new(),
            counters,
            capability_evaluator: Arc::new(CapabilityRequirementEvaluator::new()),
            daemon_provenance: DaemonProvenanceFacts::default(),
            #[cfg(test)]
            control_dispatch_delay: None,
            #[cfg(test)]
            provenance_probe_override: None,
        }
    }

    /// Set the central storage policy: registering modules then receive their
    /// resolved storage descriptor in HELLO_ACK.
    pub fn with_storage_config(
        mut self,
        storage_config: Option<crate::daemon_config::StorageConfig>,
    ) -> Self {
        self.storage_config = storage_config;
        self
    }

    /// Set the machine id served to every registering module (HELLO_ACK) and on
    /// `server.describe`.
    pub fn with_machine_id(mut self, machine_id: Option<crate::machine_id::MachineId>) -> Self {
        self.machine_id = machine_id;
        self
    }

    /// Configure the exact reserved module and target ids permitted to relay
    /// opaque admission facts. Config-file loading validates this authority;
    /// this builder keeps the same policy available to embedded test daemons.
    pub fn with_admission_facts_config(
        mut self,
        carrier_module_id: Option<String>,
        targets: Option<Vec<String>>,
    ) -> Self {
        self.admission_facts_carrier_module_id = carrier_module_id;
        self.admission_facts_targets = targets;
        self
    }

    /// Set the module ids whose scopes may carry `agent_id` and `delegates`.
    /// Replaces the scope table with an empty one under the new list, so call it
    /// while building the handler, before any module can sync.
    pub fn with_scope_authority_owners(mut self, owners: Vec<String>) -> Self {
        self.scopes = Arc::new(RwLock::new(ScopeTable::new(owners.iter().cloned())));
        self.scope_authority_owners = owners;
        self
    }

    /// Override the route.bind relay timeout. Used by tests that assert the
    /// timeout path so they don't block on the production-safe default.
    pub fn with_route_bind_relay_timeout(mut self, timeout: Duration) -> Self {
        self.route_bind_relay_timeout = timeout;
        self
    }

    /// Install per-module route.bind relay budget overrides. A module id
    /// listed here wins over the daemon-wide default set via
    /// `with_route_bind_relay_timeout`. Values are pre-resolved at parse time
    /// from `subc.jsonc` (per-module > daemon-wide > absent), so callers pass
    /// the same `Duration` the bind path will use.
    pub fn with_route_bind_relay_timeouts(
        mut self,
        timeouts: impl IntoIterator<Item = (String, Duration)>,
    ) -> Self {
        self.route_bind_relay_timeouts = timeouts.into_iter().collect();
        self
    }

    /// Resolve the route.bind relay budget for a specific target module id.
    /// Per-module overrides win; the daemon-wide value (set via
    /// `with_route_bind_relay_timeout` or the built-in default) is the
    /// fallback. Exposed so config-aware callers (bootstrap, tests) can audit
    /// the same resolution `handle_route_open` will use.
    pub fn route_bind_relay_timeout_for(&self, module_id: &str) -> Duration {
        self.route_bind_relay_timeouts
            .get(module_id)
            .copied()
            .unwrap_or(self.route_bind_relay_timeout)
    }

    /// Override the per-module bind-relay breaker policy.
    ///
    /// Used by tests, which cannot spend three production budgets opening a
    /// breaker or twenty seconds waiting for its cooldown. The production
    /// values are `DEFAULT_ROUTE_BIND_BREAKER_THRESHOLD` and
    /// `DEFAULT_ROUTE_BIND_BREAKER_COOLDOWN`, whose doc comments carry the
    /// reasoning for the numbers.
    pub fn with_route_bind_breaker(mut self, threshold: u32, cooldown: Duration) -> Self {
        self.route_bind_breaker_threshold = threshold.max(1);
        self.route_bind_breaker_cooldown = cooldown;
        self
    }

    #[cfg(test)]
    pub(crate) fn with_health_probe_timeout(mut self, timeout: Duration) -> Self {
        self.health_probe_timeout = timeout;
        self
    }

    #[cfg(test)]
    pub(crate) fn with_control_dispatch_delay(mut self, delay: Duration) -> Self {
        self.control_dispatch_delay = Some(delay);
        self
    }

    pub fn with_process_liveness(
        mut self,
        process_liveness: Arc<dyn ModuleProcessLiveness>,
    ) -> Self {
        self.process_liveness = Some(process_liveness);
        self
    }

    pub fn with_supervisor(mut self, supervisor: SupervisorHandle) -> Self {
        self.supervisor = supervisor;
        self
    }

    pub fn with_daemon_provenance(
        mut self,
        pid: u32,
        started_at_ms: u64,
        executable_path: Option<PathBuf>,
        build_git_sha: Option<String>,
        build_lock_digest: Option<String>,
    ) -> Self {
        let executable_identity = executable_path.as_deref().and_then(spawned_file_identity);
        let process_start_time = process_start_time(pid);
        self.daemon_provenance = DaemonProvenanceFacts {
            build: DaemonBuildProvenance {
                build_git_sha,
                build_lock_digest,
            },
            pid: Some(pid),
            started_at_ms: Some(started_at_ms),
            start_clock: None,
            executable_path,
            executable_identity,
            process_start_time,
            probe: ExecutableIdentityProbe::default(),
        };
        self
    }

    pub(crate) fn with_daemon_start_clock(mut self, clock: crate::clock::StartClock) -> Self {
        self.daemon_provenance.start_clock = Some(clock);
        self
    }

    #[cfg(test)]
    fn with_provenance_probe_result(mut self, result: subc_control::RunningImageAgreement) -> Self {
        self.provenance_probe_override = Some(result);
        self
    }

    /// Install the configured module set and its reserved capability bindings.
    /// Bindings are configuration-scoped and may point at a provider that has not
    /// been installed yet, so this does not require the bound module to exist.
    pub fn with_capability_config(
        self,
        modules: impl IntoIterator<Item = (String, bool)>,
        reserved_capabilities: BTreeMap<String, String>,
    ) -> Self {
        self.capability_evaluator
            .configure(modules, reserved_capabilities);
        self
    }

    pub fn with_supervisor_rescan(
        mut self,
        supervisor: Supervisor,
        config_path: impl Into<PathBuf>,
        configured_port: Option<u16>,
    ) -> Self {
        self.rescan = Some(SupervisorRescanContext {
            supervisor,
            config_path: config_path.into(),
            configured_port,
            storage_config: self.storage_config.clone(),
            admission_facts_carrier_module_id: self.admission_facts_carrier_module_id.clone(),
            admission_facts_targets: self.admission_facts_targets.clone(),
            scope_authority_owners: self.scope_authority_owners.clone(),
        });
        self
    }

    pub fn with_connected_clients(mut self, connected_clients: ConnectedClients) -> Self {
        self.connected_clients = connected_clients;
        self
    }

    pub fn forwarding(&self) -> Arc<ForwardingTable> {
        Arc::clone(&self.forwarding)
    }

    pub(crate) fn counters(&self) -> DaemonCounters {
        self.counters.clone()
    }

    /// Wake at each candidate's own deadline so a stalled fresh exec emits its
    /// requirement event without depending on an operator polling a status command.
    pub fn spawn_capability_deadline_loop(self: Arc<Self>) {
        tokio::spawn(async move {
            loop {
                self.capability_evaluator
                    .wait_for_change_or_deadline()
                    .await;
                self.refresh_capability_requirements();
            }
        });
    }

    fn runtime_capability_snapshot(
        &self,
    ) -> Result<(Vec<RuntimeModule>, Vec<RegisteredModule>), RouterError> {
        let runtime = self
            .supervisor
            .list()
            .into_iter()
            .map(|module| {
                let status = module.status().map_err(|err| {
                    RouterError::backend(0, 0, format!("failed to read capability status: {err}"))
                })?;
                Ok(RuntimeModule {
                    module_id: status.module_id,
                    state: status.state,
                    enabled: status.enabled,
                })
            })
            .collect::<Result<Vec<_>, RouterError>>()?;
        let (_, registrations) = self.registry.list_modules().map_err(|err| {
            RouterError::backend(
                0,
                0,
                format!("failed to list capability registrations: {err}"),
            )
        })?;
        let registrations = registrations
            .into_iter()
            .map(|registration| RegisteredModule {
                module_id: registration.manifest.module_id,
                module_version: registration.manifest.module_version,
                capabilities: registration.manifest.capabilities,
            })
            .collect();
        Ok((runtime, registrations))
    }

    /// The capability side effects of a module becoming the active registration
    /// for its id: cache its manifest (warning if its claims drifted), run the
    /// deny census when its declarations call for one, and recompute the
    /// requirement statuses. An ordinary HELLO does this as it registers; a swap
    /// candidate's does not, and the supervisor does it at promotion instead,
    /// through [`crate::supervise::SwapPromotionObserver`].
    fn apply_registration_capabilities(&self, registration: &crate::registry::ModuleRegistration) {
        let cached_registration = RegisteredModule {
            module_id: registration.manifest.module_id.clone(),
            module_version: registration.manifest.module_version.clone(),
            capabilities: registration.manifest.capabilities.clone(),
        };
        if self.capability_evaluator.record_hello(&cached_registration) {
            warn!(
                module_id = %cached_registration.module_id,
                "capability claims drifted from the cached manifest"
            );
        }
        if capability_census_trigger(None, registration.manifest.capabilities.as_ref()) {
            self.enforce_capability_denies();
        }
        self.refresh_capability_requirements();
    }

    /// Point the shared supervisor handle at this handler for swap promotions.
    /// Called wherever a handler is put behind the `Arc` the router serves, so
    /// it can be held weakly.
    pub(crate) fn install_swap_promotion_observer(self: &Arc<Self>) {
        let observer: std::sync::Weak<dyn crate::supervise::SwapPromotionObserver> =
            Arc::downgrade(self) as std::sync::Weak<ControlHandler>;
        self.supervisor.set_swap_promotion_observer(observer);
    }

    pub fn refresh_capability_requirements(&self) {
        match self.runtime_capability_snapshot() {
            Ok((runtime, registrations)) => {
                log_requirement_events(
                    self.capability_evaluator
                        .evaluate_now(&runtime, &registrations),
                );
            }
            Err(err) => warn!(error = %err, "failed to recompute capability requirements"),
        }
    }

    /// Reconcile only live, attested route bindings after a capability deny edge
    /// or target claim was added. This is deliberately a control-plane census:
    /// the opaque forwarding hot path must not grow a per-frame capability check.
    fn enforce_capability_denies(&self) {
        let (_, registrations) = match self.registry.list_modules() {
            Ok(snapshot) => snapshot,
            Err(err) => {
                warn!(error = %err, "failed to read registrations for capability deny census");
                return;
            }
        };
        let manifests = registrations
            .into_iter()
            .map(|registration| {
                (
                    registration.manifest.module_id.clone(),
                    registration.manifest,
                )
            })
            .collect::<BTreeMap<_, _>>();
        let census = match self.forwarding.route_census(None) {
            Ok(census) => census,
            Err(err) => {
                warn!(error = %err, "failed to read route census for capability deny enforcement");
                return;
            }
        };

        for (target_module_id, routes) in census {
            let Some(target_manifest) = manifests.get(&target_module_id) else {
                continue;
            };
            let mut closed_routes = Vec::new();
            let mut module_goodbyes = Vec::new();
            for route in routes {
                let Principal::Reserved {
                    module_id: opening_module_id,
                } = &route.principal
                else {
                    continue;
                };
                let Some(opening_manifest) = manifests.get(opening_module_id) else {
                    continue;
                };
                let Some(capability) = denied_capability(opening_manifest, target_manifest) else {
                    continue;
                };

                match self.forwarding.release_client_route(
                    route.goodbye_target.connection_id,
                    route.goodbye_target.channel,
                    route.goodbye_target.epoch,
                ) {
                    Ok(RouteRelease::Removed(module_goodbye)) => {
                        warn!(
                            opening_module_id,
                            target_module_id,
                            capability,
                            "force-closing route because an attested capability deny edge now matches"
                        );
                        closed_routes.push(route);
                        module_goodbyes.push(module_goodbye);
                    }
                    Ok(RouteRelease::Stale | RouteRelease::Absent) => {}
                    Err(err) => warn!(
                        opening_module_id,
                        target_module_id,
                        capability,
                        error = %err,
                        "failed to force-close capability-denied route"
                    ),
                }
            }

            if closed_routes.is_empty() {
                continue;
            }
            send_route_control_pushes(
                &self.forwarding,
                closed_routes,
                ClientControlPush::RouteClosed {
                    module_id: target_module_id,
                    channels: Vec::new(),
                    reason: RouteCloseReason::CapabilityDenied,
                    drained: false,
                    abandoned: 0,
                    excluded_subscriptions: 0,
                    terminal: Some(false),
                },
            );
            self.emit_route_goodbyes(module_goodbyes);
        }
    }

    /// Why a registered module is not accepting new route binds, or `None` when
    /// it is. This is the module's effective readiness: its declared readiness
    /// first, then every `need: required` capability it declares evaluating to
    /// `provided`. `route.open` and `catalog.list` both read it here so the
    /// catalog never reports a module routable that `route.open` would refuse.
    fn not_ready_reason(
        &self,
        registration: &crate::registry::ModuleRegistration,
    ) -> Option<NotReadyReason> {
        if !registration.ready {
            return Some(NotReadyReason {
                reason: NotReadyReason::DECLARED_NOT_READY.to_string(),
                capability: None,
            });
        }
        self.first_unprovided_required_capability(registration)
            .map(|capability| NotReadyReason {
                reason: NotReadyReason::REQUIRED_CAPABILITY_UNPROVIDED.to_string(),
                capability: Some(capability),
            })
    }

    /// The lexicographically first capability this registration declares
    /// `need: required` whose evaluator verdict is not `provided`.
    ///
    /// The verdicts are the capability evaluator's own; nothing here decides
    /// what "provided" means. The evaluator counts a capability provided as
    /// soon as a module claiming it has REGISTERED, not once that module is
    /// ready. That distinction is what keeps two modules that require each
    /// other's capabilities from deadlocking: if "provided" meant "the claimant
    /// is ready", each would wait for the other to become ready first and
    /// neither ever would. Do not tighten it to readiness.
    ///
    /// A required capability with no verdict at all means this registration's
    /// HELLO or catalog.update landed after the last recompute; recompute once
    /// rather than let a missing verdict read as either answer. If it is still
    /// missing (the recompute itself failed) the capability counts as
    /// unprovided: the refusal is retryable, and routing a module whose
    /// required provider is unknown is the outcome this check exists to stop.
    fn first_unprovided_required_capability(
        &self,
        registration: &crate::registry::ModuleRegistration,
    ) -> Option<String> {
        let required = registration
            .manifest
            .capabilities
            .iter()
            .flat_map(|declarations| declarations.requires.iter())
            .filter(|requirement| requirement.need == CapabilityNeed::Required)
            .map(|requirement| requirement.capability.as_str())
            .collect::<BTreeSet<_>>();
        if required.is_empty() {
            return None;
        }
        let module_id = registration.manifest.module_id.as_str();
        let verdict = |capability: &str| self.capability_evaluator.verdict(module_id, capability);
        if required
            .iter()
            .any(|capability| verdict(capability).is_none())
        {
            self.refresh_capability_requirements();
        }
        required
            .into_iter()
            .find(|capability| verdict(capability) != Some(CapabilityVerdict::Provided))
            .map(str::to_string)
    }

    fn capability_requirement_statuses(&self) -> Vec<CapabilityRequirementStatus> {
        self.capability_evaluator
            .statuses()
            .into_iter()
            .map(capability_requirement_status)
            .collect()
    }

    /// Remove a connection's registry entries WITHOUT signalling the supervisor's
    /// registration-release watch. The signal is what the supervisor waits on
    /// before spawning a replacement, so it must only fire once forwarding
    /// teardown is also done (see [`Self::cleanup_connection`] /
    /// [`Self::handle_goodbye`]). Used directly only where there is no forwarding
    /// state to tear down (a HELLO that failed before module registration).
    fn deregister_connection(
        &self,
        connection_id: ConnectionId,
    ) -> Result<Vec<crate::registry::ModuleRegistration>, RegistryError> {
        self.registry.deregister_connection(connection_id)
    }

    pub(crate) fn route_open_target(&self, frame: &Frame) -> Option<String> {
        if frame.header.channel != 0 || frame.header.ty != FrameType::Request {
            return None;
        }
        let Ok(ClientControlRequest::RouteOpen { target, .. }) =
            parse_client_control_request(&frame.body)
        else {
            return None;
        };
        Some(target_module_id(&target).to_string())
    }

    pub(crate) fn route_open_capacity_refusal(
        &self,
        ctx: &RouteCtx,
        frame: &Frame,
        target_module_id: &str,
        in_flight: usize,
        limit: usize,
    ) -> Result<Frame, RouterError> {
        self.route_open_admission_refusal_frame(
            ctx,
            frame,
            target_module_id,
            "open_admission_full",
            (in_flight, limit),
            format!(
                "connection already has {in_flight} route.open binds in flight (limit {limit}); retry after one settles"
            ),
        )
    }

    fn route_open_target_capacity_refusal(
        &self,
        ctx: &RouteCtx,
        frame: &Frame,
        target_module_id: &str,
        in_flight: usize,
    ) -> Result<Frame, RouterError> {
        self.route_open_admission_refusal_frame(
            ctx,
            frame,
            target_module_id,
            "target_binds_full",
            (in_flight, MAX_PENDING_ROUTE_BINDS_PER_TARGET),
            format!(
                "module_id '{target_module_id}' already has {in_flight} route.bind relays in flight; retry after one settles"
            ),
        )
    }

    /// Admission pressure clears as existing binds settle, so its refusal must
    /// remain in the deployed SDKs' closed retryable set: `unknown_module`,
    /// `module_reloading`, `module_warming`, `target_unavailable`, or
    /// `module_timeout`. `target_unavailable` is honest for an attempt that
    /// cannot currently reach its target; `module_timeout` would falsely claim
    /// that a wait expired. A new, cleaner code would be terminal to deployed
    /// clients, so it requires a client-tolerance rollout before daemon emission.
    fn route_open_admission_refusal_frame(
        &self,
        ctx: &RouteCtx,
        frame: &Frame,
        target_module_id: &str,
        reason: &'static str,
        (in_flight, limit): (usize, usize),
        message: impl Into<String>,
    ) -> Result<Frame, RouterError> {
        let code = error_codes::TARGET_UNAVAILABLE;
        self.counters.increment_route_open_refused(code);
        info!(
            target: "control",
            code,
            reason,
            module_id = ?target_module_id,
            connection_id = ctx.connection_id.get(),
            in_flight,
            limit,
            "route.open refused"
        );
        control_error_frame(frame, code, message.into())
    }

    /// Test-only compatibility entry point for unit control handling that does not have a socket sink.
    ///
    /// The real server path uses [`Self::handle_control_frame`] so module HELLO registration can
    /// record the module connection's [`crate::FrameSink`] and session attach can await the module
    /// relay response. This seam stays cfg(test) so production has only one channel-0 path.
    #[cfg(test)]
    pub fn handle_control(
        &self,
        connection_id: ConnectionId,
        frame: Frame,
    ) -> Result<Vec<Frame>, RouterError> {
        match frame.header.ty {
            FrameType::Ping => Ok(vec![pong(&frame)?]),
            FrameType::Hello => self.handle_hello(connection_id, None, frame),
            FrameType::Goodbye => self.handle_goodbye(connection_id),
            ty => Ok(vec![control_error_frame(
                &frame,
                "unsupported_control_frame",
                format!("unsupported channel-0 frame {ty:?}"),
            )?]),
        }
    }

    pub async fn handle_control_frame(
        &self,
        ctx: &RouteCtx,
        frame: Frame,
    ) -> Result<Vec<Frame>, RouterError> {
        self.handle_control_frame_timed(ctx, frame, None).await
    }

    pub(crate) async fn handle_control_frame_timed(
        &self,
        ctx: &RouteCtx,
        frame: Frame,
        dispatch_started_at: Option<StdInstant>,
    ) -> Result<Vec<Frame>, RouterError> {
        match frame.header.ty {
            FrameType::Ping => Ok(vec![pong(&frame)?]),
            FrameType::Hello => {
                self.handle_hello(ctx.connection_id, Some(ctx.egress.clone()), frame)
            }
            FrameType::Goodbye => self.handle_goodbye(ctx.connection_id),
            FrameType::Cancel => {
                if self
                    .supervisor
                    .cancel_spawn_subscription(ctx.connection_id, frame.header.corr)
                {
                    Ok(Vec::new())
                } else {
                    Ok(vec![control_error_frame(
                        &frame,
                        "unknown_subscription",
                        "no supervisor spawn subscription has this correlation id",
                    )?])
                }
            }
            FrameType::Request => {
                if self
                    .forwarding
                    .module_endpoint_for_connection(ctx.connection_id)
                    .map_err(RouterError::Forwarding)?
                    .is_some()
                {
                    if !is_known_module_request_op(&frame.body) {
                        return Ok(vec![control_error_frame(
                            &frame,
                            "unsupported_control_frame",
                            "module-originated channel-0 REQUEST is not supported",
                        )?]);
                    }
                    let request = match parse_module_control_request_from_module(&frame.body) {
                        Ok(request) => request,
                        Err((err, ControlRequestBodyError::UnknownOp)) => {
                            return Ok(vec![control_error_frame(
                                &frame,
                                "unsupported_control_frame",
                                format!("unsupported module-originated channel-0 REQUEST: {err}"),
                            )?])
                        }
                        Err((err, ControlRequestBodyError::InvalidBody)) => {
                            return Ok(vec![control_error_frame(
                                &frame,
                                "invalid_control_body",
                                format!("malformed module control body: {err}"),
                            )?])
                        }
                    };
                    let op = module_control_request_op(&request);
                    let corr = frame.header.corr;
                    log_control_dispatch_arrival(op, ctx.connection_id, corr);
                    let result =
                        self.handle_module_control_request(ctx.connection_id, frame, request);
                    log_slow_control_dispatch(dispatch_started_at, op, ctx.connection_id, corr);
                    return result;
                }

                if is_known_module_request_op(&frame.body) {
                    return Ok(vec![control_error_frame(
                        &frame,
                        "not_registered",
                        "catalog.update requires an active module registration owned by this connection",
                    )?]);
                }

                let request = match parse_client_control_request(&frame.body) {
                    Ok(request) => request,
                    Err((err, ControlRequestBodyError::UnknownOp)) => {
                        return Ok(vec![control_error_frame(
                            &frame,
                            "unknown_control_op",
                            format!("unknown client control op: {err}"),
                        )?])
                    }
                    Err((err, ControlRequestBodyError::InvalidBody)) => {
                        return Ok(vec![control_error_frame(
                            &frame,
                            "invalid_control_body",
                            format!("malformed client control body: {err}"),
                        )?])
                    }
                };
                let op = client_control_request_op(&request);
                let corr = frame.header.corr;
                log_control_dispatch_arrival(op, ctx.connection_id, corr);
                #[cfg(test)]
                if let Some(delay) = self.control_dispatch_delay {
                    tokio::time::sleep(delay).await;
                }
                let result = self
                    .handle_client_control_request(ctx, frame, request)
                    .await;
                log_slow_control_dispatch(dispatch_started_at, op, ctx.connection_id, corr);
                result
            }
            FrameType::Push => {
                let Some(endpoint) = self
                    .forwarding
                    .module_endpoint_for_connection(ctx.connection_id)
                    .map_err(RouterError::Forwarding)?
                else {
                    return Ok(vec![control_error_frame(
                        &frame,
                        "unsupported_control_frame",
                        "client-originated channel-0 PUSH is not supported",
                    )?]);
                };
                self.handle_status_update(endpoint, frame)
            }
            FrameType::Response | FrameType::Error
                if self
                    .forwarding
                    .module_endpoint_for_connection(ctx.connection_id)
                    .map_err(RouterError::Forwarding)?
                    .is_some() =>
            {
                self.handle_module_relay_response(ctx.connection_id, frame)
            }
            ty => Ok(vec![control_error_frame(
                &frame,
                "unsupported_control_frame",
                format!("unsupported channel-0 frame {ty:?}"),
            )?]),
        }
    }

    pub fn cleanup_connection(
        &self,
        connection_id: ConnectionId,
    ) -> Result<Vec<crate::registry::ModuleRegistration>, RegistryError> {
        let crash_closed = self
            .registry
            .get_module_by_connection(connection_id)?
            .and_then(|registration| {
                self.forwarding
                    .module_endpoint_for_connection(connection_id)
                    .ok()
                    .flatten()
                    .and_then(|endpoint| self.forwarding.endpoint_routes(endpoint).ok())
                    .map(|routes| (registration.manifest.module_id, routes))
            });
        let crash_closed = crash_closed.map(|(module_id, routes)| {
            let terminal = match self.supervisor.get(&module_id) {
                None => false,
                Some(module) => match module.will_recover_after_connection_loss() {
                    Ok(will_recover) => !will_recover,
                    Err(err) => {
                        warn!(
                            %module_id,
                            error = %err,
                            "failed to read crash recovery verdict; reporting non-terminal conservatively"
                        );
                        false
                    }
                },
            };
            // The forwarding table gates all providers at the start of daemon
            // shutdown, before their connections are closed. An ordinary
            // module disconnect still reports crash if that gate is not set.
            let reason = match self.forwarding.is_daemon_draining() {
                Ok(true) => RouteCloseReason::Restart,
                Ok(false) => RouteCloseReason::Crash,
                Err(err) => {
                    warn!(error = %err, "failed to read daemon drain state; reporting crash conservatively");
                    RouteCloseReason::Crash
                }
            };
            (module_id, routes, reason, terminal)
        });
        let registrations = self.deregister_connection(connection_id);
        let cleanup = if crash_closed.is_some() {
            self.forwarding.cleanup_connection_counted(connection_id)
        } else {
            // A module connection's teardown needs the count of abandoned
            // route.bind relays for its route.closed notice below. Any other
            // connection, such as a client's, sends no such notice and needs
            // only its routes released, so it uses the route-only wrapper and
            // reports zero.
            self.forwarding
                .cleanup_connection(connection_id)
                .map(|released| crate::forwarding::ConnectionCleanup {
                    released,
                    abandoned_relays: 0,
                })
        };
        // The route.closed push waits for forwarding teardown because only
        // teardown knows how many pending route.bind relays it aborted. It still
        // goes out before the GOODBYEs for the released routes, and its targets
        // were captured above, before teardown removed those routes.
        if let Some((module_id, routes, reason, terminal)) = crash_closed {
            let abandoned = cleanup
                .as_ref()
                .map_or(0, |cleanup| cleanup.abandoned_relays);
            send_route_control_pushes(
                &self.forwarding,
                routes,
                ClientControlPush::RouteClosed {
                    module_id,
                    channels: Vec::new(),
                    reason,
                    drained: false,
                    abandoned,
                    excluded_subscriptions: 0,
                    terminal: Some(terminal),
                },
            );
        }
        if let Ok(cleanup) = cleanup {
            self.emit_route_goodbyes(cleanup.released);
        }
        // Signal the registration-release watch only now that BOTH registry and
        // forwarding teardown are done, so a supervisor waiting to spawn a
        // replacement never observes release while old routes still exist.
        if matches!(&registrations, Ok(r) if !r.is_empty()) {
            crate::supervise::notify_registration_release();
            self.capability_evaluator.wake_deadline_loop();
            self.refresh_capability_requirements();
        }
        self.supervisor.remove_spawn_subscribers(connection_id);
        // Sync authority dies with its connection, so the owner's next
        // connection can take it; the owner's scopes stay as they are.
        self.hello_launch_nonces
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
            .forget(connection_id);
        self.scopes
            .write()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
            .release_connection(connection_id);
        registrations
    }

    pub(crate) fn handle_route_goodbye(
        &self,
        connection_id: ConnectionId,
        route_channel: u16,
        route_epoch: u32,
    ) -> Result<bool, RouterError> {
        debug!(
            connection_id = connection_id.get(),
            route_channel, route_epoch, "handling route GOODBYE"
        );
        let RouteRelease::Removed(released_route) = self
            .forwarding
            .release_client_route(connection_id, route_channel, route_epoch)
            .map_err(RouterError::Forwarding)?
        else {
            return Ok(false);
        };
        self.emit_route_goodbyes(vec![released_route]);
        Ok(true)
    }

    fn emit_route_goodbyes(&self, released_routes: Vec<GoodbyeTarget>) {
        for released in released_routes {
            let frame = match Frame::build_with_version(
                released.negotiated_ver,
                FrameType::Goodbye,
                control_flags(),
                released.channel,
                released.epoch,
                0,
                Vec::new(),
            ) {
                Ok(frame) => frame,
                Err(err) => {
                    warn!(
                        route_channel = released.channel,
                        error = %err,
                        "failed to build route GOODBYE frame"
                    );
                    continue;
                }
            };
            if !released.close_on_delivery_failure() {
                crate::forwarding::send_module_route_goodbye(
                    &self.counters,
                    &released.sink,
                    frame,
                    released.module_id.as_deref(),
                    "client route released",
                );
                continue;
            }
            if let Err(err) = released.sink.try_send(frame) {
                warn!(
                    target_connection_id = released.connection_id.get(),
                    route_channel = released.channel,
                    error = %err,
                    "route GOODBYE was not delivered to client; closing target connection"
                );
                if self
                    .forwarding
                    .escalate_client_delivery_failure(
                        released.connection_id,
                        released.channel,
                        released.epoch,
                        CloseReason::new(
                            "route_goodbye_delivery_failed",
                            format!(
                                "failed to enqueue route GOODBYE for channel {}: {err}",
                                released.channel
                            ),
                        ),
                        crate::forwarding::UndeliveredFrame {
                            module_id: released.module_id.as_deref(),
                            sink: &released.sink,
                        },
                    )
                    .unwrap_or(false)
                {
                    self.counters.increment_goodbye_relay_client_failed();
                }
            }
        }
    }

    /// Best-effort GOODBYE to a module for a route channel subc reserved but then
    /// abandoned (route.bind relay timed out, its waiter was cancelled, or subc's
    /// own commit failed after the module had already accepted). Without this, a
    /// module that accepts late keeps a binding subc has torn down, so a later
    /// frame on that module channel could misdeliver if the channel is reused.
    ///
    /// Never closes the shared module connection on failure: a dropped notification
    /// only wastes a bounded amount of warm module-side state, which the module's
    /// own idle reaper reclaims. Only call this once the route.bind relay was
    /// actually enqueued to the module — if the relay send itself failed, the
    /// module never created a binding and there is nothing to tear down.
    fn send_abandoned_route_bind_goodbye(
        &self,
        module_sink: &crate::FrameSink,
        negotiated_ver: u8,
        module_channel: u16,
        module_epoch: u32,
    ) {
        let frame = match Frame::build_with_version(
            negotiated_ver,
            FrameType::Goodbye,
            control_flags(),
            module_channel,
            module_epoch,
            0,
            Vec::new(),
        ) {
            Ok(frame) => frame,
            Err(err) => {
                warn!(
                    route_channel = module_channel,
                    error = %err,
                    "failed to build GOODBYE for abandoned route.bind"
                );
                return;
            }
        };
        crate::forwarding::send_module_route_goodbye(
            &self.counters,
            module_sink,
            frame,
            None,
            "abandoned route.bind",
        );
    }

    fn handle_hello(
        &self,
        connection_id: ConnectionId,
        sink: Option<crate::FrameSink>,
        frame: Frame,
    ) -> Result<Vec<Frame>, RouterError> {
        debug!(
            connection_id = connection_id.get(),
            corr = frame.header.corr,
            "handling HELLO"
        );
        // A module connection has one identity for its entire lifetime. A second
        // registration would leave the old registry owner behind while replacing
        // its forwarding endpoint and launch nonce.
        if self
            .registry
            .get_module_by_connection(connection_id)
            .map_err(|err| RouterError::backend(0, frame.header.corr, err.to_string()))?
            .is_some()
        {
            return Ok(vec![control_error_frame(
                &frame,
                "invalid_hello",
                "connection is already registered as a module",
            )?]);
        }
        let hello_value = match serde_json::from_slice::<serde_json::Value>(&frame.body) {
            Ok(value) => value,
            Err(err) => {
                return Ok(vec![control_error_frame(
                    &frame,
                    "invalid_hello",
                    format!("malformed HELLO body: {err}"),
                )?])
            }
        };
        if let Err(err) = validate_hello_capability_grammar(&hello_value) {
            return Ok(vec![control_error_frame(
                &frame,
                "invalid_capability_grammar",
                err.to_string(),
            )?]);
        }
        if let Err(err) = validate_hello_self_signal_declarations(&hello_value) {
            return Ok(vec![control_error_frame(
                &frame,
                "invalid_manifest",
                err.to_string(),
            )?]);
        }
        if let Some(provenance) = hello_value
            .get("manifest")
            .and_then(|manifest| manifest.get("provenance"))
        {
            if let Err(err) = serde_json::from_value::<ManifestProvenance>(provenance.clone()) {
                return Ok(vec![control_error_frame(
                    &frame,
                    "invalid_manifest",
                    format!("malformed manifest provenance: {err}"),
                )?]);
            }
        }
        let hello = match serde_json::from_value::<ModuleHelloBody>(hello_value) {
            Ok(hello) => hello,
            Err(err) => {
                return Ok(vec![control_error_frame(
                    &frame,
                    "invalid_hello",
                    format!("malformed HELLO body: {err}"),
                )?])
            }
        };

        if hello.protocol_ver != hello.manifest.protocol_ver {
            return Ok(vec![control_error_frame(
                &frame,
                "invalid_manifest",
                format!(
                    "HELLO protocol_ver {} does not match manifest protocol_ver {}",
                    hello.protocol_ver, hello.manifest.protocol_ver
                ),
            )?]);
        }

        if hello.manifest.module_id.trim().is_empty() {
            return Ok(vec![control_error_frame(
                &frame,
                "invalid_manifest",
                "manifest module_id must not be empty",
            )?]);
        }

        let negotiated_ver = match negotiate_version(hello.protocol_ver) {
            Ok(negotiated_ver) => negotiated_ver,
            Err(message) => {
                return Ok(vec![control_error_frame(
                    &frame,
                    "version_unsupported",
                    message,
                )?])
            }
        };

        // Swap gate, ahead of the reserved gate on purpose. While a blue/green
        // swap is open for this id, the only HELLO admitted as a second process
        // is the one carrying the candidate's launch nonce (the swap token), and
        // it registers into the candidate slot rather than being refused as a
        // duplicate. Run after the reserved gate, a reserved module's candidate
        // would be refused `reserved_module` for presenting a nonce that gate
        // does not know. See `SupervisorHandle::swap_hello_admission`.
        let swap_admission = self
            .supervisor
            .swap_hello_admission(&hello.manifest.module_id, hello.launch_nonce.as_deref());
        if swap_admission == SwapHelloAdmission::Refused {
            warn!(
                module_id = %hello.manifest.module_id,
                connection_id = connection_id.get(),
                "HELLO refused: a swap is open for this module_id and the launch nonce is not one the supervisor minted for it"
            );
            return Ok(vec![control_error_frame(
                &frame,
                "swap_token_invalid",
                format!(
                    "module_id '{}' is being swapped; HELLO without the swap candidate's launch nonce is rejected",
                    hello.manifest.module_id
                ),
            )?]);
        }
        let swap_candidate = swap_admission == SwapHelloAdmission::Candidate;

        // Reserved-module identity gate: a module_id configured `reserved` may be
        // registered ONLY by the process subc spawned for it, proven by echoing the
        // one-time launch nonce subc injected. A non-reserved id has no recorded
        // nonce and always passes. This blocks a key-holder from impersonating a
        // security-boundary module (e.g. the credential vault) while the real one is
        // down/restarting and its registration slot is momentarily free. A swap
        // candidate has already proven the same thing with its own nonce above.
        if let Some(rejection) = (!swap_candidate)
            .then(|| {
                self.supervisor.reserved_hello_rejection(
                    &hello.manifest.module_id,
                    hello.launch_nonce.as_deref(),
                )
            })
            .flatten()
        {
            let message = match rejection {
                ReservedHelloRejection::Exact { module_id } => format!(
                    "module_id '{module_id}' is reserved; HELLO without a valid launch nonce is rejected"
                ),
                ReservedHelloRejection::Prefix {
                    prefix,
                    owner_module_id,
                } => format!(
                    "module_id '{}' matches reserved prefix '{prefix}' owned by '{owner_module_id}'; HELLO without the owner launch nonce is rejected",
                    hello.manifest.module_id
                ),
            };
            return Ok(vec![control_error_frame(
                &frame,
                "reserved_module",
                message,
            )?]);
        }

        let reserved_capability_refusals = self.capability_evaluator.reserved_hello_refusals(
            &hello.manifest.module_id,
            hello.manifest.capabilities.as_ref(),
        );
        if let Some(refusal) = reserved_capability_refusals.first() {
            let capability = refusal.capability.clone();
            let bound_module = refusal.claimants[0].clone();
            log_duplicate_claim_events(reserved_capability_refusals);
            return Ok(vec![control_error_frame(
                &frame,
                "reserved_capability",
                format!(
                    "capability '{}' is reserved for module_id '{}'; claimant '{}' was refused",
                    capability, bound_module, hello.manifest.module_id
                ),
            )?]);
        }

        // A connection that already opened client routes must not also register as
        // a module: cleanup would then release only one side and leak the other.
        if self
            .forwarding
            .connection_has_client_routes(connection_id)
            .map_err(RouterError::Forwarding)?
        {
            return Ok(vec![control_error_frame(
                &frame,
                "invalid_hello",
                "connection has open client routes and cannot also register as a module",
            )?]);
        }

        // Kept for scope sync authority, which goes only to the connection that
        // presented the module's current launch nonce. Recorded before the
        // registration is attempted: a connection whose registration then fails
        // has no registration, so it cannot sync anyway, and cleanup forgets it.
        self.hello_launch_nonces
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
            .record(connection_id, hello.launch_nonce.as_deref());
        let control_ops = effective_module_control_ops(hello.control_ops);
        // Built before anything is registered so an encoding failure leaves no
        // registry or forwarding state behind.
        let hello_ack = self.build_hello_ack(&frame, negotiated_ver, &hello.manifest.module_id)?;
        if swap_candidate {
            return self.register_swap_candidate(
                connection_id,
                sink,
                &frame,
                hello.manifest,
                negotiated_ver,
                control_ops,
                hello_ack,
            );
        }
        let registration = match self.registry.register_with_control_ops(
            hello.manifest,
            negotiated_ver,
            connection_id,
            control_ops,
        ) {
            Ok(registration) => registration,
            Err(RegistryError::DuplicateModuleId { module_id }) => {
                return Ok(vec![control_error_frame(
                    &frame,
                    "duplicate_module_id",
                    format!(
                        "module_id '{module_id}' is already registered; duplicate HELLO rejected"
                    ),
                )?])
            }
            Err(err @ RegistryError::PathHazardModuleId { .. }) => {
                return Ok(vec![control_error_frame(
                    &frame,
                    "invalid_module_id",
                    err.to_string(),
                )?])
            }
            Err(err) => {
                return Ok(vec![control_error_frame(
                    &frame,
                    "registry_error",
                    err.to_string(),
                )?])
            }
        };

        let reply = if let Some(sink) = sink {
            // The forwarding table's module store is also the daemon-to-module
            // control-RPC lane, so every HELLO gets a live endpoint even when the
            // manifest has no routable provider role. Non-routable modules still
            // cannot receive route.bind in production: `handle_route_open` checks
            // the registry manifest with `target_has_required_role` before the
            // only production call to `begin_route_bind_relay_for` below that
            // route.open path. The remaining direct relay callers are unit tests
            // and benchmark harnesses that construct forwarding state explicitly.
            //
            // The HELLO_ACK is queued by the forwarding table itself, before the
            // endpoint becomes visible, and is NOT returned as a reply. A module
            // reads HELLO_ACK first and exits on anything else; a reply is only
            // written after this handler returns, by which time a route.open on
            // another connection could already have queued a route.bind request
            // for this module ahead of it.
            let concurrency = manifest_concurrency(&registration.manifest);
            if let Err(err) = self.forwarding.register_module_connection_acked(
                connection_id,
                registration.manifest.module_id.clone(),
                negotiated_ver,
                concurrency,
                sink,
                hello_ack,
            ) {
                // Forwarding registration failed, so there is no forwarding
                // state to tear down. Remove the registry entry and signal the
                // release watch directly.
                if matches!(self.deregister_connection(connection_id), Ok(r) if !r.is_empty()) {
                    crate::supervise::notify_registration_release();
                }
                return Ok(vec![control_error_frame(
                    &frame,
                    if matches!(err, ForwardingError::ConnectionRoleConflict { .. }) {
                        "invalid_hello"
                    } else {
                        forwarding_error_code(&err)
                    },
                    err.to_string(),
                )?]);
            }
            Vec::new()
        } else {
            // No sink means no forwarding endpoint, so nothing can be routed
            // ahead of the ack; it goes out as the reply.
            vec![hello_ack]
        };

        // Exposure over assumption: Concurrency's serde default is pinned to the
        // pre-field behavior (ModuleManaged), so a management surface that is
        // genuinely Serial and just never declared it inherits concurrent
        // delivery silently. Logging which registrations RESOLVED BY DEFAULT
        // turns "no module has been bitten yet" into the checkable claim "no
        // module is exposed" -- one read of the boot log instead of a fleet
        // audit. Detected from the raw HELLO bytes because the serde default
        // deliberately erases the absent/declared distinction from the type.
        if manifest_concurrency_was_defaulted(&frame.body, &registration.manifest) {
            info!(
                module_id = %registration.manifest.module_id,
                "management surface registered with DEFAULTED concurrency=module_managed (manifest predates the field; declare the real lane)"
            );
        }

        self.apply_registration_capabilities(&registration);

        info!(
            module_id = %registration.manifest.module_id,
            module_version = %registration.manifest.module_version,
            negotiated_ver,
            routable_provider = manifest_provides_routable_role(&registration.manifest),
            connection_id = connection_id.get(),
            "module registered"
        );

        Ok(reply)
    }

    /// Register a HELLO the swap gate admitted into the candidate slot of the
    /// registry and of forwarding, where it is reachable over its own
    /// connection (its `catalog.update` finds it) but by no by-id lookup, so
    /// nothing routes to it until the supervisor cuts over.
    ///
    /// Registry first, then forwarding, the same order as an ordinary HELLO;
    /// a forwarding failure removes the registry entry again. The capability
    /// census is not run: it describes routable modules, and this one is not
    /// routable until promotion.
    #[allow(clippy::too_many_arguments)]
    fn register_swap_candidate(
        &self,
        connection_id: ConnectionId,
        sink: Option<crate::FrameSink>,
        frame: &Frame,
        manifest: ModuleManifest,
        negotiated_ver: u8,
        control_ops: Vec<String>,
        hello_ack: Frame,
    ) -> Result<Vec<Frame>, RouterError> {
        let module_id = manifest.module_id.clone();
        let registration = match self.registry.register_candidate_with_control_ops(
            manifest,
            negotiated_ver,
            connection_id,
            control_ops,
        ) {
            Ok(registration) => registration,
            Err(RegistryError::DuplicateModuleId { module_id }) => {
                return Ok(vec![control_error_frame(
                    frame,
                    "duplicate_module_id",
                    format!(
                        "module_id '{module_id}' already has a swap candidate registered; duplicate HELLO rejected"
                    ),
                )?])
            }
            Err(err @ RegistryError::PathHazardModuleId { .. }) => {
                return Ok(vec![control_error_frame(
                    frame,
                    "invalid_module_id",
                    err.to_string(),
                )?])
            }
            Err(err) => {
                return Ok(vec![control_error_frame(
                    frame,
                    "registry_error",
                    err.to_string(),
                )?])
            }
        };
        let reply = if let Some(sink) = sink {
            // Same ordering as an ordinary HELLO: the forwarding table queues
            // the HELLO_ACK before the candidate endpoint is inserted, because
            // a module exits if its first frame after HELLO is anything else.
            let concurrency = manifest_concurrency(&registration.manifest);
            if let Err(err) = self.forwarding.register_candidate_module_connection_acked(
                connection_id,
                module_id.clone(),
                negotiated_ver,
                concurrency,
                sink,
                hello_ack,
            ) {
                if matches!(self.deregister_connection(connection_id), Ok(r) if !r.is_empty()) {
                    crate::supervise::notify_registration_release();
                }
                return Ok(vec![control_error_frame(
                    frame,
                    forwarding_error_code(&err),
                    err.to_string(),
                )?]);
            }
            Vec::new()
        } else {
            vec![hello_ack]
        };
        self.supervisor.mark_swap_candidate_admitted(&module_id);
        info!(
            module_id = %module_id,
            module_version = %registration.manifest.module_version,
            negotiated_ver,
            ready = registration.ready,
            connection_id = connection_id.get(),
            "swap candidate registered; not routable until cutover"
        );
        Ok(reply)
    }

    fn build_hello_ack(
        &self,
        frame: &Frame,
        negotiated_ver: u8,
        module_id: &str,
    ) -> Result<Frame, RouterError> {
        let ack = ModuleHelloAckBody {
            negotiated_ver,
            subc_ops: module_subc_ops(),
            subc_capabilities: self.subc_capabilities.as_ref().to_vec(),
            storage: self
                .storage_config
                .as_ref()
                .map(|cfg| cfg.descriptor_for(module_id)),
            machine_id: self.machine_id.as_ref().map(|id| id.as_str().to_owned()),
        };
        let body = serde_json::to_vec(&ack).map_err(|err| {
            RouterError::backend(
                0,
                frame.header.corr,
                format!("failed to encode HELLO_ACK: {err}"),
            )
        })?;

        Frame::build_with_version(
            negotiated_ver,
            FrameType::HelloAck,
            control_flags(),
            0,
            0,
            frame.header.corr,
            body,
        )
        .map_err(RouterError::FrameBuild)
    }

    async fn handle_client_control_request(
        &self,
        ctx: &RouteCtx,
        frame: Frame,
        request: ClientControlRequest,
    ) -> Result<Vec<Frame>, RouterError> {
        match request {
            ClientControlRequest::ServerDescribe {} => self.handle_server_describe(frame),
            ClientControlRequest::CatalogList { module_id } => {
                self.handle_catalog_list(frame, module_id)
            }
            ClientControlRequest::RouteOpen {
                target,
                identity,
                consumer_identity,
                consumer_capabilities,
                role_versions,
                admission_facts,
                scope,
            } => {
                self.handle_route_open(
                    ctx,
                    frame,
                    RouteOpenRequest {
                        target,
                        identity,
                        consumer_identity,
                        consumer_capabilities,
                        role_versions,
                        admission_facts,
                        scope,
                    },
                )
                .await
            }
            ClientControlRequest::RoutePoll {
                route_channel,
                route_epoch,
                kind,
            } => self.handle_route_poll(ctx, frame, route_channel, route_epoch, kind),
            ClientControlRequest::SupervisorList {} => self.handle_supervisor_list(frame).await,
            ClientControlRequest::SupervisorSpawnSnapshot {} => {
                self.handle_supervisor_spawn_snapshot(frame)
            }
            ClientControlRequest::SupervisorSpawnSubscribe { since } => {
                self.handle_supervisor_spawn_subscribe(ctx, frame, since)
            }
            ClientControlRequest::SupervisorRestart {
                module_id,
                drain_timeout_ms,
            } => {
                self.handle_supervisor_restart(frame, module_id, drain_timeout_ms)
                    .await
            }
            ClientControlRequest::SupervisorSwap {
                module_id,
                ready_timeout_ms,
            } => {
                self.handle_supervisor_swap(frame, module_id, ready_timeout_ms)
                    .await
            }
            ClientControlRequest::SupervisorReload { module_id } => {
                self.handle_supervisor_reload(frame, module_id).await
            }
            ClientControlRequest::SupervisorRescan { preview } => {
                self.handle_supervisor_rescan(frame, preview).await
            }
            ClientControlRequest::SupervisorReleaseReserved { module_id } => {
                self.handle_supervisor_release_reserved(frame, module_id)
                    .await
            }
            ClientControlRequest::SupervisorSetEnabled { module_id, enabled } => {
                self.handle_supervisor_set_enabled(frame, module_id, enabled)
                    .await
            }
            ClientControlRequest::SupervisorHealthProbe { module_id } => {
                self.handle_supervisor_health_probe(frame, module_id).await
            }
            ClientControlRequest::SupervisorHealth {} => self.handle_supervisor_health(frame),
            ClientControlRequest::SupervisorRoutes { module_id } => {
                self.handle_supervisor_routes(frame, module_id)
            }
            ClientControlRequest::SupervisorProvenance { module_id } => {
                self.handle_supervisor_provenance(frame, module_id).await
            }
            ClientControlRequest::SupervisorStderrTail {
                module_id,
                max_lines,
                max_bytes,
            } => self.handle_supervisor_stderr_tail(frame, module_id, max_lines, max_bytes),
            ClientControlRequest::SupervisorTerminals { module_id } => {
                self.handle_supervisor_terminals(frame, module_id).await
            }
        }
    }

    fn handle_module_control_request(
        &self,
        connection_id: ConnectionId,
        frame: Frame,
        request: ModuleControlRequestFromModule,
    ) -> Result<Vec<Frame>, RouterError> {
        match request {
            ModuleControlRequestFromModule::CatalogUpdate {
                provides,
                capabilities,
                ready,
            } => self.handle_catalog_update(connection_id, frame, provides, capabilities, ready),
            ModuleControlRequestFromModule::LiveRoots {} => {
                let registered = self
                    .registry
                    .get_module_by_connection(connection_id)
                    .map_err(|err| RouterError::backend(0, frame.header.corr, err.to_string()))?;
                let Some(registration) = registered else {
                    return Ok(vec![control_error_frame(&frame, "not_registered", "supervisor.live_roots requires an active module registration owned by this connection")?]);
                };
                let response = self
                    .forwarding
                    .live_roots(&registration.manifest.module_id)
                    .map_err(RouterError::Forwarding)?;
                Ok(vec![control_response_body_frame(
                    &frame,
                    &response,
                    "ModuleControlResponseToModule::LiveRoots",
                )?])
            }
            ModuleControlRequestFromModule::ScopeSync { generation, scopes } => {
                self.handle_scope_sync(connection_id, frame, generation, scopes)
            }
            ModuleControlRequestFromModule::ScopeDescribe { owner, scope_ref } => {
                self.handle_scope_describe(connection_id, frame, owner, scope_ref)
            }
        }
    }

    /// `scope.sync`: the owner is the module registered on this connection.
    /// A connection with no registration (every client connection, `direct`
    /// included) is refused `not_registered` before the table is consulted.
    fn handle_scope_sync(
        &self,
        connection_id: ConnectionId,
        frame: Frame,
        generation: u64,
        scopes: Vec<ScopeRecord>,
    ) -> Result<Vec<Frame>, RouterError> {
        let Some(registration) = self
            .registry
            .get_module_by_connection(connection_id)
            .map_err(|err| RouterError::backend(0, frame.header.corr, err.to_string()))?
        else {
            return Ok(vec![control_error_frame(
                &frame,
                "not_registered",
                "scope.sync requires an active module registration owned by this connection",
            )?]);
        };
        let owner = registration.manifest.module_id;
        let current_nonce = self.supervisor.spawn_launch_nonce_for(&owner);
        let is_current_launch = |connection: ConnectionId| {
            self.hello_launch_nonces
                .lock()
                .unwrap_or_else(|poisoned| poisoned.into_inner())
                .presented(connection, current_nonce.as_deref())
        };
        // Lock order is the scope table, then the forwarding table: the new
        // tags are published, and the routes the change closes are selected,
        // while the scope table is still write-locked, so no admission can read
        // a record whose tag is not yet published.
        let mut table = self
            .scopes
            .write()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        let outcome = table.sync(&owner, connection_id, is_current_launch, generation, scopes);
        let drained = match &outcome {
            Ok(applied) => self
                .forwarding
                .publish_scope_changes(&applied.tag_changes)
                .map_err(RouterError::Forwarding)?,
            Err(_) => Vec::new(),
        };
        drop(table);
        match outcome {
            Ok(applied) => {
                let counts = ScopeOutcomeCounts::of(&applied.results);
                info!(
                    owner = %owner,
                    generation,
                    records = applied.results.len(),
                    created = counts.created,
                    replaced = counts.replaced,
                    updated = counts.updated,
                    unchanged = counts.unchanged,
                    refused = counts.refused,
                    ended = applied.ended.len(),
                    tag_changes = applied.tag_changes.len(),
                    routes_closed = drained.len(),
                    "scope sync accepted"
                );
                // An accepted sync can still refuse individual records, and the
                // owner is the only party that sees the reply. Name them here so
                // an operator can tell a refused session from a missing one
                // without the owner's logs. Capped so a sync that refuses
                // thousands cannot flood the log; the count above is complete.
                for refused in applied
                    .results
                    .iter()
                    .filter(|result| result.outcome == ScopeRecordOutcome::Refused)
                    .take(MAX_LOGGED_REFUSED_SCOPE_RECORDS)
                {
                    warn!(
                        owner = %owner,
                        generation,
                        scope_ref = %refused.scope_ref,
                        scope_epoch = refused.scope_epoch,
                        code = refused.code.as_deref().unwrap_or(""),
                        "scope record refused"
                    );
                }
                self.close_scope_drained_routes(drained);
                let response = ModuleControlResponseToModule::ScopeSync {
                    generation,
                    results: applied.results,
                    ended: applied.ended,
                };
                Ok(vec![control_response_body_frame(
                    &frame,
                    &response,
                    "ModuleControlResponseToModule::ScopeSync",
                )?])
            }
            Err(refusal) => {
                info!(
                    owner = %owner,
                    generation,
                    code = refusal.code,
                    "scope sync refused"
                );
                Ok(vec![control_error_frame(
                    &frame,
                    refusal.code,
                    refusal.message,
                )?])
            }
        }
    }

    /// Tell both ends of each route a scope change closed. The module gets a
    /// channel-scoped GOODBYE and so does the client: the GOODBYE is what ends
    /// the client's route handle. The client also gets `route.closed` with the
    /// scope reason, one push per module and reason, so it can tell a revoked
    /// route from an ordinary close and not reopen it.
    fn close_scope_drained_routes(&self, drained: Vec<crate::forwarding::ScopeDrainedRoute>) {
        if drained.is_empty() {
            return;
        }
        let mut pushes: BTreeMap<(String, String), (RouteCloseReason, Vec<EndpointRoute>)> =
            BTreeMap::new();
        let mut goodbyes = Vec::with_capacity(drained.len() * 2);
        for route in drained {
            warn!(
                module_id = %route.module_id,
                reason = ?route.reason,
                client_connection_id = route.client.connection_id.get(),
                route_channel = route.client.channel,
                "closing route because its scope changed"
            );
            pushes
                .entry((route.module_id.clone(), format!("{:?}", route.reason)))
                .or_insert_with(|| (route.reason, Vec::new()))
                .1
                .push(EndpointRoute {
                    goodbye_target: route.client.clone(),
                    principal: Principal::Unverified,
                    bound_at: Instant::now(),
                    draining: false,
                    drain_reason: None,
                });
            goodbyes.push(route.module);
            goodbyes.push(route.client);
        }
        for ((module_id, _), (reason, routes)) in pushes {
            send_route_control_pushes(
                &self.forwarding,
                routes,
                ClientControlPush::RouteClosed {
                    module_id,
                    channels: Vec::new(),
                    reason,
                    drained: false,
                    abandoned: 0,
                    excluded_subscriptions: 0,
                    terminal: Some(false),
                },
            );
        }
        self.emit_route_goodbyes(goodbyes);
    }

    /// `scope.describe`: any registered module may read any scope, because a
    /// provider must read the scope a route it serves is stamped with.
    fn handle_scope_describe(
        &self,
        connection_id: ConnectionId,
        frame: Frame,
        owner: Principal,
        scope_ref: String,
    ) -> Result<Vec<Frame>, RouterError> {
        let registered = self
            .registry
            .get_module_by_connection(connection_id)
            .map_err(|err| RouterError::backend(0, frame.header.corr, err.to_string()))?;
        if registered.is_none() {
            return Ok(vec![control_error_frame(
                &frame,
                "not_registered",
                "scope.describe requires an active module registration owned by this connection",
            )?]);
        }
        let description = self
            .scopes
            .read()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
            .describe(&owner, &scope_ref);
        let owner_configured = match &owner {
            // Ask whether the owner is configured (`is_configured`), not
            // whether it is on the roster (`get(..).is_some()`): a supervised
            // module's process can register and describe a scope before the
            // supervisor has put it on the roster.
            Principal::Reserved { module_id } => self.supervisor.is_configured(module_id),
            _ => false,
        };
        let response = ModuleControlResponseToModule::ScopeDescribe {
            status: description.status,
            scope_epoch: description.scope_epoch,
            daemon_incarnation: self.supervisor.spawn_snapshot().cursor.daemon_incarnation,
            owner_synced: description.owner_synced,
            owner_configured,
            scope: description.stamp,
        };
        Ok(vec![control_response_body_frame(
            &frame,
            &response,
            "ModuleControlResponseToModule::ScopeDescribe",
        )?])
    }

    fn handle_catalog_update(
        &self,
        connection_id: ConnectionId,
        frame: Frame,
        provides: Vec<ProviderRole>,
        capabilities: Option<CapabilityDeclarations>,
        ready: Option<bool>,
    ) -> Result<Vec<Frame>, RouterError> {
        self.refresh_capability_requirements();
        let Some(registration) = self
            .registry
            .get_module_by_connection(connection_id)
            .map_err(|err| RouterError::backend(0, frame.header.corr, err.to_string()))?
        else {
            return Ok(vec![control_error_frame(
                &frame,
                "not_registered",
                "catalog.update requires an active module registration owned by this connection",
            )?]);
        };

        if let Some(message) =
            catalog_update_frozen_field_message(&registration.manifest, &provides)
        {
            return Ok(vec![control_error_frame(
                &frame,
                "catalog_update_frozen_field",
                message,
            )?]);
        }

        let mut candidate = registration.manifest.clone();
        candidate.provides = provides.clone();
        candidate.capabilities = capabilities
            .clone()
            .or_else(|| registration.manifest.capabilities.clone());
        if let Err(err) = candidate.validate_capability_grammar() {
            return Ok(vec![control_error_frame(
                &frame,
                "invalid_capability_grammar",
                err.to_string(),
            )?]);
        }

        // Updates must honor the same reserved owner as initial registration;
        // otherwise an empty HELLO could acquire the claim after admission.
        let mut conflicts = self
            .capability_evaluator
            .reserved_hello_refusals(&candidate.module_id, candidate.capabilities.as_ref());
        if let Some(conflict) = conflicts.first() {
            let message = format!(
                "capability '{}' is reserved for module_id '{}'; claimant '{}' was refused",
                conflict.capability, conflict.claimants[0], candidate.module_id
            );
            for conflict in &mut conflicts {
                conflict.source = DuplicateClaimSource::CatalogUpdate;
            }
            log_duplicate_claim_events(conflicts);
            return Ok(vec![control_error_frame(
                &frame,
                "reserved_capability",
                message,
            )?]);
        }

        let updated = self
            .registry
            .replace_catalog_for_connection(connection_id, provides, capabilities, ready)
            .map_err(|err| RouterError::backend(0, frame.header.corr, err.to_string()))?;
        if updated.is_none() {
            return Ok(vec![control_error_frame(
                &frame,
                "not_registered",
                "catalog.update requires an active module registration owned by this connection",
            )?]);
        }
        if let Ok((_, registrations)) = self.runtime_capability_snapshot() {
            log_duplicate_claim_events(
                self.capability_evaluator
                    .duplicate_claims(DuplicateClaimSource::CatalogUpdate, &registrations),
            );
        }
        if capability_census_trigger(
            registration.manifest.capabilities.as_ref(),
            updated
                .as_ref()
                .and_then(|entry| entry.manifest.capabilities.as_ref()),
        ) {
            self.enforce_capability_denies();
        }
        self.refresh_capability_requirements();

        let response = ModuleControlResponseToModule::CatalogUpdate {};
        control_response_body_frame(
            &frame,
            &response,
            "ModuleControlResponseToModule::CatalogUpdate",
        )
        .map(|frame| vec![frame])
    }

    fn handle_server_describe(&self, frame: Frame) -> Result<Vec<Frame>, RouterError> {
        self.refresh_capability_requirements();
        // A bare connection count is ambiguous between many clients holding a
        // route each and one client accumulating hundreds, so publish the
        // concentration alongside it. Route state is best-effort here: a
        // diagnostic endpoint must still answer if the forwarding lock is
        // contended.
        let mut counters = self.counters.snapshot();
        if let (Ok((connections_with_routes, max)), Some(obj)) = (
            self.forwarding.client_route_concentration(),
            counters.as_object_mut(),
        ) {
            obj.insert(
                "client_connections_with_routes".into(),
                connections_with_routes.into(),
            );
            obj.insert("max_routes_on_one_connection".into(), max.into());
        }
        // A module that is being fast-refused and a module that is fine look
        // identical from a client that retries and succeeds, so name the open
        // breakers here. This rides the existing free-form counters object
        // rather than a new wire field, so no sibling that deserializes
        // `ServerDescribe` has to be rebuilt to keep reading it.
        if let (Some(open_breakers), Some(obj)) = (
            self.route_bind_breakers.open_snapshot(),
            counters.as_object_mut(),
        ) {
            obj.insert("route_bind_breakers_open".into(), open_breakers);
        }
        let response = ClientControlResponse::ServerDescribe {
            protocol_ver: PROTOCOL_VERSION,
            subc_ops: subc_ops(),
            capabilities: self.subc_capabilities.as_ref().to_vec(),
            connected_clients: self.connected_clients.count(),
            counters: Some(counters),
            build_git_sha: Some(env!("SUBC_BUILD_GIT_SHA").to_string()),
            build_lock_digest: Some(env!("SUBC_BUILD_LOCK_DIGEST").to_string()),
            capability_requirements: self.capability_requirement_statuses(),
            machine_id: self.machine_id.as_ref().map(|id| id.as_str().to_owned()),
        };
        Ok(vec![control_response_body_frame(
            &frame,
            &response,
            "ClientControlResponse::ServerDescribe",
        )?])
    }

    fn handle_catalog_list(
        &self,
        frame: Frame,
        module_id: Option<String>,
    ) -> Result<Vec<Frame>, RouterError> {
        let (generation, modules) = self.registry.list_modules().map_err(|err| {
            RouterError::backend(0, frame.header.corr, format!("registry error: {err}"))
        })?;
        let entries = modules
            .into_iter()
            .filter(|registration| {
                module_id
                    .as_deref()
                    .map(|wanted| registration.manifest.module_id == wanted)
                    .unwrap_or(true)
            })
            .map(|registration| {
                let not_ready = self.not_ready_reason(&registration);
                let roles = registration.manifest.provides;
                CatalogEntry {
                    module_id: registration.manifest.module_id,
                    ready: not_ready.is_none(),
                    not_ready,
                    module_version: Some(registration.manifest.module_version),
                    roles,
                    control_ops: registration.control_ops,
                    capabilities: registration.manifest.capabilities,
                    self_signals: registration.manifest.self_signals,
                }
            })
            .collect();
        let response = ClientControlResponse::CatalogList {
            generation,
            modules: entries,
            subc_ops: subc_ops(),
        };
        Ok(vec![control_response_body_frame(
            &frame,
            &response,
            "ClientControlResponse::CatalogList",
        )?])
    }

    fn route_open_principal(
        &self,
        frame: &Frame,
        consumer_identity: Option<ConsumerIdentity>,
    ) -> Result<Result<Principal, Frame>, RouterError> {
        let Some(consumer_identity) = consumer_identity else {
            return Ok(Ok(Principal::Direct));
        };

        if self.supervisor.spawned_consumer_authorized(
            &consumer_identity.module_id,
            &consumer_identity.launch_nonce,
        ) {
            return Ok(Ok(Principal::Reserved {
                module_id: consumer_identity.module_id,
            }));
        }

        Ok(Err(control_error_frame(
            frame,
            "bad_consumer_identity",
            format!(
                "consumer_identity for module_id '{}' did not match a supervised launch nonce",
                consumer_identity.module_id
            ),
        )?))
    }

    /// Ordinary `route.open` refusals go through here; admission and breaker
    /// refusals log separately with their capacity or breaker state. The daemon can
    /// attest which code it sent: without the event, a client's "the daemon
    /// refused me" and the daemon's own view could only be reconciled by
    /// argument. Malformed input (`invalid_project_root`) does not come here;
    /// rejecting a request that was never a valid open is not a refusal of one.
    fn route_open_refusal_frame(
        &self,
        ctx: &RouteCtx,
        frame: &Frame,
        module_id: &str,
        reason: &'static str,
        code: &'static str,
        message: impl Into<String>,
    ) -> Result<Frame, RouterError> {
        self.observe_route_open_refusal(ctx, module_id, reason, code);
        control_error_frame(frame, code, message.into())
    }

    /// Refuse a `route.open` because the target module's bind-relay breaker is
    /// open, without attempting the relay.
    ///
    /// The wire code is `module_timeout`, which is the truth (the module has
    /// not been answering binds) and which both SDKs already classify as
    /// retryable with capped backoff. Reusing it is what keeps this change out
    /// of both SDKs; the daemon-side distinction lives in the counter key
    /// instead.
    ///
    /// DELIBERATELY NOT LOGGED PER OCCURRENCE, unlike every other refusal.
    /// While a breaker is open this fires on every open to that module, and the
    /// stall written up in `docs/designs/route-open-head-of-line.md` already
    /// produced 261 lines about a single module inside 3000 lines of daemon
    /// log. The rare transitions are logged at warn/info instead and the volume
    /// is carried by the counter, so the evidence survives without the flood.
    /// The debug line keeps a per-refusal record reachable for whoever turns
    /// the level up.
    fn route_open_breaker_refusal_frame(
        &self,
        ctx: &RouteCtx,
        frame: &Frame,
        module_id: &str,
        consecutive_timeouts: u32,
        retry_in: Duration,
        probe_in_flight: bool,
    ) -> Result<Frame, RouterError> {
        self.counters
            .increment_route_open_refused(crate::observability::ROUTE_OPEN_REFUSED_BREAKER_OPEN);
        debug!(
            target: "control",
            code = "module_timeout",
            module_id = ?module_id,
            connection_id = ctx.connection_id.get(),
            consecutive_timeouts,
            retry_in_ms = retry_in.as_millis() as u64,
            probe_in_flight,
            "route.open refused by open bind-relay breaker"
        );
        // Say what a caller can act on. An open bind-relay breaker means the
        // module timed out accepting several new routes in a row. The module
        // is still running and its established routes keep working; only new
        // route.open requests are refused until the cooldown ends and one
        // test route (the probe) gets through. A message that only counts
        // failed relays reads as "the module is down" to a worker that sees it.
        let detail = if probe_in_flight {
            "one test route is already being tried; retry once it settles".to_string()
        } else {
            format!("retrying new routes in {}s", retry_in.as_secs().max(1))
        };
        control_error_frame(
            frame,
            "module_timeout",
            format!(
                "module '{module_id}' is slow to accept new routes ({consecutive_timeouts} \
                 timed out in a row); {detail}; its established routes are unaffected"
            ),
        )
    }

    /// `code` is daemon vocabulary and prints plainly; `module_id` is the
    /// requester's bytes (an unknown target is whatever the client sent) and
    /// is Debug-formatted so control characters land in the log escaped
    /// rather than as terminal sequences for whoever tails it.
    ///
    /// `reason` names the check that refused, because one wire code has
    /// several senders: after a module registers, `target_unavailable` can
    /// come from a missing role, an inactive registration, a supervisor that
    /// has not marked the process live, a missing forwarding connection, or a
    /// failed relay, and a log that records only the code cannot say which of
    /// them fired. It is a static, daemon-chosen label per branch, so it is
    /// safe to print plainly and stays a closed set.
    fn observe_route_open_refusal(
        &self,
        ctx: &RouteCtx,
        module_id: &str,
        reason: &'static str,
        code: &'static str,
    ) {
        self.counters.increment_route_open_refused(code);
        info!(
            target: "control",
            code,
            reason,
            module_id = ?module_id,
            connection_id = ctx.connection_id.get(),
            "route.open refused"
        );
        if ROUTE_OPEN_NOT_SERVING_REASONS.contains(&reason) {
            self.route_outages.record_not_serving(module_id, reason);
        }
    }

    /// Record an ACCEPTED route.open.
    ///
    /// Refusals have been logged and counted since the attestation work; accepts
    /// were invisible, so the daemon knew every principal it stamped and wrote
    /// none of them down. The party that attests the identity was the only party
    /// not recording it, which left a credential vault unable to name the sender
    /// of a call that reached it (claustrum #43) and left the launch-nonce
    /// concurrency question unanswerable from the outside.
    ///
    /// FIELD NAMES MATCH `route.open refused` DELIBERATELY, so one grep over
    /// `code`/`module_id`/`connection_id` returns both directions of the same
    /// decision rather than two shapes a reader has to join by hand.
    ///
    /// `module_id` IS RENDERED BARE HERE AND DEBUG-ESCAPED ON THE REFUSAL PATH,
    /// and the difference carries information rather than being an
    /// inconsistency. This line is only reachable after a successful bind to a
    /// REGISTERED module, so the value has already passed HELLO validation
    /// including the path-hazard refusal and cannot contain control bytes. A
    /// refused id may be arbitrary attacker-chosen bytes and must stay escaped.
    /// So A QUOTED `module_id` IN THE LOG MEANS THE VALUE WAS NEVER VALIDATED.
    ///
    /// Bare is also what every other daemon line already emits (`module
    /// registered`, `configured module supervised`). Shipping `?module_id` here
    /// made this instrument the only one in the file whose ids did not answer
    /// `grep module_id=broca` -- 3 hits against 342 for the escaped form, in a
    /// line whose whole purpose is being grepped beside its sibling.
    ///
    /// THIS RENDERING IS UNFENCED AND THE REASON IS WORTH KNOWING: the in-crate
    /// `EventCapture` test layer implements only `record_debug`, so `Visit`
    /// forwards every field type through it and a bare `&str` and a `?`-escaped
    /// one are recorded identically. A test written against that harness passes
    /// either way -- I wrote one, measured it, and deleted it rather than ship a
    /// green assertion that cannot fail. The same limit applies to the escaping
    /// assertion in `route_open_supervised_absence_emits_refusal_fields_and_counts_code`:
    /// it reads as a guard on the Debug escaping and cannot detect its removal.
    /// Fencing either needs the real formatter, not the capture layer.
    ///
    /// `peer_addr` is NOT here and cannot be: `SO_PEERCRED`/`LOCAL_PEERPID` are
    /// unix-socket options and subc is loopback TCP, so there is no peer identity
    /// to record. The ephemeral port would decay within minutes and answer only a
    /// live question. The identity question is instead answered by counting
    /// distinct live connections presenting one module's `consumer_identity` --
    /// "is anyone else holding this secret" rather than "is this the right
    /// process".
    fn observe_route_open_accept(&self, ctx: &RouteCtx, module_id: &str, principal: &str) {
        self.route_outages.record_accepted(module_id);
        self.counters.increment_route_open_accepted(principal);
        info!(
            target: "control",
            principal,
            module_id,
            connection_id = ctx.connection_id.get(),
            "route.open accepted"
        );
    }

    fn supervised_absent_route_open_refusal_frame(
        &self,
        ctx: &RouteCtx,
        frame: &Frame,
        module_id: &str,
        code: &'static str,
        status: &crate::supervise::ModuleStatus,
    ) -> Result<Frame, RouterError> {
        self.counters.increment_route_open_refused(code);
        info!(
            target: "control",
            code,
            reason = "supervised_not_registered",
            module_id = ?module_id,
            connection_id = ctx.connection_id.get(),
            state = %status.state,
            enabled = status.enabled,
            live = status.live,
            "route.open refused"
        );
        // A supervised module whose process has not registered is not
        // serving, whatever the reason; the supervisor knows this id, so it is
        // safe to track.
        self.route_outages
            .record_not_serving(module_id, "supervised_not_registered");
        control_error_frame(
            frame,
            code,
            format!(
                "module_id '{module_id}' is supervised but not available (state={}, enabled={}, live={})",
                status.state, status.enabled, status.live
            ),
        )
    }

    async fn handle_route_open(
        &self,
        ctx: &RouteCtx,
        frame: Frame,
        request: RouteOpenRequest,
    ) -> Result<Vec<Frame>, RouterError> {
        let RouteOpenRequest {
            target,
            mut identity,
            consumer_identity,
            consumer_capabilities,
            role_versions,
            admission_facts,
            scope,
        } = request;
        let target_module_id = target_module_id(&target).to_string();
        if self
            .registry
            .get_module_by_connection(ctx.connection_id)
            .map_err(|err| RouterError::backend(0, frame.header.corr, err.to_string()))?
            .is_some()
        {
            return Ok(vec![control_error_frame(
                &frame,
                "invalid_request",
                "module connections cannot open client routes",
            )?]);
        }
        debug!(
            connection_id = ctx.connection_id.get(),
            corr = frame.header.corr,
            module_id = %target_module_id,
            "handling route.open"
        );

        // A malformed declaration is refused first, before anything about the
        // target is looked up: the same body would be refused against any
        // module, so the caller learns nothing by retrying or waiting. An empty
        // map declares nothing and travels as no field at all, so a provider
        // only ever sees a missing field or a non-empty one.
        let role_versions = role_versions.filter(|role_versions| !role_versions.is_empty());
        if let Some(Err(error)) = role_versions.as_ref().map(validate_role_versions) {
            self.observe_route_open_refusal(
                ctx,
                &target_module_id,
                "invalid_role_versions",
                error_codes::INVALID_REQUEST,
            );
            return Ok(vec![control_error_body_frame(
                &frame,
                ErrorBody {
                    code: error_codes::INVALID_REQUEST.to_string(),
                    message: error.to_string(),
                    detail: Some(serde_json::json!({ "field": ROLE_VERSIONS_FIELD })),
                },
            )?]);
        }

        // WHY THESE REPLIES DISCRIMINATE FREELY, since the usual rule is the
        // opposite. Below, a caller learns whether a module is unregistered,
        // supervised-but-down (with state/enabled/live), or registered without the
        // requested role. Elsewhere that is an enumeration leak: a probe learning
        // the shape of a fleet it cannot otherwise see.
        //
        // It is not one here, and the reason is the ACCESS MODEL rather than
        // anything about these errors. Reaching route.open requires the
        // pre-envelope HMAC handshake, whose key lives in a 0600 user-owned
        // connection file, so any caller who completes it already runs as this
        // user -- and can read subc.jsonc for the module list and `ck module
        // status` for live state. The reply discloses nothing the caller cannot
        // read more easily from disk, while the precision is load-bearing:
        // `unknown_module` is retryable and a missing role is not.
        //
        // IF THE HANDSHAKE EVER ADMITS A PRINCIPAL THAT IS NOT THIS USER -- a
        // remote transport, a sandboxed caller, a shared-host mode -- THAT
        // PREMISE DIES AND THESE THREE REPLIES MUST COLLAPSE INTO ONE.
        let Some(registration) = self
            .registry
            .get_module(&target_module_id)
            .map_err(|err| RouterError::backend(0, frame.header.corr, err.to_string()))?
        else {
            if let Some((status, warming)) =
                self.supervisor_status(&target_module_id, frame.header.corr)?
            {
                // BEFORE the two availability codes below, because for a module
                // that speaks no subc wire both of them are false comfort: they
                // say "not right now" and are retried, and this module will
                // never register no matter how long the caller waits. The
                // absence here is the declaration being honoured, not a module
                // that is late.
                if status.protocol == ModuleProtocol::None {
                    return Ok(vec![self.route_open_refusal_frame(
                        ctx,
                        &frame,
                        &target_module_id,
                        "protocol_none",
                        error_codes::MODULE_NO_PROTOCOL,
                        format!(
                            "module_id '{target_module_id}' is declared protocol: none; \
                             it speaks no subc wire and serves no routes"
                        ),
                    )?]);
                }
                let code = if warming {
                    "module_warming"
                } else {
                    "target_unavailable"
                };
                return Ok(vec![self.supervised_absent_route_open_refusal_frame(
                    ctx,
                    &frame,
                    &target_module_id,
                    code,
                    &status,
                )?]);
            }
            if let Some(removed_ago_ms) =
                self.supervisor.removal_tombstone_age_ms(&target_module_id)
            {
                return Ok(vec![self.route_open_refusal_frame(
                    ctx,
                    &frame,
                    &target_module_id,
                    "removed",
                    error_codes::MODULE_REMOVED,
                    format!("module_id '{target_module_id}' was removed {removed_ago_ms} ms ago"),
                )?]);
            }
            return Ok(vec![self.route_open_refusal_frame(
                ctx,
                &frame,
                &target_module_id,
                "not_registered",
                error_codes::UNKNOWN_MODULE,
                format!("module_id '{target_module_id}' is not registered"),
            )?]);
        };

        // Best-effort only: registry readiness and forwarding reservation use
        // different locks, so a module can flip readiness between this read and
        // the relay. Modules must still tolerate an `on_bind` while not ready.
        if !registration.ready {
            self.counters
                .increment_route_open_refused(ROUTE_OPEN_REFUSED_DECLARED_NOT_READY);
            info!(
                target: "control",
                code = error_codes::MODULE_WARMING,
                module_id = ?target_module_id,
                connection_id = ctx.connection_id.get(),
                reason = "declared_not_ready",
                "route.open refused"
            );
            // The module is registered but says it cannot take work, which is
            // an outage from the caller's side even though its process is up.
            self.route_outages
                .record_not_serving(&target_module_id, "declared_not_ready");
            return Ok(vec![control_error_body_frame(
                &frame,
                ErrorBody {
                    code: error_codes::MODULE_WARMING.to_string(),
                    message: format!(
                        "module_id '{target_module_id}' is registered and has declared itself not ready; retry"
                    ),
                    detail: Some(serde_json::json!({
                        "reason": "declared_not_ready"
                    })),
                },
            )?]);
        }

        // Effective readiness, second half: a module that declares a capability
        // `need: required` is not routable while that capability has no
        // registered provider. It is enforced HERE, as a retryable routing
        // refusal, and deliberately not as spawn ordering or a boot block. The
        // module is still started and registered and can make its own calls;
        // spawn ordering is a promise that cannot be kept once a provider
        // crashes at runtime, and refusing to boot would stop the whole
        // machine, including the tools needed to fix its configuration.
        //
        // "Provided" is the evaluator's verdict, which counts a provider as
        // soon as it has REGISTERED, not once it is ready. Two modules that
        // require each other's capabilities are therefore both routable once
        // both register; counting readiness instead would deadlock them.
        //
        // Only new opens are refused. Routes already bound when a provider
        // goes away stay bound: nothing here tears them down, and the module
        // answers them as it can. Like the readiness read above this is
        // best-effort against a provider registering or leaving concurrently.
        if let Some(capability) = self.first_unprovided_required_capability(&registration) {
            self.counters
                .increment_route_open_refused(ROUTE_OPEN_REFUSED_REQUIRED_CAPABILITY_UNPROVIDED);
            info!(
                target: "control",
                code = error_codes::MODULE_WARMING,
                module_id = ?target_module_id,
                connection_id = ctx.connection_id.get(),
                reason = NotReadyReason::REQUIRED_CAPABILITY_UNPROVIDED,
                capability = %capability,
                "route.open refused"
            );
            return Ok(vec![control_error_body_frame(
                &frame,
                ErrorBody {
                    code: error_codes::MODULE_WARMING.to_string(),
                    message: format!(
                        "module_id '{target_module_id}' requires capability '{capability}', \
                         which no registered module provides; retry"
                    ),
                    detail: Some(serde_json::json!({
                        "reason": NotReadyReason::REQUIRED_CAPABILITY_UNPROVIDED,
                        "capability": capability,
                    })),
                },
            )?]);
        }

        if !target_has_required_role(&target, &registration.manifest.provides) {
            return Ok(vec![self.route_open_refusal_frame(
                ctx,
                &frame,
                &target_module_id,
                "role_not_provided",
                "target_unavailable",
                format!("module_id '{target_module_id}' does not provide the requested target"),
            )?]);
        }

        if registration.state != ChannelState::Active {
            return Ok(vec![self.route_open_refusal_frame(
                ctx,
                &frame,
                &target_module_id,
                "registration_not_active",
                "target_unavailable",
                format!("module_id '{target_module_id}' is not active"),
            )?]);
        }

        if self
            .forwarding
            .module_is_draining(&target_module_id)
            .map_err(RouterError::Forwarding)?
        {
            return Ok(vec![self.route_open_refusal_frame(
                ctx,
                &frame,
                &target_module_id,
                "reloading",
                "module_reloading",
                format!("module_id '{target_module_id}' is reloading"),
            )?]);
        }

        if let Some(process_liveness) = self.process_liveness.as_ref().filter(|process_liveness| {
            process_liveness.process_live(&target_module_id) == Some(false)
        }) {
            // A module the supervisor is restarting or reloading can still hold
            // a registration: the old process before its connection closes, or
            // a new one that registered while the supervisor was draining. The
            // forwarding table does not see that as draining, but the consumer
            // should still be told to retry soon, exactly as for the drain
            // above, rather than that the target is unavailable.
            if process_liveness.process_replacing(&target_module_id) {
                return Ok(vec![self.route_open_refusal_frame(
                    ctx,
                    &frame,
                    &target_module_id,
                    "reloading",
                    "module_reloading",
                    format!("module_id '{target_module_id}' is reloading"),
                )?]);
            }
            return Ok(vec![self.route_open_refusal_frame(
                ctx,
                &frame,
                &target_module_id,
                "supervisor_not_live",
                "target_unavailable",
                format!("module_id '{target_module_id}' is not live"),
            )?]);
        }

        if !self
            .forwarding
            .has_live_module_connection(&target_module_id)
            .map_err(RouterError::Forwarding)?
        {
            return Ok(vec![self.route_open_refusal_frame(
                ctx,
                &frame,
                &target_module_id,
                "no_forwarding_connection",
                "target_unavailable",
                format!("module_id '{target_module_id}' has no live forwarding connection"),
            )?]);
        }

        if let Some(error) =
            self.guard_module_control_op(&frame, &target_module_id, "route.bind")?
        {
            self.observe_route_open_refusal(
                ctx,
                &target_module_id,
                "op_not_allowed",
                "op_not_allowed",
            );
            return Ok(vec![error]);
        }

        let principal = match self.route_open_principal(&frame, consumer_identity)? {
            Ok(principal) => principal,
            Err(error) => {
                self.observe_route_open_refusal(
                    ctx,
                    &target_module_id,
                    "bad_consumer_identity",
                    "bad_consumer_identity",
                );
                return Ok(vec![error]);
            }
        };

        // This is attested, control-plane policy for supervised module origins.
        // Keep it before route reservation and out of the opaque forwarding hot
        // path: data frames must never acquire a per-frame capability check.
        if let Principal::Reserved {
            module_id: opening_module_id,
        } = &principal
        {
            if let Some(opening_registration) = self
                .registry
                .get_module(opening_module_id)
                .map_err(|err| RouterError::backend(0, frame.header.corr, err.to_string()))?
            {
                if let Some(capability) =
                    denied_capability(&opening_registration.manifest, &registration.manifest)
                {
                    warn!(
                        opening_module_id,
                        target_module_id,
                        capability,
                        "refusing route.open because an attested capability deny edge matches"
                    );
                    return Ok(vec![self.route_open_refusal_frame(
                        ctx,
                        &frame,
                        &target_module_id,
                        "capability_deny_edge",
                        "capability_forbidden",
                        format!(
                            "module_id '{opening_module_id}' must never reach capability '{capability}' provided by '{target_module_id}'"
                        ),
                    )?]);
                }
            }
        }

        if admission_facts.is_some() {
            let carrier_matches = matches!(
                &principal,
                Principal::Reserved { module_id }
                    if self.admission_facts_carrier_module_id.as_deref() == Some(module_id)
            );
            if !carrier_matches {
                return Ok(vec![self.route_open_refusal_frame(
                    ctx,
                    &frame,
                    &target_module_id,
                    "admission_facts_carrier_not_permitted",
                    "admission_facts_not_permitted",
                    "admission facts may only be carried by the configured reserved module",
                )?]);
            }

            let target_allowed = self
                .admission_facts_targets
                .as_ref()
                .is_some_and(|targets| targets.iter().any(|id| id == &target_module_id));
            if !target_allowed {
                return Ok(vec![self.route_open_refusal_frame(
                    ctx,
                    &frame,
                    &target_module_id,
                    "admission_facts_target_not_listed",
                    "admission_facts_target_not_allowed",
                    format!(
                        "admission facts are not permitted for target module_id '{target_module_id}'"
                    ),
                )?]);
            }

            // Keep the value opaque to subc. The downstream admission validator owns
            // schema and semantic checks; this daemon only enforces carrier authority
            // and the configured destination allowlist.
        }

        // Scope admission, on the attested principal above and never on the
        // request body. The tag read here travels with the pending bind and is
        // compared with the published one at commit, so a sync between here
        // and the module's ack refuses the open instead of binding a stamp
        // that is no longer true.
        let (bound_scope, scope_stamp) = match scope {
            None => (None, None),
            Some(selector) => {
                let owner_configured = match &selector.owner {
                    // A reserved owner counts as configured from before its
                    // process is spawned (see `SupervisorHandle::is_configured`).
                    // So an owner that has not synced its scopes yet is refused
                    // as retryable (`scope_not_synced`), not as one that will
                    // never sync.
                    Principal::Reserved { module_id } => self.supervisor.is_configured(module_id),
                    _ => false,
                };
                let admitted = self
                    .scopes
                    .read()
                    .unwrap_or_else(|poisoned| poisoned.into_inner())
                    .admit(&principal, &target_module_id, &selector, owner_configured)
                    .and_then(|admission| {
                        crate::scopes::check_target_flow_support(
                            &admission.stamp,
                            &target_module_id,
                            registration.manifest.capabilities.as_ref(),
                        )?;
                        Ok(admission)
                    });
                match admitted {
                    Ok(admission) => (
                        Some(BoundScope {
                            owner: admission.owner,
                            scope_ref: admission.stamp.scope_ref.clone(),
                            tag: admission.tag,
                        }),
                        Some(admission.stamp),
                    ),
                    Err(refusal) => {
                        return Ok(vec![self.route_open_refusal_frame(
                            ctx,
                            &frame,
                            &target_module_id,
                            refusal.code,
                            refusal.code,
                            refusal.message,
                        )?]);
                    }
                }
            }
        };

        // Bind admits a root that no longer exists on disk, because refusing here
        // closes the only exit from a paused run: cancel needs a bound route, and a
        // renamed or reclaimed directory makes that route unopenable forever. The
        // run itself is intact and still addressable by its recorded identity.
        //
        // This does NOT relax the rule the strict constructor protects. That rule is
        // that no root is ever aliased into NEW durable state -- a missing component
        // can reappear as a symlink elsewhere, which would move the identity and
        // split a session's history across two of them. The engine now refuses the
        // two operations that create such state (send and import) at admission,
        // which is a narrower way to hold the same invariant: reads and terminations
        // are admitted, writes are not. That refusal had to ship before this line
        // changed, or there is an interval where a send commits under a provisional
        // identity -- the exact failure the original policy existed to prevent.
        //
        // Resolution follows realpath rather than lexical cleanup: the longest
        // existing ancestor is canonicalized and the missing tail re-appended, so a
        // live root is unchanged and a vanished leaf keeps the identity it was
        // admitted under. Lexical cleanup would mint a DIFFERENT identity for the
        // same caller the moment the directory vanished, which strands the run more
        // quietly than refusing it.
        let project_root = match ProjectRootId::from_path_allowing_missing(&identity.project_root) {
            Ok(project_root) => project_root,
            Err(err) => {
                return Ok(vec![control_error_frame(
                    &frame,
                    "invalid_project_root",
                    err.to_string(),
                )?])
            }
        };
        identity.project_root = project_root.as_path().to_path_buf();

        // Last gate before any relay work, and deliberately after the cheap
        // registry and availability checks above: those name a more precise
        // condition (unknown, removed, reloading) and a caller is better served
        // by the precise code than by this one.
        //
        // Everything below this point costs an egress permit, a reserved handle
        // pair and, if the module does not answer, the whole relay budget. The
        // reader no longer waits for that budget, so cap each target explicitly;
        // serial dispatch used to provide the accidental cap of one relay per
        // connection. Admission is a mutex-protected count and never waits.
        let _concurrency_guard = match self
            .route_bind_concurrency
            .try_admit(&target_module_id, MAX_PENDING_ROUTE_BINDS_PER_TARGET)
        {
            Ok(guard) => guard,
            Err(in_flight) => {
                return Ok(vec![self.route_open_target_capacity_refusal(
                    ctx,
                    &frame,
                    &target_module_id,
                    in_flight,
                )?]);
            }
        };

        // A module that has already burned the whole budget `threshold` times
        // in a row does not get to charge it again until a probe says it recovered.
        let mut breaker = match self.route_bind_breakers.admit(&target_module_id) {
            RouteBindAdmission::Admitted { guard, probe } => {
                if probe {
                    info!(
                        module_id = %target_module_id,
                        connection_id = ctx.connection_id.get(),
                        "route.bind breaker half-open: admitting one probe"
                    );
                }
                guard
            }
            RouteBindAdmission::Refused {
                consecutive_timeouts,
                retry_in,
                probe_in_flight,
            } => {
                return Ok(vec![self.route_open_breaker_refusal_frame(
                    ctx,
                    &frame,
                    &target_module_id,
                    consecutive_timeouts,
                    retry_in,
                    probe_in_flight,
                )?]);
            }
        };

        // Resolve the per-module budget here so the wait matches the operator's
        // intent for this specific target. A per-module override in
        // `subc.jsonc` (or `with_route_bind_relay_timeouts` for embedded
        // daemons) wins over the daemon-wide default.
        let route_bind_relay_timeout = self.route_bind_relay_timeout_for(&target_module_id);
        let relay_deadline = Instant::now() + route_bind_relay_timeout;
        let pending = match self
            .forwarding
            .begin_route_bind_relay_for(
                ctx.connection_id,
                ctx.egress.clone(),
                response_version(&frame),
                frame.header.corr,
                &target_module_id,
                principal.clone(),
                bound_scope,
                Some(project_root),
                relay_deadline,
            )
            .await
        {
            Ok(pending) => pending,
            Err(err) => {
                return Ok(vec![self.route_open_refusal_frame(
                    ctx,
                    &frame,
                    &target_module_id,
                    "relay_reservation_failed",
                    forwarding_error_code(&err),
                    err.to_string(),
                )?])
            }
        };
        let crate::forwarding::PendingRouteBindRelay {
            endpoint,
            module_sink,
            negotiated_ver,
            client_channel,
            client_epoch,
            module_channel,
            module_epoch,
            corr: relay_corr,
            receiver,
        } = pending;
        let mut reservation =
            RouteBindReservationGuard::new(Arc::clone(&self.forwarding), endpoint, relay_corr);

        // Reserving egress can wait while a module reconnects or a swap cuts
        // over. Check the connection the relay actually captured, not the
        // earlier by-id lookup: a flow-aware module must not vouch for a
        // replacement. The captured sink cannot turn into another connection.
        if let Some(stamp) = scope_stamp
            .as_ref()
            .filter(|stamp| stamp.attributes.flow_id.is_some())
        {
            let relay_registration = self
                .registry
                .get_module_by_connection(endpoint.connection_id)
                .map_err(|err| RouterError::backend(0, frame.header.corr, err.to_string()))?;
            if let Err(refusal) = crate::scopes::check_target_flow_support(
                stamp,
                &target_module_id,
                relay_registration
                    .as_ref()
                    .and_then(|registration| registration.manifest.capabilities.as_ref()),
            ) {
                reservation.release_and_disarm();
                return Ok(vec![self.route_open_refusal_frame(
                    ctx,
                    &frame,
                    &target_module_id,
                    refusal.code,
                    refusal.code,
                    refusal.message,
                )?]);
            }
        }

        debug!(
            connection_id = ctx.connection_id.get(),
            client_channel,
            client_epoch,
            module_channel,
            module_epoch,
            "reserved route handle pair"
        );
        // Rendered BEFORE the move into the relay, because the accept arm below
        // is where it is logged and the principal is gone by then.
        let principal_label = match &principal {
            Principal::Reserved { module_id } => format!("reserved:{module_id}"),
            Principal::Direct => "direct".to_string(),
            other => format!("{other:?}"),
        };
        let relay = ModuleControlRequest::RouteBind {
            route_channel: module_channel,
            epoch: module_epoch,
            target,
            identity,
            principal: Some(principal),
            consumer_capabilities,
            role_versions,
            admission_facts,
            scope: scope_stamp,
        };
        let relay_body = serde_json::to_vec(&relay).map_err(|err| {
            RouterError::backend(
                0,
                frame.header.corr,
                format!("failed to encode route.bind request: {err}"),
            )
        })?;
        let relay_frame = Frame::build_with_version(
            negotiated_ver,
            FrameType::Request,
            control_flags(),
            0,
            0,
            relay_corr,
            relay_body,
        )
        .map_err(RouterError::FrameBuild)?;

        if let Err(err) = module_sink.send(relay_frame).await {
            reservation.release_and_disarm();
            return Ok(vec![self.route_open_refusal_frame(
                ctx,
                &frame,
                &target_module_id,
                "relay_send_failed",
                "target_unavailable",
                err.to_string(),
            )?]);
        }

        if !self
            .forwarding
            .mark_route_bind_relay_enqueued(endpoint, relay_corr)
            .map_err(RouterError::Forwarding)?
        {
            self.send_abandoned_route_bind_goodbye(
                &module_sink,
                negotiated_ver,
                module_channel,
                module_epoch,
            );
        }

        match timeout_at(relay_deadline, receiver).await {
            Ok(Ok(RouteBindRelayOutcome::Accepted)) => {
                reservation.disarm();
                if breaker.record_accepted() {
                    info!(
                        module_id = %target_module_id,
                        "route.bind breaker closed: the probe was accepted"
                    );
                }
                self.observe_route_open_accept(ctx, &target_module_id, &principal_label);
                Ok(Vec::new())
            }
            Ok(Ok(RouteBindRelayOutcome::Rejected(body))) => {
                reservation.release_and_disarm();
                // A module that says no in microseconds is healthy. Rejection
                // is a different condition with its own refusal and must not
                // move the breaker.
                breaker.record_inconclusive();
                // The daemon's own commit re-check refused the bind because the
                // scope ended or changed after admission. The module accepted;
                // counting it as a module rejection would blame the module.
                let scope_code = match body.code.as_str() {
                    error_codes::SCOPE_CHANGED => Some(error_codes::SCOPE_CHANGED),
                    error_codes::SCOPE_ENDED => Some(error_codes::SCOPE_ENDED),
                    _ => None,
                };
                if let Some(code) = scope_code {
                    self.observe_route_open_refusal(
                        ctx,
                        &target_module_id,
                        "scope_changed_before_commit",
                        code,
                    );
                    return Ok(vec![control_error_body_frame(&frame, body)?]);
                }
                self.counters
                    .increment_route_open_refused("module_rejected");
                info!(
                    target: "control",
                    code = "module_rejected",
                    module_code = ?body.code,
                    module_id = ?target_module_id,
                    connection_id = ctx.connection_id.get(),
                    "route.open refused"
                );
                Ok(vec![control_error_body_frame(&frame, body)?])
            }
            Ok(Ok(RouteBindRelayOutcome::ModuleGone(message))) => {
                reservation.release_and_disarm();
                breaker.record_inconclusive();
                // Fires when the module's connection closes while a relayed
                // bind is pending -- typically a caller racing a module restart
                // whose bind was relayed BEFORE the drain mark went up. Logged
                // because the caller sees only its own error and the fleet has
                // already spent one diagnosis round unable to tell this arm
                // from a relay timeout without daemon-side evidence.
                tracing::warn!(
                    module_id = %target_module_id,
                    "route.bind relay abandoned: {message}"
                );
                Ok(vec![self.route_open_refusal_frame(
                    ctx,
                    &frame,
                    &target_module_id,
                    "relay_abandoned",
                    "target_unavailable",
                    message,
                )?])
            }
            Ok(Err(_)) => {
                reservation.release_and_disarm();
                breaker.record_inconclusive();
                Ok(vec![self.route_open_refusal_frame(
                    ctx,
                    &frame,
                    &target_module_id,
                    "relay_waiter_canceled",
                    "target_unavailable",
                    "route.bind relay waiter was canceled before the module responded",
                )?])
            }
            Err(_) => {
                reservation.release_and_disarm();
                // THE ONLY ARM THAT MOVES THE BREAKER. Budget exhausted with no
                // answer at all is the one condition a fast refusal can
                // usefully stand in for; every other arm already answered.
                if let Some(opened) = breaker.record_timeout(
                    self.route_bind_breaker_threshold,
                    self.route_bind_breaker_cooldown,
                ) {
                    warn!(
                        module_id = %target_module_id,
                        consecutive_timeouts = opened.consecutive_timeouts,
                        cooldown_ms = self.route_bind_breaker_cooldown.as_millis() as u64,
                        reopened_after_probe = opened.reopened_after_probe,
                        "route.bind breaker open: refusing route.open for this module without relaying until one probe says it recovered"
                    );
                }
                // The generous budget just burned to no answer: the module is
                // registered and its connection is up, but its bind handler sat
                // on the ack for the full budget (warm-on-bind, cold configure,
                // or a wedged handler). Every earlier unavailability shape
                // fast-refuses BEFORE the relay, so this arm firing means the
                // slowness is module-side -- log it so the per-module timeline
                // is reconstructable without client audit rows.
                tracing::warn!(
                    module_id = %target_module_id,
                    timeout_ms = route_bind_relay_timeout.as_millis() as u64,
                    "route.bind relay timed out: module did not ack within budget"
                );
                Ok(vec![self.route_open_refusal_frame(
                    ctx,
                    &frame,
                    &target_module_id,
                    "relay_timed_out",
                    "module_timeout",
                    format!(
                        "module_id '{target_module_id}' did not answer route.bind within {:?}",
                        route_bind_relay_timeout
                    ),
                )?])
            }
        }
    }

    fn handle_supervisor_spawn_snapshot(&self, frame: Frame) -> Result<Vec<Frame>, RouterError> {
        let response = ClientControlResponse::SupervisorSpawnSnapshot {
            snapshot: self.supervisor.spawn_snapshot(),
        };
        Ok(vec![control_response_body_frame(
            &frame,
            &response,
            "ClientControlResponse::SupervisorSpawnSnapshot",
        )?])
    }

    fn handle_supervisor_spawn_subscribe(
        &self,
        ctx: &RouteCtx,
        frame: Frame,
        since: Option<SpawnCursor>,
    ) -> Result<Vec<Frame>, RouterError> {
        match self.supervisor.subscribe_spawns(
            ctx.connection_id,
            frame.header.corr,
            response_version(&frame),
            since,
            ctx.egress.clone(),
        ) {
            Ok(()) => Ok(Vec::new()),
            Err(SpawnSubscribeRefusal::ForeignIncarnation { current }) => {
                Ok(vec![control_error_body_frame(
                    &frame,
                    ErrorBody {
                        code: "spawn_cursor_incarnation_mismatch".to_string(),
                        message: "spawn cursor belongs to a different daemon incarnation"
                            .to_string(),
                        detail: Some(serde_json::json!({
                            "current_daemon_incarnation": current
                        })),
                    },
                )?])
            }
            Err(SpawnSubscribeRefusal::TooOld { oldest }) => Ok(vec![control_error_body_frame(
                &frame,
                ErrorBody {
                    code: "spawn_cursor_too_old".to_string(),
                    message: "spawn cursor predates the retained event ring".to_string(),
                    detail: Some(serde_json::json!({
                        "oldest_retained_cursor": oldest
                    })),
                },
            )?]),
            Err(SpawnSubscribeRefusal::Frame(error)) => Err(RouterError::backend(
                0,
                frame.header.corr,
                format!("failed to open supervisor spawn subscription: {error}"),
            )),
        }
    }

    async fn handle_supervisor_list(&self, frame: Frame) -> Result<Vec<Frame>, RouterError> {
        let generation = self
            .registry
            .generation()
            .map_err(|err| RouterError::backend(0, frame.header.corr, err.to_string()))?;
        let mut modules = Vec::new();
        for module in self.supervisor.list() {
            let status = module.status_for_control("list").map_err(|err| {
                RouterError::backend(
                    0,
                    frame.header.corr,
                    format!("failed to read supervisor status: {err}"),
                )
            })?;
            let (configured, _) = module.configuration().map_err(|err| {
                RouterError::backend(
                    0,
                    frame.header.corr,
                    format!("failed to read module configuration: {err}"),
                )
            })?;
            // Status and configuration snapshots release their locks before the image probe awaits.
            let image = module.running_image_agreement().await;
            // Read per request so the figure is current when the operator asks;
            // the daemon samples nothing in between.
            let resources = Some(module.child_resource_usage());
            let pending_reload = Some(reload_verdict(
                &configured.program,
                status.spawned_from.as_deref(),
                image,
            ));
            modules.push(SupervisorEntry {
                // Keep the retired policy field on the wire for one release so
                // existing status consumers still receive the platform policy.
                launch_nonce_env: Some(!cfg!(unix)),
                module_id: status.module_id,
                state: status.state.to_string(),
                enabled: status.enabled,
                live: status.live,
                protocol: status.protocol,
                health: status.health.status,
                pending_reload,
                last_probe_ms: status.health.last_probe_ms,
                last_exit_code: status.last_exit.as_ref().and_then(|e| e.code),
                last_exit_signal: status.last_exit.as_ref().and_then(|e| e.signal),
                last_exit_ms: status.last_exit.as_ref().map(|e| e.at_ms),
                last_exit_kind: status.last_exit.as_ref().map(|e| e.kind.into()),
                restart_count: Some(status.restart_count),
                max_restarts: Some(status.max_restarts),
                lifetime_restarts: Some(status.lifetime_restarts),
                spawn_generation: Some(status.spawn_generation),
                restart_window_secs: Some(status.restart_window.as_secs()),
                drain_timeout_ms: Some(status.drain_timeout.as_millis() as u64),
                restart_backoff_ms: Some(status.restart_backoff.as_millis() as u64),
                restart_max_backoff_ms: Some(status.restart_max_backoff.as_millis() as u64),
                resources,
            });
        }
        let response = ClientControlResponse::SupervisorList {
            generation,
            modules,
        };
        Ok(vec![control_response_body_frame(
            &frame,
            &response,
            "ClientControlResponse::SupervisorList",
        )?])
    }

    fn handle_supervisor_stderr_tail(
        &self,
        frame: Frame,
        module_id: String,
        max_lines: Option<u32>,
        max_bytes: Option<u32>,
    ) -> Result<Vec<Frame>, RouterError> {
        let Some(module) = self.supervisor.get(&module_id) else {
            return Ok(vec![control_error_frame(
                &frame,
                "unknown_module",
                format!("module_id '{module_id}' is not supervised"),
            )?]);
        };

        let snapshot = module.stderr_tail(
            max_lines.map(|value| value as usize),
            max_bytes.map(|value| value as usize),
        );

        let response = ClientControlResponse::SupervisorStderrTail {
            module_id,
            tail: StderrTail {
                capture: match snapshot.capture {
                    CaptureState::Captured => StderrCaptureState::Captured,
                    CaptureState::Incomplete { reason } => {
                        StderrCaptureState::Incomplete { reason }
                    }
                    CaptureState::NotCaptured { reason } => {
                        StderrCaptureState::NotCaptured { reason }
                    }
                },
                entries: snapshot
                    .entries
                    .into_iter()
                    .map(|entry| match entry {
                        TailEntry::Line {
                            text,
                            truncated,
                            at_ms,
                        } => StderrTailEntry::Line {
                            text,
                            truncated,
                            at_ms,
                        },
                        TailEntry::ProcessStart => StderrTailEntry::ProcessStart,
                    })
                    .collect(),
                dropped_lines: snapshot.dropped_lines,
            },
        };
        Ok(vec![control_response_body_frame(
            &frame,
            &response,
            "ClientControlResponse::SupervisorStderrTail",
        )?])
    }

    async fn handle_supervisor_terminals(
        &self,
        frame: Frame,
        module_id: String,
    ) -> Result<Vec<Frame>, RouterError> {
        let Some(module) = self.supervisor.get(&module_id) else {
            return Ok(vec![control_error_frame(
                &frame,
                "unknown_module",
                format!("module_id '{module_id}' is not supervised"),
            )?]);
        };

        // The journal read runs on a blocking thread: it can be megabytes of
        // file I/O and must not occupy a runtime worker.
        let terminals = module
            .read_durable_terminal_history()
            .await
            .map_err(|error| {
                RouterError::backend(
                    0,
                    frame.header.corr,
                    format!("failed to read terminal history: {error}"),
                )
            })?;
        let response = ClientControlResponse::SupervisorTerminals {
            module_id,
            terminals,
        };
        Ok(vec![control_response_body_frame(
            &frame,
            &response,
            "ClientControlResponse::SupervisorTerminals",
        )?])
    }

    fn handle_supervisor_routes(
        &self,
        frame: Frame,
        module_id: Option<String>,
    ) -> Result<Vec<Frame>, RouterError> {
        let modules = self
            .forwarding
            .route_census(module_id.as_deref())
            .map_err(RouterError::Forwarding)?
            .into_iter()
            .map(|(module_id, routes)| SupervisorRouteModule {
                module_id,
                routes: routes
                    .into_iter()
                    .map(|route| SupervisorRoute {
                        consumer: match route.principal {
                            Principal::Reserved { module_id } => {
                                SupervisorRouteConsumer::Reserved { module_id }
                            }
                            Principal::Direct | Principal::Unverified => {
                                SupervisorRouteConsumer::Direct {
                                    connection_id: route.goodbye_target.connection_id.get(),
                                }
                            }
                        },
                        age_ms: Instant::now()
                            .saturating_duration_since(route.bound_at)
                            .as_millis()
                            .try_into()
                            .unwrap_or(u64::MAX),
                        draining: route.draining,
                        drain_reason: route.drain_reason,
                    })
                    .collect(),
            })
            .collect();
        let response = ClientControlResponse::SupervisorRoutes { modules };
        Ok(vec![control_response_body_frame(
            &frame,
            &response,
            "ClientControlResponse::SupervisorRoutes",
        )?])
    }

    async fn handle_supervisor_provenance(
        &self,
        frame: Frame,
        module_id: Option<String>,
    ) -> Result<Vec<Frame>, RouterError> {
        let mut selected = if let Some(module_id) = module_id {
            let Some(module) = self.supervisor.get(&module_id) else {
                return Ok(vec![control_error_frame(
                    &frame,
                    "unknown_module",
                    format!("module_id '{module_id}' is not supervised"),
                )?]);
            };
            vec![module]
        } else {
            self.supervisor.list()
        };

        let mut modules = Vec::with_capacity(selected.len());
        for module in selected.drain(..) {
            let status = module.status().map_err(|err| {
                RouterError::backend(
                    0,
                    frame.header.corr,
                    format!("failed to read supervisor status: {err}"),
                )
            })?;
            let module_declared = self
                .registry
                .get_module(&status.module_id)
                .map_err(|err| RouterError::backend(0, frame.header.corr, err.to_string()))?
                .and_then(|registration| registration.manifest.provenance)
                .map(|build| ModuleDeclaredProvenance::Reported { build })
                .unwrap_or(ModuleDeclaredProvenance::Unverifiable);
            #[cfg(test)]
            let running_image = match &self.provenance_probe_override {
                Some(result) => result.clone(),
                None => module.running_image_agreement().await,
            };
            #[cfg(not(test))]
            let running_image = module.running_image_agreement().await;
            modules.push(SupervisorModuleProvenance {
                module_id: status.module_id,
                module_declared,
                daemon_observed: SupervisorObservedProcess {
                    pid: status.pid,
                    spawned_at_ms: status.spawned_at_ms,
                    spawned_from: status.spawned_from,
                    running_image,
                },
            });
        }
        let daemon = SupervisorDaemonProvenance {
            daemon_build: self.daemon_provenance.build.clone(),
            daemon_observed: DaemonObservedProcess {
                pid: self.daemon_provenance.pid,
                started_at_ms: self
                    .daemon_provenance
                    .start_clock
                    .map(|clock| clock.started_at_ms())
                    .or(self.daemon_provenance.started_at_ms),
                running_image: self
                    .daemon_provenance
                    .probe
                    .observe(
                        self.daemon_provenance.pid,
                        self.daemon_provenance.executable_path.as_deref(),
                        self.daemon_provenance.executable_identity,
                        self.daemon_provenance.process_start_time,
                    )
                    .await,
            },
        };
        let response = ClientControlResponse::SupervisorProvenance { daemon, modules };
        Ok(vec![control_response_body_frame(
            &frame,
            &response,
            "ClientControlResponse::SupervisorProvenance",
        )?])
    }

    fn handle_supervisor_health(&self, frame: Frame) -> Result<Vec<Frame>, RouterError> {
        self.refresh_capability_requirements();
        let generation = self
            .registry
            .generation()
            .map_err(|err| RouterError::backend(0, frame.header.corr, err.to_string()))?;
        let modules = self
            .supervisor
            .list()
            .into_iter()
            .map(|module| {
                let status = module.status_for_control("health").map_err(|err| {
                    RouterError::backend(
                        0,
                        frame.header.corr,
                        format!("failed to read supervisor health: {err}"),
                    )
                })?;
                let module_id = status.module_id;
                let capability_detail = self
                    .capability_evaluator
                    .required_problem_detail(&module_id);
                Ok(SupervisorHealthEntry {
                    module_id,
                    status: status.health.status,
                    detail: append_capability_problem_detail(
                        status.health.detail,
                        capability_detail,
                    ),
                    metrics: status.health.metrics,
                    consecutive_failures: status.health.consecutive_failures,
                    late_answer_count: status.health.late_answer_count,
                    last_late_answer_latency_ms: status.health.last_late_answer_latency_ms,
                    last_action: status.health.last_action,
                    last_action_ms: status.health.last_action_ms,
                    last_probe_ms: status.health.last_probe_ms,
                })
            })
            .collect::<Result<Vec<_>, RouterError>>()?;
        let response = ClientControlResponse::SupervisorHealth {
            generation,
            modules,
        };
        Ok(vec![control_response_body_frame(
            &frame,
            &response,
            "ClientControlResponse::SupervisorHealth",
        )?])
    }

    async fn handle_supervisor_restart(
        &self,
        frame: Frame,
        module_id: String,
        drain_timeout_ms: Option<u64>,
    ) -> Result<Vec<Frame>, RouterError> {
        let operation_lock = self.supervisor.operation_lock();
        let _operation_guard = operation_lock.lock().await;
        let Some(module) = self.supervisor.get(&module_id) else {
            return Ok(vec![control_error_frame(
                &frame,
                "unknown_module",
                format!("module_id '{module_id}' is not supervised"),
            )?]);
        };

        self.route_outages.mark_operator_action(&module_id);
        if let Err(err) = module.restart(drain_timeout_ms).await {
            self.route_outages
                .operator_action_ended_unrefused(&module_id);
            let (code, message) = match err {
                crate::supervise::SuperviseError::Disabled { .. } => {
                    ("module_disabled", err.to_string())
                }
                crate::supervise::SuperviseError::SwapInProgress { .. } => {
                    ("swap_in_progress", err.to_string())
                }
                _ => (
                    "target_unavailable",
                    format!("failed to restart module_id '{module_id}': {err}"),
                ),
            };
            return Ok(vec![control_error_frame(&frame, code, message)?]);
        }

        let response = ClientControlResponse::SupervisorAck {
            module_id,
            applied: true,
        };
        Ok(vec![control_response_body_frame(
            &frame,
            &response,
            "ClientControlResponse::SupervisorAck",
        )?])
    }

    /// `supervisor.swap`. Answered when the swap has cut over or failed, not
    /// when the old process has finished draining: a caller whose own lane
    /// rides the old process must get its reply before that drain waits on it.
    async fn handle_supervisor_swap(
        &self,
        frame: Frame,
        module_id: String,
        ready_timeout_ms: Option<u64>,
    ) -> Result<Vec<Frame>, RouterError> {
        // The daemon-wide operation lock is held only to resolve the handle,
        // not across the swap. The swap can take its whole readiness budget,
        // and `supervisor.set_enabled` (ck module stop) takes the same lock:
        // holding it here would park an operator's stop behind the swap it is
        // meant to abort. A rescan or stop that reaches the module during the
        // swap is served by the swap itself (see `supervise_swap`).
        let module = {
            let operation_lock = self.supervisor.operation_lock();
            let _operation_guard = operation_lock.lock().await;
            self.supervisor.get(&module_id)
        };
        let Some(module) = module else {
            return Ok(vec![control_error_frame(
                &frame,
                "unknown_module",
                format!("module_id '{module_id}' is not supervised"),
            )?]);
        };

        self.route_outages.mark_operator_action(&module_id);
        if let Err(err) = module
            .swap(ready_timeout_ms.map(Duration::from_millis))
            .await
        {
            self.route_outages
                .operator_action_ended_unrefused(&module_id);
            use crate::supervise::SuperviseError;
            let message = err.to_string();
            let error = match err {
                SuperviseError::Disabled { .. } => ErrorBody::new("module_disabled", message),
                SuperviseError::SwapRefused { reason, .. } => ErrorBody {
                    code: "swap_refused".to_string(),
                    message,
                    detail: Some(serde_json::json!({ "reason": reason.as_str() })),
                },
                SuperviseError::SwapFailed {
                    arm,
                    candidate_exit,
                    ..
                } => ErrorBody {
                    code: "swap_failed".to_string(),
                    message,
                    detail: Some(serde_json::json!({
                        "arm": arm.as_str(),
                        "candidate_exit_code": candidate_exit.as_ref().and_then(|exit| exit.code),
                        "candidate_exit_signal": candidate_exit.as_ref().and_then(|exit| exit.signal),
                    })),
                },
                _ => ErrorBody::new(
                    "target_unavailable",
                    format!("failed to swap module_id '{module_id}': {message}"),
                ),
            };
            return Ok(vec![control_error_body_frame(&frame, error)?]);
        }
        // A completed swap kept the incumbent serving until cutover, so it
        // usually opened no outage; a mark left behind would make the next,
        // unrelated outage read as requested.
        self.route_outages
            .operator_action_ended_unrefused(&module_id);

        let response = ClientControlResponse::SupervisorAck {
            module_id,
            applied: true,
        };
        Ok(vec![control_response_body_frame(
            &frame,
            &response,
            "ClientControlResponse::SupervisorAck",
        )?])
    }

    async fn handle_supervisor_reload(
        &self,
        frame: Frame,
        module_id: String,
    ) -> Result<Vec<Frame>, RouterError> {
        let operation_lock = self.supervisor.operation_lock();
        let _operation_guard = operation_lock.lock().await;
        let Some(module) = self.supervisor.get(&module_id) else {
            return Ok(vec![control_error_frame(
                &frame,
                "unknown_module",
                format!("module_id '{module_id}' is not supervised"),
            )?]);
        };

        self.route_outages.mark_operator_action(&module_id);
        if let Err(err) = module.reload().await {
            self.route_outages
                .operator_action_ended_unrefused(&module_id);
            let (code, message) = match err {
                crate::supervise::SuperviseError::Disabled { .. } => {
                    ("module_disabled", err.to_string())
                }
                crate::supervise::SuperviseError::SwapInProgress { .. } => {
                    ("swap_in_progress", err.to_string())
                }
                _ => (
                    "reload_failed",
                    format!("failed to reload module_id '{module_id}': {err}"),
                ),
            };
            return Ok(vec![control_error_frame(&frame, code, message)?]);
        }

        let response = ClientControlResponse::SupervisorAck {
            module_id,
            applied: true,
        };
        Ok(vec![control_response_body_frame(
            &frame,
            &response,
            "ClientControlResponse::SupervisorAck",
        )?])
    }

    async fn handle_supervisor_rescan(
        &self,
        frame: Frame,
        preview: bool,
    ) -> Result<Vec<Frame>, RouterError> {
        let Some(context) = self.rescan.clone() else {
            return Ok(vec![control_error_frame(
                &frame,
                "rescan_unavailable",
                "the daemon was not started with a reloadable config path".to_string(),
            )?]);
        };

        let operation_lock = self.supervisor.operation_lock();
        let _operation_guard = operation_lock.lock().await;
        let loaded = match crate::daemon_config::load(&context.config_path) {
            Ok(config) => config,
            Err(err) => {
                return Ok(vec![control_error_frame(
                    &frame,
                    "invalid_daemon_config",
                    format!("supervisor rescan rejected daemon config: {err}"),
                )?])
            }
        };
        // `load` reports a missing file as Ok(None), which is correct at boot
        // (no config, nothing to supervise) and catastrophic here: rescan treats
        // "not in the config" as "remove it", so an absent file would read as an
        // empty module list and retire the entire running fleet. An editor
        // writing via write-new-then-rename, or a half-finished edit, is enough
        // to open that window. Refuse instead: a config that cannot be read
        // carries no instruction to remove anything.
        let Some(config) = loaded else {
            return Ok(vec![control_error_frame(
                &frame,
                "invalid_daemon_config",
                format!(
                    "daemon config not found at {}; refusing to rescan (an absent config would \
                     retire every supervised module)",
                    context.config_path.display()
                ),
            )?]);
        };
        let (
            configured_port,
            storage_config,
            admission_facts_carrier_module_id,
            admission_facts_targets,
            scope_authority_owners,
            modules,
            reserved_capabilities,
        ) = (
            config.port,
            config.storage,
            config.admission_facts_carrier_module_id,
            config.admission_facts_targets,
            config.scope_authority_owners,
            config.modules,
            config.reserved_capabilities,
        );

        // Collect the sections rescan cannot apply, so the REPLY carries them.
        //
        // The warning below has always been correct and has always gone only to
        // the journal -- addressed to whoever reads logs, while the person who
        // just edited the config is looking at the CLI. Naming each section
        // individually rather than setting a flag: "something outside modules
        // changed" sends the operator back to diffing their own file, which is
        // the work this is meant to save.
        let mut restart_required = Vec::new();
        for section in RestartRequiredSection::ALL {
            let changed = match section {
                RestartRequiredSection::Port => configured_port != context.configured_port,
                RestartRequiredSection::Storage => storage_config != context.storage_config,
                RestartRequiredSection::AdmissionFactsCarrierModuleId => {
                    admission_facts_carrier_module_id != context.admission_facts_carrier_module_id
                }
                RestartRequiredSection::AdmissionFactsTargets => {
                    admission_facts_targets != context.admission_facts_targets
                }
                RestartRequiredSection::ScopeAuthorityOwners => {
                    scope_authority_owners != context.scope_authority_owners
                }
            };
            if changed {
                restart_required.push(section.label().to_string());
            }
        }
        if !restart_required.is_empty() {
            warn!(
                config_path = %context.config_path.display(),
                sections = %restart_required.join(", "),
                "daemon config changed outside the modules section; restart the daemon to apply those changes"
            );
        }

        for configured in &modules {
            if let Err(err) = validate_spec(&configured.module_spec()) {
                return Ok(vec![control_error_frame(
                    &frame,
                    "invalid_daemon_config",
                    format!("supervisor rescan rejected daemon config: {err}"),
                )?]);
            }
        }

        let configured_capabilities = modules
            .iter()
            .map(|module| (module.module_id.clone(), module.enabled))
            .collect::<Vec<_>>();
        let preview_capability_warnings = if preview {
            let (_, registrations) = self.runtime_capability_snapshot()?;
            let current_modules = self
                .supervisor
                .list()
                .into_iter()
                .map(|module| module.module_id().to_string())
                .collect::<BTreeSet<_>>();
            let resulting_modules = configured_capabilities.clone();
            let removed = current_modules
                .into_iter()
                .filter(|module_id| {
                    !resulting_modules
                        .iter()
                        .any(|(configured_id, _)| configured_id == module_id)
                })
                .collect::<Vec<_>>();
            self.capability_evaluator.preview_removal_warnings(
                resulting_modules,
                &removed,
                &registrations,
            )
        } else {
            Vec::new()
        };
        let result = match self
            .reconcile_supervised_modules(&context.supervisor, modules, preview)
            .await
        {
            Ok(result) => result,
            Err(message) => {
                return Ok(vec![control_error_frame(&frame, "rescan_failed", message)?])
            }
        };
        if !preview {
            self.capability_evaluator
                .configure(configured_capabilities, reserved_capabilities);
            self.capability_evaluator.wake_deadline_loop();
            self.refresh_capability_requirements();
        }
        let mut result = result;
        result.restart_required = restart_required;
        result.capability_warnings = preview_capability_warnings;
        let response = ClientControlResponse::SupervisorRescan { result };
        Ok(vec![control_response_body_frame(
            &frame,
            &response,
            "ClientControlResponse::SupervisorRescan",
        )?])
    }

    async fn handle_supervisor_release_reserved(
        &self,
        frame: Frame,
        module_id: String,
    ) -> Result<Vec<Frame>, RouterError> {
        let Some(context) = self.rescan.clone() else {
            return Ok(vec![control_error_frame(
                &frame,
                "release_unavailable",
                "reserved-id release requires a daemon started with a reloadable config path",
            )?]);
        };
        let operation_lock = self.supervisor.operation_lock();
        let _operation_guard = operation_lock.lock().await;
        let loaded = match crate::daemon_config::load(&context.config_path) {
            Ok(Some(config)) => config,
            Ok(None) => {
                return Ok(vec![control_error_frame(
                    &frame,
                    "invalid_daemon_config",
                    format!(
                        "daemon config not found at {}; refusing to release reserved module_id '{module_id}'",
                        context.config_path.display()
                    ),
                )?])
            }
            Err(err) => {
                return Ok(vec![control_error_frame(
                    &frame,
                    "invalid_daemon_config",
                    format!("unable to verify reserved-id release against daemon config: {err}"),
                )?])
            }
        };
        if loaded
            .modules
            .iter()
            .any(|configured| configured.module_id == module_id)
        {
            return Ok(vec![control_error_frame(
                &frame,
                "reserved_module_configured",
                format!(
                    "module_id '{module_id}' remains configured; remove its config entry and rescan before releasing its reserved id"
                ),
            )?]);
        }
        if !self.supervisor.release_retained_reserved_gate(&module_id) {
            return Ok(vec![control_error_frame(
                &frame,
                "reserved_gate_not_retained",
                format!(
                    "module_id '{module_id}' has no retired reserved-id gate to release; rescan its removed reserved configuration first"
                ),
            )?]);
        }

        let response = ClientControlResponse::SupervisorAck {
            module_id,
            applied: true,
        };
        Ok(vec![control_response_body_frame(
            &frame,
            &response,
            "ClientControlResponse::SupervisorAck",
        )?])
    }

    /// Reconcile the running module set against the configured one.
    ///
    /// With `preview` set, the diff is computed and returned WITHOUT applying any
    /// of it: nothing is retired, reconfigured, enabled or spawned. The preview
    /// deliberately shares this function with the executing path rather than
    /// computing the same diff somewhere else -- two implementations of one
    /// decision agree until they do not, and the whole value of a preview is that
    /// it describes the operation that will actually run.
    async fn reconcile_supervised_modules(
        &self,
        supervisor: &Supervisor,
        configured_modules: Vec<crate::daemon_config::ConfiguredModule>,
        preview: bool,
    ) -> Result<SupervisorRescanResult, String> {
        let mut current = BTreeMap::new();
        for module in self.supervisor.list() {
            let (spec, health) = module.configuration().map_err(|err| {
                format!(
                    "failed to read configuration for module_id '{}': {err}",
                    module.module_id()
                )
            })?;
            let enabled = module
                .status()
                .map_err(|err| {
                    format!(
                        "failed to read status for module_id '{}': {err}",
                        module.module_id()
                    )
                })?
                .enabled;
            current.insert(
                module.module_id().to_string(),
                (module, spec, health, enabled),
            );
        }
        let configured = configured_modules
            .into_iter()
            .map(|module| (module.module_id.clone(), module))
            .collect::<BTreeMap<_, _>>();

        let added = configured
            .keys()
            .filter(|module_id| !current.contains_key(*module_id))
            .cloned()
            .collect::<Vec<_>>();
        let removed = current
            .keys()
            .filter(|module_id| !configured.contains_key(*module_id))
            .cloned()
            .collect::<Vec<_>>();
        let mut changed_pending_reload = Vec::new();
        let mut configuration_changes = BTreeSet::new();
        let mut enabled_changes = BTreeSet::new();
        let mut unchanged = 0_u32;

        for (module_id, configured_module) in &configured {
            let Some((_, current_spec, current_health, current_enabled)) = current.get(module_id)
            else {
                continue;
            };
            // Compare the whole launch spec so a future launch field cannot
            // accidentally become a live-only policy change. Health is stored
            // separately and applies live without replacing the process.
            let launch_changed = *current_spec != configured_module.module_spec();
            let configuration_changed =
                launch_changed || *current_health != configured_module.health;
            let enabled_changed = *current_enabled != configured_module.enabled;
            if configuration_changed {
                configuration_changes.insert(module_id.clone());
            }
            if launch_changed {
                changed_pending_reload.push(module_id.clone());
            }
            if enabled_changed {
                enabled_changes.insert(module_id.clone());
            }
            if !configuration_changed && !enabled_changed {
                unchanged = unchanged.saturating_add(1);
            }
        }

        // Everything above this point is pure computation over two snapshots.
        // Everything below MUTATES. The preview returns here so the boundary is a
        // single early return rather than a condition repeated at each mutation
        // site, where one missed guard would apply part of a change the caller was
        // told would not happen.
        if preview {
            return Ok(SupervisorRescanResult {
                added,
                removed,
                changed_pending_reload,
                enabled_changes: enabled_changes.iter().cloned().collect(),
                unchanged,
                preview: true,
                // Filled by the caller on both paths, so the preview reports
                // restart-required sections identically to an executed rescan --
                // the preview is where an operator is most likely to be looking.
                restart_required: Vec::new(),
                capability_warnings: Vec::new(),
            });
        }

        for module_id in &removed {
            let module = &current
                .get(module_id)
                .expect("removed module came from current supervisor state")
                .0;
            module.retire().await.map_err(|err| {
                format!("failed to retire module_id '{module_id}' during rescan: {err}")
            })?;
            // TOMBSTONE BEFORE RETIRE, and the order is the whole fix.
            //
            // `handle_route_open` resolves an absent module in three steps:
            // registry, then supervisor status, then tombstone. Retiring first
            // opens a window where ALL THREE ARE ABSENT -- the registry entry
            // went with the teardown above, the supervisor entry went with
            // `retire`, and the tombstone does not exist yet -- so a route.open
            // landing in it gets `unknown_module` (RETRYABLE, "never heard of
            // it") for a module that was deliberately removed and whose caller
            // should get `module_removed` (TERMINAL, carrying a removal age).
            //
            // Writing the tombstone first closes it: during the window the
            // supervisor entry still answers, so the caller gets
            // `target_unavailable` -- retryable, and TRUE, because the module
            // is mid-teardown. After both statements it is `module_removed`.
            // No instant remains where a removed module reads as one that
            // never existed.
            //
            // NOT DETERMINISTICALLY TESTABLE FROM HERE, said plainly because
            // the absence of a test beside a fix invites deletion: these are
            // two sync statements with no await between them, so reaching the
            // window needs a second worker thread to land exactly between them
            // and there is no hook to force it. MEASURED: the 25 daemon_config
            // tests pass identically with the old order and the new one, so
            // the existing suite cannot see this and a green run is not
            // evidence either way. What the suite does hold is the
            // post-condition -- a removed module answers `module_removed` --
            // which this preserves.
            //
            // Found by an Athena panel reading the shipped tree against a
            // design note (2026-09-19), as the one concrete instance of that
            // note's class that survived contact with source. Direction is
            // benign: retryable where terminal was intended, never the reverse.
            self.supervisor.record_rescan_removal(module_id);
            self.supervisor.retire(module_id);
            self.route_outages.forget(module_id);
        }

        for module_id in configured.keys() {
            let Some((module, _, _, _)) = current.get(module_id) else {
                continue;
            };
            let configured_module = configured
                .get(module_id)
                .expect("configured module id came from configured map");
            if configuration_changes.contains(module_id) {
                module
                    .update_configuration(
                        configured_module.module_spec(),
                        configured_module.health.clone(),
                        configured_module.drain_timeout_ms,
                    )
                    .await
                    .map_err(|err| {
                        format!(
                            "failed to update module_id '{module_id}' configuration during rescan: {err}"
                        )
                    })?;
            }
            if enabled_changes.contains(module_id) {
                // A rescan that starts or stops a module applies an operator's
                // edit to the config, so the resulting outage was asked for.
                self.route_outages.mark_operator_action(module_id);
                module
                    .set_enabled(configured_module.enabled)
                    .await
                    .map_err(|err| {
                        self.route_outages.operator_action_ended_unrefused(module_id);
                        format!(
                            "failed to apply module_id '{module_id}' enabled={} during rescan: {err}",
                            configured_module.enabled
                        )
                    })?;
            }
        }

        for module_id in &added {
            let configured_module = configured
                .get(module_id)
                .expect("added module id came from configured map");
            supervisor
                .supervise_configured_with_health(
                    configured_module.module_spec(),
                    configured_module.enabled,
                    configured_module.health.clone(),
                    configured_module.drain_timeout_ms,
                    configured_module.restart,
                )
                .map_err(|err| {
                    format!("failed to add module_id '{module_id}' during rescan: {err}")
                })?;
        }

        Ok(SupervisorRescanResult {
            added,
            removed,
            changed_pending_reload,
            enabled_changes: enabled_changes.iter().cloned().collect(),
            unchanged,
            preview: false,
            // Filled by the caller, which is the only layer that can see the
            // previous config to diff against.
            restart_required: Vec::new(),
            capability_warnings: Vec::new(),
        })
    }

    async fn handle_supervisor_set_enabled(
        &self,
        frame: Frame,
        module_id: String,
        enabled: bool,
    ) -> Result<Vec<Frame>, RouterError> {
        let operation_lock = self.supervisor.operation_lock();
        let _operation_guard = operation_lock.lock().await;
        let Some(module) = self.supervisor.get(&module_id) else {
            return Ok(vec![control_error_frame(
                &frame,
                "unknown_module",
                format!("module_id '{module_id}' is not supervised"),
            )?]);
        };

        // Enabling counts as well as disabling: a module an operator starts
        // is refused until it registers, and that wait was asked for.
        self.route_outages.mark_operator_action(&module_id);
        let applied = match module.set_enabled(enabled).await {
            Ok(applied) => applied,
            Err(err) => {
                self.route_outages
                    .operator_action_ended_unrefused(&module_id);
                return Ok(vec![control_error_frame(
                    &frame,
                    "target_unavailable",
                    format!("failed to set module_id '{module_id}' enabled={enabled}: {err}"),
                )?]);
            }
        };
        if !applied {
            // Already in the requested state: nothing was made unavailable,
            // so the mark must not outlive this request.
            self.route_outages
                .operator_action_ended_unrefused(&module_id);
        }

        self.capability_evaluator.wake_deadline_loop();
        self.refresh_capability_requirements();
        let response = ClientControlResponse::SupervisorAck { module_id, applied };
        Ok(vec![control_response_body_frame(
            &frame,
            &response,
            "ClientControlResponse::SupervisorAck",
        )?])
    }

    async fn handle_supervisor_health_probe(
        &self,
        frame: Frame,
        module_id: String,
    ) -> Result<Vec<Frame>, RouterError> {
        self.refresh_capability_requirements();
        let Some(registration) = self
            .registry
            .get_module(&module_id)
            .map_err(|err| RouterError::backend(0, frame.header.corr, err.to_string()))?
        else {
            return Ok(vec![control_error_frame(
                &frame,
                "unknown_module",
                format!("module_id '{module_id}' is not registered"),
            )?]);
        };

        // This guard's ACCEPT direction is fenced, but only INCIDENTALLY: no test is
        // named for it. Making `module_registration_grants_op` return false
        // unconditionally reddens five tests, and every one is named for something
        // else -- capability relay, probe/bind demultiplexing, supervision-only
        // probing. They exercise a successful advertisement check on the way to their
        // own subject.
        //
        // Real protection, fragile in a specific way: narrowing any of those tests to
        // focus on its stated subject would silently remove coverage nobody knows
        // they are carrying. Recorded here rather than as a sixth test, because the
        // useful fact is WHICH tests hold the guard up -- a new test would add
        // coverage without telling the next person what the existing ones quietly do.
        if !module_registration_grants_op(&registration.control_ops, MODULE_CONTROL_OP_HEALTH_CHECK)
        {
            return Ok(vec![control_error_frame(
                &frame,
                "health_not_advertised",
                format!("module_id '{module_id}' did not advertise health.check"),
            )?]);
        }

        let deadline = Instant::now() + self.health_probe_timeout;
        let pending = match self.forwarding.begin_module_control_rpc_for(
            &module_id,
            MODULE_CONTROL_OP_HEALTH_CHECK,
            deadline,
        ) {
            Ok(pending) => pending,
            Err(err) => {
                return Ok(vec![control_error_frame(
                    &frame,
                    forwarding_error_code(&err),
                    err.to_string(),
                )?])
            }
        };

        let PendingModuleControlRpc {
            endpoint,
            module_sink,
            negotiated_ver,
            corr: probe_corr,
            receiver,
        } = pending;
        let mut guard =
            ModuleControlRpcGuard::new(Arc::clone(&self.forwarding), endpoint, probe_corr);
        let probe_body =
            serde_json::to_vec(&ModuleControlRequest::HealthCheck {}).map_err(|err| {
                RouterError::backend(
                    0,
                    frame.header.corr,
                    format!("failed to encode health.check request: {err}"),
                )
            })?;
        let probe_frame = Frame::build_with_version(
            negotiated_ver,
            FrameType::Request,
            control_flags(),
            0,
            0,
            probe_corr,
            probe_body,
        )
        .map_err(RouterError::FrameBuild)?;

        if let Err(err) = module_sink.send(probe_frame).await {
            return Ok(vec![control_error_frame(
                &frame,
                "target_unavailable",
                err.to_string(),
            )?]);
        }

        match timeout_at(deadline, receiver).await {
            Ok(Ok(ModuleControlRpcOutcome::Response(response))) => {
                guard.disarm();
                let Some(report) = response.health_report() else {
                    return Ok(vec![control_error_frame(
                        &frame,
                        "invalid_control_body",
                        "health.check RPC returned a non-health response",
                    )?]);
                };
                // Metrics go out whole here. The supervisor's cached snapshot
                // caps this blob (see truncate_health_metrics), and this path
                // exists precisely to answer without that cap -- so applying it
                // here would leave no way to see what the cached view drops.
                let HealthReport {
                    status,
                    detail,
                    metrics,
                } = report;
                let capability_detail = self
                    .capability_evaluator
                    .required_problem_detail(&module_id);
                let response = ClientControlResponse::SupervisorHealthProbe {
                    module_id,
                    status,
                    detail: append_capability_problem_detail(detail, capability_detail),
                    metrics,
                };
                Ok(vec![control_response_body_frame(
                    &frame,
                    &response,
                    "ClientControlResponse::SupervisorHealthProbe",
                )?])
            }
            Ok(Ok(ModuleControlRpcOutcome::Rejected(body))) => {
                guard.disarm();
                Ok(vec![control_error_body_frame(&frame, body)?])
            }
            Ok(Ok(ModuleControlRpcOutcome::ModuleGone(message))) => {
                guard.disarm();
                Ok(vec![control_error_frame(
                    &frame,
                    "target_unavailable",
                    message,
                )?])
            }
            Ok(Ok(ModuleControlRpcOutcome::MalformedResponse(message))) => {
                guard.disarm();
                Ok(vec![control_error_frame(
                    &frame,
                    "invalid_control_body",
                    message,
                )?])
            }
            Ok(Ok(ModuleControlRpcOutcome::UnexpectedOp { expected, actual })) => {
                guard.disarm();
                Ok(vec![control_error_frame(
                    &frame,
                    "invalid_control_body",
                    format!("expected module-control op '{expected}', got '{actual}'"),
                )?])
            }
            Ok(Ok(ModuleControlRpcOutcome::DeadlineElapsed)) => {
                guard.disarm();
                Ok(vec![control_error_frame(
                    &frame,
                    "module_timeout",
                    format!(
                        "module_id '{module_id}' answered health.check after {:?}",
                        self.health_probe_timeout
                    ),
                )?])
            }
            Ok(Err(_)) => Ok(vec![control_error_frame(
                &frame,
                "target_unavailable",
                "health.check waiter was canceled before the module responded",
            )?]),
            Err(_) => Ok(vec![control_error_frame(
                &frame,
                "module_timeout",
                format!(
                    "module_id '{module_id}' did not answer health.check within {:?}",
                    self.health_probe_timeout
                ),
            )?]),
        }
    }

    fn supervisor_status(
        &self,
        module_id: &str,
        corr: u64,
    ) -> Result<Option<(crate::supervise::ModuleStatus, bool)>, RouterError> {
        self.supervisor
            .get(module_id)
            .map(|module| {
                let warming = module.is_warming_for_control("status").map_err(|err| {
                    RouterError::backend(
                        0,
                        corr,
                        format!(
                            "failed to read supervisor warming state for module_id '{module_id}': {err}"
                        ),
                    )
                })?;
                module.status_for_control("status").map_err(|err| {
                    RouterError::backend(
                        0,
                        corr,
                        format!(
                            "failed to read supervisor status for module_id '{module_id}': {err}"
                        ),
                    )
                }).map(|status| (status, warming))
            })
            .transpose()
    }

    fn guard_module_control_op(
        &self,
        frame: &Frame,
        module_id: &str,
        op: &str,
    ) -> Result<Option<Frame>, RouterError> {
        if self.module_grants_op(module_id, op, frame.header.corr)? {
            return Ok(None);
        }

        Ok(Some(control_error_frame(
            frame,
            "op_not_allowed",
            format!("module_id '{module_id}' did not grant control op '{op}'"),
        )?))
    }

    fn module_grants_op(&self, module_id: &str, op: &str, corr: u64) -> Result<bool, RouterError> {
        let Some(registration) = self
            .registry
            .get_module(module_id)
            .map_err(|err| RouterError::backend(0, corr, err.to_string()))?
        else {
            return Ok(false);
        };
        Ok(module_registration_grants_op(&registration.control_ops, op))
    }

    fn handle_status_update(
        &self,
        endpoint: ModuleEndpointId,
        frame: Frame,
    ) -> Result<Vec<Frame>, RouterError> {
        let update = match serde_json::from_slice::<ModuleControlPush>(&frame.body) {
            Ok(update) => update,
            Err(err) => {
                // Forward-compat: a newer module may push a channel-0 op this subc
                // version doesn't know. The control contract says unknown push ops
                // are IGNORED, never answered with an error. Only a malformed body
                // for an op we DO know is a real error worth surfacing.
                if is_known_module_push_op(&frame.body) {
                    return Ok(vec![control_error_frame(
                        &frame,
                        "invalid_control_body",
                        format!("malformed module control push body: {err}"),
                    )?]);
                }
                return Ok(Vec::new());
            }
        };

        match update {
            ModuleControlPush::RouteStatus {
                route_channel,
                route_epoch,
                status,
            } => {
                self.forwarding
                    .cache_status(endpoint, route_channel, route_epoch, status)
                    .map_err(RouterError::Forwarding)?;
            }
        }
        Ok(Vec::new())
    }

    fn handle_route_poll(
        &self,
        ctx: &RouteCtx,
        frame: Frame,
        route_channel: u16,
        route_epoch: u32,
        kind: PollKind,
    ) -> Result<Vec<Frame>, RouterError> {
        let snapshot = self
            .forwarding
            .route_poll_snapshot(ctx.connection_id, route_channel, route_epoch)
            .map_err(RouterError::Forwarding)?;
        let response = match (kind, snapshot) {
            (PollKind::Status, RoutePollSnapshot::Bound { status, .. }) => {
                ClientControlResponse::RoutePoll {
                    route_channel,
                    route_epoch,
                    status,
                    live: None,
                }
            }
            (PollKind::Status, RoutePollSnapshot::Absent) => ClientControlResponse::RoutePoll {
                route_channel,
                route_epoch,
                status: None,
                live: None,
            },
            (PollKind::Liveness, RoutePollSnapshot::Bound { module_id, .. }) => {
                // ABSENCE HERE MEANS "NOT SUPERVISED", NOT "UNKNOWN", and that
                // is what makes reporting `true` correct rather than a
                // confident guess. `process_live` returns None only when the
                // module id has no supervisor snapshot at all -- an
                // externally-started module the daemon did not spawn -- and
                // for those the supervisor has no opinion to offer, ever. It
                // is never None for a supervised module in an unknown state:
                // a supervised module always has a snapshot, and the answer
                // comes from `state == Running && process_alive`.
                //
                // The route is Bound, so the module completed a HELLO on a
                // live connection; "the process this route points at is
                // running" is therefore attested by the binding rather than
                // assumed. Reporting `false` for an unsupervised module would
                // be the actual lie -- it would tell a client its healthy
                // route is dead because the daemon does not manage the
                // process.
                //
                // IF `process_live` EVER GAINS A THIRD CASE -- a supervised
                // module whose liveness is genuinely unknown, e.g. a snapshot
                // that has not been populated yet -- THIS DEFAULT BECOMES
                // WRONG and must split: unsupervised stays true, unknown
                // becomes null so the client can tell the two apart. The
                // response field is already `Option<bool>`, so the wire can
                // carry that distinction today.
                let live = self
                    .process_liveness
                    .as_ref()
                    .and_then(|source| source.process_live(&module_id))
                    .unwrap_or(true);
                ClientControlResponse::RoutePoll {
                    route_channel,
                    route_epoch,
                    status: None,
                    live: Some(live),
                }
            }
            (PollKind::Liveness, RoutePollSnapshot::Absent) => ClientControlResponse::RoutePoll {
                route_channel,
                route_epoch,
                status: None,
                live: Some(false),
            },
        };

        Ok(vec![control_response_body_frame(
            &frame,
            &response,
            "ClientControlResponse::RoutePoll",
        )?])
    }

    pub(crate) fn observe_module_control_completion(
        &self,
        completion: ModuleControlRpcCompletion,
    ) -> bool {
        match completion {
            ModuleControlRpcCompletion::Unknown => false,
            ModuleControlRpcCompletion::Settled => true,
            ModuleControlRpcCompletion::LateHealthAnswer { module_id, latency } => {
                let latency_ms = latency.as_millis().min(u128::from(u64::MAX)) as u64;
                info!(
                    module_id = %module_id,
                    latency_ms,
                    "late health.check answer proves the module is alive"
                );
                match self
                    .supervisor
                    .record_late_health_answer(&module_id, latency_ms)
                {
                    Ok(true) => {}
                    Ok(false) => debug!(
                        module_id = %module_id,
                        latency_ms,
                        "late health.check answer has no active supervisor snapshot"
                    ),
                    Err(err) => warn!(
                        module_id = %module_id,
                        latency_ms,
                        error = %err,
                        "failed to record late health.check answer"
                    ),
                }
                true
            }
        }
    }

    /// Decide whether a failure while settling a relayed `route.bind` belongs to
    /// the module connection whose frame is being handled, or to the client that
    /// relay was opened for.
    ///
    /// This runs on the MODULE connection's frame handler, where returning `Err`
    /// ends that connection -- and a module connection carries every client's
    /// routes to that module, so ending it costs the whole fleet its tools.
    /// `ConnectionClosing` carries the id of the connection that is closing, and
    /// when that id is a CLIENT's, the condition is entirely about that one
    /// client's route.open. A client-scoped condition has no authority over a
    /// shared module connection, so it is logged and the single relay is dropped:
    /// the client is going away, and `complete_pending_relay` already removed the
    /// relay before failing, so there is nothing left to settle. Anything that
    /// relay still reserved is released by that client's own connection teardown,
    /// which is already under way -- that is what "closing" means.
    ///
    /// Every other failure is a statement about THIS connection and stays fatal:
    /// a poisoned forwarding lock, a stale module endpoint, and the module's own
    /// id in `ConnectionClosing` all mean this connection cannot keep serving
    /// frames correctly.
    fn refuse_to_end_module_connection_for_a_client(
        &self,
        module_connection_id: ConnectionId,
        corr: u64,
        err: ForwardingError,
    ) -> Result<(), RouterError> {
        if let ForwardingError::ConnectionClosing { connection_id } = err {
            if connection_id != module_connection_id {
                warn!(
                    module_connection_id = module_connection_id.get(),
                    client_connection_id = connection_id.get(),
                    corr,
                    "dropping a route.bind response for a closing client; the module connection keeps serving"
                );
                return Ok(());
            }
        }
        Err(RouterError::Forwarding(err))
    }

    fn handle_module_relay_response(
        &self,
        connection_id: ConnectionId,
        frame: Frame,
    ) -> Result<Vec<Frame>, RouterError> {
        let mut secondary_error = None;
        let outcome = match frame.header.ty {
            FrameType::Response => match serde_json::from_slice::<ControlOpProbe>(&frame.body) {
                Ok(probe) if probe.op == "route.bind" => {
                    match serde_json::from_slice::<ModuleControlResponse>(&frame.body) {
                        Ok(ModuleControlResponse::RouteBindAck {}) => {
                            RouteBindRelayOutcome::Accepted
                        }
                        Ok(other) => {
                            let message =
                                format!("route.bind response carried unexpected body: {other:?}");
                            secondary_error = Some(control_error_frame(
                                &frame,
                                "invalid_control_body",
                                message.clone(),
                            )?);
                            RouteBindRelayOutcome::ModuleGone(message)
                        }
                        Err(err) => {
                            let message = format!("malformed route.bind response body: {err}");
                            secondary_error = Some(control_error_frame(
                                &frame,
                                "invalid_control_body",
                                message.clone(),
                            )?);
                            RouteBindRelayOutcome::ModuleGone(message)
                        }
                    }
                }
                Ok(probe) => {
                    let outcome = match serde_json::from_slice::<ModuleControlResponse>(&frame.body)
                    {
                        Ok(response) => ModuleControlRpcOutcome::Response(response),
                        Err(err) => ModuleControlRpcOutcome::MalformedResponse(format!(
                            "malformed {} response body: {err}",
                            probe.op
                        )),
                    };
                    let completion = self
                        .forwarding
                        .complete_module_control_rpc(
                            connection_id,
                            frame.header.corr,
                            Some(&probe.op),
                            outcome,
                        )
                        .map_err(RouterError::Forwarding)?;
                    if !self.observe_module_control_completion(completion) {
                        debug!(
                            connection_id = connection_id.get(),
                            corr = frame.header.corr,
                            op = %probe.op,
                            "dropping late or unknown module-control RPC response"
                        );
                    }
                    return Ok(Vec::new());
                }
                Err(err) => {
                    if let Some(expected_op) = self
                        .forwarding
                        .pending_module_control_op(connection_id, frame.header.corr)
                        .map_err(RouterError::Forwarding)?
                    {
                        let completion = self
                            .forwarding
                            .complete_module_control_rpc(
                                connection_id,
                                frame.header.corr,
                                None,
                                ModuleControlRpcOutcome::MalformedResponse(format!(
                                    "malformed {expected_op} response body: {err}"
                                )),
                            )
                            .map_err(RouterError::Forwarding)?;
                        if !self.observe_module_control_completion(completion) {
                            debug!(
                                connection_id = connection_id.get(),
                                corr = frame.header.corr,
                                "dropping late malformed module-control RPC response"
                            );
                        }
                        return Ok(Vec::new());
                    }
                    let message = format!("malformed route.bind response body: {err}");
                    secondary_error = Some(control_error_frame(
                        &frame,
                        "invalid_control_body",
                        message.clone(),
                    )?);
                    RouteBindRelayOutcome::ModuleGone(message)
                }
            },
            FrameType::Error => {
                if self
                    .forwarding
                    .pending_module_control_op(connection_id, frame.header.corr)
                    .map_err(RouterError::Forwarding)?
                    .is_some()
                {
                    let outcome = match serde_json::from_slice::<ErrorBody>(&frame.body) {
                        Ok(body) => ModuleControlRpcOutcome::Rejected(body),
                        Err(err) => ModuleControlRpcOutcome::MalformedResponse(format!(
                            "malformed module-control ERROR body: {err}"
                        )),
                    };
                    let completion = self
                        .forwarding
                        .complete_module_control_rpc(
                            connection_id,
                            frame.header.corr,
                            None,
                            outcome,
                        )
                        .map_err(RouterError::Forwarding)?;
                    if !self.observe_module_control_completion(completion) {
                        debug!(
                            connection_id = connection_id.get(),
                            corr = frame.header.corr,
                            "dropping late or unknown module-control RPC error"
                        );
                    }
                    return Ok(Vec::new());
                }
                match serde_json::from_slice::<ErrorBody>(&frame.body) {
                    Ok(body) => RouteBindRelayOutcome::Rejected(body),
                    Err(err) => {
                        let message = format!("malformed route.bind ERROR body: {err}");
                        secondary_error = Some(control_error_frame(
                            &frame,
                            "invalid_control_body",
                            message.clone(),
                        )?);
                        RouteBindRelayOutcome::ModuleGone(message)
                    }
                }
            }
            ty => {
                return Ok(vec![control_error_frame(
                    &frame,
                    "unsupported_control_frame",
                    format!("unsupported module channel-0 frame {ty:?}"),
                )?])
            }
        };

        let settled =
            self.forwarding
                .complete_pending_relay(connection_id, frame.header.corr, outcome);
        let completion = match settled {
            Ok(completion) => completion,
            Err(err) => {
                self.refuse_to_end_module_connection_for_a_client(
                    connection_id,
                    frame.header.corr,
                    err,
                )?;
                return Ok(secondary_error.into_iter().collect());
            }
        };
        if let Some(target) = completion.abandoned.as_ref() {
            send_goodbye_target_best_effort(&self.counters, target, "late accepted route.bind");
        }
        if !completion.settled {
            debug!(
                connection_id = connection_id.get(),
                corr = frame.header.corr,
                frame_type = ?frame.header.ty,
                "dropping late or unknown route.bind relay response"
            );
        }
        Ok(secondary_error.into_iter().collect())
    }

    fn handle_goodbye(&self, connection_id: ConnectionId) -> Result<Vec<Frame>, RouterError> {
        debug!(connection_id = connection_id.get(), "handling GOODBYE");
        // GOODBYE ends the connection's logical session even when its socket
        // stays open. Use disconnect teardown so verdicts, client notices and
        // scope authority are released at the same lifecycle boundary.
        self.cleanup_connection(connection_id)
            .map_err(|err| RouterError::backend(0, 0, err.to_string()))?;
        Ok(Vec::new())
    }
}

impl Default for ControlHandler {
    fn default() -> Self {
        Self::new(Arc::new(Registry::default()))
    }
}

impl crate::supervise::SwapPromotionObserver for ControlHandler {
    fn swap_promoted(&self, registration: &crate::registry::ModuleRegistration) {
        self.apply_registration_capabilities(registration);
    }
}

fn capability_requirement_status(status: RequirementStatus) -> CapabilityRequirementStatus {
    CapabilityRequirementStatus {
        consumer: status.consumer,
        capability: status.capability,
        need: match status.need {
            subc_protocol::manifest::CapabilityNeed::Required => "required".to_string(),
            subc_protocol::manifest::CapabilityNeed::Optional => "optional".to_string(),
        },
        verdict: status.verdict.as_str().to_string(),
        episode_seq: status.episode_seq,
        config_satisfiable: status.config_satisfiable,
        runtime_available: status.runtime_available,
        detail: status.detail,
    }
}

fn append_capability_problem_detail(
    detail: Option<String>,
    capability_detail: Option<String>,
) -> Option<String> {
    match (detail, capability_detail) {
        (Some(detail), Some(capability_detail)) => Some(format!("{detail}; {capability_detail}")),
        (Some(detail), None) => Some(detail),
        (None, Some(capability_detail)) => Some(capability_detail),
        (None, None) => None,
    }
}

fn subc_ops() -> Vec<String> {
    SUBC_CONTROL_OPS
        .iter()
        .map(|op| (*op).to_string())
        .collect()
}

fn module_subc_ops() -> Vec<String> {
    SUBC_CONTROL_OPS
        .iter()
        .chain(MODULE_TO_SUBC_CONTROL_OPS.iter())
        .map(|op| (*op).to_string())
        .collect()
}

#[cfg(test)]
fn module_baseline_control_ops() -> Vec<String> {
    MODULE_BASELINE_CONTROL_OPS
        .iter()
        .map(|op| (*op).to_string())
        .collect()
}

fn effective_module_control_ops(declared: Option<Vec<String>>) -> Vec<String> {
    let mut seen = HashSet::new();
    let mut effective = Vec::new();
    for op in MODULE_BASELINE_CONTROL_OPS {
        if seen.insert((*op).to_string()) {
            effective.push((*op).to_string());
        }
    }
    for op in declared.unwrap_or_default() {
        if seen.insert(op.clone()) {
            effective.push(op);
        }
    }
    effective
}

fn module_registration_grants_op(control_ops: &[String], op: &str) -> bool {
    MODULE_BASELINE_CONTROL_OPS.contains(&op) || control_ops.iter().any(|granted| granted == op)
}

fn target_module_id(target: &RouteTarget) -> &str {
    match target {
        RouteTarget::ToolProvider { module_id }
        | RouteTarget::ManagementSurface { module_id }
        | RouteTarget::InternalService { module_id, .. } => module_id,
    }
}

fn target_has_required_role(target: &RouteTarget, roles: &[ProviderRole]) -> bool {
    roles.iter().any(|role| match (target, role) {
        (RouteTarget::ToolProvider { .. }, ProviderRole::ToolProvider { .. }) => true,
        (RouteTarget::ManagementSurface { .. }, ProviderRole::ManagementSurface { .. }) => true,
        (
            RouteTarget::InternalService { service_id, .. },
            ProviderRole::InternalService {
                service_id: provided,
                ..
            },
        ) => service_id == provided,
        _ => false,
    })
}

fn is_routable_role(role: &ProviderRole) -> bool {
    matches!(
        role,
        ProviderRole::ToolProvider { .. }
            | ProviderRole::ManagementSurface { .. }
            | ProviderRole::InternalService { .. }
    )
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ControlRequestBodyError {
    UnknownOp,
    InvalidBody,
}

#[derive(Debug, Deserialize)]
struct ControlOpProbe {
    op: String,
}

/// Channel-0 push ops this subc version understands. A push whose `op` is not in
/// this set is treated as a forward-compat unknown and ignored rather than errored.
const MODULE_PUSH_OPS: &[&str] = &["route.status"];

fn is_known_module_push_op(body: &[u8]) -> bool {
    serde_json::from_slice::<ControlOpProbe>(body)
        .map(|probe| MODULE_PUSH_OPS.contains(&probe.op.as_str()))
        .unwrap_or(false)
}

fn is_known_module_request_op(body: &[u8]) -> bool {
    serde_json::from_slice::<ControlOpProbe>(body)
        .map(|probe| is_module_to_subc_op(&probe.op))
        .unwrap_or(false)
}

fn is_module_to_subc_op(op: &str) -> bool {
    MODULE_TO_SUBC_CONTROL_OPS.contains(&op) || MODULE_TO_SUBC_UNADVERTISED_OPS.contains(&op)
}

fn log_control_dispatch_arrival(op: &'static str, connection_id: ConnectionId, corr: u64) {
    debug!(
        op = %op,
        connection_id = connection_id.get(),
        corr,
        "control dispatch"
    );
}

fn log_slow_control_dispatch(
    dispatch_started_at: Option<StdInstant>,
    op: &'static str,
    connection_id: ConnectionId,
    corr: u64,
) {
    let Some(dispatch_started_at) = dispatch_started_at else {
        return;
    };
    let elapsed = dispatch_started_at.elapsed();
    if elapsed >= SLOW_CONTROL_DISPATCH_THRESHOLD {
        warn!(
            op = %op,
            connection_id = connection_id.get(),
            corr,
            elapsed_ms = elapsed.as_millis() as u64,
            "slow control dispatch"
        );
    }
}

fn client_control_request_op(request: &ClientControlRequest) -> &'static str {
    match request {
        ClientControlRequest::ServerDescribe {} => ops::SERVER_DESCRIBE,
        ClientControlRequest::SupervisorProvenance { .. } => ops::SUPERVISOR_PROVENANCE,
        ClientControlRequest::CatalogList { .. } => ops::CATALOG_LIST,
        ClientControlRequest::RouteOpen { .. } => ops::ROUTE_OPEN,
        ClientControlRequest::RoutePoll { .. } => ops::ROUTE_POLL,
        ClientControlRequest::SupervisorList {} => ops::SUPERVISOR_LIST,
        ClientControlRequest::SupervisorSpawnSnapshot {} => ops::SUPERVISOR_SPAWN_SNAPSHOT,
        ClientControlRequest::SupervisorSpawnSubscribe { .. } => ops::SUPERVISOR_SPAWN_SUBSCRIBE,
        ClientControlRequest::SupervisorRestart { .. } => ops::SUPERVISOR_RESTART,
        ClientControlRequest::SupervisorSwap { .. } => ops::SUPERVISOR_SWAP,
        ClientControlRequest::SupervisorReload { .. } => ops::SUPERVISOR_RELOAD,
        ClientControlRequest::SupervisorRescan { .. } => ops::SUPERVISOR_RESCAN,
        ClientControlRequest::SupervisorReleaseReserved { .. } => ops::SUPERVISOR_RELEASE_RESERVED,
        ClientControlRequest::SupervisorSetEnabled { .. } => ops::SUPERVISOR_SET_ENABLED,
        ClientControlRequest::SupervisorHealthProbe { .. } => ops::SUPERVISOR_HEALTH_PROBE,
        ClientControlRequest::SupervisorHealth {} => ops::SUPERVISOR_HEALTH,
        ClientControlRequest::SupervisorRoutes { .. } => ops::SUPERVISOR_ROUTES,
        ClientControlRequest::SupervisorStderrTail { .. } => ops::SUPERVISOR_STDERR_TAIL,
        ClientControlRequest::SupervisorTerminals { .. } => ops::SUPERVISOR_TERMINALS,
    }
}

fn module_control_request_op(request: &ModuleControlRequestFromModule) -> &'static str {
    match request {
        ModuleControlRequestFromModule::CatalogUpdate { .. } => MODULE_TO_SUBC_OP_CATALOG_UPDATE,
        ModuleControlRequestFromModule::LiveRoots {} => "supervisor.live_roots",
        ModuleControlRequestFromModule::ScopeSync { .. } => SCOPE_SYNC_OP,
        ModuleControlRequestFromModule::ScopeDescribe { .. } => SCOPE_DESCRIBE_OP,
    }
}

fn parse_client_control_request(
    body: &[u8],
) -> Result<ClientControlRequest, (serde_json::Error, ControlRequestBodyError)> {
    serde_json::from_slice::<ClientControlRequest>(body).map_err(|err| {
        let classification = match serde_json::from_slice::<ControlOpProbe>(body) {
            Ok(probe) if SUBC_CONTROL_OPS.contains(&probe.op.as_str()) => {
                ControlRequestBodyError::InvalidBody
            }
            Ok(_) => ControlRequestBodyError::UnknownOp,
            Err(_) => ControlRequestBodyError::InvalidBody,
        };
        (err, classification)
    })
}

fn parse_module_control_request_from_module(
    body: &[u8],
) -> Result<ModuleControlRequestFromModule, (serde_json::Error, ControlRequestBodyError)> {
    serde_json::from_slice::<ModuleControlRequestFromModule>(body).map_err(|err| {
        let classification = match serde_json::from_slice::<ControlOpProbe>(body) {
            Ok(probe) if is_module_to_subc_op(&probe.op) => ControlRequestBodyError::InvalidBody,
            Ok(_) => ControlRequestBodyError::UnknownOp,
            Err(_) => ControlRequestBodyError::InvalidBody,
        };
        (err, classification)
    })
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
enum ProviderRoleKind {
    ToolProvider,
    PipelineStage,
    ManagementSurface,
    InternalService,
}

fn provider_role_kind(role: &ProviderRole) -> ProviderRoleKind {
    match role {
        ProviderRole::ToolProvider { .. } => ProviderRoleKind::ToolProvider,
        ProviderRole::PipelineStage { .. } => ProviderRoleKind::PipelineStage,
        ProviderRole::ManagementSurface { .. } => ProviderRoleKind::ManagementSurface,
        ProviderRole::InternalService { .. } => ProviderRoleKind::InternalService,
    }
}

fn provider_role_kind_set(roles: &[ProviderRole]) -> BTreeSet<ProviderRoleKind> {
    roles.iter().map(provider_role_kind).collect()
}

/// Most refused scope records named individually in the log per sync; the
/// `refused` count on the accepted line is always complete.
const MAX_LOGGED_REFUSED_SCOPE_RECORDS: usize = 8;

/// Per-outcome counts of one accepted `scope.sync`, for its log line.
#[derive(Debug, Default, PartialEq, Eq)]
struct ScopeOutcomeCounts {
    created: usize,
    replaced: usize,
    updated: usize,
    unchanged: usize,
    refused: usize,
}

impl ScopeOutcomeCounts {
    fn of(results: &[ScopeRecordResult]) -> Self {
        let mut counts = Self::default();
        for result in results {
            let slot = match result.outcome {
                ScopeRecordOutcome::Created => &mut counts.created,
                ScopeRecordOutcome::Replaced => &mut counts.replaced,
                ScopeRecordOutcome::Updated => &mut counts.updated,
                ScopeRecordOutcome::Unchanged => &mut counts.unchanged,
                ScopeRecordOutcome::Refused => &mut counts.refused,
            };
            *slot += 1;
        }
        counts
    }
}

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

    fn result(outcome: ScopeRecordOutcome) -> ScopeRecordResult {
        ScopeRecordResult {
            scope_ref: "r".to_string(),
            scope_epoch: 1,
            outcome,
            code: None,
            message: None,
            version: None,
            parent_state: None,
        }
    }

    /// Each outcome lands in its own count, so a refused record can never be
    /// hidden inside the total the log already printed.
    #[test]
    fn every_outcome_is_counted_in_its_own_field() {
        let results = [
            result(ScopeRecordOutcome::Created),
            result(ScopeRecordOutcome::Created),
            result(ScopeRecordOutcome::Replaced),
            result(ScopeRecordOutcome::Updated),
            result(ScopeRecordOutcome::Unchanged),
            result(ScopeRecordOutcome::Refused),
            result(ScopeRecordOutcome::Refused),
            result(ScopeRecordOutcome::Refused),
        ];
        assert_eq!(
            ScopeOutcomeCounts::of(&results),
            ScopeOutcomeCounts {
                created: 2,
                replaced: 1,
                updated: 1,
                unchanged: 1,
                refused: 3,
            }
        );
    }
}

/// Return whether a catalog change can create a newly violating live route.
/// Removing an attested claim is intentionally excluded: it makes fewer routes
/// forbidden and therefore must leave the existing route census untouched.
fn capability_census_trigger(
    old: Option<&CapabilityDeclarations>,
    new: Option<&CapabilityDeclarations>,
) -> bool {
    let old_provides = old
        .map(|capabilities| capabilities.provides.iter().collect::<HashSet<_>>())
        .unwrap_or_default();
    let old_denies = old
        .map(|capabilities| capabilities.must_never_reach.iter().collect::<HashSet<_>>())
        .unwrap_or_default();
    let new = new.cloned().unwrap_or(CapabilityDeclarations {
        provides: Vec::new(),
        requires: Vec::new(),
        must_never_reach: Vec::new(),
    });

    new.provides
        .iter()
        .any(|capability| !old_provides.contains(capability))
        || new
            .must_never_reach
            .iter()
            .any(|capability| !old_denies.contains(capability))
}

/// Find the first capability an attested opener denies that an attested target
/// claims. Both manifests are live registry records, never cached or client data.
fn denied_capability<'a>(
    opening_manifest: &'a ModuleManifest,
    target_manifest: &ModuleManifest,
) -> Option<&'a str> {
    let opening_capabilities = opening_manifest.capabilities.as_ref()?;
    let target_capabilities = target_manifest.capabilities.as_ref()?;
    opening_capabilities
        .must_never_reach
        .iter()
        .find(|denied| {
            target_capabilities
                .provides
                .iter()
                .any(|provided| provided == *denied)
        })
        .map(String::as_str)
}

fn catalog_update_frozen_field_message(
    registered: &ModuleManifest,
    provides: &[ProviderRole],
) -> Option<String> {
    let old_has_provides = !registered.provides.is_empty();
    let new_has_provides = !provides.is_empty();
    if old_has_provides != new_has_provides {
        return Some(format!(
            "catalog.update cannot change module '{}' between supervision-only and routable; routability is fixed at HELLO",
            registered.module_id
        ));
    }

    if provider_role_kind_set(&registered.provides) != provider_role_kind_set(provides) {
        return Some(format!(
            "catalog.update cannot change provider role kinds for module '{}'; role kinds are fixed at HELLO",
            registered.module_id
        ));
    }

    let registered_concurrency = manifest_concurrency(registered);
    let mut candidate = registered.clone();
    candidate.provides = provides.to_vec();
    let candidate_concurrency = manifest_concurrency(&candidate);
    if candidate_concurrency != registered_concurrency {
        return Some(format!(
            "catalog.update cannot change module '{}' concurrency from {:?} to {:?}; concurrency is fixed at HELLO",
            registered.module_id, registered_concurrency, candidate_concurrency
        ));
    }

    // control_ops live beside the manifest in the HELLO body, not inside
    // ModuleManifest, so a provides-only catalog.update cannot change them.
    None
}

fn manifest_provides_routable_role(manifest: &ModuleManifest) -> bool {
    manifest.provides.iter().any(is_routable_role)
}

/// Returns the routable-provider concurrency subc should enforce for this manifest.
///
/// ToolProvider and ManagementSurface store their delivery concurrency directly.
/// InternalService has no role-specific concurrency field, so it retains the
/// existing ModuleManaged default for backward compatibility.
fn manifest_concurrency(manifest: &ModuleManifest) -> Concurrency {
    manifest
        .provides
        .iter()
        .find_map(|provider| match provider {
            ProviderRole::ToolProvider { concurrency, .. }
            | ProviderRole::ManagementSurface { concurrency, .. } => Some(concurrency.clone()),
            ProviderRole::PipelineStage { .. } | ProviderRole::InternalService { .. } => None,
        })
        .unwrap_or(Concurrency::ModuleManaged)
}

/// True when the manifest carries a ManagementSurface role whose concurrency
/// was RESOLVED BY SERDE DEFAULT rather than declared. Reads the raw HELLO
/// bytes because the typed manifest deliberately erases that distinction: the
/// default exists for wire compatibility, and this probe exists so the default
/// stays observable. Any parse irregularity returns false -- the caller only
/// logs, and a malformed body already failed registration upstream.
fn manifest_concurrency_was_defaulted(raw_hello: &[u8], manifest: &ModuleManifest) -> bool {
    let has_management_surface = manifest
        .provides
        .iter()
        .any(|provider| matches!(provider, ProviderRole::ManagementSurface { .. }));
    if !has_management_surface {
        return false;
    }
    let Ok(raw) = serde_json::from_slice::<serde_json::Value>(raw_hello) else {
        return false;
    };
    let Some(provides) = raw
        .get("manifest")
        .and_then(|manifest| manifest.get("provides"))
        .and_then(serde_json::Value::as_array)
    else {
        return false;
    };
    // ProviderRole is internally tagged (`tag = "role"`), so the wire shape is
    // flat: {"role": "management_surface", ..., "concurrency": ...} -- verified
    // against the management_surface_manifest_without_concurrency golden, not
    // recalled (the externally-tagged guess was this function's first bug).
    provides.iter().any(|role| {
        role.get("role").and_then(serde_json::Value::as_str) == Some("management_surface")
            && role.get("concurrency").is_none()
    })
}

fn negotiate_version(peer_version: u8) -> Result<u8, String> {
    if peer_version != PROTOCOL_VERSION {
        return Err(format!(
            "protocol_ver {peer_version} is unsupported; this daemon requires exactly {PROTOCOL_VERSION}"
        ));
    }
    Ok(PROTOCOL_VERSION)
}

fn pong(frame: &Frame) -> Result<Frame, RouterError> {
    Frame::build_with_version(
        response_version(frame),
        FrameType::Pong,
        frame.header.flags,
        0,
        0,
        frame.header.corr,
        Vec::new(),
    )
    .map_err(RouterError::FrameBuild)
}

fn control_error_frame(
    frame: &Frame,
    code: &'static str,
    message: impl Into<String>,
) -> Result<Frame, RouterError> {
    control_error_body_frame(
        frame,
        ErrorBody {
            code: code.to_string(),
            message: message.into(),
            detail: None,
        },
    )
}

fn control_error_body_frame(frame: &Frame, error: ErrorBody) -> Result<Frame, RouterError> {
    let body = serde_json::to_vec(&error).map_err(|err| {
        RouterError::backend(
            0,
            frame.header.corr,
            format!("failed to encode control ERROR: {err}"),
        )
    })?;

    Frame::build_with_version(
        response_version(frame),
        FrameType::Error,
        control_flags(),
        0,
        0,
        frame.header.corr,
        body,
    )
    .map_err(RouterError::FrameBuild)
}

fn control_response_body_frame<T: Serialize>(
    frame: &Frame,
    reply: &T,
    label: &'static str,
) -> Result<Frame, RouterError> {
    let body = serde_json::to_vec(reply).map_err(|err| {
        RouterError::backend(
            0,
            frame.header.corr,
            format!("failed to encode {label}: {err}"),
        )
    })?;

    Frame::build_with_version(
        response_version(frame),
        FrameType::Response,
        control_flags(),
        0,
        0,
        frame.header.corr,
        body,
    )
    .map_err(RouterError::FrameBuild)
}

/// Map a forwarding failure to the wire code a client sees.
///
/// The code is not a label: clients BRANCH on it. Both SDKs decide "retry in
/// place" with `subc_protocol::error_codes::is_retryable_route_open`, so a code
/// chosen here decides whether a caller retries or gives up.
///
/// That makes attribution the load-bearing property, not merely having a code. A
/// permanent fault published as a retryable one produces a fleet-wide retry storm
/// against something that can never recover; a transient fault published as
/// permanent gives up on work that would have succeeded. Both look correct in a
/// log, which is why `retryability_of_forwarding_codes_matches_the_failure` pins
/// the mapping per variant rather than merely asserting that some code exists.
///
/// That fence partitions by RETRYABILITY, which is coarser than identity: swapping
/// two codes on the same side of the boundary passes it. Measured rather than
/// assumed — `NoModuleConnection` re-pointed at `module_reloading` is caught only
/// by `supervision_only_module_health_probe_does_not_enable_route_open_and_cleans_up`,
/// a test named for something else that happens to assert the string.
///
/// That accidental coverage is deliberately left alone rather than promoted to a
/// named test, because it guards a property this function does not promise.
/// Checked at source: every consumer branches on the RETRYABLE SET and none on a
/// specific code within a class, so identity is free to change and only the
/// partition is a contract. Splitting it out would assert a guarantee nothing
/// depends on — and a suite that promises more than the code does is the harder
/// thing to correct later, because the next reader cannot tell which assertions
/// are load-bearing.
///
/// Pin identity here the moment a consumer branches on a specific code.
fn forwarding_error_code(err: &ForwardingError) -> &'static str {
    match err {
        ForwardingError::ConnectionRoleConflict { .. } => "invalid_request",
        ForwardingError::NoModuleConnection => "target_unavailable",
        ForwardingError::ModuleReloading { .. } => "module_reloading",
        ForwardingError::ClientRouteChannelExhausted { .. }
        | ForwardingError::ModuleRouteChannelExhausted { .. } => "route_limit",
        ForwardingError::StaleModuleEndpoint
        | ForwardingError::UnknownReservation { .. }
        | ForwardingError::ConnectionClosing { .. }
        | ForwardingError::ClientEgressClosed { .. }
        | ForwardingError::ModuleEgressUnavailable { .. } => "target_unavailable",
        // Only a swap candidate's registration can produce this, and it means
        // exactly what a second active HELLO for a live id means.
        ForwardingError::CandidateSlotOccupied { .. } => "duplicate_module_id",
        ForwardingError::RelayCorrelationExhausted
        | ForwardingError::RouteOpenBuild(_)
        | ForwardingError::Poisoned => "forwarding_error",
    }
}

fn response_version(frame: &Frame) -> u8 {
    if (MIN_SUPPORTED_VERSION..=PROTOCOL_VERSION).contains(&frame.header.ver) {
        frame.header.ver
    } else {
        PROTOCOL_VERSION
    }
}

fn control_flags() -> Flags {
    Flags::new(false, Priority::Passive, false)
}

/// GOODBYE for a route.bind the daemon gave up on after reserving the module's
/// channel. The target is the module (a client never saw the route), so this
/// takes the module path: delivered late rather than dropped when the module's
/// queue is momentarily full, and never closing its connection.
fn send_goodbye_target_best_effort(
    counters: &DaemonCounters,
    target: &GoodbyeTarget,
    context: &'static str,
) {
    let Ok(frame) = Frame::build_with_version(
        target.negotiated_ver,
        FrameType::Goodbye,
        control_flags(),
        target.channel,
        target.epoch,
        0,
        Vec::new(),
    ) else {
        return;
    };
    crate::forwarding::send_module_route_goodbye(
        counters,
        &target.sink,
        frame,
        target.module_id.as_deref(),
        context,
    );
}

pub(crate) fn send_route_control_pushes(
    forwarding: &ForwardingTable,
    routes: Vec<EndpointRoute>,
    push: ClientControlPush,
) {
    let mut targets: Vec<(GoodbyeTarget, Vec<u16>)> = Vec::new();
    for route in routes {
        let target = route.goodbye_target;
        if let Some((existing, channels)) = targets
            .iter_mut()
            .find(|(existing, _)| existing.connection_id == target.connection_id)
        {
            debug_assert_eq!(
                existing.negotiated_ver, target.negotiated_ver,
                "one connection cannot negotiate multiple frame versions"
            );
            if !channels.contains(&target.channel) {
                channels.push(target.channel);
            }
            continue;
        }
        let channel = target.channel;
        targets.push((target, vec![channel]));
    }
    for (target, mut channels) in targets {
        channels.sort_unstable();
        let mut push = push.clone();
        match &mut push {
            ClientControlPush::RouteClosing {
                channels: covered, ..
            }
            | ClientControlPush::RouteClosed {
                channels: covered, ..
            } => *covered = channels,
        }
        let body = match serde_json::to_vec(&push) {
            Ok(body) => body,
            Err(err) => {
                warn!(error = %err, "failed to serialize route lifecycle control PUSH");
                continue;
            }
        };
        let frame = match Frame::build_with_version(
            target.negotiated_ver,
            FrameType::Push,
            control_flags(),
            0,
            0,
            0,
            body.clone(),
        ) {
            Ok(frame) => frame,
            Err(err) => {
                warn!(
                    route_channel = target.channel,
                    error = %err,
                    "failed to build route lifecycle control PUSH frame"
                );
                continue;
            }
        };
        if let Err(err) = target.sink.try_send(frame) {
            if target.close_on_delivery_failure() {
                warn!(
                    target_connection_id = target.connection_id.get(),
                    route_channel = target.channel,
                    error = %err,
                    "route lifecycle control PUSH was not delivered to client; closing target connection"
                );
                let _ = forwarding.escalate_client_delivery_failure(
                    target.connection_id,
                    target.channel,
                    target.epoch,
                    CloseReason::new(
                        "route_lifecycle_push_delivery_failed",
                        format!(
                            "failed to enqueue route lifecycle control PUSH for channel {}: {err}",
                            target.channel
                        ),
                    ),
                    crate::forwarding::UndeliveredFrame {
                        module_id: target.module_id.as_deref(),
                        sink: &target.sink,
                    },
                );
            }
        }
    }
}

#[cfg(test)]
mod tests {
    #[cfg(unix)]
    #[tokio::test]
    async fn rescan_health_only_is_live_but_launch_edits_need_reload() {
        let dir = subc_test_support::TestTempDir::new("rescan-live-health");
        let path = dir.join("subc.jsonc");
        std::fs::write(&path, serde_json::json!({"version":1,"modules":{"stock":{
            "program":"/bin/sleep","args":["60"],"protocol":"none",
            "env":{"XDG_DATA_HOME":dir.path(),"XDG_RUNTIME_DIR":dir.path(),"XDG_CONFIG_HOME":dir.path()}
        }}}).to_string()).unwrap();
        let mut configured = crate::daemon_config::load(&path)
            .unwrap()
            .unwrap()
            .modules
            .pop()
            .unwrap();
        let registry = std::sync::Arc::new(crate::Registry::default());
        let handle = crate::SupervisorHandle::new();
        let supervisor = crate::Supervisor::new(registry.clone(), crate::RestartPolicy::default())
            .with_handle(handle.clone());
        let module = supervisor
            .supervise_configured_with_health(
                configured.module_spec(),
                true,
                configured.health.clone(),
                None,
                configured.restart,
            )
            .unwrap();
        let handler = super::ControlHandler::new(registry).with_supervisor(handle);
        let before = module.status().unwrap().pid;
        configured.health.http = Some("http://127.0.0.1:1/healthz".into());
        configured.health.cadence = std::time::Duration::from_secs(3600);
        let health_only = handler
            .reconcile_supervised_modules(&supervisor, vec![configured.clone()], false)
            .await
            .unwrap();
        assert!(
            health_only.changed_pending_reload.is_empty(),
            "health policy is already applied live"
        );
        assert_eq!(module.status().unwrap().pid, before);
        assert_eq!(
            module.configuration().unwrap().1.http,
            configured.health.http
        );
        configured.args = vec!["61".into()];
        let launch = handler
            .reconcile_supervised_modules(&supervisor, vec![configured], false)
            .await
            .unwrap();
        assert_eq!(launch.changed_pending_reload, ["stock"]);
        assert_eq!(
            module.status().unwrap().pid,
            before,
            "a launch edit is stored until reload"
        );
        module.drain().await.unwrap();
    }
    use std::{
        collections::BTreeMap,
        fmt,
        path::PathBuf,
        sync::{Arc, Mutex},
        time::Duration,
    };
    use subc_test_support::TestTempDir;

    use serde_json::{json, Value};
    use subc_protocol::{
        manifest::{
            Concurrency, ExecutionMode, IdentityScope, ManagementOperation,
            ManagementOperationKind, ObservabilityKind, ObservabilitySurface, ProviderRole, Tool,
        },
        session::HealthStatus,
        FrameType,
    };

    use super::*;
    use crate::{
        forwarding::{DataRoute, DataRouteState},
        registry::ChannelState,
        router::FrameSink,
        stderr_tail::DEFAULT_MAX_LINE_BYTES,
        supervise::{ModuleSpec, ModuleState, RestartPolicy, Supervisor, SupervisorHandle},
        RouteCtx, Router,
    };
    use tokio::{
        sync::mpsc,
        time::{sleep, Instant},
    };
    use tracing::{
        field::{Field, Visit},
        Event, Subscriber,
    };
    use tracing_subscriber::{layer::Context, prelude::*, Layer};

    /// Locates the `fake-aft-stub` binary from a `src/lib.rs` unit test.
    ///
    /// `CARGO_BIN_EXE_*` (compile-time `env!` and runtime `std::env::var` alike)
    /// is only populated for `tests/*.rs` integration test binaries -- this file
    /// compiles as part of the library target, which gets neither. This test's
    /// own executable path is `<target-dir>/<profile>/deps/subc_core-<hash>`,
    /// and the sibling binary lives two directories up at
    /// `<target-dir>/<profile>/fake-aft-stub`.
    ///
    /// THE BINARY IS NOT ALWAYS THERE, and the existence check below is why.
    /// `cargo test -p subc-core` builds every target including `[[bin]]`, so the
    /// stub is on disk; `cargo test -p subc-core --lib` builds ONLY the library
    /// test and leaves the stub unbuilt. A bare spawn then fails with a raw
    /// `NotFound`, which reads as a broken test rather than an unbuilt
    /// dependency -- so state the cause and the remedy instead. Deliberately a
    /// panic and not a silent skip: a test that quietly passes when it could not
    /// run is worse than one that fails, because it reports health it never
    /// verified.
    fn fake_aft_stub_path() -> PathBuf {
        let mut path = std::env::current_exe().expect("current_exe available in tests");
        path.pop(); // .../deps/
        path.pop(); // .../<profile>/
        path.push(if cfg!(windows) {
            "fake-aft-stub.exe"
        } else {
            "fake-aft-stub"
        });
        assert!(
            path.exists(),
            "fake-aft-stub not built at {}: run `cargo test -p subc-core` (which builds \
             [[bin]] targets) rather than `cargo test -p subc-core --lib` (which does not)",
            path.display()
        );
        path
    }

    /// Whether clients retry `code` in place: the predicate itself, never a copy
    /// of its set. A copied list breaks silently when a code is added to or
    /// removed from the real one, and a stale copy here would let exactly the
    /// failure this test exists to catch pass.
    fn client_retries(code: &str) -> bool {
        subc_protocol::error_codes::is_retryable_route_open(code)
    }

    /// A code is not a label — clients branch on it, so publishing the wrong KIND
    /// of failure is worse than publishing none. A permanent fault dressed as
    /// retryable makes every client in the fleet retry forever against something
    /// that cannot recover; a transient fault dressed as permanent abandons work
    /// that would have succeeded.
    ///
    /// Asserting "a code exists" cannot catch either, because the string is free
    /// to say anything. This enumerates every variant and pins which side of the
    /// retry boundary it lands on, so a new variant must be classified here
    /// deliberately rather than inheriting whichever arm it was appended to.
    #[test]
    fn retryability_of_forwarding_codes_matches_the_failure() {
        // Transient by nature: the target is booting, reloading, or its endpoint
        // was swapped mid-flight. Retrying is how these resolve.
        let transient = [
            ForwardingError::NoModuleConnection,
            ForwardingError::ModuleReloading {
                module_id: "m".into(),
            },
            ForwardingError::StaleModuleEndpoint,
            ForwardingError::UnknownReservation {
                client_channel: 1,
                module_channel: 1,
            },
            ForwardingError::ConnectionClosing {
                connection_id: ConnectionId::new(1),
            },
            ForwardingError::ClientEgressClosed {
                connection_id: ConnectionId::new(1),
            },
            ForwardingError::ModuleEgressUnavailable {
                connection_id: ConnectionId::new(1),
            },
        ];
        for err in transient {
            let code = forwarding_error_code(&err);
            assert!(
                client_retries(code),
                "{err:?} is transient but publishes {code:?}, which clients treat as permanent"
            );
        }

        // Not fixed by retrying. Channel and correlation exhaustion need the
        // caller to close routes, and a poisoned lock is a daemon that cannot
        // recover at all — the worst thing to advertise as retryable, since every
        // client would storm a daemon that will never answer.
        let permanent = [
            ForwardingError::ConnectionRoleConflict {
                connection_id: ConnectionId::new(1),
            },
            ForwardingError::ClientRouteChannelExhausted {
                connection_id: ConnectionId::new(1),
            },
            ForwardingError::ModuleRouteChannelExhausted {
                endpoint: ModuleEndpointId {
                    connection_id: ConnectionId::new(1),
                    generation: 1,
                },
            },
            ForwardingError::RelayCorrelationExhausted,
            ForwardingError::RouteOpenBuild("x".into()),
            ForwardingError::Poisoned,
        ];
        for err in permanent {
            let code = forwarding_error_code(&err);
            assert!(
                !client_retries(code),
                "{err:?} cannot be fixed by retrying but publishes {code:?}, which clients retry"
            );
        }
    }

    /// The principal is the daemon's answer to "who is calling", and modules
    /// branch on it: aft gates bash on it, cerebellum gates browser control,
    /// plexus gates connector invocation. So a stamp is an authorization input in
    /// another process, not a label — and both possible answers SUCCEED, which is
    /// what makes a wrong one quiet. An unattested caller stamped `Reserved` hands
    /// first-party capability to something that never proved it; a supervised one
    /// stamped `Direct` silently strips a module of capability it is entitled to.
    ///
    /// Neither shows up in a test that only checks the bind succeeded. Before this
    /// test the only coverage was accidental —
    /// `route_open_round_trip_via_tagged_shape_forwards_through_stub` asserts the
    /// stamped principal on its way past, so narrowing that wire-shape test to its
    /// stated subject would have deleted the last assertion on this value. It
    /// still asserts the stamp, which is now redundancy rather than the only
    /// guard: both fail under the same mutation, and this one names the reason.
    /// SCOPE: this handler's supervisor has spawned nothing, so
    /// `spawned_consumer_authorized` can only ever return false and the GRANT arm
    /// is unreachable here. Both assertions below are refusals, and a mutant that
    /// refuses everything would satisfy them.
    ///
    /// The grant side is covered where a real nonce exists: `tests/forwarding.rs`
    /// spawns a supervised consumer, reads its live nonce, and asserts the module
    /// observed `principal.kind == "reserved"` carrying that module_id — verified
    /// at source rather than assumed, since a citation is a claim about another
    /// file and ages like one. Recorded because a harness that structurally
    /// cannot reach an arm reports "none" for that arm identically to one that
    /// covers it and found nothing.
    #[tokio::test]
    async fn an_unattested_caller_is_never_stamped_as_a_supervised_module() {
        let handler = ControlHandler::default();
        let frame =
            Frame::build(FrameType::Request, control_flags(), 0, 0, 900, Vec::new()).unwrap();

        // Absent consumer_identity is the ordinary case: a human at a terminal, or
        // any process holding the connection file. Nothing was proved, so nothing
        // may be granted beyond the unattested floor.
        let stamped = handler.route_open_principal(&frame, None).unwrap().unwrap();
        assert_eq!(
            stamped,
            Principal::Direct,
            "a caller that proved nothing must not be stamped as a supervised module"
        );

        // A claimed module_id with a nonce no supervised child was given is a
        // forgery attempt, not a weaker caller: it must be REFUSED rather than
        // quietly demoted to Direct, or an impersonation attempt looks identical
        // to an ordinary unattested connection.
        let forged = handler
            .route_open_principal(
                &frame,
                Some(ConsumerIdentity {
                    module_id: "aft".to_string(),
                    launch_nonce: "not-a-real-nonce".to_string(),
                }),
            )
            .unwrap();
        let refusal = forged.expect_err("an unmatched launch nonce must not yield a principal");
        assert_eq!(parse_error(&refusal)["code"], "bad_consumer_identity");
    }

    /// The test above hands `route_open_principal` an identity it built itself,
    /// which proves the stamping rule and nothing about where the identity comes
    /// from. The real producer is a wire body, and the two are joined by a serde
    /// field name that nothing else asserts.
    ///
    /// That join fails quietly in one specific way: an unrecognised key is simply
    /// absent after parsing, so a renamed or misspelled `consumer_identity`
    /// yields `None` and every supervised module silently drops to `Direct`.
    /// Capability-wise that is the safe direction, but it surfaces far from its
    /// cause — as a module mysteriously refused bash — and it would pass every
    /// test that builds its own input.
    ///
    /// Deliberately NOT closed with `deny_unknown_fields`: refusing unknown keys
    /// would break every client the moment the daemon gains a field, trading a
    /// quiet demotion for a hard refusal on additive change. Asserting the join
    /// instead means a rename breaks a test here rather than the fleet.
    #[test]
    fn a_wire_body_actually_yields_the_consumer_identity_the_daemon_stamps_from() {
        let body = br#"{"op":"route.open","target":{"kind":"tool_provider","module_id":"m"},"identity":{"session":"s","project_root":"/p","harness":"h"},"consumer_identity":{"module_id":"aft","launch_nonce":"n"}}"#;
        let parsed: ClientControlRequest = serde_json::from_slice(body).unwrap();
        let ClientControlRequest::RouteOpen {
            consumer_identity, ..
        } = parsed
        else {
            panic!("route.open body must parse as RouteOpen");
        };
        assert_eq!(
            consumer_identity,
            Some(ConsumerIdentity {
                module_id: "aft".to_string(),
                launch_nonce: "n".to_string(),
            }),
            "the wire field name must reach the value route_open_principal reads"
        );
    }

    fn manifest(module_id: &str, protocol_ver: u8) -> ModuleManifest {
        ModuleManifest::builder(module_id, "0.1.0")
            .protocol_ver(protocol_ver)
            .provides(vec![ProviderRole::ToolProvider {
                tools: vec![Tool {
                    name: "read".to_string(),
                    description: None,
                    execution_mode: ExecutionMode::Pure,
                    schema: json!({"type": "object"}),
                }],
                identity_scope: vec![IdentityScope::Project, IdentityScope::Session],
                concurrency: Concurrency::ModuleManaged,
                emits_push: true,
                sub_supervises: true,
            }])
            .build()
    }

    fn hello_frame(module_id: &str, protocol_ver: u8, corr: u64) -> Frame {
        hello_frame_with_control_ops(module_id, protocol_ver, corr, None)
    }

    fn hello_frame_with_control_ops(
        module_id: &str,
        protocol_ver: u8,
        corr: u64,
        control_ops: Option<Vec<String>>,
    ) -> Frame {
        hello_frame_full(module_id, protocol_ver, corr, control_ops, None)
    }

    fn hello_frame_with_nonce(
        module_id: &str,
        protocol_ver: u8,
        corr: u64,
        launch_nonce: Option<&str>,
    ) -> Frame {
        hello_frame_full(
            module_id,
            protocol_ver,
            corr,
            None,
            launch_nonce.map(ToOwned::to_owned),
        )
    }

    fn hello_frame_full(
        module_id: &str,
        protocol_ver: u8,
        corr: u64,
        control_ops: Option<Vec<String>>,
        launch_nonce: Option<String>,
    ) -> Frame {
        let body = serde_json::to_vec(&ModuleHelloBody {
            manifest: manifest(module_id, protocol_ver),
            protocol_ver,
            control_ops,
            launch_nonce,
        })
        .unwrap();
        Frame::build(FrameType::Hello, control_flags(), 0, 0, corr, body).unwrap()
    }

    fn non_routable_hello_frame_with_control_ops(
        module_id: &str,
        corr: u64,
        control_ops: Option<Vec<String>>,
    ) -> Frame {
        let mut manifest = manifest(module_id, PROTOCOL_VERSION);
        manifest.provides.clear();
        let body = serde_json::to_vec(&ModuleHelloBody {
            manifest,
            protocol_ver: PROTOCOL_VERSION,
            control_ops,
            launch_nonce: None,
        })
        .unwrap();
        Frame::build(FrameType::Hello, control_flags(), 0, 0, corr, body).unwrap()
    }

    fn capability_grammar_hello_frame(
        capabilities: Value,
        runtime_computed: Option<Value>,
        corr: u64,
    ) -> Frame {
        let mut body = serde_json::to_value(ModuleHelloBody {
            manifest: manifest("capability-grammar-test", PROTOCOL_VERSION),
            protocol_ver: PROTOCOL_VERSION,
            control_ops: None,
            launch_nonce: None,
        })
        .expect("HELLO body serializes");
        body["manifest"]["capabilities"] = capabilities;
        if let Some(runtime_computed) = runtime_computed {
            body["runtime_computed"] = runtime_computed;
        }
        Frame::build(
            FrameType::Hello,
            control_flags(),
            0,
            0,
            corr,
            serde_json::to_vec(&body).expect("HELLO body reserializes"),
        )
        .expect("HELLO frame builds")
    }

    fn channel_request(channel: u16, corr: u64) -> Frame {
        Frame::build(
            FrameType::Request,
            Flags::new(true, Priority::Interactive, false),
            channel,
            0,
            corr,
            b"opaque".to_vec(),
        )
        .unwrap()
    }

    fn route_ctx(
        connection_id: ConnectionId,
    ) -> (RouteCtx, mpsc::Receiver<crate::router::OutboundFrame>) {
        let (tx, rx) = mpsc::channel(8);
        (
            RouteCtx {
                connection_id,
                egress: FrameSink::new(tx),
            },
            rx,
        )
    }

    fn parse_ack(frame: &Frame) -> ModuleHelloAckBody {
        serde_json::from_slice(&frame.body).unwrap()
    }

    /// Register a module over a connection that has a sink and return the
    /// HELLO_ACK the module reads. A successful HELLO queues its ack on the
    /// module's own sink rather than returning it as a reply, so the ack is
    /// taken off `rx` here and whatever the test reads next is what followed it.
    async fn hello_via_sink(
        handler: &ControlHandler,
        ctx: &RouteCtx,
        rx: &mut mpsc::Receiver<crate::router::OutboundFrame>,
        hello: Frame,
    ) -> Frame {
        let replies = handler.handle_control_frame(ctx, hello).await.unwrap();
        assert!(
            replies.is_empty(),
            "a registered HELLO replies with nothing; its ack is already queued: {replies:?}"
        );
        let ack = rx
            .try_recv()
            .expect("HELLO_ACK is queued on the module sink")
            .frame;
        assert_eq!(ack.header.ty, FrameType::HelloAck);
        ack
    }

    fn parse_error(frame: &Frame) -> Value {
        serde_json::from_slice(&frame.body).unwrap()
    }

    fn parse_route_poll(frame: &Frame) -> ClientControlResponse {
        serde_json::from_slice(&frame.body).unwrap()
    }

    fn route_poll_frame(corr: u64, kind: PollKind, route_channel: u16) -> Frame {
        let body = serde_json::to_vec(&ClientControlRequest::RoutePoll {
            route_channel,
            route_epoch: 0,
            kind,
        })
        .unwrap();
        Frame::build(FrameType::Request, control_flags(), 0, 0, corr, body).unwrap()
    }

    fn supervisor_health_probe_frame(corr: u64, module_id: &str) -> Frame {
        let body = serde_json::to_vec(&ClientControlRequest::SupervisorHealthProbe {
            module_id: module_id.to_string(),
        })
        .unwrap();
        Frame::build(FrameType::Request, control_flags(), 0, 0, corr, body).unwrap()
    }

    fn route_open_frame(corr: u64, module_id: &str, project_root: TestTempDir) -> Frame {
        route_open_frame_with_consumer_capabilities(corr, module_id, project_root, None)
    }

    fn route_open_frame_with_consumer_capabilities(
        corr: u64,
        module_id: &str,
        project_root: TestTempDir,
        consumer_capabilities: Option<Vec<String>>,
    ) -> Frame {
        let body = serde_json::to_vec(&ClientControlRequest::RouteOpen {
            target: RouteTarget::ToolProvider {
                module_id: module_id.to_string(),
            },
            identity: BindIdentity::new(
                project_root.path().to_path_buf(),
                "unit".to_string(),
                "session".to_string(),
            ),
            consumer_identity: None,
            consumer_capabilities,
            role_versions: None,
            admission_facts: None,
            scope: None,
        })
        .unwrap();
        Frame::build(FrameType::Request, control_flags(), 0, 0, corr, body).unwrap()
    }

    fn route_open_frame_with_role_versions(
        corr: u64,
        module_id: &str,
        project_root: TestTempDir,
        role_versions: Option<BTreeMap<String, String>>,
    ) -> Frame {
        let body = serde_json::to_vec(&ClientControlRequest::RouteOpen {
            target: RouteTarget::ToolProvider {
                module_id: module_id.to_string(),
            },
            identity: BindIdentity::new(
                project_root.path().to_path_buf(),
                "unit".to_string(),
                format!("session-{corr}"),
            ),
            consumer_identity: None,
            consumer_capabilities: None,
            role_versions,
            admission_facts: None,
            scope: None,
        })
        .unwrap();
        Frame::build(FrameType::Request, control_flags(), 0, 0, corr, body).unwrap()
    }

    fn role_versions(entries: &[(&str, &str)]) -> BTreeMap<String, String> {
        entries
            .iter()
            .map(|(role, version)| (role.to_string(), version.to_string()))
            .collect()
    }

    fn route_open_frame_with_admission_facts(
        corr: u64,
        module_id: &str,
        project_root: TestTempDir,
        consumer_identity: Option<subc_control::ConsumerIdentity>,
        facts: Option<Value>,
    ) -> Frame {
        let body = serde_json::to_vec(&ClientControlRequest::RouteOpen {
            target: RouteTarget::ToolProvider {
                module_id: module_id.to_string(),
            },
            identity: BindIdentity::new(
                project_root.path().to_path_buf(),
                "unit".to_string(),
                format!("session-{corr}"),
            ),
            consumer_identity,
            consumer_capabilities: None,
            role_versions: None,
            admission_facts: facts,
            scope: None,
        })
        .unwrap();
        Frame::build(FrameType::Request, control_flags(), 0, 0, corr, body).unwrap()
    }

    #[derive(Clone, Default)]
    struct EventCapture {
        events: Arc<Mutex<Vec<CapturedEvent>>>,
    }

    #[derive(Clone, Debug)]
    struct CapturedEvent {
        target: String,
        level: tracing::Level,
        fields: BTreeMap<String, String>,
    }

    impl EventCapture {
        fn events(&self) -> Vec<CapturedEvent> {
            self.events.lock().unwrap().clone()
        }
    }

    impl<S> Layer<S> for EventCapture
    where
        S: Subscriber,
    {
        fn on_event(&self, event: &Event<'_>, _context: Context<'_, S>) {
            let mut visitor = EventFieldVisitor::default();
            event.record(&mut visitor);
            self.events.lock().unwrap().push(CapturedEvent {
                target: event.metadata().target().to_string(),
                level: *event.metadata().level(),
                fields: visitor.fields,
            });
        }
    }

    #[derive(Default)]
    struct EventFieldVisitor {
        fields: BTreeMap<String, String>,
    }

    impl Visit for EventFieldVisitor {
        fn record_debug(&mut self, field: &Field, value: &dyn fmt::Debug) {
            self.fields
                .insert(field.name().to_string(), format!("{value:?}"));
        }
    }

    fn health_response(corr: u64, status: HealthStatus) -> Frame {
        let body = serde_json::to_vec(&ModuleControlResponse::HealthCheck {
            status,
            detail: Some("warming".to_string()),
            metrics: Some(json!({"queue_depth": 3})),
        })
        .unwrap();
        Frame::build(FrameType::Response, control_flags(), 0, 0, corr, body).unwrap()
    }

    fn route_bind_ack(corr: u64) -> Frame {
        let body = serde_json::to_vec(&ModuleControlResponse::RouteBindAck {}).unwrap();
        Frame::build(FrameType::Response, control_flags(), 0, 0, corr, body).unwrap()
    }

    fn unique_project_root(label: &str) -> TestTempDir {
        TestTempDir::new(label)
    }

    fn assert_route_poll_liveness(frame: &Frame, expected_live: bool) {
        match parse_route_poll(frame) {
            ClientControlResponse::RoutePoll {
                status: None,
                live: Some(live),
                ..
            } => assert_eq!(live, expected_live),
            other => panic!("unexpected route.poll response: {other:?}"),
        }
    }

    fn bind_liveness_route(
        registry: &Registry,
        forwarding: &ForwardingTable,
        module_id: &str,
    ) -> (RouteCtx, u16, u32) {
        let module_connection = ConnectionId::new(101);
        let client_connection = ConnectionId::new(202);
        let registration = registry
            .register_with_control_ops(
                manifest(module_id, PROTOCOL_VERSION),
                PROTOCOL_VERSION,
                module_connection,
                module_baseline_control_ops(),
            )
            .unwrap();
        let (module_tx, _module_rx) = mpsc::channel(8);
        let endpoint = forwarding
            .register_module_connection(
                module_connection,
                module_id.to_string(),
                PROTOCOL_VERSION,
                manifest_concurrency(&registration.manifest),
                FrameSink::new(module_tx),
            )
            .unwrap();
        let (client_ctx, _client_rx) = route_ctx(client_connection);
        let pending = forwarding
            .begin_route_bind_relay_for_test(
                client_connection,
                client_ctx.egress.clone(),
                1,
                module_id,
            )
            .unwrap();
        assert_eq!(pending.endpoint, endpoint);
        let route_channel = pending.client_channel;
        let route_epoch = pending.client_epoch;
        forwarding
            .complete_pending_relay(
                module_connection,
                pending.corr,
                RouteBindRelayOutcome::Accepted,
            )
            .unwrap();
        (client_ctx, route_channel, route_epoch)
    }

    struct FakeProcessLiveness {
        live: Option<bool>,
    }

    impl ModuleProcessLiveness for FakeProcessLiveness {
        fn process_live(&self, _module_id: &str) -> Option<bool> {
            self.live
        }
    }

    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn supervisor_stderr_tail_converts_a_real_truncated_ring_entry_to_prefix_only_wire_data()
    {
        let registry = Arc::new(Registry::default());
        let supervisor_handle = SupervisorHandle::new();
        let supervisor = Supervisor::new(
            Arc::clone(&registry),
            RestartPolicy::new(1, Duration::from_millis(10)),
        )
        .with_handle(supervisor_handle.clone());
        let source_line = format!("config error: {}", "x".repeat(DEFAULT_MAX_LINE_BYTES));
        let module = supervisor
            .spawn(ModuleSpec {
                module_id: "stderr-tail-wire".to_string(),
                program: fake_aft_stub_path(),
                args: Vec::new(),
                env: vec![
                    ("FAKE_AFT_STDERR_LINE".to_string(), source_line.clone()),
                    ("FAKE_AFT_EXIT_CODE".to_string(), "1".to_string()),
                ],
                reserved: false,
                reserved_prefixes: Vec::new(),
                protocol: ModuleProtocol::Subc,
                overlap: Default::default(),
            })
            .unwrap();

        let deadline = Instant::now() + Duration::from_secs(5);
        loop {
            let tail = module.stderr_tail(None, None);
            if tail
                .entries
                .iter()
                .any(|entry| matches!(entry, TailEntry::ProcessStart))
                && tail.entries.iter().any(|entry| {
                    matches!(
                        entry,
                        TailEntry::Line {
                            truncated: true,
                            ..
                        }
                    )
                })
            {
                break;
            }
            assert!(
                Instant::now() < deadline,
                "module did not produce a truncated line and restart boundary: {tail:?}"
            );
            sleep(Duration::from_millis(10)).await;
        }

        let handler = ControlHandler::new(Arc::clone(&registry)).with_supervisor(supervisor_handle);
        let request = ClientControlRequest::SupervisorStderrTail {
            module_id: "stderr-tail-wire".to_string(),
            max_lines: None,
            max_bytes: None,
        };
        let frame = Frame::build(
            FrameType::Request,
            control_flags(),
            0,
            0,
            1,
            serde_json::to_vec(&request).unwrap(),
        )
        .unwrap();
        let (ctx, _egress) = route_ctx(ConnectionId::new(1));
        let responses = handler.handle_control_frame(&ctx, frame).await.unwrap();
        let ClientControlResponse::SupervisorStderrTail { tail, .. } =
            serde_json::from_slice(&responses[0].body).unwrap()
        else {
            panic!("expected supervisor.stderr_tail response");
        };

        assert!(
            tail.entries
                .iter()
                .any(|entry| matches!(entry, StderrTailEntry::ProcessStart)),
            "the control response lost the restart boundary"
        );
        let Some(StderrTailEntry::Line {
            text,
            truncated,
            at_ms,
        }) = tail.entries.iter().find(|entry| {
            matches!(
                entry,
                StderrTailEntry::Line {
                    truncated: true,
                    ..
                }
            )
        })
        else {
            panic!("the control response lost the truncated line");
        };
        assert_eq!(text, &source_line[..DEFAULT_MAX_LINE_BYTES]);
        assert!(*truncated);
        assert!(
            at_ms.is_some(),
            "the control response lost the line's capture time"
        );
    }

    /// `supervisor.terminals` reads journal files. On a single-worker runtime a
    /// read done on the worker thread would stall every other task until it
    /// finished; the read must run off the worker so this test's own task keeps
    /// running while the read is paused.
    #[tokio::test(flavor = "current_thread")]
    async fn supervisor_terminals_reads_the_journal_off_the_runtime_worker() {
        let dir = TestTempDir::new("terminals-off-worker");
        let journal_path = dir.join("terminals.jsonl");
        let registry = Arc::new(Registry::default());
        let supervisor_handle = SupervisorHandle::new();
        let supervisor =
            Supervisor::new(Arc::clone(&registry), RestartPolicy::new(1, Duration::ZERO))
                .with_handle(supervisor_handle.clone())
                .with_terminal_journal(journal_path.clone(), "off-worker-daemon".to_string());
        let module = supervisor
            .spawn(ModuleSpec {
                module_id: "terminal-off-worker".to_string(),
                program: fake_aft_stub_path(),
                args: Vec::new(),
                env: vec![("FAKE_AFT_EXIT_CODE".to_string(), "23".to_string())],
                reserved: false,
                reserved_prefixes: Vec::new(),
                protocol: ModuleProtocol::Subc,
                overlap: Default::default(),
            })
            .unwrap();
        let deadline = Instant::now() + Duration::from_secs(5);
        while module.terminal_history().entries.len() != 2 {
            assert!(Instant::now() < deadline, "module did not record two exits");
            sleep(Duration::from_millis(10)).await;
        }

        let (started, release) = crate::terminal_journal::read_pause::install(&journal_path);
        let handler =
            Arc::new(ControlHandler::new(Arc::clone(&registry)).with_supervisor(supervisor_handle));
        let frame = Frame::build(
            FrameType::Request,
            control_flags(),
            0,
            0,
            1,
            serde_json::to_vec(&ClientControlRequest::SupervisorTerminals {
                module_id: "terminal-off-worker".to_string(),
            })
            .unwrap(),
        )
        .unwrap();
        let (ctx, _egress) = route_ctx(ConnectionId::new(1));
        let spawned_at = std::time::Instant::now();
        let read = tokio::spawn({
            let handler = Arc::clone(&handler);
            async move { handler.handle_control_frame(&ctx, frame).await }
        });
        // Waiting for the pause from a blocking thread keeps this task pending,
        // so the runtime's single worker is free to run the read task.
        tokio::task::spawn_blocking(move || started.recv_timeout(Duration::from_secs(5)))
            .await
            .unwrap()
            .expect("the history read reached its pause");
        let elapsed = spawned_at.elapsed();
        assert!(
            elapsed < Duration::from_secs(2) && !read.is_finished(),
            "this task could not run while the history read was paused \
             (resumed after {elapsed:?}, read finished: {})",
            read.is_finished()
        );

        drop(release);
        let responses = read.await.unwrap().unwrap();
        let response: ClientControlResponse = serde_json::from_slice(&responses[0].body).unwrap();
        let ClientControlResponse::SupervisorTerminals { terminals, .. } = response else {
            panic!("expected supervisor.terminals response");
        };
        assert_eq!(terminals.entries.len(), 2);
        assert_eq!(terminals.journal_skipped_lines, 0);
        assert_eq!(terminals.journal_read_errors, 0);
    }

    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn supervisor_terminals_golden_is_generated_through_the_real_handler() {
        let registry = Arc::new(Registry::default());
        let supervisor_handle = SupervisorHandle::new();
        let supervisor =
            Supervisor::new(Arc::clone(&registry), RestartPolicy::new(1, Duration::ZERO))
                .with_handle(supervisor_handle.clone());
        let module = supervisor
            .spawn(ModuleSpec {
                module_id: "terminal-golden".to_string(),
                program: fake_aft_stub_path(),
                args: Vec::new(),
                env: vec![("FAKE_AFT_EXIT_CODE".to_string(), "23".to_string())],
                reserved: false,
                reserved_prefixes: Vec::new(),
                protocol: ModuleProtocol::Subc,
                overlap: Default::default(),
            })
            .unwrap();

        let deadline = Instant::now() + Duration::from_secs(5);
        while module.terminal_history().entries.len() != 2 {
            assert!(
                Instant::now() < deadline,
                "module did not retain two terminal exits: {:?}",
                module.terminal_history()
            );
            sleep(Duration::from_millis(10)).await;
        }

        let handler = ControlHandler::new(Arc::clone(&registry)).with_supervisor(supervisor_handle);
        let request = ClientControlRequest::SupervisorTerminals {
            module_id: "terminal-golden".to_string(),
        };
        let frame = Frame::build(
            FrameType::Request,
            control_flags(),
            0,
            0,
            1,
            serde_json::to_vec(&request).unwrap(),
        )
        .unwrap();
        let (ctx, _egress) = route_ctx(ConnectionId::new(1));
        let responses = handler.handle_control_frame(&ctx, frame).await.unwrap();
        let response: ClientControlResponse = serde_json::from_slice(&responses[0].body).unwrap();
        let ClientControlResponse::SupervisorTerminals { terminals, .. } = &response else {
            panic!("expected supervisor.terminals response");
        };
        assert_eq!(terminals.entries.len(), 2);
        assert_eq!(terminals.dropped, 0);

        let mut rendered = serde_json::to_value(response).unwrap();
        // Wall-clock fields are the observation contract, but not stable fixture
        // bytes; normalize only them after the real handler has shaped the response.
        rendered["daemon_started_at_ms"] = json!(1_700_000_000_000u64);
        for (index, entry) in rendered["entries"]
            .as_array_mut()
            .expect("terminal response entries array")
            .iter_mut()
            .enumerate()
        {
            entry["at_ms"] = json!(1_700_000_000_001u64 + index as u64);
        }

        let golden_path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
            .join("../subc-control/tests/golden/client_control_response_supervisor_terminals.json");
        let serialized = serde_json::to_string_pretty(&rendered).unwrap() + "\n";
        if std::env::var_os("UPDATE_GOLDEN").is_some() {
            std::fs::write(&golden_path, &serialized).unwrap();
        }
        let expected: Value =
            serde_json::from_str(&std::fs::read_to_string(&golden_path).unwrap()).unwrap();
        assert_eq!(rendered, expected);
    }

    #[test]
    fn hello_registers_manifest_and_returns_ack() {
        let registry = Arc::new(Registry::default());
        let handler = ControlHandler::new(Arc::clone(&registry));
        let conn = ConnectionId::new(1);

        let responses = handler
            .handle_control(conn, hello_frame("aft", PROTOCOL_VERSION, 7))
            .unwrap();

        assert_eq!(responses.len(), 1);
        assert_eq!(responses[0].header.ty, FrameType::HelloAck);
        assert_eq!(responses[0].header.channel, 0);
        assert_eq!(responses[0].header.corr, 7);
        let ack = parse_ack(&responses[0]);
        assert_eq!(ack.negotiated_ver, PROTOCOL_VERSION);
        assert!(ack
            .subc_capabilities
            .contains(&CAP_MANIFEST_REGISTRATION.to_string()));
        assert!(ack.subc_ops.contains(&ops::SUPERVISOR_LIST.to_string()));
        assert!(ack.subc_ops.contains(&ops::SUPERVISOR_RESTART.to_string()));
        assert!(ack
            .subc_ops
            .contains(&ops::SUPERVISOR_SET_ENABLED.to_string()));
        assert!(ack
            .subc_ops
            .contains(&MODULE_TO_SUBC_OP_CATALOG_UPDATE.to_string()));

        let registration = registry.get_module("aft").unwrap().unwrap();
        assert_eq!(registration.negotiated_ver, PROTOCOL_VERSION);
        assert_eq!(registration.state, ChannelState::Active);
        assert_eq!(registration.connection_id, conn);
        assert_eq!(registration.control_ops, module_baseline_control_ops());
    }

    #[test]
    fn capability_grammar_refusals_name_the_field_and_leave_no_catalog_entry() {
        let invalid_identifiers = [
            ("case_change", "credentials-Provider/v1"),
            ("leading_zero", "credentials-provider/v01"),
            ("trailing_hyphen", "credentials-provider-/v1"),
            ("consecutive_hyphens", "credentials--provider/v1"),
            ("uppercase", "Credentials-provider/v1"),
            ("missing_v", "credentials-provider/1"),
            ("whitespace", "credentials provider/v1"),
            ("zero_version", "credentials-provider/v0"),
            ("out_of_range_version", "credentials-provider/v4294967296"),
            (
                "overlength_name",
                "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/v1",
            ),
        ];
        let mut cases = invalid_identifiers
            .into_iter()
            .map(|(name, identifier)| {
                (
                    format!("identifier_{name}"),
                    "capabilities.provides[0]".to_string(),
                    identifier.to_string(),
                    json!({ "provides": [identifier] }),
                    None,
                )
            })
            .collect::<Vec<_>>();
        cases.extend([
            (
                "unknown_need".to_string(),
                "capabilities.requires[0].need".to_string(),
                "deferred".to_string(),
                json!({ "requires": [{ "capability": "credentials-provider/v1", "need": "deferred" }] }),
                None,
            ),
            (
                "duplicate_provides".to_string(),
                "capabilities.provides[1]".to_string(),
                "credentials-provider/v1".to_string(),
                json!({ "provides": ["credentials-provider/v1", "credentials-provider/v1"] }),
                None,
            ),
            (
                "duplicate_must_never_reach".to_string(),
                "capabilities.must_never_reach[1]".to_string(),
                "credentials-provider/v1".to_string(),
                json!({ "must_never_reach": ["credentials-provider/v1", "credentials-provider/v1"] }),
                None,
            ),
            (
                "duplicate_requires_same_need".to_string(),
                "capabilities.requires[1]".to_string(),
                "credentials-provider/v1".to_string(),
                json!({ "requires": [
                    { "capability": "credentials-provider/v1", "need": "required" },
                    { "capability": "credentials-provider/v1", "need": "required" }
                ] }),
                None,
            ),
            (
                "duplicate_requires_conflicting_need".to_string(),
                "capabilities.requires[1]".to_string(),
                "credentials-provider/v1".to_string(),
                json!({ "requires": [
                    { "capability": "credentials-provider/v1", "need": "required" },
                    { "capability": "credentials-provider/v1", "need": "optional" }
                ] }),
                None,
            ),
            (
                "capabilities_root_pointer".to_string(),
                "runtime_computed[0]".to_string(),
                "/capabilities".to_string(),
                json!({}),
                Some(json!(["/capabilities"])),
            ),
            (
                "capabilities_descendant_pointer".to_string(),
                "runtime_computed[0]".to_string(),
                "/capabilities/provides".to_string(),
                json!({}),
                Some(json!(["/capabilities/provides"])),
            ),
            (
                "malformed_pointer_without_leading_slash".to_string(),
                "runtime_computed[0]".to_string(),
                "capabilities".to_string(),
                json!({}),
                Some(json!(["capabilities"])),
            ),
            (
                "malformed_pointer_escape".to_string(),
                "runtime_computed[0]".to_string(),
                "/roles/~2/tools".to_string(),
                json!({}),
                Some(json!(["/roles/~2/tools"])),
            ),
            (
                "unknown_capabilities_field".to_string(),
                "capabilities.future".to_string(),
                "<array>".to_string(),
                json!({ "future": [] }),
                None,
            ),
        ]);

        for (index, (name, field, value, capabilities, runtime_computed)) in
            cases.into_iter().enumerate()
        {
            let registry = Arc::new(Registry::default());
            let handler = ControlHandler::new(Arc::clone(&registry));
            let response = handler
                .handle_control(
                    ConnectionId::new((index + 1) as u64),
                    capability_grammar_hello_frame(
                        capabilities,
                        runtime_computed,
                        index as u64 + 1,
                    ),
                )
                .expect("invalid HELLO returns a refusal");

            assert_eq!(response.len(), 1, "{name} must emit one refusal");
            let error = parse_error(&response[0]);
            assert_eq!(error["code"], "invalid_capability_grammar", "{name}");
            let message = error["message"]
                .as_str()
                .expect("error message is a string");
            assert!(
                message.contains(&field),
                "{name}: field missing from {message}"
            );
            assert!(
                message.contains(&value),
                "{name}: value missing from {message}"
            );
            assert_eq!(
                registry
                    .active_registration_count()
                    .expect("registry reads"),
                0,
                "{name}: refused HELLO must not create a catalog entry"
            );
        }
    }

    #[test]
    fn legal_runtime_pointer_and_capabilities_are_mirrored_in_catalog_list() {
        let registry = Arc::new(Registry::default());
        let handler = ControlHandler::new(Arc::clone(&registry));
        let capabilities = json!({
            "provides": ["credentials-provider/v1"],
            "requires": [{ "capability": "context-transform/v1", "need": "optional" }],
            "must_never_reach": ["federation-transport/v1"]
        });
        let response = handler
            .handle_control(
                ConnectionId::new(99),
                capability_grammar_hello_frame(
                    capabilities.clone(),
                    Some(json!(["/roles/0/tools"])),
                    99,
                ),
            )
            .expect("valid HELLO registers");
        assert_eq!(response[0].header.ty, FrameType::HelloAck);

        let request = Frame::build(
            FrameType::Request,
            control_flags(),
            0,
            0,
            100,
            serde_json::to_vec(&ClientControlRequest::CatalogList { module_id: None })
                .expect("catalog request serializes"),
        )
        .expect("catalog request frame builds");
        let response = handler
            .handle_catalog_list(request, None)
            .expect("catalog list succeeds");
        let ClientControlResponse::CatalogList { modules, .. } =
            serde_json::from_slice(&response[0].body).expect("catalog response decodes")
        else {
            panic!("catalog request must return catalog.list");
        };
        assert_eq!(modules.len(), 1);
        assert_eq!(
            serde_json::to_value(&modules[0].capabilities).expect("catalog capabilities serialize"),
            capabilities
        );
    }

    #[test]
    fn catalog_list_mirrors_management_operation_description() {
        let registry = Arc::new(Registry::default());
        let handler = ControlHandler::new(Arc::clone(&registry));
        let description = "List managed records and return their identifiers and metadata.";
        let mut manifest = manifest("described-management", PROTOCOL_VERSION);
        manifest.provides = vec![ProviderRole::ManagementSurface {
            operations: vec![ManagementOperation {
                name: "records.list".to_string(),
                kind: ManagementOperationKind::Query,
                description: Some(description.to_string()),
            }],
            config_schema: json!({"type": "object"}),
            observability: vec![ObservabilitySurface {
                name: "records.stats".to_string(),
                kind: ObservabilityKind::Snapshot,
            }],
            identity_scope: vec![IdentityScope::Project],
            concurrency: Concurrency::ModuleManaged,
        }];
        registry
            .register_with_control_ops(
                manifest,
                PROTOCOL_VERSION,
                ConnectionId::new(99),
                Vec::new(),
            )
            .expect("described management manifest registers");

        let request = Frame::build(
            FrameType::Request,
            control_flags(),
            0,
            0,
            100,
            serde_json::to_vec(&ClientControlRequest::CatalogList { module_id: None })
                .expect("catalog request serializes"),
        )
        .expect("catalog request frame builds");
        let response = handler
            .handle_catalog_list(request, None)
            .expect("catalog list succeeds");
        let body: Value = serde_json::from_slice(&response[0].body).expect("catalog response JSON");
        assert_eq!(
            body["modules"][0]["roles"][0]["operations"][0]["description"], description,
            "catalog.list must preserve the declared operation description verbatim"
        );
    }

    #[test]
    fn reserved_capability_refusal_mutation_proof_leaves_no_catalog_entry() {
        let registry = Arc::new(Registry::default());
        let handler = ControlHandler::new(Arc::clone(&registry)).with_capability_config(
            [("vault".to_string(), true), ("squatter".to_string(), true)],
            BTreeMap::from([("credentials-provider/v1".to_string(), "vault".to_string())]),
        );
        let mut squatter = manifest("squatter", PROTOCOL_VERSION);
        squatter.capabilities = Some(subc_protocol::manifest::CapabilityDeclarations {
            provides: vec!["credentials-provider/v1".to_string()],
            requires: Vec::new(),
            must_never_reach: Vec::new(),
        });
        let frame = Frame::build(
            FrameType::Hello,
            control_flags(),
            0,
            0,
            77,
            serde_json::to_vec(&ModuleHelloBody {
                manifest: squatter,
                protocol_ver: PROTOCOL_VERSION,
                control_ops: None,
                launch_nonce: None,
            })
            .expect("HELLO serializes"),
        )
        .expect("HELLO frame builds");
        let response = handler
            .handle_control(ConnectionId::new(77), frame)
            .expect("reserved claim receives a typed refusal");
        assert_eq!(parse_error(&response[0])["code"], "reserved_capability");
        assert_eq!(
            registry
                .active_registration_count()
                .expect("registry reads"),
            0,
            "a reserved capability refusal must not leave a catalog entry"
        );
    }

    #[test]
    fn stale_relay_settlement_cannot_release_the_half_open_probe() {
        for settlement in ["timeout", "inconclusive", "drop"] {
            let breakers = RouteBindBreakers::default();
            let RouteBindAdmission::Admitted {
                guard: mut old,
                probe: false,
            } = breakers.admit("prov")
            else {
                panic!("ordinary relay admitted")
            };
            let RouteBindAdmission::Admitted {
                guard: mut opener, ..
            } = breakers.admit("prov")
            else {
                panic!("second relay admitted")
            };
            assert!(
                !opener
                    .record_timeout(1, Duration::ZERO)
                    .unwrap()
                    .reopened_after_probe
            );
            let RouteBindAdmission::Admitted {
                guard: mut probe,
                probe: true,
            } = breakers.admit("prov")
            else {
                panic!("one cooldown probe admitted")
            };
            match settlement {
                "timeout" => assert!(
                    !old.record_timeout(1, Duration::ZERO)
                        .unwrap()
                        .reopened_after_probe
                ),
                "inconclusive" => old.record_inconclusive(),
                "drop" => drop(old),
                _ => unreachable!(),
            }
            assert!(
                matches!(
                    breakers.admit("prov"),
                    RouteBindAdmission::Refused {
                        probe_in_flight: true,
                        ..
                    }
                ),
                "{settlement} of a pre-open relay cannot release the real probe"
            );
            assert!(
                probe
                    .record_timeout(1, Duration::ZERO)
                    .unwrap()
                    .reopened_after_probe
            );
            assert!(matches!(
                breakers.admit("prov"),
                RouteBindAdmission::Admitted { probe: true, .. }
            ));
        }
        let breakers = RouteBindBreakers::default();
        let admit = || match breakers.admit("prov") {
            RouteBindAdmission::Admitted { guard, .. } => guard,
            _ => panic!("relay admitted"),
        };
        admit().record_timeout(1, Duration::ZERO);
        let mut old_probe = admit();
        breakers.reset_for_new_module_connection("prov");
        admit().record_timeout(1, Duration::ZERO);
        let _new_probe = admit();
        old_probe.record_inconclusive();
        assert!(matches!(
            breakers.admit("prov"),
            RouteBindAdmission::Refused {
                probe_in_flight: true,
                ..
            }
        ));
    }

    #[tokio::test]
    async fn catalog_update_refuses_reserved_capabilities_for_active_and_candidate() {
        for candidate in [false, true] {
            let registry = Arc::new(Registry::default());
            let handler = ControlHandler::new(Arc::clone(&registry)).with_capability_config(
                [("vault".to_string(), true), ("squatter".to_string(), true)],
                BTreeMap::from([("credentials-provider/v1".to_string(), "vault".to_string())]),
            );
            let conn = ConnectionId::new(77);
            let (ctx, mut rx) = route_ctx(conn);
            let initial = capability_manifest("squatter", &[], &[]);
            if candidate {
                registry
                    .register_candidate_with_control_ops(
                        initial.clone(),
                        PROTOCOL_VERSION,
                        conn,
                        module_baseline_control_ops(),
                    )
                    .unwrap();
                handler
                    .forwarding
                    .register_candidate_module_connection(
                        conn,
                        "squatter".to_string(),
                        PROTOCOL_VERSION,
                        manifest_concurrency(&initial),
                        ctx.egress.clone(),
                    )
                    .unwrap();
            } else {
                hello_via_sink(
                    &handler,
                    &ctx,
                    &mut rx,
                    hello_frame_with_manifest(initial.clone(), 1),
                )
                .await;
            }
            let response = handler
                .handle_control_frame(
                    &ctx,
                    catalog_update_with_capabilities_frame(
                        2,
                        capability_manifest("squatter", &["credentials-provider/v1"], &[])
                            .capabilities
                            .unwrap(),
                    ),
                )
                .await
                .unwrap();
            assert_eq!(parse_error(&response[0])["code"], "reserved_capability");
            assert_eq!(
                registry
                    .get_module_by_connection(conn)
                    .unwrap()
                    .unwrap()
                    .manifest,
                initial
            );
        }
    }

    #[test]
    fn server_describe_surfaces_required_capability_verdict_fields() {
        let registry = Arc::new(Registry::default());
        let handler = ControlHandler::new(Arc::clone(&registry)).with_capability_config(
            [
                ("consumer".to_string(), true),
                ("provider".to_string(), false),
            ],
            BTreeMap::new(),
        );
        let mut consumer = manifest("consumer", PROTOCOL_VERSION);
        consumer.capabilities = Some(subc_protocol::manifest::CapabilityDeclarations {
            provides: Vec::new(),
            requires: vec![subc_protocol::manifest::CapabilityRequirement {
                capability: "credentials-provider/v1".to_string(),
                need: subc_protocol::manifest::CapabilityNeed::Required,
            }],
            must_never_reach: Vec::new(),
        });
        let hello = Frame::build(
            FrameType::Hello,
            control_flags(),
            0,
            0,
            78,
            serde_json::to_vec(&ModuleHelloBody {
                manifest: consumer,
                protocol_ver: PROTOCOL_VERSION,
                control_ops: None,
                launch_nonce: None,
            })
            .expect("HELLO serializes"),
        )
        .expect("HELLO frame builds");
        handler
            .handle_control(ConnectionId::new(78), hello)
            .expect("consumer registers");
        let describe = Frame::build(
            FrameType::Request,
            control_flags(),
            0,
            0,
            79,
            serde_json::to_vec(&ClientControlRequest::ServerDescribe {})
                .expect("request serializes"),
        )
        .expect("describe frame builds");
        let response = handler
            .handle_server_describe(describe)
            .expect("server.describe succeeds");
        let rendered: Value = serde_json::from_slice(&response[0].body).expect("response JSON");
        let requirement = &rendered["capability_requirements"][0];
        assert_eq!(requirement["consumer"], "consumer");
        assert_eq!(requirement["verdict"], "never_provided");
        assert_eq!(requirement["episode_seq"], 1);
        assert_eq!(requirement["config_satisfiable"], false);
        assert_eq!(requirement["runtime_available"], false);
        assert!(requirement["detail"]
            .as_str()
            .expect("detail string")
            .contains("credentials-provider/v1"));
    }

    #[test]
    fn catalog_list_omits_capabilities_for_legacy_manifest() {
        let registry = Arc::new(Registry::default());
        let handler = ControlHandler::new(Arc::clone(&registry));
        let hello = handler
            .handle_control(
                ConnectionId::new(101),
                hello_frame("legacy-capability-manifest", PROTOCOL_VERSION, 101),
            )
            .expect("legacy HELLO registers");
        assert_eq!(hello[0].header.ty, FrameType::HelloAck);

        let request = Frame::build(
            FrameType::Request,
            control_flags(),
            0,
            0,
            102,
            serde_json::to_vec(&ClientControlRequest::CatalogList { module_id: None })
                .expect("catalog request serializes"),
        )
        .expect("catalog request frame builds");
        let response = handler
            .handle_catalog_list(request, None)
            .expect("catalog list succeeds");
        let body: Value = serde_json::from_slice(&response[0].body).expect("catalog response JSON");
        assert!(
            body["modules"][0].get("capabilities").is_none(),
            "legacy manifest must retain an absent capabilities field on catalog.list"
        );
    }

    #[test]
    fn hello_ack_omits_storage_when_no_storage_config() {
        let registry = Arc::new(Registry::default());
        let handler = ControlHandler::new(Arc::clone(&registry));
        let responses = handler
            .handle_control(
                ConnectionId::new(1),
                hello_frame("aft", PROTOCOL_VERSION, 7),
            )
            .unwrap();
        let ack = parse_ack(&responses[0]);
        assert_eq!(ack.storage, None, "no storage config -> no descriptor");
        assert_eq!(ack.machine_id, None, "no machine id configured -> no field");
    }

    #[tokio::test]
    async fn hello_ack_and_server_describe_carry_the_configured_machine_id() {
        let id = crate::machine_id::MachineId::parse("0123456789abcdef0123456789abcdef").unwrap();
        let registry = Arc::new(Registry::default());
        let handler = ControlHandler::new(Arc::clone(&registry)).with_machine_id(Some(id.clone()));
        let responses = handler
            .handle_control(
                ConnectionId::new(1),
                hello_frame("aft", PROTOCOL_VERSION, 7),
            )
            .unwrap();
        let ack = parse_ack(&responses[0]);
        assert_eq!(ack.machine_id.as_deref(), Some(id.as_str()));

        let described = handler
            .handle_control_frame(
                &route_ctx(ConnectionId::new(2)).0,
                Frame::build(
                    FrameType::Request,
                    control_flags(),
                    0,
                    0,
                    9,
                    serde_json::to_vec(&ClientControlRequest::ServerDescribe {}).unwrap(),
                )
                .unwrap(),
            )
            .await
            .unwrap();
        let ClientControlResponse::ServerDescribe { machine_id, .. } =
            serde_json::from_slice(&described[0].body).unwrap()
        else {
            panic!("server.describe answered with another shape");
        };
        assert_eq!(machine_id.as_deref(), Some(id.as_str()));
    }

    #[test]
    fn hello_ack_delivers_resolved_storage_descriptor_per_module() {
        // With a central sqlite storage policy, each registering module gets its
        // own resolved descriptor in HELLO_ACK, keyed by its module id.
        let registry = Arc::new(Registry::default());
        let handler = ControlHandler::new(Arc::clone(&registry)).with_storage_config(Some(
            crate::daemon_config::StorageConfig::Sqlite {
                data_home: std::path::PathBuf::from("/data"),
            },
        ));

        let responses = handler
            .handle_control(
                ConnectionId::new(1),
                hello_frame("alfonso-routing", PROTOCOL_VERSION, 7),
            )
            .unwrap();
        let ack = parse_ack(&responses[0]);
        assert_eq!(
            ack.storage,
            Some(serde_json::json!({
                "module_id": "alfonso-routing",
                "storage_namespace": "default",
                "isolation": { "kind": "module" },
                "backend": {
                    "backend": "sqlite",
                    "path": "/data/cortexkit/alfonso-routing/store.db"
                }
            })),
            "the delivered descriptor is the module's own sqlite store path"
        );
    }

    #[test]
    fn hello_control_ops_none_is_baseline_and_guard_rejects_synthetic_gated_op() {
        let registry = Arc::new(Registry::default());
        let handler = ControlHandler::new(Arc::clone(&registry));
        let conn = ConnectionId::new(1);
        let responses = handler
            .handle_control(
                conn,
                hello_frame_with_control_ops("aft", PROTOCOL_VERSION, 7, None),
            )
            .unwrap();
        assert_eq!(responses[0].header.ty, FrameType::HelloAck);
        let registration = registry.get_module("aft").unwrap().unwrap();
        assert_eq!(registration.control_ops, module_baseline_control_ops());

        let frame =
            Frame::build(FrameType::Request, control_flags(), 0, 0, 77, Vec::new()).unwrap();
        assert!(handler
            .guard_module_control_op(&frame, "aft", "route.bind")
            .unwrap()
            .is_none());
        let error = handler
            .guard_module_control_op(&frame, "aft", "test.synthetic")
            .unwrap()
            .expect("synthetic ungranted op should be rejected");
        assert_eq!(error.header.ty, FrameType::Error);
        assert_eq!(parse_error(&error)["code"], "op_not_allowed");
    }

    #[test]
    fn hello_control_ops_some_adds_optional_grants() {
        let registry = Arc::new(Registry::default());
        let handler = ControlHandler::new(Arc::clone(&registry));
        handler
            .handle_control(
                ConnectionId::new(1),
                hello_frame_with_control_ops(
                    "aft",
                    PROTOCOL_VERSION,
                    7,
                    Some(vec![
                        "future.synthetic".to_string(),
                        "route.bind".to_string(),
                    ]),
                ),
            )
            .unwrap();
        let registration = registry.get_module("aft").unwrap().unwrap();
        assert_eq!(
            registration.control_ops,
            vec![
                "route.bind".to_string(),
                "route.status".to_string(),
                "future.synthetic".to_string(),
            ]
        );
        let frame =
            Frame::build(FrameType::Request, control_flags(), 0, 0, 78, Vec::new()).unwrap();
        assert!(handler
            .guard_module_control_op(&frame, "aft", "future.synthetic")
            .unwrap()
            .is_none());
    }

    #[tokio::test]
    async fn health_probe_refuses_unadvertised_module_without_sending_frame() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding));
        let (module_ctx, mut module_rx) = route_ctx(ConnectionId::new(10));
        hello_via_sink(
            &handler,
            &module_ctx,
            &mut module_rx,
            hello_frame_with_control_ops("aft", PROTOCOL_VERSION, 7, None),
        )
        .await;

        let (client_ctx, _client_rx) = route_ctx(ConnectionId::new(20));
        let responses = handler
            .handle_control_frame(&client_ctx, supervisor_health_probe_frame(77, "aft"))
            .await
            .unwrap();
        assert_eq!(responses.len(), 1);
        assert_eq!(responses[0].header.ty, FrameType::Error);
        assert_eq!(parse_error(&responses[0])["code"], "health_not_advertised");
        assert!(module_rx.try_recv().is_err());
    }

    #[tokio::test]
    async fn health_probe_demuxes_while_route_bind_relay_is_in_flight() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding));
        let (module_ctx, mut module_rx) = route_ctx(ConnectionId::new(30));
        hello_via_sink(
            &handler,
            &module_ctx,
            &mut module_rx,
            hello_frame_with_control_ops(
                "aft",
                PROTOCOL_VERSION,
                7,
                Some(vec![MODULE_CONTROL_OP_HEALTH_CHECK.to_string()]),
            ),
        )
        .await;

        let project_root = unique_project_root("demux");
        let (route_client_ctx, mut route_client_rx) = route_ctx(ConnectionId::new(31));
        let route_handler = handler.clone();
        let route_task = tokio::spawn(async move {
            route_handler
                .handle_control_frame(
                    &route_client_ctx,
                    route_open_frame(100, "aft", project_root),
                )
                .await
                .unwrap()
        });
        let bind_frame = tokio::time::timeout(Duration::from_secs(1), module_rx.recv())
            .await
            .unwrap()
            .unwrap();
        assert!(matches!(
            serde_json::from_slice::<ModuleControlRequest>(&bind_frame.body).unwrap(),
            ModuleControlRequest::RouteBind { .. }
        ));

        let (health_client_ctx, _health_client_rx) = route_ctx(ConnectionId::new(32));
        let health_handler = handler.clone();
        let health_task = tokio::spawn(async move {
            health_handler
                .handle_control_frame(
                    &health_client_ctx,
                    supervisor_health_probe_frame(101, "aft"),
                )
                .await
                .unwrap()
        });
        let health_frame = tokio::time::timeout(Duration::from_secs(1), module_rx.recv())
            .await
            .unwrap()
            .unwrap();
        assert_eq!(
            serde_json::from_slice::<ModuleControlRequest>(&health_frame.body).unwrap(),
            ModuleControlRequest::HealthCheck {}
        );

        handler
            .handle_control_frame(
                &module_ctx,
                health_response(health_frame.header.corr, HealthStatus::Degraded),
            )
            .await
            .unwrap();
        let health_response = health_task.await.unwrap();
        assert_eq!(health_response.len(), 1);
        match serde_json::from_slice::<ClientControlResponse>(&health_response[0].body).unwrap() {
            ClientControlResponse::SupervisorHealthProbe {
                module_id,
                status,
                detail,
                metrics,
            } => {
                assert_eq!(module_id, "aft");
                assert_eq!(status, HealthStatus::Degraded);
                assert_eq!(detail.as_deref(), Some("warming"));
                assert_eq!(metrics, Some(json!({"queue_depth": 3})));
            }
            other => panic!("unexpected health response: {other:?}"),
        }

        handler
            .handle_control_frame(&module_ctx, route_bind_ack(bind_frame.header.corr))
            .await
            .unwrap();
        let route_response = route_task.await.unwrap();
        assert!(route_response.is_empty());
        let published = route_client_rx.recv().await.unwrap();
        assert!(matches!(
            serde_json::from_slice::<ClientControlResponse>(&published.body).unwrap(),
            ClientControlResponse::RouteOpen { .. }
        ));
    }

    /// Start one `route.open` on `client_connection` and return its still-running
    /// handler task together with the `route.bind` the module received for it.
    /// The handler blocks until the module answers, so it has to run as a task
    /// while the test drives the module side.
    async fn relay_route_open(
        handler: &ControlHandler,
        client_connection: ConnectionId,
        client_egress: &FrameSink,
        module_rx: &mut mpsc::Receiver<crate::router::OutboundFrame>,
        corr: u64,
        module_id: &str,
        project_root_label: &str,
    ) -> (tokio::task::JoinHandle<Vec<Frame>>, Frame) {
        let ctx = RouteCtx {
            connection_id: client_connection,
            egress: client_egress.clone(),
        };
        let handler = handler.clone();
        let project_root = unique_project_root(project_root_label);
        let module_id = module_id.to_string();
        let dispatch = tracing::dispatcher::get_default(|dispatch| dispatch.clone());
        let task = tokio::spawn(async move {
            let _guard = tracing::dispatcher::set_default(&dispatch);
            handler
                .handle_control_frame(&ctx, route_open_frame(corr, &module_id, project_root))
                .await
                .unwrap()
        });
        let bind = tokio::time::timeout(Duration::from_secs(2), module_rx.recv())
            .await
            .expect("module receives the relayed route.bind")
            .expect("module egress is open");
        (task, bind.frame)
    }

    fn route_bind_channel(frame: &Frame) -> (u16, u32) {
        match serde_json::from_slice::<ModuleControlRequest>(&frame.body).unwrap() {
            ModuleControlRequest::RouteBind {
                route_channel,
                epoch,
                ..
            } => (route_channel, epoch),
            other => panic!("expected a route.bind request, got {other:?}"),
        }
    }

    fn published_route(frame: &Frame) -> (u16, u32) {
        match serde_json::from_slice::<ClientControlResponse>(&frame.body).unwrap() {
            ClientControlResponse::RouteOpen {
                route_channel,
                route_epoch,
            } => (route_channel, route_epoch),
            other => panic!("expected a route.open response, got {other:?}"),
        }
    }

    /// Reproduction of a production outage. A client had `route.open`s in
    /// flight to a module and was already marked closing -- its egress had refused a
    /// module frame, so the daemon asked its connection to end -- while its sink
    /// was still open. When the module acked those binds, the daemon refused to
    /// commit a route for a closing client, and that refusal was returned from
    /// the MODULE connection's frame handler, where a router error that has no
    /// ERROR-frame translation ends the connection. The module saw EOF, exited 0,
    /// the supervisor correctly did not respawn a clean exit, and every seat lost
    /// its tools for hours -- one client's teardown took down a connection
    /// carrying ~170 other routes.
    ///
    /// The window is opened here by calling the production path that opens it
    /// (`escalate_client_delivery_failure`) rather than by closing a socket. The
    /// state that matters is "in `closing_connections`, sink still open, relay
    /// still pending", and it lasts only from the close request until the
    /// connection loop reacts to it; a socket-level test can flood a client into
    /// that escalation but cannot pin the module's ack inside the window. Closing
    /// the socket instead takes the other path entirely -- connection teardown
    /// removes the pending relay under the same lock, so the ack finds nothing.
    #[tokio::test]
    async fn late_bind_ack_for_a_closing_client_keeps_the_module_connection_serving() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding));

        let module_connection = ConnectionId::new(30);
        let (module_ctx, mut module_rx) = route_ctx(module_connection);
        hello_via_sink(
            &handler,
            &module_ctx,
            &mut module_rx,
            hello_frame("aft", PROTOCOL_VERSION, 7),
        )
        .await;

        let dying_client = ConnectionId::new(31);
        let (dying_ctx, mut dying_rx) = route_ctx(dying_client);

        // A published route on the dying client. The escalation below only marks
        // a connection closing for a route it has already published.
        let (first_task, first_bind) = relay_route_open(
            &handler,
            dying_client,
            &dying_ctx.egress,
            &mut module_rx,
            100,
            "aft",
            "closing-first",
        )
        .await;
        handler
            .handle_control_frame(&module_ctx, route_bind_ack(first_bind.header.corr))
            .await
            .unwrap();
        assert!(first_task.await.unwrap().is_empty());
        let (first_channel, first_epoch) = published_route(&dying_rx.recv().await.unwrap());

        // A second route.open from the same client, relayed and awaiting its ack.
        let (second_task, second_bind) = relay_route_open(
            &handler,
            dying_client,
            &dying_ctx.egress,
            &mut module_rx,
            101,
            "aft",
            "closing-second",
        )
        .await;
        let (abandoned_channel, abandoned_epoch) = route_bind_channel(&second_bind);

        // The window: the client is closing, its sink is still open, and its
        // second bind is still pending.
        assert!(forwarding
            .escalate_client_delivery_failure(
                dying_client,
                first_channel,
                first_epoch,
                CloseReason::new(
                    "module_to_client_delivery_failed",
                    "client egress refused a module frame",
                ),
                crate::forwarding::UndeliveredFrame {
                    module_id: None,
                    sink: &dying_ctx.egress,
                },
            )
            .unwrap());
        assert!(!dying_ctx.egress.is_closed());

        // The frame that used to end the module connection.
        let ack = handler
            .handle_control_frame(&module_ctx, route_bind_ack(second_bind.header.corr))
            .await;
        let module_loop_error = ack.as_ref().err().map(ToString::to_string);
        if module_loop_error.is_some() {
            // What the server's connection loop does with a router error that has
            // no ERROR-frame translation: end the connection, which releases the
            // module's registration and every route on it.
            handler.cleanup_connection(module_connection).unwrap();
        }
        // Read the module's next frame before opening the co-tenant's route, so
        // the GOODBYE assertion below is about THIS ack and not about later
        // traffic. `None` means the module was told nothing.
        let post_ack_module_frame = tokio::time::timeout(Duration::from_secs(1), module_rx.recv())
            .await
            .ok()
            .flatten();

        // 1. The module connection is still registered.
        assert!(
            registry
                .get_module_by_connection(module_connection)
                .unwrap()
                .is_some(),
            "one client's closing connection ended the shared module connection: \
             {module_loop_error:?}"
        );
        // ...and still serving: another client can open and use a route on it.
        let cotenant = ConnectionId::new(32);
        let (cotenant_ctx, mut cotenant_rx) = route_ctx(cotenant);
        let (cotenant_task, cotenant_bind) = relay_route_open(
            &handler,
            cotenant,
            &cotenant_ctx.egress,
            &mut module_rx,
            102,
            "aft",
            "closing-cotenant",
        )
        .await;
        handler
            .handle_control_frame(&module_ctx, route_bind_ack(cotenant_bind.header.corr))
            .await
            .unwrap();
        assert!(cotenant_task.await.unwrap().is_empty());
        let (cotenant_channel, cotenant_epoch) =
            published_route(&cotenant_rx.recv().await.unwrap());
        assert!(matches!(
            forwarding
                .lookup_data_route(cotenant, cotenant_channel, cotenant_epoch)
                .unwrap(),
            DataRoute::Client(DataRouteState::Bound(_))
        ));

        // 2. The module was told to drop the binding it created for the route
        //    that will never be published.
        let goodbye = post_ack_module_frame
            .expect("module receives a GOODBYE for the abandoned route channel");
        assert_eq!(goodbye.header.ty, FrameType::Goodbye);
        assert_eq!(goodbye.header.channel, abandoned_channel);
        assert_eq!(goodbye.header.epoch, abandoned_epoch);

        // 3. The dying client received nothing: no route was ever published to
        //    it. Its route.open is answered as unavailable, which the connection
        //    loop would write to a socket that is already going away.
        assert!(dying_rx.try_recv().is_err());
        let second_response = second_task.await.unwrap();
        assert_eq!(second_response.len(), 1);
        assert_eq!(
            parse_error(&second_response[0])["code"],
            "target_unavailable"
        );
    }

    /// The fence at the module-loop boundary, stated as its own contract: which
    /// forwarding failures are allowed to end the module connection that is being
    /// served. A `ConnectionClosing` naming some client is about that client, and
    /// a module connection is shared; the same error naming the module's own
    /// connection is about this connection and must stay fatal, as must failures
    /// that are about the forwarding table itself.
    #[test]
    fn only_the_modules_own_closing_connection_ends_the_module_loop() {
        let handler = ControlHandler::default();
        let module_connection = ConnectionId::new(30);
        let client_connection = ConnectionId::new(31);

        handler
            .refuse_to_end_module_connection_for_a_client(
                module_connection,
                77,
                ForwardingError::ConnectionClosing {
                    connection_id: client_connection,
                },
            )
            .expect("a closing client must never end the module connection");

        assert!(matches!(
            handler.refuse_to_end_module_connection_for_a_client(
                module_connection,
                78,
                ForwardingError::ConnectionClosing {
                    connection_id: module_connection,
                },
            ),
            Err(RouterError::Forwarding(ForwardingError::ConnectionClosing {
                connection_id
            })) if connection_id == module_connection
        ));
        assert!(matches!(
            handler.refuse_to_end_module_connection_for_a_client(
                module_connection,
                79,
                ForwardingError::Poisoned,
            ),
            Err(RouterError::Forwarding(ForwardingError::Poisoned))
        ));
        assert!(matches!(
            handler.refuse_to_end_module_connection_for_a_client(
                module_connection,
                80,
                ForwardingError::StaleModuleEndpoint,
            ),
            Err(RouterError::Forwarding(
                ForwardingError::StaleModuleEndpoint
            ))
        ));
    }

    /// The spawn-attestation guard is what stops a connected module from claiming
    /// another module's identity and being stamped `Reserved` for it. Every other
    /// test that supplies a consumer_identity supplies a CORRECT one, because a
    /// correct one is what the rest of the flow needs -- so the guard's rejection
    /// branch was never the subject of an assertion, only its acceptance branch.
    ///
    /// Deleting the guard's EFFECT (granting Reserved unconditionally) leaves the
    /// whole subc-core library suite green; only the forwarding integration tests
    /// notice, and they notice for unrelated reasons. This test exists so the
    /// refusal itself is asserted where the guard lives: it fails if the identity
    /// check stops refusing, which is the direction that matters, since a guard
    /// that wrongly ACCEPTS is silent while one that wrongly REJECTS is loud.
    #[tokio::test]
    async fn route_open_refuses_consumer_identity_that_fails_spawn_attestation() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let supervisor = SupervisorHandle::new();
        supervisor.set_spawn_nonce("fed", "fed-nonce".to_string());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding))
                .with_supervisor(supervisor);

        let (target_ctx, mut target_rx) = route_ctx(ConnectionId::new(90));
        hello_via_sink(
            &handler,
            &target_ctx,
            &mut target_rx,
            hello_frame("target", PROTOCOL_VERSION, 1),
        )
        .await;

        // A real supervised module id presenting the wrong nonce. This is the
        // impersonation case: the attacker knows a privileged module_id, which is
        // public, and guesses at the nonce, which is not.
        let wrong_nonce = handler
            .handle_control_frame(
                &route_ctx(ConnectionId::new(91)).0,
                route_open_frame_with_admission_facts(
                    20,
                    "target",
                    unique_project_root("admission-facts"),
                    Some(subc_control::ConsumerIdentity {
                        module_id: "fed".to_string(),
                        launch_nonce: "not-the-real-nonce".to_string(),
                    }),
                    None,
                ),
            )
            .await
            .unwrap();
        assert_eq!(
            parse_error(&wrong_nonce[0])["code"],
            "bad_consumer_identity",
            "a mismatched launch nonce must be refused, not stamped Reserved"
        );

        // A module id the supervisor never spawned at all, so no nonce exists to
        // compare against. An implementation that treats "no record" as "nothing
        // to check" fails open here while passing the case above.
        let never_spawned = handler
            .handle_control_frame(
                &route_ctx(ConnectionId::new(92)).0,
                route_open_frame_with_admission_facts(
                    21,
                    "target",
                    unique_project_root("admission-facts"),
                    Some(subc_control::ConsumerIdentity {
                        module_id: "never-spawned".to_string(),
                        launch_nonce: "any-nonce".to_string(),
                    }),
                    None,
                ),
            )
            .await
            .unwrap();
        assert_eq!(
            parse_error(&never_spawned[0])["code"],
            "bad_consumer_identity",
            "an unspawned module_id must be refused rather than accepted for lack of a record"
        );
    }

    /// The refusal test above proves the guard says NO. Nothing proved it can say
    /// YES, and the difference is not academic: replacing the whole authorization
    /// with `false` -- admitting no consumer identity at all, revoking Reserved
    /// standing for every supervised module in the fleet -- leaves 110 of the 111
    /// library tests GREEN. The one that notices does so by HANGING, because it
    /// waits for a bind that can no longer happen.
    ///
    /// A hang is the weakest signal a suite can produce. In CI it reads as a slow
    /// or flaky test, invites a RETRY rather than an investigation, and the retry
    /// hangs too and gets blamed on the runner. So a total revocation of the
    /// daemon's trust grant would have shipped behind a symptom nobody attributes
    /// to code.
    ///
    /// The bias is structural rather than accidental. A REFUSAL looks like a
    /// failure someone writes a test for; a GRANT looks like the happy path. Every
    /// binary-outcome guard whose STRICTNESS is the point acquires a refusal-heavy
    /// suite for that reason, and this one is the purest case in the daemon.
    ///
    /// This test asserts the EFFECT rather than the absence of an error: the module
    /// receives a RouteBind and it carries `Reserved` naming the attested module.
    /// A guard that admitted nobody would produce no bind at all; one that admitted
    /// everybody would stamp the wrong principal, which the refusal test catches.
    #[tokio::test]
    async fn route_open_stamps_reserved_for_a_correctly_attested_consumer() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let supervisor = SupervisorHandle::new();
        supervisor.set_spawn_nonce("fed", "fed-nonce".to_string());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding))
                .with_supervisor(supervisor);

        let (target_ctx, mut target_rx) = route_ctx(ConnectionId::new(95));
        hello_via_sink(
            &handler,
            &target_ctx,
            &mut target_rx,
            hello_frame("target", PROTOCOL_VERSION, 1),
        )
        .await;

        let (client_ctx, mut client_rx) = route_ctx(ConnectionId::new(96));
        let route_handler = handler.clone();
        let route_task = tokio::spawn(async move {
            route_handler
                .handle_control_frame(
                    &client_ctx,
                    route_open_frame_with_admission_facts(
                        30,
                        "target",
                        unique_project_root("admission-facts"),
                        Some(subc_control::ConsumerIdentity {
                            module_id: "fed".to_string(),
                            launch_nonce: "fed-nonce".to_string(),
                        }),
                        None,
                    ),
                )
                .await
                .unwrap()
        });

        // BOUND THE WAIT. The first version of this test recv'd unbounded, and under
        // the very mutation it exists to catch -- a guard that admits nobody -- no
        // bind is ever sent, so it HUNG rather than failing. That reproduces the
        // exact defect being fixed: a total revocation detected only as a stalled
        // suite, which reads as flakiness and invites a retry. An acceptance test
        // that waits for an effect must bound the wait, or a red becomes a hang.
        let bind_frame = tokio::time::timeout(Duration::from_secs(5), target_rx.recv())
            .await
            .expect("no route.bind within 5s: the consumer-identity guard refused a correctly attested consumer")
            .expect("module control channel closed before route.bind");
        let bind: ModuleControlRequest = serde_json::from_slice(&bind_frame.body).unwrap();
        let ModuleControlRequest::RouteBind { principal, .. } = bind else {
            panic!("expected route.bind")
        };
        assert_eq!(
            principal,
            Some(Principal::Reserved {
                module_id: "fed".to_string()
            }),
            "a correctly attested consumer must be stamped Reserved for its own id"
        );

        handler
            .handle_control_frame(&target_ctx, route_bind_ack(bind_frame.header.corr))
            .await
            .unwrap();
        assert!(route_task.await.unwrap().is_empty());
        assert!(
            matches!(
                serde_json::from_slice::<ClientControlResponse>(
                    &client_rx.recv().await.unwrap().body
                )
                .unwrap(),
                ClientControlResponse::RouteOpen { .. }
            ),
            "the route must actually open, not merely avoid an error"
        );
    }

    #[tokio::test(start_paused = true)]
    async fn supervisor_routes_serializes_live_draining_bindings_from_the_real_handler() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let supervisor = SupervisorHandle::new();
        supervisor.set_spawn_nonce("fed", "fed-nonce".to_string());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding))
                .with_supervisor(supervisor);

        let (target_ctx, mut target_rx) = route_ctx(ConnectionId::new(101));
        hello_via_sink(
            &handler,
            &target_ctx,
            &mut target_rx,
            hello_frame("target", PROTOCOL_VERSION, 1),
        )
        .await;

        let (direct_ctx, mut direct_rx) = route_ctx(ConnectionId::new(102));
        let direct_handler = handler.clone();
        let direct_open = tokio::spawn(async move {
            direct_handler
                .handle_control_frame(
                    &direct_ctx,
                    route_open_frame(2, "target", unique_project_root("route-census-direct")),
                )
                .await
                .unwrap()
        });
        let direct_bind = tokio::time::timeout(Duration::from_secs(5), target_rx.recv())
            .await
            .expect("no direct route.bind within 5s")
            .expect("target control channel closed before direct route.bind");
        handler
            .handle_control_frame(&target_ctx, route_bind_ack(direct_bind.header.corr))
            .await
            .unwrap();
        assert!(direct_open.await.unwrap().is_empty());
        let _ = direct_rx.recv().await.unwrap();

        let (reserved_ctx, mut reserved_rx) = route_ctx(ConnectionId::new(103));
        let reserved_handler = handler.clone();
        let reserved_open = tokio::spawn(async move {
            reserved_handler
                .handle_control_frame(
                    &reserved_ctx,
                    route_open_frame_with_admission_facts(
                        3,
                        "target",
                        unique_project_root("admission-facts"),
                        Some(ConsumerIdentity {
                            module_id: "fed".to_string(),
                            launch_nonce: "fed-nonce".to_string(),
                        }),
                        None,
                    ),
                )
                .await
                .unwrap()
        });
        let reserved_bind = tokio::time::timeout(Duration::from_secs(5), target_rx.recv())
            .await
            .expect("no reserved route.bind within 5s")
            .expect("target control channel closed before reserved route.bind");
        handler
            .handle_control_frame(&target_ctx, route_bind_ack(reserved_bind.header.corr))
            .await
            .unwrap();
        assert!(reserved_open.await.unwrap().is_empty());
        let _ = reserved_rx.recv().await.unwrap();

        forwarding
            .begin_module_drain("target", subc_control::RouteCloseReason::Reload)
            .unwrap();
        let (census_ctx, _census_rx) = route_ctx(ConnectionId::new(104));
        let census_body = serde_json::to_vec(&ClientControlRequest::SupervisorRoutes {
            module_id: Some("target".to_string()),
        })
        .unwrap();
        let census_frame =
            Frame::build(FrameType::Request, control_flags(), 0, 0, 4, census_body).unwrap();
        let response = handler
            .handle_control_frame(&census_ctx, census_frame)
            .await
            .unwrap()
            .pop()
            .unwrap();
        let actual: Value = serde_json::from_slice(&response.body).unwrap();
        let decoded: ClientControlResponse = serde_json::from_value(actual.clone()).unwrap();
        assert!(matches!(
            decoded,
            ClientControlResponse::SupervisorRoutes { .. }
        ));
        let routes = actual["modules"][0]["routes"].as_array().unwrap();
        assert_eq!(routes.len(), 2);
        assert!(routes.iter().all(|route| route["draining"] == true));
        // The census carries WHY: the reason the drain was begun with, in the
        // route.closing vocabulary, on every draining route this drain marked.
        assert!(
            routes.iter().all(|route| route["drain_reason"] == "reload"),
            "draining routes must name the drain's reason: {routes:?}"
        );
        assert!(routes.iter().any(|route| {
            route["consumer"] == serde_json::json!({"kind": "direct", "connection_id": 102})
        }));
        assert!(routes.iter().any(|route| {
            route["consumer"] == serde_json::json!({"kind": "reserved", "module_id": "fed"})
        }));

        let golden_path = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"))
            .join("../subc-control/tests/golden/client_control_response_supervisor_routes.json");
        if std::env::var_os("UPDATE_GOLDEN").is_some() {
            std::fs::write(
                &golden_path,
                format!("{}\n", serde_json::to_string_pretty(&actual).unwrap()),
            )
            .unwrap();
        }
        let expected: Value =
            serde_json::from_str(&std::fs::read_to_string(golden_path).unwrap()).unwrap();
        assert_eq!(actual, expected);
    }

    async fn query_live_roots(
        handler: &ControlHandler,
        module_ctx: &RouteCtx,
    ) -> ModuleControlResponseToModule {
        let body = serde_json::to_vec(&ModuleControlRequestFromModule::LiveRoots {}).unwrap();
        let frame = Frame::build(FrameType::Request, control_flags(), 0, 0, 900, body).unwrap();
        let response = handler
            .handle_control_frame(module_ctx, frame)
            .await
            .unwrap()
            .pop()
            .unwrap();
        serde_json::from_slice(&response.body).unwrap()
    }

    #[tokio::test(start_paused = true)]
    async fn supervisor_live_roots_root_known_arm_counts_bound_and_pending_from_real_handler() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let handler = ControlHandler::with_forwarding(registry, forwarding);
        let (target_ctx, mut target_rx) = route_ctx(ConnectionId::new(301));
        hello_via_sink(
            &handler,
            &target_ctx,
            &mut target_rx,
            hello_frame("target", PROTOCOL_VERSION, 1),
        )
        .await;
        let root = unique_project_root("live-roots-known");
        let path = ProjectRootId::from_path_allowing_missing(root.path())
            .unwrap()
            .as_path()
            .to_path_buf();
        let (client_ctx, mut client_rx) = route_ctx(ConnectionId::new(302));
        let open_handler = handler.clone();
        let opened = tokio::spawn(async move {
            open_handler
                .handle_control_frame(&client_ctx, route_open_frame(2, "target", root))
                .await
                .unwrap()
        });
        let bind = tokio::time::timeout(Duration::from_secs(5), target_rx.recv())
            .await
            .unwrap()
            .unwrap();
        handler
            .handle_control_frame(&target_ctx, route_bind_ack(bind.header.corr))
            .await
            .unwrap();
        assert!(opened.await.unwrap().is_empty());
        let _ = client_rx.recv().await.unwrap();

        let root = unique_project_root("live-roots-pending");
        let pending_path = ProjectRootId::from_path_allowing_missing(root.path())
            .unwrap()
            .as_path()
            .to_path_buf();
        let (client_ctx, _client_rx) = route_ctx(ConnectionId::new(303));
        let open_handler = handler.clone();
        let pending = tokio::spawn(async move {
            open_handler
                .handle_control_frame(&client_ctx, route_open_frame(3, "target", root))
                .await
                .unwrap()
        });
        let pending_bind = tokio::time::timeout(Duration::from_secs(5), target_rx.recv())
            .await
            .unwrap()
            .unwrap();
        let actual = query_live_roots(&handler, &target_ctx).await;
        let ModuleControlResponseToModule::LiveRoots {
            roots,
            unknown_root_bindings,
            total_bindings,
        } = actual
        else {
            panic!("expected live roots")
        };
        assert_eq!(total_bindings, 2, "root-known arm must count live routes");
        assert_eq!(unknown_root_bindings, 0);
        assert_eq!(
            roots.len(),
            2,
            "root-known arm must retain each canonical root"
        );
        assert_eq!(
            total_bindings,
            roots.iter().map(|r| r.bound + r.pending).sum::<u64>() + unknown_root_bindings
        );
        let counts = roots
            .iter()
            .map(|root| (root.project_root.clone(), root.bound, root.pending))
            .collect::<Vec<_>>();
        let mut expected = vec![(path, 1, 0), (pending_path, 0, 1)];
        expected.sort_by(|a, b| a.0.cmp(&b.0));
        assert_eq!(
            counts, expected,
            "roots must sort by path and count pending separately"
        );
        handler
            .handle_control_frame(&target_ctx, route_bind_ack(pending_bind.header.corr))
            .await
            .unwrap();
        assert!(pending.await.unwrap().is_empty());
    }

    #[tokio::test(start_paused = true)]
    async fn supervisor_live_roots_unknown_root_arm_is_not_no_bindings() {
        let forwarding = Arc::new(ForwardingTable::default());
        let handler =
            ControlHandler::with_forwarding(Arc::new(Registry::default()), Arc::clone(&forwarding));
        let (target_ctx, mut target_rx) = route_ctx(ConnectionId::new(311));
        hello_via_sink(
            &handler,
            &target_ctx,
            &mut target_rx,
            hello_frame("target", PROTOCOL_VERSION, 1),
        )
        .await;
        let (client_ctx, _client_rx) = route_ctx(ConnectionId::new(312));
        let pending = forwarding
            .begin_route_bind_relay_for_test(
                client_ctx.connection_id,
                client_ctx.egress.clone(),
                2,
                "target",
            )
            .unwrap();
        forwarding
            .complete_pending_relay(
                target_ctx.connection_id,
                pending.corr,
                RouteBindRelayOutcome::Accepted,
            )
            .unwrap();
        let actual = query_live_roots(&handler, &target_ctx).await;
        let ModuleControlResponseToModule::LiveRoots {
            roots,
            unknown_root_bindings,
            total_bindings,
        } = actual
        else {
            panic!("expected live roots")
        };
        assert!(roots.is_empty(), "unknown-root arm must not invent a root");
        assert_eq!(
            unknown_root_bindings, 1,
            "unknown-root arm must not read as no bindings"
        );
        assert_eq!(total_bindings, 1, "unknown-root arm has a live binding");
        assert_eq!(
            total_bindings,
            roots.iter().map(|r| r.bound + r.pending).sum::<u64>() + unknown_root_bindings
        );
    }

    /// A module reads HELLO_ACK as its first frame and exits on anything else,
    /// so the ack has to be on its outbound queue before the module is
    /// routable. The connection loop writes a handler's replies only after the
    /// handler returns; this test stops in exactly that gap, runs a real
    /// route.open from another connection, and only then writes whatever the
    /// HELLO handler returned, the way the loop would. If the ack were still a
    /// reply, the route.bind request would reach the module first.
    #[tokio::test(start_paused = true)]
    async fn hello_ack_reaches_the_module_before_a_route_bind_raced_into_the_reply_gap() {
        let forwarding = Arc::new(ForwardingTable::default());
        let handler =
            ControlHandler::with_forwarding(Arc::new(Registry::default()), Arc::clone(&forwarding));
        let (module_ctx, mut module_rx) = route_ctx(ConnectionId::new(341));
        let replies = handler
            .handle_control_frame(&module_ctx, hello_frame("raced", PROTOCOL_VERSION, 7))
            .await
            .unwrap();
        let queued_by_hello = module_rx.len();

        let (client_ctx, mut client_rx) = route_ctx(ConnectionId::new(342));
        let open_handler = handler.clone();
        let open = tokio::spawn(async move {
            open_handler
                .handle_control_frame(
                    &client_ctx,
                    route_open_frame(2, "raced", unique_project_root("hello-ack-race")),
                )
                .await
                .unwrap()
        });
        // Let the route.open run until its route.bind is on the module's queue.
        let mut spins = 0;
        while module_rx.len() == queued_by_hello {
            spins += 1;
            assert!(spins < 10_000, "route.open never queued a route.bind");
            tokio::task::yield_now().await;
        }

        // Now the connection loop's half: write the HELLO handler's replies.
        for reply in replies {
            module_ctx.egress.send(reply).await.unwrap();
        }

        let first = module_rx.recv().await.unwrap().frame;
        assert_eq!(
            first.header.ty,
            FrameType::HelloAck,
            "the first frame a registering module reads must be its HELLO_ACK"
        );
        assert_eq!(first.header.corr, 7);
        let second = module_rx.recv().await.unwrap().frame;
        assert_eq!(second.header.ty, FrameType::Request);
        assert!(
            matches!(
                serde_json::from_slice::<ModuleControlRequest>(&second.body).unwrap(),
                ModuleControlRequest::RouteBind { .. }
            ),
            "the route.bind follows the ack"
        );
        assert!(module_rx.try_recv().is_err(), "nothing else was queued");

        handler
            .handle_control_frame(&module_ctx, route_bind_ack(second.header.corr))
            .await
            .unwrap();
        assert!(open.await.unwrap().is_empty());
        let _ = client_rx.recv().await.unwrap();
    }

    #[tokio::test(start_paused = true)]
    async fn supervisor_live_roots_cross_module_scope_uses_requesting_connection() {
        let handler = ControlHandler::with_forwarding(
            Arc::new(Registry::default()),
            Arc::new(ForwardingTable::default()),
        );
        let (first_ctx, mut first_rx) = route_ctx(ConnectionId::new(315));
        let (second_ctx, mut second_rx) = route_ctx(ConnectionId::new(316));
        hello_via_sink(
            &handler,
            &first_ctx,
            &mut first_rx,
            hello_frame("first", PROTOCOL_VERSION, 1),
        )
        .await;
        hello_via_sink(
            &handler,
            &second_ctx,
            &mut second_rx,
            hello_frame("second", PROTOCOL_VERSION, 2),
        )
        .await;
        let root = unique_project_root("second-only");
        let (client_ctx, _client_rx) = route_ctx(ConnectionId::new(317));
        let cloned = handler.clone();
        let open = tokio::spawn(async move {
            cloned
                .handle_control_frame(&client_ctx, route_open_frame(3, "second", root))
                .await
                .unwrap()
        });
        let bind = tokio::time::timeout(Duration::from_secs(5), second_rx.recv())
            .await
            .unwrap()
            .unwrap();
        let first = query_live_roots(&handler, &first_ctx).await;
        let second = query_live_roots(&handler, &second_ctx).await;
        assert!(
            matches!(
                first,
                ModuleControlResponseToModule::LiveRoots {
                    total_bindings: 0,
                    ..
                }
            ),
            "cross-module scope must not expose another module's roots"
        );
        assert!(
            matches!(
                second,
                ModuleControlResponseToModule::LiveRoots {
                    total_bindings: 1,
                    ..
                }
            ),
            "second module must see its pending route"
        );
        handler
            .handle_control_frame(&second_ctx, route_bind_ack(bind.header.corr))
            .await
            .unwrap();
        assert!(open.await.unwrap().is_empty());
    }

    #[tokio::test(start_paused = true)]
    async fn supervisor_live_roots_no_bindings_arm_is_empty() {
        let handler = ControlHandler::with_forwarding(
            Arc::new(Registry::default()),
            Arc::new(ForwardingTable::default()),
        );
        let (target_ctx, mut target_rx) = route_ctx(ConnectionId::new(321));
        hello_via_sink(
            &handler,
            &target_ctx,
            &mut target_rx,
            hello_frame("target", PROTOCOL_VERSION, 1),
        )
        .await;
        let actual = query_live_roots(&handler, &target_ctx).await;
        let ModuleControlResponseToModule::LiveRoots {
            roots,
            unknown_root_bindings,
            total_bindings,
        } = actual
        else {
            panic!("expected live roots")
        };
        assert!(roots.is_empty());
        assert_eq!(unknown_root_bindings, 0);
        assert_eq!(total_bindings, 0);
        assert_eq!(
            total_bindings,
            roots.iter().map(|r| r.bound + r.pending).sum::<u64>() + unknown_root_bindings
        );
    }

    /// Read the vendored fed corpus rather than hand-building a package.
    ///
    /// A hand-built object encodes what the test author believed the carrier
    /// emits. These vectors are what it actually emits, and one of them exists
    /// specifically to pin OUR side of the seam: its note reads "SUBC relay
    /// ignores additive unknown fields at the traversal emit terminus."
    fn fed_admission_facts_vectors() -> Vec<(String, Value)> {
        let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
            .join("tests/fixtures/fed/admission-facts-emit.jsonl");
        let text = std::fs::read_to_string(&path)
            .unwrap_or_else(|err| panic!("vendored fed corpus unreadable at {path:?}: {err}"));
        let vectors: Vec<(String, Value)> = text
            .lines()
            .filter(|line| !line.trim().is_empty())
            .map(|line| {
                let entry: Value = serde_json::from_str(line).expect("corpus line must be JSON");
                let id = entry["corpus_id"]
                    .as_str()
                    .expect("every vector carries a corpus_id")
                    .to_string();
                (id, entry["package"].clone())
            })
            .collect();
        // Pin the count: a corpus that silently shrinks would take its coverage
        // with it, and a suite reading N-1 vectors reports the same clean pass
        // as one reading N.
        assert_eq!(
            vectors.len(),
            3,
            "vendored fed corpus changed size; re-sync from subc-federation"
        );

        // Pin what makes the corpus DISCRIMINATING, not just present.
        //
        // The relay test below takes its expected value from the corpus, so the
        // corpus supplies the test's power to detect a lossy relay rather than
        // its correctness. A relay that dropped unrecognised fields would still
        // be caught -- but only by a package carrying fields it does not know.
        // Shrink every package to the handful of keys any implementation would
        // recognise and the test keeps passing over an input that can no longer
        // fail, which is the same clean green as a corpus that shrank away.
        //
        // So assert the precondition rather than duplicating the packages here:
        // at least one vector must carry a field beyond the small common set.
        // That is one claim to maintain instead of nine, and it fails loudly if
        // a re-sync ever flattens the corpus.
        const COMMONLY_MODELLED: [&str; 3] = ["schema", "verified_class", "org"];
        let richest = vectors
            .iter()
            .filter_map(|(_, package)| package.as_object())
            .map(|object| {
                object
                    .keys()
                    .filter(|key| !COMMONLY_MODELLED.contains(&key.as_str()))
                    .count()
            })
            .max()
            .unwrap_or(0);
        assert!(
            richest >= 2,
            "vendored corpus no longer carries a package with unmodelled fields, \
             so the relay test can no longer distinguish a verbatim relay from a lossy one"
        );

        vectors
    }

    /// The relay must carry the carrier's package through BYTE-FOR-BYTE.
    ///
    /// The gate test below proves the ACCESS RULE (who may send facts, to whom).
    /// This proves the PAYLOAD RULE, which the gate cannot: it hand-builds a
    /// three-key object, so a relay that quietly dropped fields it did not
    /// recognise would satisfy it. These vectors carry nine keys including ones
    /// this crate has no type for, so a typed relay fails here and only here.
    #[tokio::test]
    async fn admission_facts_relay_carries_vendored_packages_verbatim() {
        for (corpus_id, package) in fed_admission_facts_vectors() {
            let registry = Arc::new(Registry::default());
            let forwarding = Arc::new(ForwardingTable::default());
            let supervisor = SupervisorHandle::new();
            supervisor.set_spawn_nonce("fed", "fed-nonce".to_string());
            let handler =
                ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding))
                    .with_supervisor(supervisor)
                    .with_admission_facts_config(
                        Some("fed".to_string()),
                        Some(vec!["target".to_string()]),
                    );

            let (target_ctx, mut target_rx) = route_ctx(ConnectionId::new(90));
            hello_via_sink(
                &handler,
                &target_ctx,
                &mut target_rx,
                hello_frame("target", PROTOCOL_VERSION, 1),
            )
            .await;

            let (client_ctx, _client_rx) = route_ctx(ConnectionId::new(91));
            let route_handler = handler.clone();
            let expected = package.clone();
            let route_task = tokio::spawn(async move {
                route_handler
                    .handle_control_frame(
                        &client_ctx,
                        route_open_frame_with_admission_facts(
                            20,
                            "target",
                            unique_project_root("admission-facts"),
                            Some(subc_control::ConsumerIdentity {
                                module_id: "fed".to_string(),
                                launch_nonce: "fed-nonce".to_string(),
                            }),
                            Some(package),
                        ),
                    )
                    .await
                    .unwrap()
            });

            let bind_frame = target_rx.recv().await.unwrap();
            let bind: ModuleControlRequest = serde_json::from_slice(&bind_frame.body).unwrap();
            let ModuleControlRequest::RouteBind {
                admission_facts, ..
            } = bind
            else {
                panic!("{corpus_id}: expected route.bind")
            };
            assert_eq!(
                admission_facts,
                Some(expected),
                "{corpus_id}: relay must not add, drop or reshape any field"
            );

            handler
                .handle_control_frame(&target_ctx, route_bind_ack(bind_frame.header.corr))
                .await
                .unwrap();
            route_task.await.unwrap();
        }
    }

    #[tokio::test]
    async fn admission_facts_gate_checks_carrier_target_and_precedence() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let supervisor = SupervisorHandle::new();
        supervisor.set_spawn_nonce("fed", "fed-nonce".to_string());
        supervisor.set_spawn_nonce("other", "other-nonce".to_string());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding))
                .with_supervisor(supervisor)
                .with_admission_facts_config(
                    Some("fed".to_string()),
                    Some(vec!["target".to_string()]),
                );

        let (target_ctx, mut target_rx) = route_ctx(ConnectionId::new(70));
        hello_via_sink(
            &handler,
            &target_ctx,
            &mut target_rx,
            hello_frame("target", PROTOCOL_VERSION, 1),
        )
        .await;
        let (other_ctx, mut other_rx) = route_ctx(ConnectionId::new(71));
        hello_via_sink(
            &handler,
            &other_ctx,
            &mut other_rx,
            hello_frame("other", PROTOCOL_VERSION, 2),
        )
        .await;

        let facts = json!({"schema": 1, "verified_class": "member", "org": "01H"});
        let expected_facts = facts.clone();
        let (client_ctx, mut client_rx) = route_ctx(ConnectionId::new(72));
        let route_handler = handler.clone();
        let route_task = tokio::spawn(async move {
            route_handler
                .handle_control_frame(
                    &client_ctx,
                    route_open_frame_with_admission_facts(
                        10,
                        "target",
                        unique_project_root("admission-facts"),
                        Some(subc_control::ConsumerIdentity {
                            module_id: "fed".to_string(),
                            launch_nonce: "fed-nonce".to_string(),
                        }),
                        Some(facts.clone()),
                    ),
                )
                .await
                .unwrap()
        });
        let bind_frame = target_rx.recv().await.unwrap();
        let bind: ModuleControlRequest = serde_json::from_slice(&bind_frame.body).unwrap();
        let ModuleControlRequest::RouteBind {
            admission_facts, ..
        } = bind
        else {
            panic!("expected route.bind")
        };
        assert_eq!(admission_facts, Some(expected_facts));
        handler
            .handle_control_frame(&target_ctx, route_bind_ack(bind_frame.header.corr))
            .await
            .unwrap();
        assert!(route_task.await.unwrap().is_empty());
        assert!(matches!(
            serde_json::from_slice::<ClientControlResponse>(&client_rx.recv().await.unwrap().body)
                .unwrap(),
            ClientControlResponse::RouteOpen { .. }
        ));

        let direct = handler
            .handle_control_frame(
                &route_ctx(ConnectionId::new(73)).0,
                route_open_frame_with_admission_facts(
                    11,
                    "target",
                    unique_project_root("admission-facts"),
                    None,
                    Some(json!({"x": 1})),
                ),
            )
            .await
            .unwrap();
        assert_eq!(
            parse_error(&direct[0])["code"],
            "admission_facts_not_permitted"
        );

        let different_reserved = handler
            .handle_control_frame(
                &route_ctx(ConnectionId::new(77)).0,
                route_open_frame_with_admission_facts(
                    15,
                    "target",
                    unique_project_root("admission-facts"),
                    Some(subc_control::ConsumerIdentity {
                        module_id: "other".to_string(),
                        launch_nonce: "other-nonce".to_string(),
                    }),
                    Some(json!({"x": 1})),
                ),
            )
            .await
            .unwrap();
        assert_eq!(
            parse_error(&different_reserved[0])["code"],
            "admission_facts_not_permitted"
        );

        let other_target = handler
            .handle_control_frame(
                &route_ctx(ConnectionId::new(74)).0,
                route_open_frame_with_admission_facts(
                    12,
                    "other",
                    unique_project_root("admission-facts"),
                    Some(subc_control::ConsumerIdentity {
                        module_id: "fed".to_string(),
                        launch_nonce: "fed-nonce".to_string(),
                    }),
                    Some(json!({"x": 1})),
                ),
            )
            .await
            .unwrap();
        assert_eq!(
            parse_error(&other_target[0])["code"],
            "admission_facts_target_not_allowed"
        );

        let nonexistent = handler
            .handle_control_frame(
                &route_ctx(ConnectionId::new(75)).0,
                route_open_frame_with_admission_facts(
                    13,
                    "missing",
                    unique_project_root("admission-facts"),
                    None,
                    Some(json!({"x": 1})),
                ),
            )
            .await
            .unwrap();
        assert_eq!(parse_error(&nonexistent[0])["code"], "unknown_module");

        let described = handler
            .handle_control_frame(
                &route_ctx(ConnectionId::new(76)).0,
                Frame::build(
                    FrameType::Request,
                    control_flags(),
                    0,
                    0,
                    14,
                    serde_json::to_vec(&ClientControlRequest::ServerDescribe {}).unwrap(),
                )
                .unwrap(),
            )
            .await
            .unwrap();
        let ClientControlResponse::ServerDescribe { capabilities, .. } =
            serde_json::from_slice(&described[0].body).unwrap()
        else {
            panic!("expected server.describe response")
        };
        assert!(capabilities
            .iter()
            .any(|cap| cap == "admission_facts_relay_v1"));
    }

    #[tokio::test]
    async fn admission_facts_without_configured_carrier_are_rejected() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let handler = ControlHandler::with_forwarding(registry, forwarding);
        let (target_ctx, mut target_rx) = route_ctx(ConnectionId::new(78));
        hello_via_sink(
            &handler,
            &target_ctx,
            &mut target_rx,
            hello_frame("target", PROTOCOL_VERSION, 1),
        )
        .await;

        let responses = handler
            .handle_control_frame(
                &route_ctx(ConnectionId::new(79)).0,
                route_open_frame_with_admission_facts(
                    16,
                    "target",
                    unique_project_root("admission-facts"),
                    None,
                    Some(json!({"x": 1})),
                ),
            )
            .await
            .unwrap();
        assert_eq!(
            parse_error(&responses[0])["code"],
            "admission_facts_not_permitted"
        );
    }

    #[tokio::test]
    async fn route_open_relays_consumer_capabilities_verbatim() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding));
        let (module_ctx, mut module_rx) = route_ctx(ConnectionId::new(37));
        hello_via_sink(
            &handler,
            &module_ctx,
            &mut module_rx,
            hello_frame("aft", PROTOCOL_VERSION, 7),
        )
        .await;

        let expected = vec!["elicitation".to_string(), "roots".to_string()];
        let expected_for_request = expected.clone();
        let project_root = unique_project_root("consumer-capabilities-present");
        let (client_ctx, mut client_rx) = route_ctx(ConnectionId::new(38));
        let route_handler = handler.clone();
        let route_task = tokio::spawn(async move {
            route_handler
                .handle_control_frame(
                    &client_ctx,
                    route_open_frame_with_consumer_capabilities(
                        401,
                        "aft",
                        project_root,
                        Some(expected_for_request),
                    ),
                )
                .await
                .unwrap()
        });
        let bind_frame = tokio::time::timeout(Duration::from_secs(1), module_rx.recv())
            .await
            .unwrap()
            .unwrap();
        let bind: ModuleControlRequest = serde_json::from_slice(&bind_frame.body).unwrap();
        let ModuleControlRequest::RouteBind {
            consumer_capabilities,
            ..
        } = bind
        else {
            panic!("expected route.bind request, got {bind:?}");
        };
        assert_eq!(consumer_capabilities, Some(expected.clone()));

        handler
            .handle_control_frame(&module_ctx, route_bind_ack(bind_frame.header.corr))
            .await
            .unwrap();
        let route_response = route_task.await.unwrap();
        assert!(route_response.is_empty());
        let published = client_rx.recv().await.unwrap();
        assert!(matches!(
            serde_json::from_slice::<ClientControlResponse>(&published.body).unwrap(),
            ClientControlResponse::RouteOpen { .. }
        ));
    }

    #[tokio::test]
    async fn route_open_without_consumer_capabilities_relays_none() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding));
        let (module_ctx, mut module_rx) = route_ctx(ConnectionId::new(39));
        hello_via_sink(
            &handler,
            &module_ctx,
            &mut module_rx,
            hello_frame("aft", PROTOCOL_VERSION, 7),
        )
        .await;

        let project_root = unique_project_root("consumer-capabilities-absent");
        let (client_ctx, mut client_rx) = route_ctx(ConnectionId::new(40));
        let route_handler = handler.clone();
        let route_task = tokio::spawn(async move {
            route_handler
                .handle_control_frame(&client_ctx, route_open_frame(402, "aft", project_root))
                .await
                .unwrap()
        });
        let bind_frame = tokio::time::timeout(Duration::from_secs(1), module_rx.recv())
            .await
            .unwrap()
            .unwrap();
        let bind: ModuleControlRequest = serde_json::from_slice(&bind_frame.body).unwrap();
        let ModuleControlRequest::RouteBind {
            consumer_capabilities,
            ..
        } = bind
        else {
            panic!("expected route.bind request, got {bind:?}");
        };
        assert_eq!(consumer_capabilities, None);

        handler
            .handle_control_frame(&module_ctx, route_bind_ack(bind_frame.header.corr))
            .await
            .unwrap();
        let route_response = route_task.await.unwrap();
        assert!(route_response.is_empty());
        let published = client_rx.recv().await.unwrap();
        assert!(matches!(
            serde_json::from_slice::<ClientControlResponse>(&published.body).unwrap(),
            ClientControlResponse::RouteOpen { .. }
        ));
    }

    /// Opens a route to a freshly registered `aft` with `sent` as the
    /// route.open's role_versions, acks the bind, and returns the role_versions
    /// the module's bind carried.
    async fn bind_role_versions_for(
        sent: Option<BTreeMap<String, String>>,
        connection: u64,
    ) -> Option<BTreeMap<String, String>> {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding));
        let (module_ctx, mut module_rx) = route_ctx(ConnectionId::new(connection));
        hello_via_sink(
            &handler,
            &module_ctx,
            &mut module_rx,
            hello_frame("aft", PROTOCOL_VERSION, 7),
        )
        .await;
        let project_root = unique_project_root("role-versions");
        let (client_ctx, mut client_rx) = route_ctx(ConnectionId::new(connection + 1));
        let route_handler = handler.clone();
        let route_task = tokio::spawn(async move {
            route_handler
                .handle_control_frame(
                    &client_ctx,
                    route_open_frame_with_role_versions(403, "aft", project_root, sent),
                )
                .await
                .unwrap()
        });
        let bind_frame = tokio::time::timeout(Duration::from_secs(1), module_rx.recv())
            .await
            .expect("a well-formed route.open reaches the module as a bind")
            .unwrap();
        let bind: ModuleControlRequest = serde_json::from_slice(&bind_frame.body).unwrap();
        let ModuleControlRequest::RouteBind { role_versions, .. } = bind else {
            panic!("expected route.bind request, got {bind:?}");
        };
        handler
            .handle_control_frame(&module_ctx, route_bind_ack(bind_frame.header.corr))
            .await
            .unwrap();
        assert!(route_task.await.unwrap().is_empty());
        let published = client_rx.recv().await.unwrap();
        assert!(matches!(
            serde_json::from_slice::<ClientControlResponse>(&published.body).unwrap(),
            ClientControlResponse::RouteOpen { .. }
        ));
        role_versions
    }

    #[tokio::test]
    async fn route_open_relays_role_versions_verbatim() {
        let sent = role_versions(&[("tool-provider", "v1"), ("management-surface", "v12")]);
        assert_eq!(
            bind_role_versions_for(Some(sent.clone()), 141).await,
            Some(sent)
        );
    }

    /// An empty map declares nothing, so the provider sees no field rather
    /// than an empty object it would have to treat as a second "none".
    #[tokio::test]
    async fn route_open_with_empty_or_absent_role_versions_relays_none() {
        assert_eq!(bind_role_versions_for(None, 143).await, None);
        assert_eq!(
            bind_role_versions_for(Some(BTreeMap::new()), 145).await,
            None
        );
    }

    #[tokio::test]
    async fn route_open_refuses_malformed_role_versions_before_any_bind() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding));
        let (module_ctx, mut module_rx) = route_ctx(ConnectionId::new(147));
        hello_via_sink(
            &handler,
            &module_ctx,
            &mut module_rx,
            hello_frame("aft", PROTOCOL_VERSION, 7),
        )
        .await;

        let nine: BTreeMap<String, String> = (0..9)
            .map(|index| (format!("role-{index}"), "v1".to_string()))
            .collect();
        for (label, malformed) in [
            (
                "invalid role name",
                role_versions(&[("Tool_Provider", "v1")]),
            ),
            ("invalid version", role_versions(&[("tool-provider", "v0")])),
            ("nine entries", nine),
        ] {
            // A refused open answers at once; one that reached the module
            // would wait for its bind ack and trip this timeout.
            let responses = tokio::time::timeout(
                Duration::from_secs(1),
                handler.handle_control_frame(
                    &route_ctx(ConnectionId::new(148)).0,
                    route_open_frame_with_role_versions(
                        404,
                        "aft",
                        unique_project_root("role-versions-malformed"),
                        Some(malformed),
                    ),
                ),
            )
            .await
            .unwrap_or_else(|_| panic!("{label}: the open was relayed instead of refused"))
            .unwrap();
            assert_eq!(responses.len(), 1, "{label}");
            assert_eq!(responses[0].header.ty, FrameType::Error, "{label}");
            let error = parse_error(&responses[0]);
            assert_eq!(error["code"], "invalid_request", "{label}: {error}");
            assert_eq!(
                error["detail"]["field"], "role_versions",
                "{label}: {error}"
            );
            assert!(
                !error_codes::is_retryable_route_open(error["code"].as_str().unwrap()),
                "{label}: a malformed declaration is terminal"
            );
            assert!(
                module_rx.try_recv().is_err(),
                "{label}: the module must never see a bind"
            );
        }
    }

    /// `route-role-versions/v1` is in HELLO_ACK and `server.describe`, so a
    /// consumer can tell this daemon forwards the field from one that would
    /// drop it.
    #[tokio::test]
    async fn route_role_versions_capability_is_advertised() {
        let handler = ControlHandler::new(Arc::new(Registry::default()));
        let (ctx, mut rx) = route_ctx(ConnectionId::new(149));
        let ack = hello_via_sink(
            &handler,
            &ctx,
            &mut rx,
            hello_frame("m", PROTOCOL_VERSION, 1),
        )
        .await;
        let ack = parse_ack(&ack);
        assert!(
            ack.subc_capabilities
                .iter()
                .any(|c| c == "route-role-versions/v1"),
            "{:?}",
            ack.subc_capabilities
        );

        let body = serde_json::to_vec(&ClientControlRequest::ServerDescribe {}).unwrap();
        let frame = Frame::build(FrameType::Request, control_flags(), 0, 0, 5, body).unwrap();
        let reply = handler
            .handle_control_frame(&route_ctx(ConnectionId::new(150)).0, frame)
            .await
            .unwrap()
            .pop()
            .unwrap();
        let ClientControlResponse::ServerDescribe { capabilities, .. } =
            serde_json::from_slice(&reply.body).unwrap()
        else {
            panic!("not a server.describe reply");
        };
        assert!(
            capabilities.iter().any(|c| c == CAP_ROUTE_ROLE_VERSIONS_V1),
            "{capabilities:?}"
        );
    }

    #[tokio::test]
    async fn supervision_only_module_health_probe_does_not_enable_route_open_and_cleans_up() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding))
                .with_health_probe_timeout(Duration::from_secs(5));
        let (module_ctx, mut module_rx) = route_ctx(ConnectionId::new(35));
        hello_via_sink(
            &handler,
            &module_ctx,
            &mut module_rx,
            non_routable_hello_frame_with_control_ops(
                "mcp",
                300,
                Some(vec![MODULE_CONTROL_OP_HEALTH_CHECK.to_string()]),
            ),
        )
        .await;
        assert!(registry
            .get_module("mcp")
            .unwrap()
            .unwrap()
            .manifest
            .provides
            .is_empty());

        let (route_client_ctx, _route_client_rx) = route_ctx(ConnectionId::new(36));
        let route_response = handler
            .handle_control_frame(
                &route_client_ctx,
                route_open_frame(301, "mcp", unique_project_root("non-routable-mcp")),
            )
            .await
            .unwrap();
        assert_eq!(route_response[0].header.ty, FrameType::Error);
        assert_eq!(
            parse_error(&route_response[0])["code"],
            "target_unavailable"
        );
        assert!(parse_error(&route_response[0])["message"]
            .as_str()
            .unwrap()
            .contains("does not provide the requested target"));
        assert!(module_rx.try_recv().is_err());

        let (health_client_ctx, _health_client_rx) = route_ctx(ConnectionId::new(37));
        let health_handler = handler.clone();
        let health_task = tokio::spawn(async move {
            health_handler
                .handle_control_frame(
                    &health_client_ctx,
                    supervisor_health_probe_frame(302, "mcp"),
                )
                .await
                .unwrap()
        });
        let health_frame = tokio::time::timeout(Duration::from_secs(1), module_rx.recv())
            .await
            .unwrap()
            .unwrap();
        assert_eq!(
            serde_json::from_slice::<ModuleControlRequest>(&health_frame.body).unwrap(),
            ModuleControlRequest::HealthCheck {}
        );
        handler
            .handle_control_frame(
                &module_ctx,
                health_response(health_frame.header.corr, HealthStatus::Ok),
            )
            .await
            .unwrap();
        let health_response = health_task.await.unwrap();
        assert_eq!(health_response[0].header.ty, FrameType::Response);
        match serde_json::from_slice::<ClientControlResponse>(&health_response[0].body).unwrap() {
            ClientControlResponse::SupervisorHealthProbe {
                module_id, status, ..
            } => {
                assert_eq!(module_id, "mcp");
                assert_eq!(status, HealthStatus::Ok);
            }
            other => panic!("unexpected health response: {other:?}"),
        }

        // Exercise the forwarding cleanup path directly while leaving the registry
        // advertisement in place. If cleanup leaves a stale control sink behind,
        // the next probe will enqueue onto it and wait for the long probe timeout
        // instead of returning an immediate no-connection error.
        forwarding
            .cleanup_connection(module_ctx.connection_id)
            .unwrap();
        let (cleanup_probe_ctx, _cleanup_probe_rx) = route_ctx(ConnectionId::new(38));
        let cleanup_response = tokio::time::timeout(
            Duration::from_millis(200),
            handler.handle_control_frame(
                &cleanup_probe_ctx,
                supervisor_health_probe_frame(303, "mcp"),
            ),
        )
        .await
        .expect("probe should fail immediately when the control lane is gone")
        .unwrap();
        assert_eq!(cleanup_response[0].header.ty, FrameType::Error);
        assert_eq!(
            parse_error(&cleanup_response[0])["code"],
            "target_unavailable"
        );
        assert!(parse_error(&cleanup_response[0])["message"]
            .as_str()
            .unwrap()
            .contains("no module connection"));

        handler
            .cleanup_connection(module_ctx.connection_id)
            .unwrap();
    }

    #[tokio::test]
    async fn route_open_classifies_unregistered_running_supervised_module_as_warming() {
        let registry = Arc::new(Registry::default());
        let supervisor_handle = SupervisorHandle::new();
        let supervisor =
            Supervisor::new(Arc::clone(&registry), RestartPolicy::new(0, Duration::ZERO))
                .with_handle(supervisor_handle.clone())
                .with_connection_file_path(
                    std::env::temp_dir()
                        .join(format!("subc-route-open-warming-{}", std::process::id())),
                );
        let module = supervisor
            .supervise_configured(
                ModuleSpec {
                    module_id: "warming".to_string(),
                    program: fake_aft_stub_path(),
                    args: Vec::new(),
                    env: Vec::new(),
                    reserved: false,
                    reserved_prefixes: Vec::new(),
                    protocol: ModuleProtocol::Subc,
                    overlap: Default::default(),
                },
                true,
            )
            .unwrap();
        assert_eq!(module.state().unwrap(), ModuleState::Running);

        let handler = ControlHandler::new(Arc::clone(&registry)).with_supervisor(supervisor_handle);
        let (ctx, _rx) = route_ctx(ConnectionId::new(39));
        let response = handler
            .handle_control_frame(
                &ctx,
                route_open_frame(304, "warming", unique_project_root("warming")),
            )
            .await
            .unwrap();
        module.stop().await.unwrap();

        assert_eq!(response[0].header.ty, FrameType::Error);
        let error = parse_error(&response[0]);
        assert_eq!(error["code"], "module_warming");
        assert!(error["message"]
            .as_str()
            .unwrap()
            .contains("state=running, enabled=true, live=false"));
    }

    #[test]
    fn route_open_connection_cap_logs_admission_reason_and_capacity() {
        let handler = ControlHandler::new(Arc::new(Registry::default()));
        let capture = EventCapture::default();
        let _subscriber =
            tracing::subscriber::set_default(tracing_subscriber::registry().with(capture.clone()));
        let (ctx, _rx) = route_ctx(ConnectionId::new(96));
        let limit = crate::server::MAX_PENDING_ROUTE_OPENS_PER_CONNECTION;
        let pending = (0..limit).collect::<Vec<_>>();
        let response = handler
            .route_open_capacity_refusal(
                &ctx,
                &route_open_frame(396, "busy", unique_project_root("connection-cap")),
                "busy",
                pending.len(),
                limit,
            )
            .unwrap();
        assert_eq!(parse_error(&response)["code"], "target_unavailable");
        let event = capture
            .events()
            .into_iter()
            .find(|event| {
                event.target == "control"
                    && event.fields.get("reason") == Some(&"\"open_admission_full\"".to_string())
            })
            .expect("connection admission refusal event");
        assert_eq!(event.fields.get("in_flight"), Some(&limit.to_string()));
        assert_eq!(event.fields.get("limit"), Some(&limit.to_string()));
    }

    #[test]
    fn route_open_target_cap_logs_admission_reason_and_capacity() {
        let handler = ControlHandler::new(Arc::new(Registry::default()));
        let capture = EventCapture::default();
        let _subscriber =
            tracing::subscriber::set_default(tracing_subscriber::registry().with(capture.clone()));
        let (ctx, _rx) = route_ctx(ConnectionId::new(97));
        let limit = MAX_PENDING_ROUTE_BINDS_PER_TARGET;
        let guards = (0..limit)
            .map(|_| {
                handler
                    .route_bind_concurrency
                    .try_admit("busy", limit)
                    .unwrap()
            })
            .collect::<Vec<_>>();
        let in_flight = match handler.route_bind_concurrency.try_admit("busy", limit) {
            Err(in_flight) => in_flight,
            Ok(_) => panic!("target cap must refuse after {limit} admissions"),
        };
        let response = handler
            .route_open_target_capacity_refusal(
                &ctx,
                &route_open_frame(397, "busy", unique_project_root("target-cap")),
                "busy",
                in_flight,
            )
            .unwrap();
        assert_eq!(parse_error(&response)["code"], "target_unavailable");
        let event = capture
            .events()
            .into_iter()
            .find(|event| {
                event.target == "control"
                    && event.fields.get("reason") == Some(&"\"target_binds_full\"".to_string())
            })
            .expect("target admission refusal event");
        assert_eq!(event.fields.get("in_flight"), Some(&limit.to_string()));
        assert_eq!(event.fields.get("limit"), Some(&limit.to_string()));
        drop(guards);
    }

    /// One wire code has several senders, so the refusal line names the check
    /// that refused. This drives the shared refusal path for ordinary refusals
    /// with an unregistered
    /// target and requires the branch label on the event.
    #[tokio::test]
    async fn route_open_refusal_names_the_check_that_refused() {
        let handler = ControlHandler::new(Arc::new(Registry::default()));
        let capture = EventCapture::default();
        let _subscriber =
            tracing::subscriber::set_default(tracing_subscriber::registry().with(capture.clone()));
        let (ctx, _rx) = route_ctx(ConnectionId::new(95));
        let response = handler
            .handle_control_frame(
                &ctx,
                route_open_frame(395, "nobody", unique_project_root("refusal-reason")),
            )
            .await
            .unwrap();

        assert_eq!(parse_error(&response[0])["code"], "unknown_module");
        let event = capture
            .events()
            .into_iter()
            .find(|event| {
                event.target == "control"
                    && event.fields.get("code") == Some(&"\"unknown_module\"".to_string())
            })
            .expect("route.open refusal event");
        assert_eq!(
            event.fields.get("reason"),
            Some(&"\"not_registered\"".to_string())
        );
    }

    #[tokio::test]
    async fn route_open_supervised_absence_emits_refusal_fields_and_counts_code() {
        let registry = Arc::new(Registry::default());
        let supervisor_handle = SupervisorHandle::new();
        let supervisor =
            Supervisor::new(Arc::clone(&registry), RestartPolicy::new(0, Duration::ZERO))
                .with_handle(supervisor_handle.clone())
                .with_connection_file_path(std::env::temp_dir().join(format!(
                    "subc-route-open-refusal-info-{}",
                    std::process::id()
                )));
        let module = supervisor
            .supervise_configured(
                ModuleSpec {
                    module_id: "warming".to_string(),
                    program: fake_aft_stub_path(),
                    args: Vec::new(),
                    env: Vec::new(),
                    reserved: false,
                    reserved_prefixes: Vec::new(),
                    protocol: ModuleProtocol::Subc,
                    overlap: Default::default(),
                },
                true,
            )
            .unwrap();
        assert_eq!(module.state().unwrap(), ModuleState::Running);

        let handler = ControlHandler::new(Arc::clone(&registry)).with_supervisor(supervisor_handle);
        assert!(handler
            .counters()
            .snapshot()
            .get("route_open_refused_by_code")
            .is_none());
        let capture = EventCapture::default();
        let _subscriber =
            tracing::subscriber::set_default(tracing_subscriber::registry().with(capture.clone()));
        let (ctx, _rx) = route_ctx(ConnectionId::new(94));
        let response = handler
            .handle_control_frame(
                &ctx,
                route_open_frame(394, "warming", unique_project_root("refusal-info")),
            )
            .await
            .unwrap();
        module.stop().await.unwrap();

        assert_eq!(parse_error(&response[0])["code"], "module_warming");
        let event = capture
            .events()
            .into_iter()
            .find(|event| {
                event.target == "control"
                    && event.fields.get("code") == Some(&"\"module_warming\"".to_string())
            })
            .expect("route.open refusal event");
        assert_eq!(
            event.fields.get("module_id"),
            Some(&"\"warming\"".to_string())
        );
        assert_eq!(event.fields.get("connection_id"), Some(&"94".to_string()));
        assert_eq!(
            event.fields.get("reason"),
            Some(&"\"supervised_not_registered\"".to_string())
        );
        assert_eq!(event.fields.get("state"), Some(&"running".to_string()));
        assert_eq!(event.fields.get("enabled"), Some(&"true".to_string()));
        assert_eq!(event.fields.get("live"), Some(&"false".to_string()));
        assert_eq!(
            handler.counters().snapshot()["route_open_refused_by_code"],
            json!({ "module_warming": 1 })
        );
    }

    const OUTAGE_START: &str = "route.open refusing module: not serving";
    const OUTAGE_RECOVERED: &str = "route.open accepted again after module outage";

    fn outage_lines(capture: &EventCapture, message: &str) -> Vec<CapturedEvent> {
        capture
            .events()
            .into_iter()
            .filter(|event| event.fields.get("message").map(String::as_str) == Some(message))
            .collect()
    }

    fn supervise_stub(
        registry: &Arc<Registry>,
        module_id: &str,
        enabled: bool,
    ) -> (SupervisorHandle, crate::supervise::SupervisedModule) {
        let supervisor_handle = SupervisorHandle::new();
        let supervisor =
            Supervisor::new(Arc::clone(registry), RestartPolicy::new(0, Duration::ZERO))
                .with_handle(supervisor_handle.clone())
                .with_connection_file_path(std::env::temp_dir().join(format!(
                    "subc-route-outage-{module_id}-{}",
                    std::process::id()
                )));
        let module = supervisor
            .supervise_configured(
                ModuleSpec {
                    module_id: module_id.to_string(),
                    program: fake_aft_stub_path(),
                    args: Vec::new(),
                    env: Vec::new(),
                    reserved: false,
                    reserved_prefixes: Vec::new(),
                    protocol: ModuleProtocol::Subc,
                    overlap: Default::default(),
                },
                enabled,
            )
            .unwrap();
        (supervisor_handle, module)
    }

    fn supervisor_restart_frame(corr: u64, module_id: &str) -> Frame {
        let body = serde_json::to_vec(&ClientControlRequest::SupervisorRestart {
            module_id: module_id.to_string(),
            drain_timeout_ms: Some(50),
        })
        .unwrap();
        Frame::build(FrameType::Request, control_flags(), 0, 0, corr, body).unwrap()
    }

    /// Two handlers built over one forwarding table must share one outage
    /// tracker; separate trackers would each log their own opening line for
    /// the same outage.
    #[test]
    fn handlers_over_one_forwarding_table_share_the_outage_tracker() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let first = ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding));
        let second = ControlHandler::with_forwarding(registry, forwarding);
        assert!(Arc::ptr_eq(&first.route_outages, &second.route_outages));
    }

    /// A client can name any module id it likes. Refusing an unknown one,
    /// however often, must not create outage state or outage lines, or the
    /// tracker would be a memory sink any client could fill.
    #[tokio::test(flavor = "current_thread")]
    async fn route_open_unknown_module_refusals_add_no_outage_state() {
        let handler = ControlHandler::new(Arc::new(Registry::default()));
        let capture = EventCapture::default();
        let _subscriber =
            tracing::subscriber::set_default(tracing_subscriber::registry().with(capture.clone()));
        let (ctx, _rx) = route_ctx(ConnectionId::new(90));
        for corr in 0..8 {
            let response = handler
                .handle_control_frame(
                    &ctx,
                    route_open_frame(
                        380 + corr,
                        &format!("nobody-{corr}"),
                        unique_project_root("outage-unknown"),
                    ),
                )
                .await
                .unwrap();
            assert_eq!(parse_error(&response[0])["code"], "unknown_module");
        }

        assert_eq!(handler.route_outages.tracked_module_count(), 0);
        assert!(outage_lines(&capture, OUTAGE_START).is_empty());
        assert!(outage_lines(&capture, OUTAGE_RECOVERED).is_empty());
    }

    /// Drives the refusal path end to end: a supervised module that served
    /// before and stopped being registered with no instruction to stop is a
    /// WARN, and the same module refused after an operator `supervisor.restart`
    /// is an INFO.
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn route_open_outage_level_separates_operator_restart_from_unexplained() {
        let registry = Arc::new(Registry::default());
        let (supervisor_handle, module) = supervise_stub(&registry, "outage-restart", true);
        let handler = ControlHandler::new(Arc::clone(&registry)).with_supervisor(supervisor_handle);
        let capture = EventCapture::default();
        let _subscriber =
            tracing::subscriber::set_default(tracing_subscriber::registry().with(capture.clone()));
        let (ctx, _rx) = route_ctx(ConnectionId::new(91));
        // The stub never registers, so pretend it served once: otherwise every
        // refusal would fall in its startup window.
        handler.route_outages.record_accepted("outage-restart");

        let response = handler
            .handle_control_frame(
                &ctx,
                route_open_frame(391, "outage-restart", unique_project_root("outage-a")),
            )
            .await
            .unwrap();
        assert_eq!(response[0].header.ty, FrameType::Error);
        let starts = outage_lines(&capture, OUTAGE_START);
        assert_eq!(starts.len(), 1, "{starts:?}");
        assert_eq!(starts[0].level, tracing::Level::WARN);
        assert_eq!(starts[0].fields["initiated_by"], "\"unexplained\"");
        assert_eq!(starts[0].fields["reason"], "\"supervised_not_registered\"");
        assert_eq!(starts[0].fields["module_id"], "\"outage-restart\"");
        handler.route_outages.record_accepted("outage-restart");
        assert_eq!(outage_lines(&capture, OUTAGE_RECOVERED).len(), 1);

        let restart = handler
            .handle_control_frame(&ctx, supervisor_restart_frame(392, "outage-restart"))
            .await
            .unwrap();
        assert_eq!(
            restart[0].header.ty,
            FrameType::Response,
            "{:?}",
            parse_error(&restart[0])
        );
        handler
            .handle_control_frame(
                &ctx,
                route_open_frame(393, "outage-restart", unique_project_root("outage-b")),
            )
            .await
            .unwrap();
        module.stop().await.unwrap();

        let starts = outage_lines(&capture, OUTAGE_START);
        assert_eq!(starts.len(), 2, "{starts:?}");
        assert_eq!(starts[1].level, tracing::Level::INFO);
        assert_eq!(starts[1].fields["initiated_by"], "\"operator\"");
    }

    /// A restart refused before it touched the module (here: the module is
    /// disabled) must clear its operator mark, so the next real outage is
    /// still reported as a warning.
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn failed_operator_restart_leaves_no_operator_mark() {
        let registry = Arc::new(Registry::default());
        let (supervisor_handle, _module) = supervise_stub(&registry, "outage-disabled", false);
        let handler = ControlHandler::new(Arc::clone(&registry)).with_supervisor(supervisor_handle);
        let capture = EventCapture::default();
        let _subscriber =
            tracing::subscriber::set_default(tracing_subscriber::registry().with(capture.clone()));
        let (ctx, _rx) = route_ctx(ConnectionId::new(92));
        handler.route_outages.record_accepted("outage-disabled");

        let restart = handler
            .handle_control_frame(&ctx, supervisor_restart_frame(394, "outage-disabled"))
            .await
            .unwrap();
        assert_eq!(parse_error(&restart[0])["code"], "module_disabled");
        assert!(!handler.route_outages.has_operator_mark("outage-disabled"));

        handler
            .handle_control_frame(
                &ctx,
                route_open_frame(395, "outage-disabled", unique_project_root("outage-c")),
            )
            .await
            .unwrap();
        let starts = outage_lines(&capture, OUTAGE_START);
        assert_eq!(starts.len(), 1, "{starts:?}");
        assert_eq!(starts[0].level, tracing::Level::WARN);
    }

    #[tokio::test(flavor = "current_thread")]
    async fn route_open_unknown_module_escapes_target_module_id() {
        let handler = ControlHandler::new(Arc::new(Registry::default()));
        let capture = EventCapture::default();
        let _subscriber =
            tracing::subscriber::set_default(tracing_subscriber::registry().with(capture.clone()));
        let hostile_module_id = "\u{1b}]52;c;AAAA\u{07}";
        let (ctx, _rx) = route_ctx(ConnectionId::new(95));
        let response = handler
            .handle_control_frame(
                &ctx,
                route_open_frame(
                    395,
                    hostile_module_id,
                    unique_project_root("hostile-target-module-id"),
                ),
            )
            .await
            .unwrap();

        assert_eq!(parse_error(&response[0])["code"], "unknown_module");
        let event = capture
            .events()
            .into_iter()
            .find(|event| {
                event.target == "control"
                    && event.fields.get("code") == Some(&"\"unknown_module\"".to_string())
            })
            .expect("route.open unknown-module refusal event");
        let logged = event.fields.get("module_id").expect("module_id field");
        assert!(!logged.bytes().any(|byte| byte < 0x20));
        assert_eq!(logged, r#""\u{1b}]52;c;AAAA\u{7}""#);
    }

    #[tokio::test(flavor = "current_thread")]
    async fn route_open_module_rejection_uses_daemon_counter_key() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding));
        let module_connection = ConnectionId::new(95);
        let (module_ctx, mut module_rx) = route_ctx(module_connection);
        hello_via_sink(
            &handler,
            &module_ctx,
            &mut module_rx,
            hello_frame("aft", PROTOCOL_VERSION, 395),
        )
        .await;

        let client_connection = ConnectionId::new(96);
        let (client_ctx, _client_rx) = route_ctx(client_connection);
        let capture = EventCapture::default();
        let _subscriber =
            tracing::subscriber::set_default(tracing_subscriber::registry().with(capture.clone()));
        let (route_task, bind) = relay_route_open(
            &handler,
            client_connection,
            &client_ctx.egress,
            &mut module_rx,
            396,
            "aft",
            "hostile-module-code",
        )
        .await;
        let hostile_code = "\u{1b}]52;c;AAAA\u{07}";
        let rejection = Frame::build(
            FrameType::Error,
            control_flags(),
            0,
            0,
            bind.header.corr,
            serde_json::to_vec(&ErrorBody::new(hostile_code, "module refused route.bind")).unwrap(),
        )
        .unwrap();
        handler
            .handle_control_frame(&module_ctx, rejection)
            .await
            .unwrap();

        let response = route_task.await.unwrap();
        assert_eq!(parse_error(&response[0])["code"], hostile_code);
        let counters = handler.counters().snapshot();
        assert_eq!(
            counters["route_open_refused_by_code"],
            json!({ "module_rejected": 1 })
        );
        assert!(counters["route_open_refused_by_code"]
            .get(hostile_code)
            .is_none());

        let event = capture
            .events()
            .into_iter()
            .find(|event| {
                event.target == "control"
                    && event.fields.get("code") == Some(&"\"module_rejected\"".to_string())
            })
            .expect("route.open module-rejection refusal event");
        let logged = event.fields.get("module_code").expect("module_code field");
        assert!(!logged.bytes().any(|byte| byte < 0x20));
        assert_eq!(logged, r#""\u{1b}]52;c;AAAA\u{7}""#);
    }

    #[tokio::test]
    async fn route_open_keeps_failed_unregistered_supervised_module_unavailable() {
        let registry = Arc::new(Registry::default());
        let supervisor_handle = SupervisorHandle::new();
        let missing_program = std::env::temp_dir().join(format!(
            "subc-route-open-missing-program-{}",
            std::process::id()
        ));
        let supervisor =
            Supervisor::new(Arc::clone(&registry), RestartPolicy::new(0, Duration::ZERO))
                .with_handle(supervisor_handle.clone());
        let module = supervisor
            .supervise_configured(
                ModuleSpec {
                    module_id: "failed".to_string(),
                    program: missing_program,
                    args: Vec::new(),
                    env: Vec::new(),
                    reserved: false,
                    reserved_prefixes: Vec::new(),
                    protocol: ModuleProtocol::Subc,
                    overlap: Default::default(),
                },
                true,
            )
            .unwrap();
        assert_eq!(module.state().unwrap(), ModuleState::Failed);

        let handler = ControlHandler::new(Arc::clone(&registry)).with_supervisor(supervisor_handle);
        let (ctx, _rx) = route_ctx(ConnectionId::new(40));
        let response = handler
            .handle_control_frame(
                &ctx,
                route_open_frame(305, "failed", unique_project_root("failed")),
            )
            .await
            .unwrap();

        assert_eq!(response[0].header.ty, FrameType::Error);
        let error = parse_error(&response[0]);
        assert_eq!(error["code"], "target_unavailable");
        assert!(error["message"]
            .as_str()
            .unwrap()
            .contains("state=failed, enabled=true, live=false"));
    }

    #[tokio::test]
    async fn route_open_role_mismatch_remains_target_unavailable() {
        let registry = Arc::new(Registry::default());
        let handler = ControlHandler::new(Arc::clone(&registry));
        handler
            .handle_control(
                ConnectionId::new(41),
                non_routable_hello_frame_with_control_ops("health-only", 306, None),
            )
            .unwrap();

        let (ctx, _rx) = route_ctx(ConnectionId::new(42));
        let response = handler
            .handle_control_frame(
                &ctx,
                route_open_frame(307, "health-only", unique_project_root("role-mismatch")),
            )
            .await
            .unwrap();

        assert_eq!(parse_error(&response[0])["code"], "target_unavailable");
        assert!(parse_error(&response[0])["message"]
            .as_str()
            .unwrap()
            .contains("does not provide the requested target"));
    }

    #[tokio::test]
    async fn route_open_inactive_registration_remains_target_unavailable() {
        let registry = Arc::new(Registry::default());
        let handler = ControlHandler::new(Arc::clone(&registry));
        handler
            .handle_control(
                ConnectionId::new(43),
                hello_frame("inactive", PROTOCOL_VERSION, 308),
            )
            .unwrap();
        assert!(registry
            .set_module_state_for_test("inactive", ChannelState::Closed)
            .unwrap());

        let (ctx, _rx) = route_ctx(ConnectionId::new(44));
        let response = handler
            .handle_control_frame(
                &ctx,
                route_open_frame(309, "inactive", unique_project_root("inactive")),
            )
            .await
            .unwrap();

        assert_eq!(parse_error(&response[0])["code"], "target_unavailable");
        assert!(parse_error(&response[0])["message"]
            .as_str()
            .unwrap()
            .contains("is not active"));
    }

    #[tokio::test]
    async fn late_health_reply_is_recorded_through_the_module_response_path() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let supervisor_handle = SupervisorHandle::new();
        let supervisor = Supervisor::new(Arc::clone(&registry), crate::RestartPolicy::default())
            .with_forwarding(Arc::clone(&forwarding))
            .with_handle(supervisor_handle.clone());
        let module = supervisor
            .supervise_configured(
                crate::ModuleSpec {
                    module_id: "late-health-response".to_string(),
                    program: PathBuf::from("disabled-module"),
                    args: Vec::new(),
                    env: Vec::new(),
                    reserved: false,
                    reserved_prefixes: Vec::new(),
                    protocol: ModuleProtocol::Subc,
                    overlap: Default::default(),
                },
                false,
            )
            .unwrap();
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding))
                .with_supervisor(supervisor_handle);
        let (module_ctx, _module_rx) = route_ctx(ConnectionId::new(39));
        handler
            .handle_control_frame(
                &module_ctx,
                hello_frame_with_control_ops(
                    "late-health-response",
                    PROTOCOL_VERSION,
                    7,
                    Some(vec![MODULE_CONTROL_OP_HEALTH_CHECK.to_string()]),
                ),
            )
            .await
            .unwrap();
        let probe_started_at = Instant::now() - Duration::from_millis(80);
        let pending = forwarding
            .begin_health_probe_rpc_for(
                "late-health-response",
                MODULE_CONTROL_OP_HEALTH_CHECK,
                probe_started_at,
                Instant::now() - Duration::from_millis(1),
            )
            .unwrap();
        assert!(forwarding
            .tombstone_health_probe_rpc(pending.endpoint, pending.corr)
            .unwrap());

        let responses = handler
            .handle_control_frame(&module_ctx, health_response(pending.corr, HealthStatus::Ok))
            .await
            .unwrap();

        assert!(responses.is_empty());
        let health = module.status().unwrap().health;
        assert_eq!(health.late_answer_count, 1);
        assert!(health.last_late_answer_latency_ms.unwrap() >= 80);
    }

    #[tokio::test]
    async fn health_probe_timeout_and_module_death_are_typed() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding))
                .with_health_probe_timeout(Duration::from_millis(50));
        let (module_ctx, mut module_rx) = route_ctx(ConnectionId::new(40));
        hello_via_sink(
            &handler,
            &module_ctx,
            &mut module_rx,
            hello_frame_with_control_ops(
                "aft",
                PROTOCOL_VERSION,
                7,
                Some(vec![MODULE_CONTROL_OP_HEALTH_CHECK.to_string()]),
            ),
        )
        .await;

        let (client_ctx, _client_rx) = route_ctx(ConnectionId::new(41));
        let responses = handler
            .handle_control_frame(&client_ctx, supervisor_health_probe_frame(201, "aft"))
            .await
            .unwrap();
        assert_eq!(responses[0].header.ty, FrameType::Error);
        assert_eq!(parse_error(&responses[0])["code"], "module_timeout");
        let _ = module_rx.try_recv();

        let (client_ctx, _client_rx) = route_ctx(ConnectionId::new(42));
        let health_handler = handler.clone();
        let death_task = tokio::spawn(async move {
            health_handler
                .handle_control_frame(&client_ctx, supervisor_health_probe_frame(202, "aft"))
                .await
                .unwrap()
        });
        tokio::time::timeout(Duration::from_secs(1), module_rx.recv())
            .await
            .unwrap()
            .unwrap();
        handler
            .cleanup_connection(module_ctx.connection_id)
            .unwrap();
        let responses = death_task.await.unwrap();
        assert_eq!(responses[0].header.ty, FrameType::Error);
        assert_eq!(parse_error(&responses[0])["code"], "target_unavailable");
    }

    #[test]
    fn hello_requires_exact_protocol_version() {
        for (connection, offered) in [(1, PROTOCOL_VERSION - 1), (2, PROTOCOL_VERSION + 1)] {
            let registry = Arc::new(Registry::default());
            let handler = ControlHandler::new(Arc::clone(&registry));
            let responses = handler
                .handle_control(
                    ConnectionId::new(connection),
                    hello_frame("aft", offered, 9),
                )
                .unwrap();

            assert_eq!(responses.len(), 1);
            assert_eq!(responses[0].header.ty, FrameType::Error);
            let error = parse_error(&responses[0]);
            assert_eq!(error["code"], "version_unsupported");
            assert!(registry.get_module("aft").unwrap().is_none());
            assert_eq!(registry.active_registration_count().unwrap(), 0);
        }
    }

    #[test]
    fn unknown_module_push_op_is_ignored_but_malformed_known_op_errors() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding));
        let module_connection = ConnectionId::new(301);
        let registration = registry
            .register_with_control_ops(
                manifest("aft-push", PROTOCOL_VERSION),
                PROTOCOL_VERSION,
                module_connection,
                module_baseline_control_ops(),
            )
            .unwrap();
        let (module_tx, _module_rx) = mpsc::channel(8);
        let endpoint = forwarding
            .register_module_connection(
                module_connection,
                "aft-push".to_string(),
                PROTOCOL_VERSION,
                manifest_concurrency(&registration.manifest),
                FrameSink::new(module_tx),
            )
            .unwrap();

        // A push op this version does not know is ignored (forward-compat), not errored.
        let unknown = Frame::build(
            FrameType::Push,
            control_flags(),
            0,
            0,
            5,
            serde_json::to_vec(&json!({"op": "route.future.v2", "extra": 1})).unwrap(),
        )
        .unwrap();
        let out = handler.handle_status_update(endpoint, unknown).unwrap();
        assert!(
            out.is_empty(),
            "unknown push op must be ignored, got {out:?}"
        );

        // A malformed body for a KNOWN op is a real error worth surfacing.
        let malformed = Frame::build(
            FrameType::Push,
            control_flags(),
            0,
            0,
            6,
            serde_json::to_vec(&json!({"op": "route.status"})).unwrap(),
        )
        .unwrap();
        let out = handler.handle_status_update(endpoint, malformed).unwrap();
        assert_eq!(out.len(), 1);
        assert_eq!(out[0].header.ty, FrameType::Error);
        assert_eq!(parse_error(&out[0])["code"], "invalid_control_body");
    }

    #[test]
    fn hello_rejected_when_connection_already_owns_client_routes() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding));
        // Commits a client route on connection 202 (bound to a module on conn 101).
        let _ = bind_liveness_route(&registry, &forwarding, "aft-module");
        let client_connection = ConnectionId::new(202);

        // That same connection now tries to register as a module: rejected, so one
        // connection never holds both client-route and module-endpoint state.
        let responses = handler
            .handle_control(
                client_connection,
                hello_frame("aft-second", PROTOCOL_VERSION, 9),
            )
            .unwrap();
        assert_eq!(responses[0].header.ty, FrameType::Error);
        assert_eq!(parse_error(&responses[0])["code"], "invalid_hello");
        assert!(registry.get_module("aft-second").unwrap().is_none());
    }

    #[tokio::test]
    async fn second_hello_preserves_registration_routes_and_launch_nonce() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let handler = ControlHandler::with_forwarding(registry.clone(), forwarding.clone());
        let (module_ctx, mut module_rx) = route_ctx(ConnectionId::new(101));
        hello_via_sink(
            &handler,
            &module_ctx,
            &mut module_rx,
            hello_frame_with_nonce("alpha", PROTOCOL_VERSION, 1, Some("alpha-nonce")),
        )
        .await;
        let (client_ctx, mut client_rx) = route_ctx(ConnectionId::new(202));
        let pending = forwarding
            .begin_route_bind_relay_for_test(
                client_ctx.connection_id,
                client_ctx.egress.clone(),
                2,
                "alpha",
            )
            .unwrap();
        forwarding
            .complete_pending_relay(
                module_ctx.connection_id,
                pending.corr,
                RouteBindRelayOutcome::Accepted,
            )
            .unwrap();
        client_rx.try_recv().unwrap();
        for module_id in ["beta", "alpha"] {
            let replies = handler
                .handle_control_frame(
                    &module_ctx,
                    hello_frame_with_nonce(module_id, PROTOCOL_VERSION, 3, Some("replacement")),
                )
                .await
                .unwrap();
            assert_eq!(replies.len(), 1, "second HELLO must be refused");
            assert_eq!(parse_error(&replies[0])["code"], "invalid_hello");
        }
        assert_eq!(registry.list_modules().unwrap().1.len(), 1);
        assert!(registry.get_module("beta").unwrap().is_none());
        assert!(matches!(
            forwarding
                .lookup_data_route(
                    client_ctx.connection_id,
                    pending.client_channel,
                    pending.client_epoch,
                )
                .unwrap(),
            DataRoute::Client(DataRouteState::Bound(_))
        ));
        assert!(handler
            .hello_launch_nonces
            .lock()
            .unwrap()
            .presented(module_ctx.connection_id, Some("alpha-nonce")));
        assert!(module_rx.try_recv().is_err());
    }

    #[test]
    fn reserved_module_hello_requires_matching_launch_nonce() {
        let registry = Arc::new(Registry::default());
        let supervisor = SupervisorHandle::new();
        // The supervisor recorded the nonce it injected when it spawned the reserved
        // module; the HELLO verifier checks against the same shared handle.
        supervisor.set_reserved_nonce("vault", "the-real-nonce".to_string());
        let handler = ControlHandler::new(Arc::clone(&registry)).with_supervisor(supervisor);

        // A HELLO with NO nonce is rejected.
        let no_nonce = handler
            .handle_control(
                ConnectionId::new(1),
                hello_frame("vault", PROTOCOL_VERSION, 1),
            )
            .unwrap();
        assert_eq!(no_nonce[0].header.ty, FrameType::Error);
        assert_eq!(parse_error(&no_nonce[0])["code"], "reserved_module");
        assert!(registry.get_module("vault").unwrap().is_none());

        // A HELLO with the WRONG nonce is rejected.
        let wrong = handler
            .handle_control(
                ConnectionId::new(2),
                hello_frame_with_nonce("vault", PROTOCOL_VERSION, 2, Some("forged")),
            )
            .unwrap();
        assert_eq!(wrong[0].header.ty, FrameType::Error);
        assert_eq!(parse_error(&wrong[0])["code"], "reserved_module");
        assert!(registry.get_module("vault").unwrap().is_none());

        // A HELLO with the CORRECT nonce registers.
        let ok = handler
            .handle_control(
                ConnectionId::new(3),
                hello_frame_with_nonce("vault", PROTOCOL_VERSION, 3, Some("the-real-nonce")),
            )
            .unwrap();
        assert_eq!(ok[0].header.ty, FrameType::HelloAck);
        assert!(registry.get_module("vault").unwrap().is_some());
    }

    #[test]
    fn reserved_prefix_hello_uses_delimiter_sensitive_owner_nonce() {
        let registry = Arc::new(Registry::default());
        let supervisor = SupervisorHandle::new();
        supervisor.set_spawn_nonce("federation", "owner-nonce".to_string());
        supervisor.set_reserved_prefixes("federation", &["fed:".to_string()]);
        let handler = ControlHandler::new(Arc::clone(&registry)).with_supervisor(supervisor);

        let squat = handler
            .handle_control(
                ConnectionId::new(1),
                hello_frame("fed:peerA:tool", PROTOCOL_VERSION, 1),
            )
            .unwrap();
        assert_eq!(squat[0].header.ty, FrameType::Error);
        assert_eq!(parse_error(&squat[0])["code"], "reserved_module");
        assert!(parse_error(&squat[0])["message"]
            .as_str()
            .unwrap()
            .contains("fed:"));

        let accepted_peer = handler
            .handle_control(
                ConnectionId::new(2),
                hello_frame_with_nonce("fed:peerA:tool", PROTOCOL_VERSION, 2, Some("owner-nonce")),
            )
            .unwrap();
        assert_eq!(accepted_peer[0].header.ty, FrameType::HelloAck);

        let accepted_short = handler
            .handle_control(
                ConnectionId::new(3),
                hello_frame_with_nonce("fed:x", PROTOCOL_VERSION, 3, Some("owner-nonce")),
            )
            .unwrap();
        assert_eq!(accepted_short[0].header.ty, FrameType::HelloAck);

        for (conn, module_id) in [(4, "fedx:tool"), (5, "fed"), (6, "FED:x")] {
            let response = handler
                .handle_control(
                    ConnectionId::new(conn),
                    hello_frame(module_id, PROTOCOL_VERSION, conn),
                )
                .unwrap();
            assert_eq!(response[0].header.ty, FrameType::HelloAck, "{module_id}");
        }
    }

    #[test]
    fn exact_reserved_module_takes_precedence_over_reserved_prefix() {
        let registry = Arc::new(Registry::default());
        let supervisor = SupervisorHandle::new();
        supervisor.set_spawn_nonce("federation", "owner-nonce".to_string());
        supervisor.set_reserved_prefixes("federation", &["fed:".to_string()]);
        supervisor.set_reserved_nonce("fed:special", "exact-nonce".to_string());
        let handler = ControlHandler::new(Arc::clone(&registry)).with_supervisor(supervisor);

        let owner_nonce = handler
            .handle_control(
                ConnectionId::new(1),
                hello_frame_with_nonce("fed:special", PROTOCOL_VERSION, 1, Some("owner-nonce")),
            )
            .unwrap();
        assert_eq!(owner_nonce[0].header.ty, FrameType::Error);
        assert_eq!(parse_error(&owner_nonce[0])["code"], "reserved_module");
        assert!(registry.get_module("fed:special").unwrap().is_none());

        let exact_nonce = handler
            .handle_control(
                ConnectionId::new(2),
                hello_frame_with_nonce("fed:special", PROTOCOL_VERSION, 2, Some("exact-nonce")),
            )
            .unwrap();
        assert_eq!(exact_nonce[0].header.ty, FrameType::HelloAck);
        assert!(registry.get_module("fed:special").unwrap().is_some());
    }

    #[test]
    fn non_reserved_module_ignores_launch_nonce() {
        let registry = Arc::new(Registry::default());
        // No reserved nonce recorded for these ids: they are not reserved, so HELLO
        // registration succeeds whether a spawned process echoes a nonce or not.
        let handler = ControlHandler::new(Arc::clone(&registry));
        let no_nonce = handler
            .handle_control(
                ConnectionId::new(1),
                hello_frame("aft-no-nonce", PROTOCOL_VERSION, 1),
            )
            .unwrap();
        assert_eq!(no_nonce[0].header.ty, FrameType::HelloAck);
        assert!(registry.get_module("aft-no-nonce").unwrap().is_some());

        let echoed_nonce = handler
            .handle_control(
                ConnectionId::new(2),
                hello_frame_with_nonce("aft-with-nonce", PROTOCOL_VERSION, 2, Some("spawn-nonce")),
            )
            .unwrap();
        assert_eq!(echoed_nonce[0].header.ty, FrameType::HelloAck);
        assert!(registry.get_module("aft-with-nonce").unwrap().is_some());
    }

    #[test]
    fn malformed_hello_returns_error_and_handler_still_answers_ping() {
        let handler = ControlHandler::default();
        let conn = ConnectionId::new(1);
        let malformed = Frame::build(
            FrameType::Hello,
            control_flags(),
            0,
            0,
            3,
            b"{not json".to_vec(),
        )
        .unwrap();

        let error = handler.handle_control(conn, malformed).unwrap();
        assert_eq!(error[0].header.ty, FrameType::Error);
        assert_eq!(parse_error(&error[0])["code"], "invalid_hello");

        let ping = Frame::build(FrameType::Ping, control_flags(), 0, 0, 4, Vec::new()).unwrap();
        let pong = handler.handle_control(conn, ping).unwrap();
        assert_eq!(pong[0].header.ty, FrameType::Pong);
        assert_eq!(pong[0].header.corr, 4);
    }

    #[test]
    fn duplicate_module_id_is_rejected_without_replacing_active_registration() {
        let registry = Arc::new(Registry::default());
        let handler = ControlHandler::new(Arc::clone(&registry));

        handler
            .handle_control(
                ConnectionId::new(1),
                hello_frame("aft", PROTOCOL_VERSION, 1),
            )
            .unwrap();
        let duplicate = handler
            .handle_control(
                ConnectionId::new(2),
                hello_frame("aft", PROTOCOL_VERSION, 2),
            )
            .unwrap();

        assert_eq!(duplicate[0].header.ty, FrameType::Error);
        assert_eq!(parse_error(&duplicate[0])["code"], "duplicate_module_id");
        let registration = registry.get_module("aft").unwrap().unwrap();
        assert_eq!(registration.connection_id, ConnectionId::new(1));
    }

    #[test]
    fn liveness_poll_reports_false_when_process_liveness_reports_dead() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let process_liveness = Arc::new(FakeProcessLiveness { live: Some(false) });
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding))
                .with_process_liveness(process_liveness);
        let (ctx, route_channel, route_epoch) =
            bind_liveness_route(&registry, &forwarding, "aft-dead");
        let responses = handler
            .handle_route_poll(
                &ctx,
                route_poll_frame(41, PollKind::Liveness, route_channel),
                route_channel,
                route_epoch,
                PollKind::Liveness,
            )
            .unwrap();

        assert_eq!(responses.len(), 1);
        assert_eq!(responses[0].header.ty, FrameType::Response);
        assert_route_poll_liveness(&responses[0], false);
    }

    #[test]
    fn liveness_poll_without_process_source_uses_bound_route() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding));
        let (ctx, route_channel, route_epoch) =
            bind_liveness_route(&registry, &forwarding, "aft-bound-only");
        let responses = handler
            .handle_route_poll(
                &ctx,
                route_poll_frame(42, PollKind::Liveness, route_channel),
                route_channel,
                route_epoch,
                PollKind::Liveness,
            )
            .unwrap();

        assert_route_poll_liveness(&responses[0], true);
    }

    #[test]
    fn liveness_poll_untracked_process_source_uses_bound_route() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let process_liveness = Arc::new(FakeProcessLiveness { live: None });
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding))
                .with_process_liveness(process_liveness);
        let (ctx, route_channel, route_epoch) =
            bind_liveness_route(&registry, &forwarding, "aft-untracked");
        let responses = handler
            .handle_route_poll(
                &ctx,
                route_poll_frame(43, PollKind::Liveness, route_channel),
                route_channel,
                route_epoch,
                PollKind::Liveness,
            )
            .unwrap();

        assert_route_poll_liveness(&responses[0], true);
    }

    #[tokio::test]
    async fn unknown_op_returns_unknown_control_op() {
        let handler = ControlHandler::default();
        let (ctx, _rx) = route_ctx(ConnectionId::new(77));
        let request = Frame::build(
            FrameType::Request,
            control_flags(),
            0,
            0,
            55,
            br#"{"op":"route.nope","route_channel":1}"#.to_vec(),
        )
        .unwrap();

        let response = handler.handle_control_frame(&ctx, request).await.unwrap();

        assert_eq!(response.len(), 1);
        assert_eq!(response[0].header.ty, FrameType::Error);
        assert_eq!(response[0].header.corr, 55);
        assert_eq!(parse_error(&response[0])["code"], "unknown_control_op");
    }

    #[tokio::test]
    async fn supervisor_provenance_rejects_unknown_exact_module() {
        let handler = ControlHandler::default();
        let (ctx, _rx) = route_ctx(ConnectionId::new(79));
        let request = Frame::build(
            FrameType::Request,
            control_flags(),
            0,
            0,
            57,
            br#"{"op":"supervisor.provenance","module_id":"missing"}"#.to_vec(),
        )
        .unwrap();

        let response = handler.handle_control_frame(&ctx, request).await.unwrap();

        assert_eq!(response.len(), 1);
        assert_eq!(response[0].header.ty, FrameType::Error);
        assert_eq!(response[0].header.corr, 57);
        let error = parse_error(&response[0]);
        assert_eq!(error["code"], "unknown_module");
        assert_eq!(error["message"], "module_id 'missing' is not supervised");
    }

    #[test]
    fn provenance_probe_override_keeps_handler_tests_deterministic() {
        let expected = subc_control::RunningImageAgreement::Unavailable {
            reason: subc_control::RunningImageUnavailableReason::HashFailed,
        };
        let handler = ControlHandler::default().with_provenance_probe_result(expected.clone());
        assert_eq!(handler.provenance_probe_override, Some(expected));
    }

    #[test]
    fn reload_verdict_detects_configured_program_different_from_spawned_path() {
        let verdict = reload_verdict(
            std::path::Path::new("/bin/new"),
            Some(std::path::Path::new("/bin/old")),
            subc_control::RunningImageAgreement::Unavailable {
                reason: subc_control::RunningImageUnavailableReason::HashFailed,
            },
        );
        assert!(matches!(
            verdict.path,
            subc_control::ReloadPathAgreement::Mismatch { configured, spawned_from }
                if configured == std::path::Path::new("/bin/new")
                    && spawned_from == std::path::Path::new("/bin/old")
        ));
    }

    #[test]
    fn reload_verdict_detects_replaced_image_at_same_path() {
        let image = subc_control::RunningImageAgreement::Mismatch {
            running: subc_control::RunningImageEvidence::LinuxProcSha256 {
                digest: "old".into(),
            },
            disk: subc_control::RunningImageEvidence::LinuxProcSha256 {
                digest: "new".into(),
            },
        };
        let verdict = reload_verdict(
            std::path::Path::new("/bin/same"),
            Some(std::path::Path::new("/bin/same")),
            image.clone(),
        );
        assert_eq!(verdict.path, subc_control::ReloadPathAgreement::Match);
        assert_eq!(verdict.image, image);
    }

    #[test]
    fn reload_verdict_preserves_stopped_and_unavailable_reasons() {
        let image = subc_control::RunningImageAgreement::Unavailable {
            reason: subc_control::RunningImageUnavailableReason::NotRunning,
        };
        let verdict = reload_verdict(std::path::Path::new("/bin/same"), None, image.clone());
        assert_eq!(
            verdict.path,
            subc_control::ReloadPathAgreement::Unavailable {
                reason: subc_control::ReloadPathUnavailableReason::NotRunning,
            }
        );
        assert_eq!(verdict.image, image);

        let unconfirmed = subc_control::RunningImageAgreement::Unavailable {
            reason: subc_control::RunningImageUnavailableReason::ProcessIdentityUnconfirmed,
        };
        let verdict = reload_verdict(
            std::path::Path::new("/bin/same"),
            Some(std::path::Path::new("/bin/same")),
            unconfirmed.clone(),
        );
        assert_eq!(verdict.path, subc_control::ReloadPathAgreement::Match);
        assert_eq!(verdict.image, unconfirmed);
    }

    #[test]
    fn reload_verdict_preserves_each_image_unavailability_reason() {
        use subc_control::RunningImageUnavailableReason as Reason;

        for reason in [
            Reason::NotRunning,
            Reason::UnsupportedPlatform,
            Reason::RunningExecutableUnreadable,
            Reason::SpawnedPathUnreadable,
            Reason::HashFailed,
            Reason::ProcessIdentityUnconfirmed,
            Reason::Unknown("future_probe_reason".to_string()),
        ] {
            let image = subc_control::RunningImageAgreement::Unavailable {
                reason: reason.clone(),
            };
            let verdict = reload_verdict(
                std::path::Path::new("/bin/same"),
                Some(std::path::Path::new("/bin/same")),
                image.clone(),
            );
            assert_eq!(verdict.path, subc_control::ReloadPathAgreement::Match);
            assert_eq!(verdict.image, image, "{reason:?}");
        }
    }

    #[tokio::test]
    async fn malformed_control_bodies_return_invalid_control_body() {
        let handler = ControlHandler::default();
        let (ctx, _rx) = route_ctx(ConnectionId::new(78));

        for (corr, body) in [
            (56, br#"{"route_channel":1}"#.as_slice()),
            (57, br#"{"op":17,"route_channel":1}"#.as_slice()),
            (
                58,
                br#"{"op":"route.poll","route_channel":"bad","kind":"status"}"#.as_slice(),
            ),
        ] {
            let request = Frame::build(
                FrameType::Request,
                control_flags(),
                0,
                0,
                corr,
                body.to_vec(),
            )
            .unwrap();
            let response = handler.handle_control_frame(&ctx, request).await.unwrap();

            assert_eq!(response.len(), 1);
            assert_eq!(response[0].header.ty, FrameType::Error);
            assert_eq!(response[0].header.corr, corr);
            assert_eq!(parse_error(&response[0])["code"], "invalid_control_body");
        }
    }

    #[tokio::test]
    async fn goodbye_tears_down_registration_and_later_channel_is_unknown() {
        let registry = Arc::new(Registry::default());
        let control = Arc::new(ControlHandler::new(Arc::clone(&registry)));
        let router = Router::with_control_handler(Arc::clone(&control));
        let connection = router.begin_connection();
        let (ctx, mut rx) = route_ctx(connection.id());

        router
            .route_for_connection(&ctx, hello_frame("aft", PROTOCOL_VERSION, 11))
            .await
            .unwrap();
        let response = rx.recv().await.unwrap();
        let ack = parse_ack(&response);
        assert_eq!(ack.negotiated_ver, PROTOCOL_VERSION);
        let channel = 1;

        let goodbye =
            Frame::build(FrameType::Goodbye, control_flags(), 0, 0, 12, Vec::new()).unwrap();
        router.route_for_connection(&ctx, goodbye).await.unwrap();
        assert!(rx.try_recv().is_err());
        assert!(registry.get_module("aft").unwrap().is_none());

        router
            .route_for_connection(&ctx, channel_request(channel, 13))
            .await
            .unwrap();
        let error_frame = rx.recv().await.unwrap();
        assert_eq!(error_frame.header.ty, FrameType::Error);
        assert_eq!(error_frame.header.channel, channel);
    }

    #[tokio::test]
    async fn module_goodbye_refreshes_requirements_and_pushes_route_closed() {
        let registry = Arc::new(Registry::default());
        let handler = ControlHandler::new(registry).with_capability_config(
            [("prov".to_string(), true), ("cons".to_string(), true)],
            BTreeMap::new(),
        );
        let (provider_ctx, mut provider_rx) = route_ctx(ConnectionId::new(701));
        register_capability_manifest(
            &handler,
            &provider_ctx,
            &mut provider_rx,
            capability_manifest("prov", &["thing/v1"], &[]),
            1,
        )
        .await;
        let mut consumer = capability_manifest("cons", &[], &[]);
        consumer.capabilities.as_mut().unwrap().requires.push(
            subc_protocol::manifest::CapabilityRequirement {
                capability: "thing/v1".to_string(),
                need: subc_protocol::manifest::CapabilityNeed::Required,
            },
        );
        let (consumer_ctx, mut consumer_rx) = route_ctx(ConnectionId::new(702));
        register_capability_manifest(&handler, &consumer_ctx, &mut consumer_rx, consumer, 2).await;
        assert_eq!(
            handler.capability_evaluator.verdict("cons", "thing/v1"),
            Some(CapabilityVerdict::Provided)
        );
        let (mut client_rx, _) = open_route_for_capability_test(
            &handler,
            &provider_ctx,
            &mut provider_rx,
            703,
            3,
            "prov",
            None,
        )
        .await;
        let goodbye =
            Frame::build(FrameType::Goodbye, control_flags(), 0, 0, 4, Vec::new()).unwrap();
        handler
            .handle_control_frame(&provider_ctx, goodbye)
            .await
            .unwrap();
        assert_eq!(
            handler.capability_evaluator.verdict("cons", "thing/v1"),
            Some(CapabilityVerdict::NeverProvided)
        );
        let closed = client_rx
            .try_recv()
            .expect("GOODBYE pushes route.closed before route GOODBYE");
        assert!(
            matches!(serde_json::from_slice::<ClientControlPush>(&closed.body).unwrap(),
            ClientControlPush::RouteClosed { module_id, channels, .. } if module_id == "prov" && channels.len() == 1)
        );
        assert_eq!(client_rx.try_recv().unwrap().header.ty, FrameType::Goodbye);
        assert_eq!(handler.forwarding.active_binding_count().unwrap(), 0);
    }

    #[tokio::test]
    async fn dropping_router_connection_releases_registration() {
        let registry = Arc::new(Registry::default());
        let control = Arc::new(ControlHandler::new(Arc::clone(&registry)));
        let router = Router::with_control_handler(control);
        let connection = router.begin_connection();
        let (ctx, mut rx) = route_ctx(connection.id());

        router
            .route_for_connection(&ctx, hello_frame("aft", PROTOCOL_VERSION, 31))
            .await
            .unwrap();
        let response = rx.recv().await.unwrap();
        let ack = parse_ack(&response);
        assert_eq!(ack.negotiated_ver, PROTOCOL_VERSION);
        assert!(registry.get_module("aft").unwrap().is_some());

        drop(connection);

        assert!(registry.get_module("aft").unwrap().is_none());
        assert_eq!(registry.active_registration_count().unwrap(), 0);
    }

    fn capability_manifest(
        module_id: &str,
        provides: &[&str],
        must_never_reach: &[&str],
    ) -> ModuleManifest {
        let mut manifest = manifest(module_id, PROTOCOL_VERSION);
        manifest.capabilities = Some(CapabilityDeclarations {
            provides: provides
                .iter()
                .map(|capability| (*capability).to_string())
                .collect(),
            requires: Vec::new(),
            must_never_reach: must_never_reach
                .iter()
                .map(|capability| (*capability).to_string())
                .collect(),
        });
        manifest
    }

    fn hello_frame_with_manifest(manifest: ModuleManifest, corr: u64) -> Frame {
        Frame::build(
            FrameType::Hello,
            control_flags(),
            0,
            0,
            corr,
            serde_json::to_vec(&ModuleHelloBody {
                protocol_ver: manifest.protocol_ver,
                manifest,
                control_ops: None,
                launch_nonce: None,
            })
            .expect("capability test HELLO serializes"),
        )
        .expect("capability test HELLO frame builds")
    }

    fn catalog_update_with_capabilities_frame(
        corr: u64,
        capabilities: CapabilityDeclarations,
    ) -> Frame {
        Frame::build(
            FrameType::Request,
            control_flags(),
            0,
            0,
            corr,
            serde_json::to_vec(&ModuleControlRequestFromModule::CatalogUpdate {
                provides: manifest("catalog-update-placeholder", PROTOCOL_VERSION).provides,
                capabilities: Some(capabilities),
                ready: None,
            })
            .expect("capability catalog.update serializes"),
        )
        .expect("capability catalog.update frame builds")
    }

    async fn register_capability_manifest(
        handler: &ControlHandler,
        ctx: &RouteCtx,
        rx: &mut mpsc::Receiver<crate::router::OutboundFrame>,
        manifest: ModuleManifest,
        corr: u64,
    ) {
        hello_via_sink(handler, ctx, rx, hello_frame_with_manifest(manifest, corr)).await;
    }

    async fn open_route_for_capability_test(
        handler: &ControlHandler,
        target_ctx: &RouteCtx,
        target_rx: &mut mpsc::Receiver<crate::router::OutboundFrame>,
        client_connection_id: u64,
        corr: u64,
        target_module_id: &str,
        consumer_identity: Option<ConsumerIdentity>,
    ) -> (
        mpsc::Receiver<crate::router::OutboundFrame>,
        ModuleControlRequest,
    ) {
        let (client_ctx, mut client_rx) = route_ctx(ConnectionId::new(client_connection_id));
        let route_handler = handler.clone();
        let target_module_id = target_module_id.to_string();
        let route_task = tokio::spawn(async move {
            route_handler
                .handle_control_frame(
                    &client_ctx,
                    route_open_frame_with_admission_facts(
                        corr,
                        &target_module_id,
                        unique_project_root("admission-facts"),
                        consumer_identity,
                        None,
                    ),
                )
                .await
                .expect("capability test route.open succeeds")
        });
        let bind = tokio::time::timeout(Duration::from_secs(1), target_rx.recv())
            .await
            .expect("capability test route.open must reach route.bind")
            .expect("target control receiver stays open");
        let bind_request: ModuleControlRequest =
            serde_json::from_slice(&bind.body).expect("route.bind decodes");
        handler
            .handle_control_frame(target_ctx, route_bind_ack(bind.header.corr))
            .await
            .expect("capability test route.bind ACK succeeds");
        assert!(route_task.await.expect("route.open task joins").is_empty());
        let opened = client_rx
            .recv()
            .await
            .expect("successful route.open publishes a response");
        assert!(matches!(
            serde_json::from_slice::<ClientControlResponse>(&opened.body),
            Ok(ClientControlResponse::RouteOpen { .. })
        ));
        (client_rx, bind_request)
    }

    fn assert_capability_denied_push(frame: Frame, target_module_id: &str) {
        assert_eq!(frame.header.ty, FrameType::Push);
        assert_eq!(frame.header.channel, 0);
        let push = serde_json::from_slice::<ClientControlPush>(&frame.body)
            .expect("route.closed control push decodes");
        let ClientControlPush::RouteClosed { channels, .. } = &push else {
            panic!("expected route.closed");
        };
        assert_eq!(channels.len(), 1, "exactly one violating route closed");
        let channels = channels.clone();
        assert_eq!(
            push,
            ClientControlPush::RouteClosed {
                module_id: target_module_id.to_string(),
                channels,
                reason: RouteCloseReason::CapabilityDenied,
                drained: false,
                abandoned: 0,
                excluded_subscriptions: 0,
                terminal: Some(false),
            }
        );
    }

    #[tokio::test]
    async fn route_open_capability_forbidden_mutation_proof_creates_no_route() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let supervisor = SupervisorHandle::new();
        supervisor.set_spawn_nonce("opener", "opener-nonce".to_string());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding))
                .with_supervisor(supervisor);
        let (target_ctx, mut target_rx) = route_ctx(ConnectionId::new(700));
        let (opener_ctx, mut opener_rx) = route_ctx(ConnectionId::new(701));
        register_capability_manifest(
            &handler,
            &target_ctx,
            &mut target_rx,
            capability_manifest("target", &["credentials-provider/v1"], &[]),
            1,
        )
        .await;
        register_capability_manifest(
            &handler,
            &opener_ctx,
            &mut opener_rx,
            capability_manifest("opener", &[], &["credentials-provider/v1"]),
            2,
        )
        .await;

        let (client_ctx, _client_rx) = route_ctx(ConnectionId::new(702));
        let replies = handler
            .handle_control_frame(
                &client_ctx,
                route_open_frame_with_admission_facts(
                    3,
                    "target",
                    unique_project_root("admission-facts"),
                    Some(ConsumerIdentity {
                        module_id: "opener".to_string(),
                        launch_nonce: "opener-nonce".to_string(),
                    }),
                    None,
                ),
            )
            .await
            .expect("denied route.open returns a typed frame");
        assert_eq!(parse_error(&replies[0])["code"], "capability_forbidden");
        assert_eq!(forwarding.active_binding_count().unwrap(), 0);
        assert!(
            target_rx.try_recv().is_err(),
            "forbidden route.open must not relay route.bind"
        );
    }

    #[tokio::test]
    async fn capability_deny_edge_hello_mutation_proof_force_closes_existing_route() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let supervisor = SupervisorHandle::new();
        supervisor.set_spawn_nonce("opener", "opener-nonce".to_string());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding))
                .with_supervisor(supervisor);
        let (target_ctx, mut target_rx) = route_ctx(ConnectionId::new(710));
        let (old_opener_ctx, mut old_opener_rx) = route_ctx(ConnectionId::new(711));
        register_capability_manifest(
            &handler,
            &target_ctx,
            &mut target_rx,
            capability_manifest("target", &["credentials-provider/v1"], &[]),
            1,
        )
        .await;
        register_capability_manifest(
            &handler,
            &old_opener_ctx,
            &mut old_opener_rx,
            capability_manifest("opener", &[], &[]),
            2,
        )
        .await;
        let (mut client_rx, _) = open_route_for_capability_test(
            &handler,
            &target_ctx,
            &mut target_rx,
            712,
            3,
            "target",
            Some(ConsumerIdentity {
                module_id: "opener".to_string(),
                launch_nonce: "opener-nonce".to_string(),
            }),
        )
        .await;
        assert_eq!(forwarding.active_binding_count().unwrap(), 1);

        handler
            .cleanup_connection(old_opener_ctx.connection_id)
            .expect("old opener registration cleans up");
        let (new_opener_ctx, mut new_opener_rx) = route_ctx(ConnectionId::new(713));
        register_capability_manifest(
            &handler,
            &new_opener_ctx,
            &mut new_opener_rx,
            capability_manifest("opener", &[], &["credentials-provider/v1"]),
            4,
        )
        .await;

        assert_capability_denied_push(
            client_rx
                .try_recv()
                .expect("HELLO deny addition must emit route.closed")
                .frame,
            "target",
        );
        assert_eq!(forwarding.active_binding_count().unwrap(), 0);
        assert!(matches!(
            target_rx.try_recv(),
            Ok(outbound) if outbound.header.ty == FrameType::Goodbye
        ));
    }

    #[tokio::test]
    async fn capability_claim_catalog_update_mutation_proof_force_closes_existing_route() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let supervisor = SupervisorHandle::new();
        supervisor.set_spawn_nonce("opener", "opener-nonce".to_string());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding))
                .with_supervisor(supervisor);
        let (target_ctx, mut target_rx) = route_ctx(ConnectionId::new(720));
        let (opener_ctx, mut opener_rx) = route_ctx(ConnectionId::new(721));
        register_capability_manifest(
            &handler,
            &target_ctx,
            &mut target_rx,
            capability_manifest("target", &[], &[]),
            1,
        )
        .await;
        register_capability_manifest(
            &handler,
            &opener_ctx,
            &mut opener_rx,
            capability_manifest("opener", &[], &["credentials-provider/v1"]),
            2,
        )
        .await;
        let (mut client_rx, _) = open_route_for_capability_test(
            &handler,
            &target_ctx,
            &mut target_rx,
            722,
            3,
            "target",
            Some(ConsumerIdentity {
                module_id: "opener".to_string(),
                launch_nonce: "opener-nonce".to_string(),
            }),
        )
        .await;
        assert_eq!(forwarding.active_binding_count().unwrap(), 1);

        let replies = handler
            .handle_control_frame(
                &target_ctx,
                catalog_update_with_capabilities_frame(
                    4,
                    CapabilityDeclarations {
                        provides: vec!["credentials-provider/v1".to_string()],
                        requires: Vec::new(),
                        must_never_reach: Vec::new(),
                    },
                ),
            )
            .await
            .expect("claim catalog.update succeeds");
        assert!(matches!(
            serde_json::from_slice::<ModuleControlResponseToModule>(&replies[0].body),
            Ok(ModuleControlResponseToModule::CatalogUpdate {})
        ));
        assert_capability_denied_push(
            client_rx
                .try_recv()
                .expect("claim addition must emit route.closed")
                .frame,
            "target",
        );
        assert_eq!(forwarding.active_binding_count().unwrap(), 0);
        assert!(matches!(
            target_rx.try_recv(),
            Ok(outbound) if outbound.header.ty == FrameType::Goodbye
        ));
    }

    #[tokio::test]
    async fn capability_claim_removal_mutation_proof_keeps_route_open_without_close_frame() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let supervisor = SupervisorHandle::new();
        supervisor.set_spawn_nonce("opener", "opener-nonce".to_string());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding))
                .with_supervisor(supervisor);
        let (target_ctx, mut target_rx) = route_ctx(ConnectionId::new(730));
        let (opener_ctx, mut opener_rx) = route_ctx(ConnectionId::new(731));
        register_capability_manifest(
            &handler,
            &target_ctx,
            &mut target_rx,
            capability_manifest("target", &["credentials-provider/v1"], &[]),
            1,
        )
        .await;
        register_capability_manifest(
            &handler,
            &opener_ctx,
            &mut opener_rx,
            capability_manifest("opener", &[], &[]),
            2,
        )
        .await;
        let (mut client_rx, _) = open_route_for_capability_test(
            &handler,
            &target_ctx,
            &mut target_rx,
            732,
            3,
            "target",
            Some(ConsumerIdentity {
                module_id: "opener".to_string(),
                launch_nonce: "opener-nonce".to_string(),
            }),
        )
        .await;
        assert_eq!(forwarding.active_binding_count().unwrap(), 1);

        handler
            .handle_control_frame(
                &target_ctx,
                catalog_update_with_capabilities_frame(
                    4,
                    CapabilityDeclarations {
                        provides: Vec::new(),
                        requires: Vec::new(),
                        must_never_reach: Vec::new(),
                    },
                ),
            )
            .await
            .expect("claim removal catalog.update succeeds");
        assert_eq!(
            forwarding.active_binding_count().unwrap(),
            1,
            "removing an attested target claim must leave the route census unchanged"
        );
        assert!(
            client_rx.try_recv().is_err(),
            "claim removal must not emit route.closed capability_denied"
        );
        assert!(
            target_rx.try_recv().is_err(),
            "claim removal must not send the target a route GOODBYE"
        );
    }

    /// A direct client may open a route to a denied capability provider; this
    /// policy applies only to attested supervised module origins, not to direct clients.
    #[tokio::test]
    async fn direct_client_scope_honesty_mutation_proof_opens_denied_capability_provider() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let supervisor = SupervisorHandle::new();
        supervisor.set_spawn_nonce("opener", "opener-nonce".to_string());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding))
                .with_supervisor(supervisor);
        let (target_ctx, mut target_rx) = route_ctx(ConnectionId::new(740));
        let (opener_ctx, mut opener_rx) = route_ctx(ConnectionId::new(741));
        register_capability_manifest(
            &handler,
            &target_ctx,
            &mut target_rx,
            capability_manifest("target", &["credentials-provider/v1"], &[]),
            1,
        )
        .await;
        register_capability_manifest(
            &handler,
            &opener_ctx,
            &mut opener_rx,
            capability_manifest("opener", &[], &["credentials-provider/v1"]),
            2,
        )
        .await;

        let (_client_rx, bind) = open_route_for_capability_test(
            &handler,
            &target_ctx,
            &mut target_rx,
            742,
            3,
            "target",
            None,
        )
        .await;
        let ModuleControlRequest::RouteBind { principal, .. } = bind else {
            panic!("direct scope-honesty route must bind");
        };
        assert_eq!(principal, Some(Principal::Direct));
        assert_eq!(forwarding.active_binding_count().unwrap(), 1);
    }

    /// A module that denies a capability receives no self-route exemption when it
    /// also attestedly provides that capability.
    #[tokio::test]
    async fn must_never_reach_self_route_is_capability_forbidden() {
        let registry = Arc::new(Registry::default());
        let forwarding = Arc::new(ForwardingTable::default());
        let supervisor = SupervisorHandle::new();
        supervisor.set_spawn_nonce("self-provider", "self-nonce".to_string());
        let handler =
            ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding))
                .with_supervisor(supervisor);
        let (self_ctx, mut self_rx) = route_ctx(ConnectionId::new(750));
        register_capability_manifest(
            &handler,
            &self_ctx,
            &mut self_rx,
            capability_manifest(
                "self-provider",
                &["credentials-provider/v1"],
                &["credentials-provider/v1"],
            ),
            1,
        )
        .await;

        let (client_ctx, _client_rx) = route_ctx(ConnectionId::new(751));
        let replies = handler
            .handle_control_frame(
                &client_ctx,
                route_open_frame_with_admission_facts(
                    2,
                    "self-provider",
                    unique_project_root("admission-facts"),
                    Some(ConsumerIdentity {
                        module_id: "self-provider".to_string(),
                        launch_nonce: "self-nonce".to_string(),
                    }),
                    None,
                ),
            )
            .await
            .expect("self-route refusal returns a typed frame");
        assert_eq!(parse_error(&replies[0])["code"], "capability_forbidden");
        assert_eq!(forwarding.active_binding_count().unwrap(), 0);
        assert!(
            self_rx.try_recv().is_err(),
            "self denial must not relay route.bind"
        );
    }

    #[test]
    fn unsupported_channel_zero_frame_returns_error() {
        let handler = ControlHandler::default();
        let request = Frame::build(
            FrameType::Request,
            control_flags(),
            0,
            0,
            21,
            b"opaque".to_vec(),
        )
        .unwrap();

        let response = handler
            .handle_control(ConnectionId::new(1), request)
            .unwrap();

        assert_eq!(response[0].header.ty, FrameType::Error);
        assert_eq!(
            parse_error(&response[0])["code"],
            "unsupported_control_frame"
        );
    }

    /// Blue/green swap at the control-plane boundary. The supervisor that opens
    /// a swap is not wired yet, so the candidate is registered here directly
    /// into the registry and forwarding candidate slots, the way the swap's
    /// HELLO admission will.
    mod swap {
        use super::*;

        const INCUMBENT: ConnectionId = ConnectionId::new(30);
        const CANDIDATE: ConnectionId = ConnectionId::new(40);

        struct Swap {
            registry: Arc<Registry>,
            forwarding: Arc<ForwardingTable>,
            handler: ControlHandler,
            incumbent_ctx: RouteCtx,
            incumbent_rx: mpsc::Receiver<crate::router::OutboundFrame>,
            candidate_ctx: RouteCtx,
            candidate_rx: mpsc::Receiver<crate::router::OutboundFrame>,
        }

        async fn swap_with_incumbent() -> Swap {
            let registry = Arc::new(Registry::default());
            let forwarding = Arc::new(ForwardingTable::default());
            let handler =
                ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding));
            let (incumbent_ctx, mut incumbent_rx) = route_ctx(INCUMBENT);
            hello_via_sink(
                &handler,
                &incumbent_ctx,
                &mut incumbent_rx,
                hello_frame("aft", PROTOCOL_VERSION, 7),
            )
            .await;
            let (candidate_ctx, candidate_rx) = route_ctx(CANDIDATE);
            Swap {
                registry,
                forwarding,
                handler,
                incumbent_ctx,
                incumbent_rx,
                candidate_ctx,
                candidate_rx,
            }
        }

        fn register_candidate(swap: &Swap, ready: Option<bool>) {
            let mut candidate_manifest = manifest("aft", PROTOCOL_VERSION);
            candidate_manifest.ready = ready;
            let registration = swap
                .registry
                .register_candidate_with_control_ops(
                    candidate_manifest,
                    PROTOCOL_VERSION,
                    CANDIDATE,
                    module_baseline_control_ops(),
                )
                .unwrap();
            swap.forwarding
                .register_candidate_module_connection(
                    CANDIDATE,
                    "aft".to_string(),
                    PROTOCOL_VERSION,
                    manifest_concurrency(&registration.manifest),
                    swap.candidate_ctx.egress.clone(),
                )
                .unwrap();
        }

        fn cutover(swap: &Swap) -> crate::forwarding::ModuleEndpointId {
            let cutover = swap.forwarding.cutover_candidate("aft").unwrap().unwrap();
            swap.registry.promote_candidate("aft").unwrap().unwrap();
            cutover.incumbent.unwrap()
        }

        fn keyed_total(counters: &Value, key: &str) -> u64 {
            counters[key]
                .as_object()
                .map(|counts| counts.values().filter_map(Value::as_u64).sum())
                .unwrap_or(0)
        }

        /// An ack from the incumbent for a bind it was sent before cutover,
        /// arriving before the incumbent is drained. The incumbent is the live
        /// connection carrying every other client's routes, so the ack must
        /// not end it: the waiting client is told to retry, the reservation is
        /// given back, and the incumbent is told to drop just that binding.
        #[tokio::test]
        async fn incumbent_ack_between_promotion_and_drain_keeps_the_incumbent_serving() {
            let mut swap = swap_with_incumbent().await;
            let handler = swap.handler.clone();

            // A co-tenant route, bound on the incumbent before the swap.
            let cotenant = ConnectionId::new(31);
            let (cotenant_ctx, mut cotenant_rx) = route_ctx(cotenant);
            let (cotenant_task, cotenant_bind) = relay_route_open(
                &handler,
                cotenant,
                &cotenant_ctx.egress,
                &mut swap.incumbent_rx,
                100,
                "aft",
                "swap-cotenant",
            )
            .await;
            handler
                .handle_control_frame(
                    &swap.incumbent_ctx,
                    route_bind_ack(cotenant_bind.header.corr),
                )
                .await
                .unwrap();
            assert!(cotenant_task.await.unwrap().is_empty());
            let (cotenant_channel, cotenant_epoch) =
                published_route(&cotenant_rx.recv().await.unwrap());

            // A second route.open, relayed to the incumbent and not yet acked.
            let caller = ConnectionId::new(32);
            let (caller_ctx, mut caller_rx) = route_ctx(caller);
            let (caller_task, caller_bind) = relay_route_open(
                &handler,
                caller,
                &caller_ctx.egress,
                &mut swap.incumbent_rx,
                101,
                "aft",
                "swap-caller",
            )
            .await;
            let (abandoned_channel, abandoned_epoch) = route_bind_channel(&caller_bind);

            register_candidate(&swap, None);
            cutover(&swap);

            // The incumbent acks after promotion and before any drain.
            let ack = handler
                .handle_control_frame(&swap.incumbent_ctx, route_bind_ack(caller_bind.header.corr))
                .await;
            let module_loop_error = ack.as_ref().err().map(ToString::to_string);
            if module_loop_error.is_some() {
                // What the connection loop does with an untranslated router
                // error: end the connection, releasing every route on it.
                handler.cleanup_connection(INCUMBENT).unwrap();
            }

            // 1. The incumbent's other routes survive.
            assert!(
                cotenant_rx.try_recv().is_err(),
                "the co-tenant route on the incumbent was torn down by one late ack: \
                 {module_loop_error:?}"
            );
            assert!(matches!(
                swap.forwarding
                    .lookup_data_route(cotenant, cotenant_channel, cotenant_epoch)
                    .unwrap(),
                DataRoute::Client(DataRouteState::Bound(_))
            ));
            assert_eq!(module_loop_error, None);
            assert!(swap
                .registry
                .get_module_by_connection(INCUMBENT)
                .unwrap()
                .is_some());

            // 2. Exactly one channel-scoped GOODBYE to the incumbent.
            let goodbye = tokio::time::timeout(Duration::from_secs(1), swap.incumbent_rx.recv())
                .await
                .expect("the incumbent is told to drop the abandoned binding")
                .unwrap()
                .frame;
            assert_eq!(goodbye.header.ty, FrameType::Goodbye);
            assert_eq!(goodbye.header.channel, abandoned_channel);
            assert_eq!(goodbye.header.epoch, abandoned_epoch);
            assert!(swap.incumbent_rx.try_recv().is_err());

            // 3. The waiting client gets a retryable refusal and no route.
            let response = caller_task.await.unwrap();
            assert_eq!(response.len(), 1);
            assert_eq!(parse_error(&response[0])["code"], "module_reloading");
            assert!(caller_rx.try_recv().is_err());

            // 4. The reservation pair is given back, and the pending bind
            //    settled exactly once: one accepted open (the co-tenant) and one
            //    refused open (the caller), nothing counted twice.
            assert_eq!(swap.forwarding.reserved_route_count().unwrap(), (0, 0));
            let counters = handler.counters().snapshot();
            assert_eq!(
                keyed_total(&counters, "route_open_accepted_by_principal"),
                1
            );
            assert_eq!(keyed_total(&counters, "route_open_refused_by_code"), 1);
            assert_eq!(counters["route_open_refused_by_code"]["module_rejected"], 1);
        }

        /// After cutover the incumbent is drained BY ENDPOINT. Draining by module
        /// id would resolve to the promoted candidate and every new route.open
        /// would be refused as reloading, leaving neither process routable.
        #[tokio::test]
        async fn route_open_after_cutover_and_incumbent_drain_is_relayed_to_the_candidate() {
            let mut swap = swap_with_incumbent().await;
            register_candidate(&swap, None);
            let incumbent = cutover(&swap);
            swap.forwarding
                .begin_endpoint_drain(incumbent, RouteCloseReason::Restart)
                .unwrap()
                .expect("the incumbent is still registered");

            let client = ConnectionId::new(33);
            let (client_ctx, mut client_rx) = route_ctx(client);
            let route_handler = swap.handler.clone();
            let open_ctx = RouteCtx {
                connection_id: client,
                egress: client_ctx.egress.clone(),
            };
            let mut route_task = tokio::spawn(async move {
                route_handler
                    .handle_control_frame(
                        &open_ctx,
                        route_open_frame(90, "aft", unique_project_root("swap-after-drain")),
                    )
                    .await
                    .unwrap()
            });
            let bind = tokio::select! {
                bind = swap.candidate_rx.recv() => bind.expect("candidate egress is open").frame,
                response = &mut route_task => {
                    let response = response.unwrap();
                    panic!(
                        "post-cutover route.open was refused instead of relayed to the candidate: {}",
                        parse_error(&response[0])["code"]
                    );
                }
            };
            swap.handler
                .handle_control_frame(&swap.candidate_ctx, route_bind_ack(bind.header.corr))
                .await
                .unwrap();
            assert!(route_task.await.unwrap().is_empty());
            let (channel, epoch) = published_route(&client_rx.recv().await.unwrap());
            match swap
                .forwarding
                .lookup_data_route(client, channel, epoch)
                .unwrap()
            {
                DataRoute::Client(DataRouteState::Bound(route)) => {
                    assert_eq!(route.module_endpoint.connection_id, CANDIDATE)
                }
                other => panic!("expected a bound route on the candidate, got {other:?}"),
            }
            assert!(swap.incumbent_rx.try_recv().is_err());
        }

        /// A candidate declares itself ready with `catalog.update` on its own
        /// connection. If the connection-keyed registry lookups searched only the
        /// active slot, this would answer `not_registered` and the candidate
        /// would never become ready.
        #[tokio::test]
        async fn candidate_catalog_update_ready_reaches_the_candidate_registration() {
            let swap = swap_with_incumbent().await;
            register_candidate(&swap, Some(false));
            let update = Frame::build(
                FrameType::Request,
                control_flags(),
                0,
                0,
                55,
                serde_json::to_vec(&ModuleControlRequestFromModule::CatalogUpdate {
                    provides: manifest("aft", PROTOCOL_VERSION).provides,
                    capabilities: None,
                    ready: Some(true),
                })
                .unwrap(),
            )
            .unwrap();

            let replies = swap
                .handler
                .handle_control_frame(&swap.candidate_ctx, update)
                .await
                .unwrap();

            assert_eq!(replies.len(), 1);
            assert_eq!(
                replies[0].header.ty,
                FrameType::Response,
                "candidate catalog.update was refused: {:?}",
                serde_json::from_slice::<Value>(&replies[0].body).ok()
            );
            assert!(swap.registry.get_candidate("aft").unwrap().unwrap().ready);
            assert_eq!(
                swap.registry
                    .get_module("aft")
                    .unwrap()
                    .unwrap()
                    .connection_id,
                INCUMBENT
            );
        }
    }

    /// The HELLO gate while the supervisor has a swap open: only the nonce it
    /// minted for the candidate admits a second process, into the candidate
    /// slot, and that check runs ahead of the reserved-module gate.
    mod swap_admission {
        use super::*;

        const INCUMBENT_NONCE: &str = "incumbent-nonce";
        const CANDIDATE_NONCE: &str = "candidate-nonce";

        fn handler_with_incumbent(
            module_id: &str,
            reserved: bool,
        ) -> (Arc<Registry>, SupervisorHandle, ControlHandler) {
            let registry = Arc::new(Registry::default());
            let supervisor = SupervisorHandle::new();
            supervisor.set_spawn_nonce(module_id, INCUMBENT_NONCE.to_string());
            if reserved {
                supervisor.set_reserved_nonce(module_id, INCUMBENT_NONCE.to_string());
            }
            let handler =
                ControlHandler::new(Arc::clone(&registry)).with_supervisor(supervisor.clone());
            let incumbent = handler
                .handle_control(
                    ConnectionId::new(1),
                    hello_frame_with_nonce(module_id, PROTOCOL_VERSION, 1, Some(INCUMBENT_NONCE)),
                )
                .unwrap();
            assert_eq!(incumbent[0].header.ty, FrameType::HelloAck);
            supervisor.open_swap(module_id, CANDIDATE_NONCE.to_string());
            (registry, supervisor, handler)
        }

        /// Design mutation arm (ii). On an UNRESERVED id the reserved gate
        /// admits every nonce, so while a swap is open the swap gate is the only
        /// thing between a key-holder and the candidate slot. A nonce the
        /// supervisor did not mint, or none at all, is refused, and neither the
        /// incumbent's registration nor the candidate slot moves.
        #[test]
        fn unminted_nonce_on_an_unreserved_id_with_an_open_swap_is_refused() {
            let (registry, _supervisor, handler) = handler_with_incumbent("aft", false);

            for (connection, nonce) in [(2, Some("forged")), (3, None)] {
                let replies = handler
                    .handle_control(
                        ConnectionId::new(connection),
                        hello_frame_with_nonce("aft", PROTOCOL_VERSION, connection, nonce),
                    )
                    .unwrap();
                assert_eq!(replies[0].header.ty, FrameType::Error);
                assert_eq!(
                    parse_error(&replies[0])["code"],
                    "swap_token_invalid",
                    "nonce {nonce:?}"
                );
            }
            assert!(registry.get_candidate("aft").unwrap().is_none());
            assert_eq!(
                registry.get_module("aft").unwrap().unwrap().connection_id,
                ConnectionId::new(1)
            );

            // Control: the minted token is admitted, into the candidate slot,
            // and only once.
            let admitted = handler
                .handle_control(
                    ConnectionId::new(4),
                    hello_frame_with_nonce("aft", PROTOCOL_VERSION, 4, Some(CANDIDATE_NONCE)),
                )
                .unwrap();
            assert_eq!(admitted[0].header.ty, FrameType::HelloAck);
            assert_eq!(
                registry
                    .get_candidate("aft")
                    .unwrap()
                    .unwrap()
                    .connection_id,
                ConnectionId::new(4)
            );
            assert_eq!(
                registry.get_module("aft").unwrap().unwrap().connection_id,
                ConnectionId::new(1),
                "the candidate must not take the active slot"
            );
            let replayed = handler
                .handle_control(
                    ConnectionId::new(5),
                    hello_frame_with_nonce("aft", PROTOCOL_VERSION, 5, Some(CANDIDATE_NONCE)),
                )
                .unwrap();
            assert_eq!(parse_error(&replayed[0])["code"], "swap_token_invalid");

            // The case only this gate covers: the incumbent has died mid-swap,
            // so its duplicate refusal is gone too, and without the gate a
            // key-holder would take the id's ACTIVE slot.
            handler.cleanup_connection(ConnectionId::new(1)).unwrap();
            let squatter = handler
                .handle_control(
                    ConnectionId::new(6),
                    hello_frame_with_nonce("aft", PROTOCOL_VERSION, 6, Some("forged")),
                )
                .unwrap();
            assert_eq!(parse_error(&squatter[0])["code"], "swap_token_invalid");
            assert!(
                registry.get_module("aft").unwrap().is_none(),
                "a squatter took the active slot of an id being swapped"
            );
        }

        /// Design mutation arm (iii). A reserved module's candidate presents a
        /// nonce the reserved gate has never seen (that gate holds the
        /// incumbent's), so the swap gate must run first or the candidate is
        /// refused `reserved_module` and a reserved module can never be swapped.
        #[test]
        fn reserved_module_candidate_is_admitted_ahead_of_the_reserved_gate() {
            let (registry, _supervisor, handler) = handler_with_incumbent("vault", true);

            let replies = handler
                .handle_control(
                    ConnectionId::new(2),
                    hello_frame_with_nonce("vault", PROTOCOL_VERSION, 2, Some(CANDIDATE_NONCE)),
                )
                .unwrap();

            assert_eq!(
                replies[0].header.ty,
                FrameType::HelloAck,
                "reserved candidate refused: {:?}",
                serde_json::from_slice::<Value>(&replies[0].body).ok()
            );
            assert_eq!(
                registry
                    .get_candidate("vault")
                    .unwrap()
                    .unwrap()
                    .connection_id,
                ConnectionId::new(2)
            );
        }

        /// With no swap open the gate is inert: the incumbent's reserved gate
        /// and duplicate refusal behave exactly as before.
        #[test]
        fn without_an_open_swap_the_ordinary_gates_decide() {
            let (registry, supervisor, handler) = handler_with_incumbent("vault", true);
            supervisor.close_swap("vault");

            let candidate = handler
                .handle_control(
                    ConnectionId::new(2),
                    hello_frame_with_nonce("vault", PROTOCOL_VERSION, 2, Some(CANDIDATE_NONCE)),
                )
                .unwrap();
            assert_eq!(parse_error(&candidate[0])["code"], "reserved_module");
            let duplicate = handler
                .handle_control(
                    ConnectionId::new(3),
                    hello_frame_with_nonce("vault", PROTOCOL_VERSION, 3, Some(INCUMBENT_NONCE)),
                )
                .unwrap();
            assert_eq!(parse_error(&duplicate[0])["code"], "duplicate_module_id");
            assert!(registry.get_candidate("vault").unwrap().is_none());
        }
    }

    /// `scope.sync` and `scope.describe` through the real control handler: who
    /// may sync is decided by the registration and launch nonce of the module
    /// connection, never by the request body.
    mod scopes {
        use subc_protocol::scope::{
            ParentState, ScopeCarrier, ScopeKind, ScopeParent, ScopeRecordOutcome, ScopeStamp,
            ScopeStatus,
        };

        use super::*;

        const OWNER: &str = "prefrontal-core";

        fn head(scope_ref: &str, scope_epoch: u64) -> ScopeRecord {
            ScopeRecord {
                scope_ref: scope_ref.to_string(),
                scope_epoch,
                kind: ScopeKind::Head,
                parent: None,
                child_owners: Vec::new(),
                carriers: Vec::new(),
                attributes: Default::default(),
            }
        }

        async fn call(
            handler: &ControlHandler,
            ctx: &RouteCtx,
            request: &ModuleControlRequestFromModule,
        ) -> Frame {
            let body = serde_json::to_vec(request).unwrap();
            let frame = Frame::build(FrameType::Request, control_flags(), 0, 0, 77, body).unwrap();
            let mut replies = handler.handle_control_frame(ctx, frame).await.unwrap();
            assert_eq!(replies.len(), 1, "{replies:?}");
            replies.pop().unwrap()
        }

        async fn sync(
            handler: &ControlHandler,
            ctx: &RouteCtx,
            generation: u64,
            scopes: Vec<ScopeRecord>,
        ) -> Result<ModuleControlResponseToModule, String> {
            let reply = call(
                handler,
                ctx,
                &ModuleControlRequestFromModule::ScopeSync { generation, scopes },
            )
            .await;
            match reply.header.ty {
                FrameType::Response => Ok(serde_json::from_slice(&reply.body).unwrap()),
                _ => Err(parse_error(&reply)["code"].as_str().unwrap().to_string()),
            }
        }

        async fn describe(
            handler: &ControlHandler,
            ctx: &RouteCtx,
            owner: &str,
            scope_ref: &str,
        ) -> ModuleControlResponseToModule {
            let reply = call(
                handler,
                ctx,
                &ModuleControlRequestFromModule::ScopeDescribe {
                    owner: Principal::Reserved {
                        module_id: owner.to_string(),
                    },
                    scope_ref: scope_ref.to_string(),
                },
            )
            .await;
            assert_eq!(
                reply.header.ty,
                FrameType::Response,
                "{:?}",
                parse_error(&reply)
            );
            serde_json::from_slice(&reply.body).unwrap()
        }

        /// Register `module_id` on `connection` with `nonce`, returning its ctx.
        async fn module(
            handler: &ControlHandler,
            connection: u64,
            module_id: &str,
            nonce: Option<&str>,
        ) -> (RouteCtx, mpsc::Receiver<crate::router::OutboundFrame>) {
            let (ctx, mut rx) = route_ctx(ConnectionId::new(connection));
            hello_via_sink(
                handler,
                &ctx,
                &mut rx,
                hello_frame_with_nonce(module_id, PROTOCOL_VERSION, connection, nonce),
            )
            .await;
            (ctx, rx)
        }

        /// `direct` and every other client connection has no registration, so
        /// it can neither sync nor own a scope.
        #[tokio::test]
        async fn a_client_connection_cannot_sync_or_describe() {
            let handler = ControlHandler::new(Arc::new(Registry::default()));
            let (ctx, _rx) = route_ctx(ConnectionId::new(9));
            for request in [
                ModuleControlRequestFromModule::ScopeSync {
                    generation: 1,
                    scopes: vec![head("s", 1)],
                },
                ModuleControlRequestFromModule::ScopeDescribe {
                    owner: Principal::Direct,
                    scope_ref: "s".to_string(),
                },
            ] {
                let reply = call(&handler, &ctx, &request).await;
                assert_eq!(parse_error(&reply)["code"], "not_registered", "{request:?}");
            }
            assert!(
                !handler
                    .scopes
                    .read()
                    .unwrap()
                    .describe(
                        &Principal::Reserved {
                            module_id: OWNER.to_string()
                        },
                        "s"
                    )
                    .owner_synced
            );
        }

        /// A module the supervisor did not spawn registers without a launch
        /// nonce, so it is never an owner's current launch.
        #[tokio::test]
        async fn a_module_without_a_supervised_launch_cannot_sync() {
            let handler = ControlHandler::new(Arc::new(Registry::default()));
            let (ctx, _rx) = module(&handler, 1, OWNER, None).await;
            assert_eq!(
                sync(&handler, &ctx, 1, vec![head("s", 1)]).await,
                Err(error_codes::SCOPE_SYNC_NOT_AUTHORITY.to_string())
            );
        }

        #[tokio::test]
        async fn sync_authority_follows_the_supervisors_recorded_spawn_nonce_across_a_swap() {
            let supervisor = SupervisorHandle::new();
            supervisor.set_spawn_nonce(OWNER, "n1".to_string());
            let handler = ControlHandler::new(Arc::new(Registry::default()))
                .with_supervisor(supervisor.clone());
            let (incumbent, _incumbent_rx) = module(&handler, 1, OWNER, Some("n1")).await;
            sync(&handler, &incumbent, 1, vec![head("s", 1)])
                .await
                .expect("the current launch syncs");

            // A swap candidate registers with the swap token and is refused
            // while the incumbent keeps syncing.
            supervisor.open_swap(OWNER, "n2".to_string());
            let (candidate, _candidate_rx) = module(&handler, 2, OWNER, Some("n2")).await;
            assert_eq!(
                sync(&handler, &candidate, 1, vec![head("x", 1)]).await,
                Err(error_codes::SCOPE_SYNC_NOT_AUTHORITY.to_string())
            );
            sync(&handler, &incumbent, 2, vec![head("s", 1)])
                .await
                .expect("the serving owner syncs during the swap");

            // The swap fails and is rolled back. The candidate never held sync
            // authority, and still cannot sync.
            supervisor.close_swap(OWNER);
            assert_eq!(
                sync(&handler, &candidate, 1, vec![head("x", 1)]).await,
                Err(error_codes::SCOPE_SYNC_NOT_AUTHORITY.to_string())
            );
            sync(&handler, &incumbent, 3, vec![head("s", 1)])
                .await
                .expect("the serving owner syncs after the rollback");
            handler.cleanup_connection(candidate.connection_id).unwrap();

            // A swap that cuts over. Promotion records the candidate's nonce as
            // the module's spawn nonce, which is what `set_spawn_nonce` does
            // here; the promoted connection then takes authority at any
            // generation and the superseded incumbent is refused.
            supervisor.open_swap(OWNER, "n3".to_string());
            let (promoted, _promoted_rx) = module(&handler, 3, OWNER, Some("n3")).await;
            supervisor.set_spawn_nonce(OWNER, "n3".to_string());
            let reply = sync(&handler, &promoted, 1, vec![head("s", 1)])
                .await
                .expect("the promoted launch takes authority");
            let ModuleControlResponseToModule::ScopeSync { results, .. } = reply else {
                panic!("unexpected reply {reply:?}");
            };
            assert_eq!(results[0].outcome, ScopeRecordOutcome::Unchanged);
            assert_eq!(
                sync(&handler, &incumbent, 4, Vec::new()).await,
                Err(error_codes::SCOPE_SYNC_NOT_AUTHORITY.to_string())
            );
        }

        /// Authority dies with its connection: the cleanup path releases it,
        /// so the owner's next connection takes it at any generation.
        #[tokio::test]
        async fn closing_the_authority_connection_frees_sync_authority() {
            let supervisor = SupervisorHandle::new();
            supervisor.set_spawn_nonce(OWNER, "n1".to_string());
            let handler = ControlHandler::new(Arc::new(Registry::default()))
                .with_supervisor(supervisor.clone());
            let (first, _first_rx) = module(&handler, 1, OWNER, Some("n1")).await;
            sync(&handler, &first, 10, vec![head("s", 1)])
                .await
                .unwrap();
            handler.cleanup_connection(first.connection_id).unwrap();

            let (second, _second_rx) = module(&handler, 2, OWNER, Some("n1")).await;
            sync(&handler, &second, 1, vec![head("s", 1)])
                .await
                .expect("the next connection takes the released authority");
        }

        #[tokio::test]
        async fn module_goodbye_releases_scope_sync_authority_without_socket_close() {
            let supervisor = SupervisorHandle::new();
            supervisor.set_spawn_nonce(OWNER, "n1".to_string());
            let handler =
                ControlHandler::new(Arc::new(Registry::default())).with_supervisor(supervisor);
            let (first, _rx) = module(&handler, 1, OWNER, Some("n1")).await;
            sync(&handler, &first, 10, vec![head("s", 1)])
                .await
                .unwrap();
            handler
                .handle_control_frame(
                    &first,
                    Frame::build(FrameType::Goodbye, control_flags(), 0, 0, 4, Vec::new()).unwrap(),
                )
                .await
                .unwrap();
            let (second, _rx) = module(&handler, 2, OWNER, Some("n1")).await;
            sync(&handler, &second, 1, vec![head("s", 1)])
                .await
                .expect("GOODBYE releases authority even if the old socket remains open");
        }

        #[tokio::test]
        async fn describe_reports_the_incarnation_and_whether_the_owner_is_configured() {
            let registry = Arc::new(Registry::default());
            let supervisor_handle = SupervisorHandle::new();
            let supervisor = Supervisor::new(Arc::clone(&registry), RestartPolicy::default())
                .with_handle(supervisor_handle.clone())
                .with_daemon_incarnation("incarnation-7".to_string());
            // Configured with enabled: false, so the supervisor lists the
            // module without spawning a process for it.
            supervisor
                .supervise_configured(
                    ModuleSpec {
                        module_id: OWNER.to_string(),
                        program: PathBuf::from("/nonexistent/prefrontal-core"),
                        args: Vec::new(),
                        env: Vec::new(),
                        reserved: false,
                        reserved_prefixes: Vec::new(),
                        protocol: ModuleProtocol::Subc,
                        overlap: Default::default(),
                    },
                    false,
                )
                .unwrap();
            supervisor_handle.set_spawn_nonce(OWNER, "n1".to_string());
            let handler =
                ControlHandler::new(Arc::clone(&registry)).with_supervisor(supervisor_handle);
            let (reader, _reader_rx) = module(&handler, 5, "reader", None).await;

            // Configured but not yet synced: a reader waits for the owner.
            let ModuleControlResponseToModule::ScopeDescribe {
                status,
                daemon_incarnation,
                owner_synced,
                owner_configured,
                scope,
                ..
            } = describe(&handler, &reader, OWNER, "s").await
            else {
                panic!("not a describe reply");
            };
            assert_eq!(status, ScopeStatus::NotLive);
            assert_eq!(daemon_incarnation, "incarnation-7");
            assert!(!owner_synced);
            assert!(owner_configured);
            assert!(scope.is_none());

            // Not a supervised module: the owner will never sync, and a reader
            // refuses rather than waits.
            let ModuleControlResponseToModule::ScopeDescribe {
                status,
                owner_configured,
                ..
            } = describe(&handler, &reader, "ghost", "s").await
            else {
                panic!("not a describe reply");
            };
            assert_eq!(status, ScopeStatus::NotLive);
            assert!(!owner_configured);

            // Live, with the stamp fields and the computed owner_authorized.
            let (owner, _owner_rx) = module(&handler, 6, OWNER, Some("n1")).await;
            sync(&handler, &owner, 1, vec![head("s", 4)]).await.unwrap();
            let ModuleControlResponseToModule::ScopeDescribe {
                status,
                scope_epoch,
                owner_synced,
                scope,
                ..
            } = describe(&handler, &reader, OWNER, "s").await
            else {
                panic!("not a describe reply");
            };
            assert_eq!(status, ScopeStatus::Live);
            assert_eq!(scope_epoch, Some(4));
            assert!(owner_synced);
            let stamp = scope.expect("a live scope carries its stamp");
            assert!(
                stamp.owner_authorized,
                "prefrontal-core is the default authority"
            );
            assert_eq!(stamp.kind, ScopeKind::Head);
        }

        #[tokio::test]
        async fn scope_authority_owners_decides_owner_authorized() {
            let supervisor = SupervisorHandle::new();
            supervisor.set_spawn_nonce("broca", "b1".to_string());
            let handler = ControlHandler::new(Arc::new(Registry::default()))
                .with_supervisor(supervisor)
                .with_scope_authority_owners(vec!["broca".to_string()]);
            let (broca, _rx) = module(&handler, 1, "broca", Some("b1")).await;
            let mut gated = head("s", 1);
            gated.attributes.agent_id = Some("agent".to_string());
            sync(&handler, &broca, 1, vec![gated]).await.unwrap();
            let ModuleControlResponseToModule::ScopeDescribe { scope, .. } =
                describe(&handler, &broca, "broca", "s").await
            else {
                panic!("not a describe reply");
            };
            assert!(scope.unwrap().owner_authorized);
        }

        /// With route admission, the stamp, the commit re-check and drains in
        /// place, the feature is advertised: the module ops in HELLO_ACK, and
        /// `scopes/v1` in HELLO_ACK and `server.describe`.
        #[tokio::test]
        async fn scope_ops_and_the_scopes_capability_are_advertised() {
            let handler = ControlHandler::new(Arc::new(Registry::default()));
            let (ctx, mut rx) = route_ctx(ConnectionId::new(1));
            let ack = hello_via_sink(
                &handler,
                &ctx,
                &mut rx,
                hello_frame("m", PROTOCOL_VERSION, 1),
            )
            .await;
            let ack = parse_ack(&ack);
            for op in [SCOPE_SYNC_OP, SCOPE_DESCRIBE_OP] {
                assert!(ack.subc_ops.iter().any(|o| o == op), "{:?}", ack.subc_ops);
            }
            assert!(ack.subc_capabilities.iter().any(|c| c == CAP_SCOPES_V1));

            let (client, _client_rx) = route_ctx(ConnectionId::new(2));
            let body = serde_json::to_vec(&ClientControlRequest::ServerDescribe {}).unwrap();
            let frame = Frame::build(FrameType::Request, control_flags(), 0, 0, 5, body).unwrap();
            let reply = handler
                .handle_control_frame(&client, frame)
                .await
                .unwrap()
                .pop()
                .unwrap();
            let ClientControlResponse::ServerDescribe { capabilities, .. } =
                serde_json::from_slice(&reply.body).unwrap()
            else {
                panic!("not a server.describe reply");
            };
            assert!(
                capabilities.iter().any(|c| c == CAP_SCOPES_V1),
                "{capabilities:?}"
            );
        }

        // ---- route admission, stamps, commit re-check and drains ----------

        const PLEXUS: &str = "plexus";
        const OTHER: &str = "other";
        const AFT: &str = "aft";
        const BROCA: &str = "broca";
        const MAGIC: &str = "magic-context";

        fn nonce(module_id: &str) -> String {
            format!("nonce-{module_id}")
        }

        fn wide_ctx(connection: u64) -> (RouteCtx, mpsc::Receiver<crate::router::OutboundFrame>) {
            let (tx, rx) = mpsc::channel(64);
            (
                RouteCtx {
                    connection_id: ConnectionId::new(connection),
                    egress: FrameSink::new(tx),
                },
                rx,
            )
        }

        /// A daemon with a configured owner (prefrontal-core) registered on its
        /// own module connection, two routable targets (plexus, other), and
        /// launch nonces minted for the modules that open routes as carriers.
        struct Rig {
            handler: ControlHandler,
            forwarding: Arc<ForwardingTable>,
            owner: RouteCtx,
            _owner_rx: mpsc::Receiver<crate::router::OutboundFrame>,
            modules: BTreeMap<String, (RouteCtx, mpsc::Receiver<crate::router::OutboundFrame>)>,
            generation: u64,
            next_connection: u64,
            _supervisor: Supervisor,
        }

        async fn rig() -> Rig {
            rig_with_flow_support(true).await
        }

        async fn rig_with_flow_support(flow_support: bool) -> Rig {
            let registry = Arc::new(Registry::default());
            let forwarding = Arc::new(ForwardingTable::default());
            let supervisor_handle = SupervisorHandle::new();
            let supervisor = Supervisor::new(Arc::clone(&registry), RestartPolicy::default())
                .with_handle(supervisor_handle.clone());
            supervisor
                .supervise_configured(
                    ModuleSpec {
                        module_id: OWNER.to_string(),
                        program: PathBuf::from("/nonexistent/prefrontal-core"),
                        args: Vec::new(),
                        env: Vec::new(),
                        reserved: false,
                        reserved_prefixes: Vec::new(),
                        protocol: ModuleProtocol::Subc,
                        overlap: Default::default(),
                    },
                    false,
                )
                .unwrap();
            for module_id in [OWNER, AFT, BROCA, MAGIC] {
                supervisor_handle.set_spawn_nonce(module_id, nonce(module_id));
            }
            let handler =
                ControlHandler::with_forwarding(Arc::clone(&registry), Arc::clone(&forwarding))
                    .with_supervisor(supervisor_handle);
            let (owner, mut owner_rx) = wide_ctx(1);
            hello_via_sink(
                &handler,
                &owner,
                &mut owner_rx,
                hello_frame_with_nonce(OWNER, PROTOCOL_VERSION, 1, Some(&nonce(OWNER))),
            )
            .await;
            let mut modules = BTreeMap::new();
            for (connection, module_id) in [(2, PLEXUS), (3, OTHER)] {
                let (ctx, mut rx) = wide_ctx(connection);
                let hello = hello_frame(module_id, PROTOCOL_VERSION, connection);
                let mut body: Value = serde_json::from_slice(&hello.body).unwrap();
                // A decoder version alone must not admit flow routes. Every
                // target here declares wire crate version 0.29.0; only one that
                // declares `flow-scopes/v1` promises flow behaviour.
                body["manifest"]["provenance"] =
                    serde_json::json!({"wire_crate_version": "0.29.0"});
                if flow_support {
                    body["manifest"]["capabilities"] =
                        serde_json::json!({"provides": ["flow-scopes/v1"]});
                }
                let hello = Frame::build(
                    FrameType::Hello,
                    control_flags(),
                    0,
                    0,
                    connection,
                    serde_json::to_vec(&body).unwrap(),
                )
                .unwrap();
                hello_via_sink(&handler, &ctx, &mut rx, hello).await;
                modules.insert(module_id.to_string(), (ctx, rx));
            }
            Rig {
                handler,
                forwarding,
                owner,
                _owner_rx: owner_rx,
                modules,
                generation: 0,
                next_connection: 100,
                _supervisor: supervisor,
            }
        }

        fn carrier(module_id: &str, targets: Option<&[&str]>) -> ScopeCarrier {
            ScopeCarrier {
                principal: Principal::Reserved {
                    module_id: module_id.to_string(),
                },
                targets: targets.map(|targets| targets.iter().map(|t| t.to_string()).collect()),
            }
        }

        /// The scope most tests open under: aft carries to any module, broca
        /// only to plexus and other, and the owner delegates as agent-1.
        fn session(scope_epoch: u64) -> ScopeRecord {
            let mut record = head("s", scope_epoch);
            record.carriers = vec![carrier(AFT, None), carrier(BROCA, Some(&[PLEXUS, OTHER]))];
            record.attributes.agent_id = Some("agent-1".to_string());
            record.attributes.delegates = true;
            record
        }

        impl Rig {
            async fn sync(&mut self, scopes: Vec<ScopeRecord>) {
                self.generation += 1;
                sync(&self.handler, &self.owner, self.generation, scopes)
                    .await
                    .expect("the owner's sync is accepted");
            }

            fn selector(&self, scope_ref: &str, scope_epoch: Option<u64>) -> ScopeSelector {
                ScopeSelector {
                    owner: Principal::Reserved {
                        module_id: OWNER.to_string(),
                    },
                    scope_ref: scope_ref.to_string(),
                    scope_epoch,
                }
            }

            fn open_frame(
                &mut self,
                opener: Option<&str>,
                target: &str,
                scope: Option<ScopeSelector>,
            ) -> (
                RouteCtx,
                mpsc::Receiver<crate::router::OutboundFrame>,
                Frame,
            ) {
                self.next_connection += 1;
                let (ctx, rx) = wide_ctx(self.next_connection);
                let root = unique_project_root("scoped-open");
                let body = serde_json::to_vec(&ClientControlRequest::RouteOpen {
                    target: RouteTarget::ToolProvider {
                        module_id: target.to_string(),
                    },
                    identity: BindIdentity::new(
                        root.path().to_path_buf(),
                        "unit".to_string(),
                        "session".to_string(),
                    ),
                    consumer_identity: opener.map(|module_id| ConsumerIdentity {
                        module_id: module_id.to_string(),
                        launch_nonce: nonce(module_id),
                    }),
                    consumer_capabilities: None,
                    role_versions: None,
                    admission_facts: None,
                    scope,
                })
                .unwrap();
                let frame = Frame::build(
                    FrameType::Request,
                    control_flags(),
                    0,
                    0,
                    self.next_connection,
                    body,
                )
                .unwrap();
                (ctx, rx, frame)
            }

            /// Open and expect a refusal before anything is relayed.
            async fn refused(
                &mut self,
                opener: Option<&str>,
                target: &str,
                scope: Option<ScopeSelector>,
            ) -> String {
                self.refusal_body(opener, target, scope).await["code"]
                    .as_str()
                    .unwrap()
                    .to_string()
            }

            async fn refusal_body(
                &mut self,
                opener: Option<&str>,
                target: &str,
                scope: Option<ScopeSelector>,
            ) -> Value {
                let (ctx, _rx, frame) = self.open_frame(opener, target, scope);
                let replies = tokio::time::timeout(
                    Duration::from_secs(2),
                    self.handler.handle_control_frame(&ctx, frame),
                )
                .await
                .expect("the open must be refused before waiting for a bind ack")
                .unwrap();
                assert_eq!(replies.len(), 1, "{replies:?}");
                assert_eq!(replies[0].header.ty, FrameType::Error);
                let (_, module_rx) = self.modules.get_mut(target).unwrap();
                assert!(
                    module_rx.try_recv().is_err(),
                    "a refused open relays nothing"
                );
                assert_eq!(self.forwarding.reserved_route_count().unwrap(), (0, 0));
                parse_error(&replies[0])
            }

            /// Start an open and return its task and the bind the target got.
            async fn relayed(
                &mut self,
                opener: Option<&str>,
                target: &str,
                scope: Option<ScopeSelector>,
            ) -> Relayed {
                let (ctx, rx, frame) = self.open_frame(opener, target, scope);
                let handler = self.handler.clone();
                let task_ctx = ctx.clone();
                let task = tokio::spawn(async move {
                    handler
                        .handle_control_frame(&task_ctx, frame)
                        .await
                        .unwrap()
                });
                let (_, module_rx) = self.modules.get_mut(target).unwrap();
                let bind = tokio::time::timeout(Duration::from_secs(2), module_rx.recv())
                    .await
                    .expect("the target receives the relayed route.bind")
                    .unwrap()
                    .frame;
                Relayed {
                    target: target.to_string(),
                    client: ctx,
                    client_rx: rx,
                    task,
                    bind,
                }
            }

            async fn ack(&self, relayed: &Relayed) {
                let (module, _) = &self.modules[&relayed.target];
                self.handler
                    .handle_control_frame(module, route_bind_ack(relayed.bind.header.corr))
                    .await
                    .unwrap();
            }

            /// Open, ack and return the bound route.
            async fn bound(
                &mut self,
                opener: Option<&str>,
                target: &str,
                scope: Option<ScopeSelector>,
            ) -> Bound {
                let relayed = self.relayed(opener, target, scope).await;
                self.ack(&relayed).await;
                let Relayed {
                    target,
                    client,
                    mut client_rx,
                    task,
                    bind,
                } = relayed;
                assert!(
                    task.await.unwrap().is_empty(),
                    "the open is answered by commit"
                );
                let (channel, epoch) = published_route(&client_rx.recv().await.unwrap().frame);
                Bound {
                    target,
                    client,
                    client_rx,
                    channel,
                    epoch,
                    bind,
                }
            }

            fn live(&self, route: &Bound) -> bool {
                matches!(
                    self.forwarding
                        .lookup_data_route(route.client.connection_id, route.channel, route.epoch)
                        .unwrap(),
                    DataRoute::Client(DataRouteState::Bound(_))
                )
            }
        }

        struct Relayed {
            target: String,
            client: RouteCtx,
            client_rx: mpsc::Receiver<crate::router::OutboundFrame>,
            task: tokio::task::JoinHandle<Vec<Frame>>,
            bind: Frame,
        }

        struct Bound {
            target: String,
            client: RouteCtx,
            client_rx: mpsc::Receiver<crate::router::OutboundFrame>,
            channel: u16,
            epoch: u32,
            bind: Frame,
        }

        impl Bound {
            /// The reason of the `route.closed` this client was sent, after
            /// checking it also got a GOODBYE on exactly this route.
            fn closed_reason(&mut self) -> RouteCloseReason {
                let mut reason = None;
                let mut goodbye = false;
                while let Ok(outbound) = self.client_rx.try_recv() {
                    let frame = outbound.frame;
                    match frame.header.ty {
                        FrameType::Goodbye => {
                            assert_eq!(
                                (frame.header.channel, frame.header.epoch),
                                (self.channel, self.epoch)
                            );
                            goodbye = true;
                        }
                        FrameType::Push => {
                            let ClientControlPush::RouteClosed {
                                reason: r,
                                module_id,
                                ..
                            } = serde_json::from_slice(&frame.body).unwrap()
                            else {
                                panic!("unexpected push");
                            };
                            assert_eq!(module_id, self.target);
                            reason = Some(r);
                        }
                        other => panic!("unexpected frame {other:?}"),
                    }
                }
                assert!(goodbye, "the client is sent a GOODBYE for the closed route");
                reason.expect("the client is told why the route closed")
            }

            fn untouched(&mut self) -> bool {
                self.client_rx.try_recv().is_err()
            }

            fn stamp(&self) -> Option<ScopeStamp> {
                match serde_json::from_slice::<ModuleControlRequest>(&self.bind.body).unwrap() {
                    ModuleControlRequest::RouteBind { scope, .. } => scope,
                    other => panic!("expected a route.bind, got {other:?}"),
                }
            }
        }

        #[tokio::test]
        async fn only_the_owner_or_a_listed_carrier_is_admitted_and_a_targeted_carrier_only_to_its_modules(
        ) {
            let mut rig = rig().await;
            let mut record = session(1);
            record.carriers = vec![carrier(AFT, None), carrier(BROCA, Some(&[PLEXUS]))];
            record.child_owners = vec![Principal::Reserved {
                module_id: MAGIC.to_string(),
            }];
            rig.sync(vec![record]).await;
            let scope = || Some(rig_selector("s", Some(1)));

            // Admitted: the owner, a bare carrier to any module, a targeted
            // carrier to its listed module.
            rig.bound(Some(OWNER), PLEXUS, scope()).await;
            rig.bound(Some(AFT), OTHER, scope()).await;
            rig.bound(Some(BROCA), PLEXUS, scope()).await;

            // Refused scope_not_carrier: a targeted carrier to an unlisted
            // module, a module that is not listed at all (a child owner is not
            // a carrier), and a direct key-holder.
            for (opener, target) in [(Some(BROCA), OTHER), (Some(MAGIC), PLEXUS), (None, PLEXUS)] {
                assert_eq!(
                    rig.refused(opener, target, scope()).await,
                    error_codes::SCOPE_NOT_CARRIER,
                    "{opener:?} -> {target}"
                );
            }
        }

        fn rig_selector(scope_ref: &str, scope_epoch: Option<u64>) -> ScopeSelector {
            ScopeSelector {
                owner: Principal::Reserved {
                    module_id: OWNER.to_string(),
                },
                scope_ref: scope_ref.to_string(),
                scope_epoch,
            }
        }

        #[tokio::test]
        async fn an_open_without_an_epoch_is_refused_the_owners_included() {
            let mut rig = rig().await;
            rig.sync(vec![session(1)]).await;
            for opener in [OWNER, AFT] {
                assert_eq!(
                    rig.refused(Some(opener), PLEXUS, Some(rig.selector("s", None)))
                        .await,
                    error_codes::SCOPE_EPOCH_REQUIRED,
                    "{opener}"
                );
            }
        }

        #[tokio::test]
        async fn admission_separates_not_synced_not_live_and_ended() {
            let mut rig = rig().await;
            // Before the configured owner's first sync: retryable.
            let code = rig
                .refused(Some(AFT), PLEXUS, Some(rig_selector("s", Some(1))))
                .await;
            assert_eq!(code, error_codes::SCOPE_NOT_SYNCED);
            assert!(subc_protocol::error_codes::is_retryable_route_open(&code));

            // An owner that is not configured will never sync: terminal.
            let ghost = ScopeSelector {
                owner: Principal::Reserved {
                    module_id: "ghost".to_string(),
                },
                scope_ref: "s".to_string(),
                scope_epoch: Some(1),
            };
            assert_eq!(
                rig.refused(Some(AFT), PLEXUS, Some(ghost)).await,
                error_codes::SCOPE_NOT_LIVE
            );

            rig.sync(vec![session(2)]).await;
            assert_eq!(
                rig.refused(Some(AFT), PLEXUS, Some(rig_selector("missing", Some(1))))
                    .await,
                error_codes::SCOPE_NOT_LIVE
            );
            for epoch in [1, 3] {
                assert_eq!(
                    rig.refused(Some(AFT), PLEXUS, Some(rig_selector("s", Some(epoch))))
                        .await,
                    error_codes::SCOPE_ENDED,
                    "epoch {epoch}"
                );
            }
            // Control: the live epoch is admitted.
            rig.bound(Some(AFT), PLEXUS, Some(rig_selector("s", Some(2))))
                .await;
        }

        #[tokio::test]
        async fn the_bind_is_stamped_and_owner_authorized_only_for_listed_owners() {
            let mut rig = rig().await;
            rig.sync(vec![session(1)]).await;
            let route = rig
                .bound(Some(AFT), PLEXUS, Some(rig_selector("s", Some(1))))
                .await;
            let stamp = route.stamp().expect("a scoped bind carries the stamp");
            assert_eq!(stamp.scope_ref, "s");
            assert_eq!(stamp.scope_epoch, 1);
            assert_eq!(stamp.kind, ScopeKind::Head);
            assert_eq!(stamp.attributes.agent_id.as_deref(), Some("agent-1"));
            assert!(stamp.attributes.delegates);
            assert!(stamp.owner_authorized);
            let unscoped = rig.bound(Some(AFT), PLEXUS, None).await;
            assert_eq!(unscoped.stamp(), None, "an unscoped open is not stamped");

            // broca owns a scope of its own on its own module connection; it is
            // not in scope_authority_owners, so its stamp is not authorized.
            let (broca, mut broca_rx) = wide_ctx(50);
            hello_via_sink(
                &rig.handler,
                &broca,
                &mut broca_rx,
                hello_frame_with_nonce(BROCA, PROTOCOL_VERSION, 50, Some(&nonce(BROCA))),
            )
            .await;
            sync(&rig.handler, &broca, 1, vec![head("b", 1)])
                .await
                .unwrap();
            let own = ScopeSelector {
                owner: Principal::Reserved {
                    module_id: BROCA.to_string(),
                },
                scope_ref: "b".to_string(),
                scope_epoch: Some(1),
            };
            let route = rig.bound(Some(BROCA), PLEXUS, Some(own)).await;
            assert!(!route.stamp().unwrap().owner_authorized);
        }

        #[tokio::test]
        async fn an_authority_owners_flow_id_without_an_agent_is_stamped_verbatim_on_bind() {
            let mut rig = rig().await;
            let mut record = head("s", 1);
            record.carriers = vec![carrier(AFT, None)];
            let flow_id = "Flow:run-7/step_2!~";
            record.attributes.flow_id = Some(flow_id.to_string());
            let reply = sync(&rig.handler, &rig.owner, 1, vec![record])
                .await
                .unwrap();
            let ModuleControlResponseToModule::ScopeSync { results, .. } = reply else {
                panic!("not a sync reply");
            };
            assert_eq!(results[0].outcome, ScopeRecordOutcome::Created);
            let route = rig
                .bound(Some(AFT), PLEXUS, Some(rig_selector("s", Some(1))))
                .await;
            assert!(rig.live(&route), "the stamped bind committed");
            let stamp = route.stamp().expect("a flow scope carries a stamp");
            assert_eq!(stamp.attributes.flow_id.as_deref(), Some(flow_id));
            assert_eq!(stamp.attributes.agent_id, None);
            assert!(!stamp.attributes.delegates);
            assert!(stamp.owner_authorized);
            let unscoped = rig.bound(Some(AFT), PLEXUS, None).await;
            assert_eq!(unscoped.stamp(), None);
        }

        #[tokio::test]
        async fn flow_scope_refuses_a_0_29_target_without_flow_capability_and_relays_nothing() {
            let mut rig = rig_with_flow_support(false).await;
            let mut record = session(1);
            record.attributes.flow_id = Some("flow:7".to_string());
            rig.sync(vec![record]).await;
            for opener in [OWNER, AFT] {
                let body = rig
                    .refusal_body(Some(opener), PLEXUS, Some(rig_selector("s", Some(1))))
                    .await;
                assert_eq!(body["code"], "target_flow_unsupported");
                let message = body["message"].as_str().unwrap();
                for required in [PLEXUS, "flow-scopes/v1"] {
                    assert!(message.contains(required), "{message}");
                }
            }
        }

        #[tokio::test]
        async fn flow_scope_admits_a_capable_target_and_preserves_flow_id_on_bind() {
            let mut rig = rig_with_flow_support(true).await;
            let mut record = session(1);
            record.attributes.flow_id = Some("flow:7".to_string());
            rig.sync(vec![record]).await;
            for opener in [OWNER, AFT] {
                let route = rig
                    .bound(Some(opener), PLEXUS, Some(rig_selector("s", Some(1))))
                    .await;
                assert!(rig.live(&route));
                assert_eq!(
                    route.stamp().unwrap().attributes.flow_id.as_deref(),
                    Some("flow:7")
                );
            }
        }

        #[tokio::test]
        async fn flow_scope_rechecks_the_relay_target_after_a_reconnect() {
            use std::future::Future;

            let mut rig = rig_with_flow_support(true).await;
            let mut record = session(1);
            record.attributes.flow_id = Some("flow:7".to_string());
            rig.sync(vec![record]).await;
            let (client, mut client_rx, frame) =
                rig.open_frame(Some(AFT), PLEXUS, Some(rig_selector("s", Some(1))));
            // Hold the route-open response permit so admission sees the first
            // target but relay reservation cannot capture an endpoint yet.
            for _ in 0..64 {
                client.egress.try_send(route_bind_ack(1)).unwrap();
            }
            let handler = rig.handler.clone();
            let mut open = Box::pin(handler.handle_control_frame(&client, frame));
            std::future::poll_fn(|cx| {
                assert!(open.as_mut().poll(cx).is_pending());
                std::task::Poll::Ready(())
            })
            .await;
            assert_eq!(rig.forwarding.reserved_route_count().unwrap(), (0, 0));

            let old_connection = rig.modules[PLEXUS].0.connection_id;
            rig.handler.cleanup_connection(old_connection).unwrap();
            let (replacement, mut replacement_rx) = wide_ctx(200);
            let hello = hello_frame(PLEXUS, PROTOCOL_VERSION, 200);
            let mut body: Value = serde_json::from_slice(&hello.body).unwrap();
            body["manifest"]["provenance"] = serde_json::json!({"wire_crate_version": "0.29.0"});
            let hello = Frame::build(
                FrameType::Hello,
                control_flags(),
                0,
                0,
                200,
                serde_json::to_vec(&body).unwrap(),
            )
            .unwrap();
            hello_via_sink(&rig.handler, &replacement, &mut replacement_rx, hello).await;

            client_rx.try_recv().unwrap();
            let replies = tokio::time::timeout(Duration::from_secs(2), open)
                .await
                .expect("the replacement is refused without waiting for a bind ack")
                .unwrap();
            assert_eq!(replies.len(), 1);
            let body = parse_error(&replies[0]);
            assert_eq!(body["code"], "target_flow_unsupported");
            for required in [PLEXUS, "flow-scopes/v1"] {
                assert!(body["message"].as_str().unwrap().contains(required));
            }
            assert!(replacement_rx.try_recv().is_err(), "no bind is relayed");
            assert!(rig.modules.get_mut(PLEXUS).unwrap().1.try_recv().is_err());
            assert_eq!(rig.forwarding.reserved_route_count().unwrap(), (0, 0));
            assert!(rig
                .handler
                .registry
                .get_module_by_connection(replacement.connection_id)
                .unwrap()
                .is_some());
        }

        #[tokio::test]
        async fn scope_without_flow_id_and_unscoped_routes_admit_a_target_without_flow_capability()
        {
            let mut rig = rig_with_flow_support(false).await;
            rig.sync(vec![session(1)]).await;
            let route = rig
                .bound(Some(AFT), PLEXUS, Some(rig_selector("s", Some(1))))
                .await;
            assert!(rig.live(&route));
            assert_eq!(route.stamp().unwrap().attributes.flow_id, None);
            let mut record = session(1);
            record.attributes.flow_id = Some("flow:7".to_string());
            rig.sync(vec![record]).await;
            let unscoped = rig.bound(Some(AFT), OTHER, None).await;
            assert!(rig.live(&unscoped));
            assert_eq!(unscoped.stamp(), None);
        }

        #[tokio::test]
        async fn a_same_epoch_flow_id_change_bumps_version_and_drains_all_scoped_routes() {
            let mut rig = rig().await;
            let mut record = session(1);
            record.attributes.flow_id = Some("flow:7".to_string());
            rig.sync(vec![record.clone()]).await;
            let before = rig.forwarding.published_scope_tag(OWNER, "s");
            let mut owner_route = rig
                .bound(Some(OWNER), PLEXUS, Some(rig_selector("s", Some(1))))
                .await;
            let mut carrier_route = rig
                .bound(Some(AFT), OTHER, Some(rig_selector("s", Some(1))))
                .await;
            let mut unscoped = rig.bound(Some(AFT), PLEXUS, None).await;
            rig.sync(vec![record.clone()]).await;
            assert_eq!(rig.forwarding.published_scope_tag(OWNER, "s"), before);
            assert!(rig.live(&owner_route) && owner_route.untouched());
            assert!(rig.live(&carrier_route) && carrier_route.untouched());

            record.attributes.flow_id = Some("flow:8".to_string());
            rig.sync(vec![record]).await;
            let after = rig.forwarding.published_scope_tag(OWNER, "s").unwrap();
            let before = before.unwrap();
            assert_eq!(after.scope_epoch, before.scope_epoch);
            assert!(after.version > before.version);
            for route in [&mut owner_route, &mut carrier_route] {
                assert!(!rig.live(route));
                assert_eq!(
                    route.closed_reason(),
                    RouteCloseReason::ScopeDelegationChanged
                );
            }
            assert!(rig.live(&unscoped) && unscoped.untouched());
            // Each provider also receives a GOODBYE for its drained route;
            // consume it before expecting the next route.bind on that sink.
            for target in [PLEXUS, OTHER] {
                let (_, module_rx) = rig.modules.get_mut(target).unwrap();
                let goodbye = module_rx
                    .try_recv()
                    .expect("the provider sees the drain")
                    .frame;
                assert_eq!(goodbye.header.ty, FrameType::Goodbye);
                assert!(module_rx.try_recv().is_err());
            }
            let rebound = rig
                .bound(Some(AFT), PLEXUS, Some(rig_selector("s", Some(1))))
                .await;
            assert_eq!(
                rebound.stamp().unwrap().attributes.flow_id.as_deref(),
                Some("flow:8")
            );
        }

        /// The owner's sync lands between admission and the module's ack. The
        /// open is refused by name, the module's other routes stay up, and the
        /// reserved pair is released. Changed content is retryable; an ended
        /// scope is not.
        #[tokio::test]
        async fn a_scope_changed_or_ended_between_admission_and_commit_refuses_the_open() {
            let mut rig = rig().await;
            rig.sync(vec![session(1)]).await;
            let mut cotenant = rig
                .bound(Some(OWNER), PLEXUS, Some(rig_selector("s", Some(1))))
                .await;

            let mut changed = session(1);
            changed.child_owners.push(Principal::Reserved {
                module_id: MAGIC.to_string(),
            });
            let mut ended = None;
            for (code, next) in [
                (error_codes::SCOPE_CHANGED, vec![changed]),
                (error_codes::SCOPE_ENDED, Vec::new()),
            ] {
                let relayed = rig
                    .relayed(Some(AFT), PLEXUS, Some(rig_selector("s", Some(1))))
                    .await;
                let (bind_channel, bind_epoch) = route_bind_channel(&relayed.bind);
                ended = Some(next.is_empty());
                rig.sync(next).await;
                rig.ack(&relayed).await;
                let replies = relayed.task.await.unwrap();
                assert_eq!(replies.len(), 1, "{replies:?}");
                assert_eq!(parse_error(&replies[0])["code"], code);
                assert_eq!(
                    subc_protocol::error_codes::is_retryable_route_open(code),
                    code == error_codes::SCOPE_CHANGED
                );
                assert_eq!(rig.forwarding.reserved_route_count().unwrap(), (0, 0));
                // The module is told to drop just the binding it created.
                let (_, plexus_rx) = rig.modules.get_mut(PLEXUS).unwrap();
                // Collected, because ending the scope also closes the co-tenant
                // route, whose GOODBYE comes first.
                let mut goodbyes = Vec::new();
                while let Ok(outbound) = plexus_rx.try_recv() {
                    assert_eq!(outbound.frame.header.ty, FrameType::Goodbye);
                    goodbyes.push((outbound.frame.header.channel, outbound.frame.header.epoch));
                }
                assert!(
                    goodbyes.contains(&(bind_channel, bind_epoch)),
                    "{goodbyes:?}"
                );
                assert!(rig
                    .handler
                    .registry
                    .get_module_by_connection(rig.modules[PLEXUS].0.connection_id)
                    .unwrap()
                    .is_some());
            }
            assert_eq!(ended, Some(true));
            // The co-tenant stayed up through the change, and closed only when
            // the scope ended, by the drain rule rather than by the commit.
            assert_eq!(cotenant.closed_reason(), RouteCloseReason::ScopeEnded);
        }

        /// Each row of the drain table on one set of routes: the owner's, a
        /// bare carrier's, and a targeted carrier's to each of its targets.
        #[tokio::test]
        async fn each_revocation_drains_exactly_the_affected_routes_with_its_own_reason() {
            struct Case {
                name: &'static str,
                change: fn(&mut ScopeRecord),
                /// Closed routes by index: owner->plexus, aft->plexus,
                /// broca->plexus, broca->other.
                closed: [Option<RouteCloseReason>; 4],
            }
            use RouteCloseReason::*;
            let cases = [
                Case {
                    name: "a carrier entry removed",
                    change: |r| {
                        r.carriers.retain(|c| {
                            c.principal
                                != Principal::Reserved {
                                    module_id: AFT.to_string(),
                                }
                        })
                    },
                    closed: [None, Some(ScopeCarrierRemoved), None, None],
                },
                Case {
                    name: "a target removed from a carrier",
                    change: |r| r.carriers[1].targets = Some(vec![PLEXUS.to_string()]),
                    closed: [None, None, None, Some(ScopeCarrierRemoved)],
                },
                Case {
                    name: "a bare carrier narrowed to targets",
                    change: |r| r.carriers[0].targets = Some(vec![OTHER.to_string()]),
                    closed: [None, Some(ScopeCarrierRemoved), None, None],
                },
                Case {
                    name: "delegates turned off",
                    change: |r| r.attributes.delegates = false,
                    closed: [Some(ScopeDelegationChanged); 4],
                },
                Case {
                    name: "agent_id changed",
                    change: |r| r.attributes.agent_id = Some("agent-2".to_string()),
                    closed: [Some(ScopeDelegationChanged); 4],
                },
                Case {
                    name: "a carrier added, child owners changed, the record re-sent",
                    change: |r| {
                        r.carriers.push(carrier(MAGIC, None));
                        r.child_owners.push(Principal::Reserved {
                            module_id: MAGIC.to_string(),
                        });
                    },
                    closed: [None; 4],
                },
                Case {
                    name: "a target added",
                    change: |r| {
                        r.carriers[1]
                            .targets
                            .as_mut()
                            .unwrap()
                            .push("third".to_string())
                    },
                    closed: [None; 4],
                },
                Case {
                    name: "delegates turned on",
                    change: |r| r.attributes.delegates = true,
                    closed: [None; 4],
                },
            ];
            for case in cases {
                let mut rig = rig().await;
                rig.sync(vec![session(1)]).await;
                let scope = || Some(rig_selector("s", Some(1)));
                let mut routes = [
                    rig.bound(Some(OWNER), PLEXUS, scope()).await,
                    rig.bound(Some(AFT), PLEXUS, scope()).await,
                    rig.bound(Some(BROCA), PLEXUS, scope()).await,
                    rig.bound(Some(BROCA), OTHER, scope()).await,
                ];
                let mut record = session(1);
                (case.change)(&mut record);
                rig.sync(vec![record]).await;
                for (index, expected) in case.closed.iter().enumerate() {
                    let route = &mut routes[index];
                    match expected {
                        Some(reason) => {
                            assert!(!rig.live(route), "{}: route {index} still live", case.name);
                            assert_eq!(
                                route.closed_reason(),
                                *reason,
                                "{}: route {index}",
                                case.name
                            );
                        }
                        None => {
                            assert!(rig.live(route), "{}: route {index} closed", case.name);
                            assert!(
                                route.untouched(),
                                "{}: route {index} was told something",
                                case.name
                            );
                        }
                    }
                }
            }
        }

        #[tokio::test]
        async fn ending_or_replacing_a_scope_and_a_parent_ending_drain_every_route_under_it() {
            // Removed, and replaced by a higher epoch.
            for next in [Vec::new(), vec![session(2)]] {
                let mut rig = rig().await;
                rig.sync(vec![session(1)]).await;
                let mut route = rig
                    .bound(Some(AFT), PLEXUS, Some(rig_selector("s", Some(1))))
                    .await;
                rig.sync(next).await;
                assert!(!rig.live(&route));
                assert_eq!(route.closed_reason(), RouteCloseReason::ScopeEnded);
            }

            // A child whose parent ends: its routes close as parent-ended, the
            // child stays live, and routes under the parent close as ended.
            let mut rig = rig().await;
            let mut child = session(1);
            child.scope_ref = "child".to_string();
            child.kind = ScopeKind::Worker;
            child.parent = Some(ScopeParent {
                owner: Principal::Reserved {
                    module_id: OWNER.to_string(),
                },
                scope_ref: "s".to_string(),
                scope_epoch: 1,
            });
            rig.sync(vec![session(1), child.clone()]).await;
            let mut child_route = rig
                .bound(Some(AFT), PLEXUS, Some(rig_selector("child", Some(1))))
                .await;
            assert_eq!(
                child_route.stamp().unwrap().parent_state,
                Some(ParentState::Linked)
            );
            rig.sync(vec![child]).await;
            assert!(!rig.live(&child_route));
            assert_eq!(
                child_route.closed_reason(),
                RouteCloseReason::ScopeParentEnded
            );
        }

        #[tokio::test]
        async fn re_sending_an_unchanged_record_drains_nothing_and_a_new_carrier_leaves_in_flight_calls(
        ) {
            let mut rig = rig().await;
            rig.sync(vec![session(1)]).await;
            let mut route = rig
                .bound(Some(AFT), PLEXUS, Some(rig_selector("s", Some(1))))
                .await;
            let before = rig.forwarding.published_scope_tag(OWNER, "s");
            rig.sync(vec![session(1)]).await;
            assert_eq!(rig.forwarding.published_scope_tag(OWNER, "s"), before);
            assert!(rig.live(&route) && route.untouched());

            // A call in flight on the route when another carrier is added. A
            // forwarded REQUEST holds one credit on the route's flow until the
            // module answers; the router takes it exactly like this.
            let DataRoute::Client(DataRouteState::Bound(binding)) = rig
                .forwarding
                .lookup_data_route(route.client.connection_id, route.channel, route.epoch)
                .unwrap()
            else {
                panic!("the route is bound");
            };
            binding.flow.acquire_tagged(9, false).await.unwrap();
            let mut widened = session(1);
            widened.carriers.push(carrier(MAGIC, None));
            rig.sync(vec![widened]).await;
            assert!(rig.live(&route) && route.untouched());
            let (_, plexus_rx) = rig.modules.get_mut(PLEXUS).unwrap();
            assert!(plexus_rx.try_recv().is_err(), "the module is told nothing");
            // The call's credit is still held on an open flow, so its answer
            // will be delivered: closing the route would have closed the flow.
            assert_eq!(binding.flow.in_flight(), 1);
            binding
                .flow
                .acquire_tagged(10, false)
                .await
                .expect("the flow is still open");
        }

        /// A swap's superseded endpoint keeps its routes until drained; ending
        /// the scope closes them there too.
        #[tokio::test]
        async fn ending_a_scope_drains_its_routes_on_a_superseded_endpoint() {
            let mut rig = rig().await;
            rig.sync(vec![session(1)]).await;
            let mut on_incumbent = rig
                .bound(Some(AFT), PLEXUS, Some(rig_selector("s", Some(1))))
                .await;

            // Swap plexus: register a candidate and cut over, leaving the
            // incumbent superseded with the route still on it.
            let (candidate, _candidate_rx) = wide_ctx(9);
            let registration = rig
                .handler
                .registry
                .register_candidate_with_control_ops(
                    manifest(PLEXUS, PROTOCOL_VERSION),
                    PROTOCOL_VERSION,
                    candidate.connection_id,
                    module_baseline_control_ops(),
                )
                .unwrap();
            rig.forwarding
                .register_candidate_module_connection(
                    candidate.connection_id,
                    PLEXUS.to_string(),
                    PROTOCOL_VERSION,
                    manifest_concurrency(&registration.manifest),
                    candidate.egress.clone(),
                )
                .unwrap();
            rig.forwarding.cutover_candidate(PLEXUS).unwrap().unwrap();
            rig.handler
                .registry
                .promote_candidate(PLEXUS)
                .unwrap()
                .unwrap();
            assert!(rig.live(&on_incumbent), "cutover alone does not drain");

            rig.sync(Vec::new()).await;
            assert!(!rig.live(&on_incumbent));
            assert_eq!(on_incumbent.closed_reason(), RouteCloseReason::ScopeEnded);
            let (_, incumbent_rx) = rig.modules.get_mut(PLEXUS).unwrap();
            let goodbye = incumbent_rx
                .try_recv()
                .expect("the superseded endpoint is told")
                .frame;
            assert_eq!(goodbye.header.ty, FrameType::Goodbye);
        }
    }
}

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

    fn hello_body(role_json: &str) -> Vec<u8> {
        format!(
            r#"{{"protocol_ver":2,"module_id":"m","manifest":{{"module_id":"m","module_version":"1.0.0","protocol_ver":2,"trust_tier":"first_party","provides":[{role_json}],"consumes":[],"bindings":{{"storage":{{"kind":"sqlite","scope":"project","owns_schema":false}},"vault_grants":[],"identity":{{"requires":[],"optional":[]}}}}}}}}"#
        )
        .into_bytes()
    }

    fn manifest_from(body: &[u8]) -> ModuleManifest {
        let value: serde_json::Value = serde_json::from_slice(body).expect("hello parses");
        serde_json::from_value(value.get("manifest").expect("manifest key").clone())
            .expect("manifest parses")
    }

    const SURFACE_TAIL: &str = r#""operations":[],"config_schema":{"type":"object"},"observability":[],"identity_scope":[]"#;

    #[test]
    fn absent_concurrency_on_management_surface_is_reported_as_defaulted() {
        let body = hello_body(&format!(
            r#"{{"role":"management_surface",{SURFACE_TAIL}}}"#
        ));
        let manifest = manifest_from(&body);
        // Precondition: serde really resolved it to the default, so the typed
        // manifest alone cannot answer the question this probe exists for.
        assert_eq!(manifest_concurrency(&manifest), Concurrency::ModuleManaged);
        assert!(manifest_concurrency_was_defaulted(&body, &manifest));
    }

    #[test]
    fn declared_concurrency_is_not_reported_even_when_it_equals_the_default() {
        let body = hello_body(&format!(
            r#"{{"role":"management_surface",{SURFACE_TAIL},"concurrency":"module_managed"}}"#
        ));
        let manifest = manifest_from(&body);
        assert_eq!(manifest_concurrency(&manifest), Concurrency::ModuleManaged);
        assert!(!manifest_concurrency_was_defaulted(&body, &manifest));
    }

    #[test]
    fn non_management_roles_are_never_reported() {
        let body = hello_body(
            r#"{"role":"internal_service","service_id":"s","transport":"bulk","agent_facing":false,"operations":[]}"#,
        );
        let manifest = manifest_from(&body);
        assert!(!manifest_concurrency_was_defaulted(&body, &manifest));
    }
}