feat(#70): helexa-router binary skeleton — plaintext axum server

Foundation for epic #69 (public multi-operator ingress proxy). New
`crates/helexa-router` workspace binary: a plaintext axum server that
reuses cortex-core types and serves the two stub endpoints the rest of
#69 builds on.

- `[router] listen` + `[[cortexes]]` config via figment + `HELEXA_ROUTER_`
  env overrides, matching the cortex/neuron convention.
- `GET /health` reports the configured downstream cortex count.
- `GET /v1/models` returns an empty OpenAI list (real cross-operator
  aggregation is #75).
- No inbound TLS listener (edge nginx terminates client TLS per #69's
  posture); no auth layer — the router forwards the client bearer to
  cortex and holds zero entitlement logic (#47 stays additive).
- 3 tests: both endpoints over a real ephemeral-port server, plus
  TOML+env config load.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F6o3ddqmYNh9kzdwq6eowh

CLAUDE.md

@@ -185,6 +185,32 @@ Run these locally before pushing. `cargo fmt --all` fixes formatting
 automatically. Clippy warnings must be resolved, not suppressed with
 `#[allow(...)]` unless there is a clear rationale.
 
+## Development workflow
+
+Work each change on its own branch; `main` stays releasable.
+
+1. Implement on a feature branch (`fix/<issue>-…`, `feat/<issue>-…`).
+2. Run the CI triad locally (`cargo fmt --check --all`,
+   `cargo clippy --workspace -- -D warnings`, `cargo test --workspace`).
+   Local builds are **CPU-only** — the `#[cfg(feature = "cuda")]` neuron/TP
+   paths do NOT compile locally. The branch CI's **CUDA type-check** job is
+   the only thing that validates them, so for any neuron change the push to
+   Gitea is the real gate, not a rubber stamp.
+3. Push the branch on local-green (no need to ask first), and background-watch
+   its CI run via the gitea-mcp `actions_run_read` tools. Start the next piece
+   of work meanwhile.
+4. Merge to `main` when the four **validation** jobs are green — Format,
+   Clippy, Test, CUDA type-check. The SRPM / COPR / version-bump jobs are the
+   deploy pipeline (they run on `main`), not validation — don't wait on them.
+5. Merging/pushing to `main` triggers the auto-deploy pipeline.
+
+Docs-only changes (no `#[cfg(feature = "cuda")]` impact) can go straight to
+`main` — there's nothing for the CUDA type-check to prove.
+
+SSH note: the gitea remote host offers multiple agent keys and cuts the
+connection before reaching the right one. This repo pins the working key via
+`git config core.sshCommand "ssh -i ~/.ssh/id_grenade -o IdentitiesOnly=yes"`.
+
 ## Environment
 
 - Targets Fedora 43 (systemd, SELinux enforcing)

Cargo.lock

@@ -1922,6 +1922,24 @@ dependencies = [
  "tracing-subscriber",
 ]
 
+[[package]]
+name = "helexa-router"
+version = "0.1.16"
+dependencies = [
+ "anyhow",
+ "axum",
+ "clap",
+ "cortex-core",
+ "figment",
+ "reqwest",
+ "serde",
+ "serde_json",
+ "tokio",
+ "tower-http",
+ "tracing",
+ "tracing-subscriber",
+]
+
 [[package]]
 name = "hermit-abi"
 version = "0.5.2"

Cargo.toml

@@ -7,6 +7,7 @@ members = [
     "crates/neuron",
     "crates/helexa-acp",
     "crates/helexa-bench",
+    "crates/helexa-router",
 ]
 
 [workspace.package]

crates/cortex-core/src/harness.rs

@@ -54,10 +54,26 @@ pub struct ModelLimit {
     pub output: usize,
 }
 
-/// Operator-set pricing in USD per 1M tokens.
+/// Operator-set pricing, **USD per 1,000,000 tokens, as JSON numbers**
+/// (`float`) — the models.dev/opencode `cost` convention, which is what
+/// helexa's primary client reads. NOT per-token, NOT decimal strings (that
+/// is OpenRouter's `pricing` shape, which helexa deliberately does not emit
+/// — see #68). A client must not rescale by 10⁶.
 ///
-/// Self-hosted deployments typically leave both at `0.0`.  Cache fields are
-/// optional — set when the backend supports a prefix-cache discount tier.
+/// `cost` is sourced from the operator's `models.toml` catalogue profile and
+/// surfaced verbatim on `/v1/models`. The *absent* vs *zero* distinction is
+/// intentional and load-bearing (#68):
+/// - **`cost` absent** (the whole object omitted) — the model is **not
+///   priced**: the operator has not declared a rate. Clients should treat
+///   spend as unknown, not free.
+/// - **`cost` present with `input`/`output` = `0.0`** — the model is
+///   **intentionally free** (self-hosted, no charge). opencode renders `$0`.
+///
+/// Cache fields are optional — set them only when the backend supports a
+/// prefix-cache discount tier (relevant once cache-token reporting, #64,
+/// lands). The advertised rate here must equal the rate metering (#51) and
+/// reconciliation (#58/#59) bill against; today both read this catalogue
+/// value.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ModelCost {
     /// USD per 1M input (prompt) tokens.
@@ -98,7 +114,8 @@ pub struct ModelInfo {
     /// `None` when neither the catalogue nor the loaded model can provide it.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub limit: Option<ModelLimit>,
-    /// Operator-set pricing in USD per 1M tokens (0.0 = free/self-hosted).
+    /// Operator-set pricing — see [`ModelCost`] for units and the
+    /// absent (not priced) vs `0.0` (intentionally free) distinction.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub cost: Option<ModelCost>,
     /// `true` when the model's tokenizer contains recognised tool-call

crates/cortex-core/src/node.rs

@@ -136,7 +136,9 @@ pub struct CortexModelEntry {
     /// at load time. `None` when neither source provides it.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub limit: Option<ModelLimit>,
-    /// Operator-set pricing in USD per 1M tokens (0.0 = free/self-hosted).
+    /// Operator-set pricing from the catalogue profile — see
+    /// [`cortex_core::harness::ModelCost`] for units (USD per 1M tokens) and
+    /// the absent (not priced) vs `0.0` (intentionally free) distinction.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub cost: Option<ModelCost>,
     /// `true` when any neuron reports this model supports tool calls.

crates/cortex-gateway/tests/model_cost.rs

@@ -0,0 +1,131 @@
+//! Issue #68: the `cost` wire contract on `GET /v1/models`.
+//!
+//! `cost` is operator-set pricing sourced from the `models.toml` catalogue
+//! profile (the source of truth today; the marketplace clearing house #59
+//! later — both must read the same value metering/#51 bills against). The
+//! shape is the models.dev/opencode convention: **USD per 1,000,000 tokens,
+//! as JSON numbers**, with optional `cache_read`/`cache_write` tiers. This
+//! test pins:
+//!   - the units/shape (per-million floats, not per-token, not strings);
+//!   - that cache fields flow through when present and are omitted otherwise;
+//!   - the load-bearing **absent vs `0.0`** distinction (#68): a model with
+//!     no catalogue `cost` omits the key entirely (price unknown), distinct
+//!     from an explicit `0.0` (intentionally free).
+//!
+//! Catalogue-only models surface via Pass 1 of `list_models` even with no
+//! feasible neuron, so this is hermetic — no nodes or poller needed.
+
+use cortex_core::config::{
+    EvictionSettings, EvictionStrategy, GatewayConfig, GatewaySettings, NeuronEndpoint,
+};
+use cortex_gateway::state::CortexState;
+use std::sync::Arc;
+use tokio::net::TcpListener;
+
+#[tokio::test]
+async fn v1_models_cost_units_shape_and_absent_vs_zero() {
+    // Three catalogue models exercise the whole contract: a priced model
+    // with cache tiers, an intentionally-free model (explicit 0.0), and an
+    // unpriced model (no `cost` block at all).
+    let models_toml = r#"
+[[models]]
+id = "priced-model"
+harness = "candle"
+cost.input = 0.5
+cost.output = 1.5
+cost.cache_read = 0.05
+cost.cache_write = 0.6
+
+[[models]]
+id = "free-model"
+harness = "candle"
+cost.input = 0.0
+cost.output = 0.0
+
+[[models]]
+id = "unpriced-model"
+harness = "candle"
+"#;
+    let cat_path = std::env::temp_dir().join("cortex_test_issue68_models.toml");
+    std::fs::write(&cat_path, models_toml).unwrap();
+
+    let config = GatewayConfig {
+        gateway: GatewaySettings {
+            listen: "127.0.0.1:0".into(),
+            metrics_listen: "127.0.0.1:0".into(),
+        },
+        eviction: EvictionSettings {
+            strategy: EvictionStrategy::Lru,
+            defrag_after_cycles: 0,
+        },
+        // Never contacted: build_app does not spawn the poller, so the
+        // catalogue alone drives /v1/models.
+        neurons: vec![NeuronEndpoint {
+            name: "mock-node".into(),
+            endpoint: "http://127.0.0.1:1".into(),
+        }],
+        models_config: cat_path.to_string_lossy().into_owned(),
+        entitlements: Default::default(),
+    };
+
+    let fleet = Arc::new(CortexState::from_config(&config));
+    let app = cortex_gateway::build_app(Arc::clone(&fleet));
+    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let addr = listener.local_addr().unwrap();
+    tokio::spawn(async move {
+        axum::serve(listener, app).await.unwrap();
+    });
+
+    let body: serde_json::Value = reqwest::Client::new()
+        .get(format!("http://{addr}/v1/models"))
+        .send()
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+
+    let data = body["data"].as_array().expect("data is an array");
+    let entry = |id: &str| {
+        data.iter()
+            .find(|m| m["id"] == id)
+            .unwrap_or_else(|| panic!("{id} present in /v1/models"))
+            .clone()
+    };
+
+    // Priced model: exact values flow through as JSON numbers (USD per 1M
+    // tokens). If anything rescaled by 10⁶ or stringified, these fail.
+    let priced = entry("priced-model");
+    assert_eq!(priced["cost"]["input"], 0.5);
+    assert_eq!(priced["cost"]["output"], 1.5);
+    assert_eq!(priced["cost"]["cache_read"], 0.05);
+    assert_eq!(priced["cost"]["cache_write"], 0.6);
+    assert!(
+        priced["cost"]["input"].is_number(),
+        "cost.input must be a JSON number, not a string"
+    );
+
+    // Intentionally free: cost present, rates explicitly 0.0. Unset cache
+    // tiers are omitted (skip_serializing_if), not emitted as null/0.
+    let free = entry("free-model");
+    assert_eq!(free["cost"]["input"], 0.0);
+    assert_eq!(free["cost"]["output"], 0.0);
+    assert!(
+        free["cost"].get("cache_read").is_none(),
+        "absent cache tiers must be omitted, not null"
+    );
+    assert!(free["cost"].get("cache_write").is_none());
+
+    // Unpriced: the whole `cost` object is omitted — "price unknown",
+    // distinct from the free model's explicit 0.0. This is the #68
+    // distinction opencode needs to avoid showing $0 for a model whose
+    // price simply hasn't been declared.
+    let unpriced = entry("unpriced-model");
+    assert!(
+        unpriced.get("cost").is_none(),
+        "a model with no catalogue cost must omit `cost` entirely, got {:?}",
+        unpriced.get("cost")
+    );
+
+    let _ = std::fs::remove_file(&cat_path);
+}

crates/helexa-router/Cargo.toml

@@ -0,0 +1,33 @@
+[package]
+name = "helexa-router"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[[bin]]
+name = "helexa-router"
+path = "src/main.rs"
+
+[lib]
+name = "helexa_router"
+path = "src/lib.rs"
+
+[dependencies]
+cortex-core = { workspace = true }
+
+tokio = { workspace = true }
+axum = { workspace = true }
+tower-http = { workspace = true }
+reqwest = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+figment = { workspace = true }
+anyhow = { workspace = true }
+clap = { workspace = true }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true }
+
+[dev-dependencies]
+# Jail (isolated cwd + env) for config tests.
+figment = { workspace = true, features = ["test"] }

crates/helexa-router/src/config.rs

@@ -0,0 +1,65 @@
+use figment::{
+    Figment,
+    providers::{Env, Format, Toml},
+};
+use serde::{Deserialize, Serialize};
+use std::path::Path;
+
+/// Top-level `helexa-router` configuration.
+///
+/// Loaded from TOML with `HELEXA_ROUTER_`-prefixed env overrides (using
+/// `__` as the nesting separator), matching the cortex/neuron convention.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RouterConfig {
+    pub router: RouterSettings,
+    /// Downstream cortex endpoints the router can dispatch to. The skeleton
+    /// (#70) only loads these; capacity/catalogue polling (#72) and
+    /// capacity-aware dispatch (#73) consume them later.
+    #[serde(default)]
+    pub cortexes: Vec<CortexEndpoint>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RouterSettings {
+    /// Address to listen on for the inbound API (e.g. "0.0.0.0:8088").
+    ///
+    /// Plaintext only — operator/edge nginx terminates client TLS in front
+    /// of the router (see #69's TLS posture). The router never owns an
+    /// inbound TLS listener.
+    pub listen: String,
+}
+
+/// One downstream cortex the router may proxy to. The router verifies the
+/// cortex's outbound TLS cert (#74) and routes on capacity (#73); it holds
+/// no entitlement logic of its own and forwards the client bearer verbatim.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CortexEndpoint {
+    /// Human-readable label (e.g. "lair-cafe").
+    pub name: String,
+    /// Base URL of the cortex gateway (e.g. "https://cortex.example.com").
+    pub endpoint: String,
+}
+
+impl RouterConfig {
+    /// Load configuration from a TOML file, with environment variable
+    /// overrides prefixed with `HELEXA_ROUTER_` and `__` as the separator
+    /// (e.g. `HELEXA_ROUTER_ROUTER__LISTEN=0.0.0.0:8088`).
+    pub fn load(path: impl AsRef<Path>) -> Result<Self, Box<figment::Error>> {
+        Figment::new()
+            .merge(Toml::file(path))
+            .merge(Env::prefixed("HELEXA_ROUTER_").split("__"))
+            .extract()
+            .map_err(Box::new)
+    }
+}
+
+impl Default for RouterConfig {
+    fn default() -> Self {
+        Self {
+            router: RouterSettings {
+                listen: "0.0.0.0:8088".into(),
+            },
+            cortexes: vec![],
+        }
+    }
+}

crates/helexa-router/src/handlers.rs

@@ -0,0 +1,37 @@
+use crate::state::RouterState;
+use axum::{Json, Router, extract::State, routing::get};
+use cortex_core::openai::ModelsResponse;
+use serde_json::{Value, json};
+use std::sync::Arc;
+
+/// Routes served by the router skeleton. The inference paths
+/// (`/v1/chat/completions`, `/v1/messages`, …) arrive with capacity-aware
+/// dispatch (#73); for now the router only answers `/health` and a stub
+/// `/v1/models`.
+pub fn api_routes() -> Router<Arc<RouterState>> {
+    Router::new()
+        .route("/v1/models", get(list_models))
+        .route("/health", get(health))
+        .route("/", get(health))
+}
+
+/// `GET /health` — liveness plus the configured downstream cortex count.
+/// Real per-cortex reachability lands with the poller (#72).
+async fn health(State(state): State<Arc<RouterState>>) -> Json<Value> {
+    Json(json!({
+        "status": "ok",
+        "cortexes": {
+            "configured": state.cortexes.len(),
+        }
+    }))
+}
+
+/// `GET /v1/models` — empty catalogue stub. The real cross-operator union
+/// (catalogue × topology feasibility, aggregated from each cortex) is the
+/// federation-catalogue issue (#75).
+async fn list_models() -> Json<ModelsResponse> {
+    Json(ModelsResponse {
+        object: "list".into(),
+        data: vec![],
+    })
+}

crates/helexa-router/src/lib.rs

@@ -0,0 +1,49 @@
+//! helexa-router — public multi-operator ingress proxy (router.helexa.ai).
+//!
+//! The router is the data-plane *ingress* tier: a geo-distributed,
+//! capacity-aware, OpenAI/Anthropic-compatible reverse proxy in front of
+//! many operator-run cortexes ("cortex-of-cortexes"). End users configure
+//! one `baseURL` and the router forwards their request to a cortex with
+//! capacity, proxying #63-shaped rejections back verbatim.
+//!
+//! It holds **zero entitlement logic** — auth/budget stays at cortex
+//! (epic #47); the router forwards the client bearer unchanged and routes
+//! on capacity (epic #69). This crate is the binary skeleton (#70):
+//! a plaintext axum server reusing `cortex-core` types, serving `/health`
+//! and a stub `/v1/models`.
+
+pub mod config;
+pub mod handlers;
+pub mod state;
+
+use anyhow::Result;
+use config::RouterConfig;
+use std::sync::Arc;
+use tower_http::cors::CorsLayer;
+use tower_http::trace::TraceLayer;
+
+/// Build the axum application: handlers + CORS + tracing. No auth layer —
+/// the router asserts no identity of its own and forwards the client bearer
+/// to the downstream cortex, which authenticates it (#69).
+pub fn build_app(state: Arc<state::RouterState>) -> axum::Router {
+    axum::Router::new()
+        .merge(handlers::api_routes())
+        .layer(CorsLayer::permissive())
+        .layer(TraceLayer::new_for_http())
+        .with_state(state)
+}
+
+/// Start the router: build state from config and bind the plaintext HTTP
+/// listener. TLS is terminated by edge nginx ahead of this process.
+pub async fn run(config: RouterConfig) -> Result<()> {
+    let state = Arc::new(state::RouterState::from_config(&config));
+    let app = build_app(state);
+
+    let listen_addr = config.router.listen.parse::<std::net::SocketAddr>()?;
+    tracing::info!("helexa-router listening on {listen_addr}");
+
+    let listener = tokio::net::TcpListener::bind(listen_addr).await?;
+    axum::serve(listener, app).await?;
+
+    Ok(())
+}

crates/helexa-router/src/main.rs

@@ -0,0 +1,52 @@
+use anyhow::Result;
+use clap::{Parser, Subcommand};
+use helexa_router::config::RouterConfig;
+use tracing_subscriber::EnvFilter;
+
+#[derive(Parser)]
+#[command(name = "helexa-router")]
+#[command(about = "Public multi-operator ingress proxy for helexa")]
+#[command(version)]
+struct Cli {
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    /// Start the router server.
+    Serve {
+        /// Path to the router config file.
+        #[arg(short, long, default_value = "helexa-router.toml")]
+        config: String,
+    },
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            EnvFilter::try_from_default_env()
+                .unwrap_or_else(|_| EnvFilter::new("info,helexa_router=debug")),
+        )
+        .init();
+
+    let cli = Cli::parse();
+
+    match cli.command {
+        Commands::Serve { config } => {
+            let cfg = RouterConfig::load(&config)
+                .map_err(|e| anyhow::anyhow!("failed to load config from '{config}': {e}"))?;
+
+            tracing::info!(
+                cortexes = cfg.cortexes.len(),
+                listen = %cfg.router.listen,
+                "starting helexa-router"
+            );
+
+            helexa_router::run(cfg).await?;
+        }
+    }
+
+    Ok(())
+}

crates/helexa-router/src/state.rs

@@ -0,0 +1,21 @@
+use crate::config::{CortexEndpoint, RouterConfig};
+
+/// Shared router state.
+///
+/// The skeleton (#70) holds only the static downstream cortex list from
+/// config. Live multi-operator topology (per-cortex capacity + catalogue)
+/// is added by the poller (#72), at which point this grows an
+/// `Arc<RwLock<...>>` topology map alongside the static endpoints.
+#[derive(Debug)]
+pub struct RouterState {
+    /// Downstream cortex endpoints, as configured.
+    pub cortexes: Vec<CortexEndpoint>,
+}
+
+impl RouterState {
+    pub fn from_config(config: &RouterConfig) -> Self {
+        Self {
+            cortexes: config.cortexes.clone(),
+        }
+    }
+}

crates/helexa-router/tests/skeleton.rs

@@ -0,0 +1,93 @@
+//! Skeleton acceptance tests for #70: the router builds, serves `/health`
+//! and `/v1/models` on a plaintext port, and loads its cortex-endpoint list
+//! from TOML with env overrides.
+
+use helexa_router::config::{CortexEndpoint, RouterConfig};
+use helexa_router::state::RouterState;
+use std::sync::Arc;
+use tokio::net::TcpListener;
+
+/// Bind the router app on an ephemeral port and return its base URL.
+async fn spawn_router(cortexes: Vec<CortexEndpoint>) -> String {
+    let cfg = RouterConfig {
+        cortexes,
+        ..Default::default()
+    };
+    let state = Arc::new(RouterState::from_config(&cfg));
+    let app = helexa_router::build_app(state);
+
+    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let addr = listener.local_addr().unwrap();
+    tokio::spawn(async move {
+        axum::serve(listener, app).await.unwrap();
+    });
+
+    format!("http://{addr}")
+}
+
+#[tokio::test]
+async fn health_reports_configured_cortex_count() {
+    let base = spawn_router(vec![
+        CortexEndpoint {
+            name: "a".into(),
+            endpoint: "https://a.example.com".into(),
+        },
+        CortexEndpoint {
+            name: "b".into(),
+            endpoint: "https://b.example.com".into(),
+        },
+    ])
+    .await;
+
+    let body: serde_json::Value = reqwest::get(format!("{base}/health"))
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+
+    assert_eq!(body["status"], "ok");
+    assert_eq!(body["cortexes"]["configured"], 2);
+}
+
+#[tokio::test]
+async fn models_returns_empty_openai_list() {
+    let base = spawn_router(vec![]).await;
+
+    let resp = reqwest::get(format!("{base}/v1/models")).await.unwrap();
+    assert!(resp.status().is_success());
+
+    let body: serde_json::Value = resp.json().await.unwrap();
+    assert_eq!(body["object"], "list");
+    assert_eq!(body["data"].as_array().unwrap().len(), 0);
+}
+
+#[test]
+#[allow(clippy::result_large_err)]
+fn config_loads_from_toml_with_env_override() {
+    figment::Jail::expect_with(|jail| {
+        jail.create_file(
+            "helexa-router.toml",
+            r#"
+[router]
+listen = "127.0.0.1:8088"
+
+[[cortexes]]
+name = "lair-cafe"
+endpoint = "https://cortex.lair.cafe"
+"#,
+        )?;
+
+        // Env override wins over the TOML value.
+        jail.set_env("HELEXA_ROUTER_ROUTER__LISTEN", "0.0.0.0:9099");
+
+        let cfg = RouterConfig::load("helexa-router.toml").expect("load config");
+
+        assert_eq!(cfg.router.listen, "0.0.0.0:9099");
+        assert_eq!(cfg.cortexes.len(), 1);
+        assert_eq!(cfg.cortexes[0].name, "lair-cafe");
+        assert_eq!(cfg.cortexes[0].endpoint, "https://cortex.lair.cafe");
+
+        Ok(())
+    });
+}

crates/neuron/src/harness/candle.rs

@@ -33,7 +33,7 @@ use crate::wire::{
 use std::collections::HashMap;
 use std::path::PathBuf;
 use std::sync::Arc;
-use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
 #[cfg(feature = "cuda")]
 use std::time::Duration;
 use std::time::{SystemTime, UNIX_EPOCH};
@@ -205,23 +205,50 @@ impl LoadedHandle {
     /// `NEURON_MAX_PROMPT_TOKENS`, when explicitly set, is applied as a
     /// clamp-only upper bound on the derived `context` — a backstop, not
     /// the authority. Unset → no clamp; the derivation stands alone.
-    pub async fn derived_limit(
+    /// Refresh the cached free-VRAM reading used by [`Self::derived_limit`]
+    /// (#53). Queries the device worker — so it MUST run off the request
+    /// path (background refresher / load-time seed), never from a control
+    /// endpoint, since the query queues behind inference on the worker.
+    /// Single-GPU caches the device's free VRAM; TP caches the tightest
+    /// free across ranks (the same value `derived_limit` used pre-cache).
+    pub async fn refresh_free_mb(&self) {
+        let free = match self {
+            LoadedHandle::Single(m) => m.query_vram().await.0,
+            #[cfg(feature = "cuda")]
+            LoadedHandle::Tp(m) => m.query_vram_tightest_free_mb().await,
+        };
+        // Don't clobber a good cached value with a transient `0`
+        // (worker gone/poisoned sentinel).
+        if free > 0 {
+            match self {
+                LoadedHandle::Single(m) => m.last_free_mb.store(free, Ordering::Release),
+                #[cfg(feature = "cuda")]
+                LoadedHandle::Tp(m) => m.last_free_mb.store(free, Ordering::Release),
+            }
+        }
+    }
+
+    pub fn derived_limit(
         &self,
         cfg: &crate::config::ContextLimitConfig,
     ) -> Option<cortex_core::harness::ModelLimit> {
         if !cfg.enabled {
             return None;
         }
+        // Read the *cached* free VRAM — never query the device worker here.
+        // This runs on `GET /models`; a live query would queue behind
+        // inference on the worker thread and stall the control plane (#53).
+        // The cache is refreshed off the request path (load + background task).
         let (profile, free_mb, rate) = match self {
             LoadedHandle::Single(m) => (
                 m.context_profile?,
-                m.query_vram().await.0,
+                m.last_free_mb.load(Ordering::Acquire),
                 m.prefill_rate.get(),
             ),
             #[cfg(feature = "cuda")]
             LoadedHandle::Tp(m) => (
                 m.context_profile?,
-                m.query_vram_tightest_free_mb().await,
+                m.last_free_mb.load(Ordering::Acquire),
                 m.prefill_rate.get(),
             ),
         };
@@ -391,6 +418,13 @@ pub struct LoadedModel {
     /// request-path enforcement reads this — `0` means "not derived yet"
     /// → fall back to the static `NEURON_MAX_PROMPT_TOKENS`.
     pub derived_input_cap: AtomicUsize,
+    /// Cached free VRAM (MiB) for the control plane (#53). `derived_limit`
+    /// (served by `GET /models`) reads this instead of querying the device
+    /// worker, which during inference is saturated processing forward jobs —
+    /// a live query would queue behind them and stall `/models`, tripping
+    /// cortex's health poller into marking the node unhealthy. Refreshed off
+    /// the request path: seeded at load, then by a background task.
+    pub last_free_mb: AtomicU64,
 }
 
 impl LoadedModel {
@@ -503,6 +537,10 @@ pub struct TpLoadedModel {
     /// Mint for pool-wide snapshot ids. Plain counter; uniqueness only
     /// needs to hold per model lifetime (snapshots die with the model).
     pub next_snapshot_id: std::sync::atomic::AtomicU64,
+    /// Cached tightest free VRAM (MiB) for the control plane (#53) — see
+    /// [`LoadedModel::last_free_mb`]. Read by `derived_limit` so `GET /models`
+    /// never fans a VRAM query out to the (inference-saturated) TP workers.
+    pub last_free_mb: AtomicU64,
 }
 
 #[cfg(feature = "cuda")]
@@ -1109,6 +1147,32 @@ fn debug_poison_armed(model_id: &str) -> bool {
     armed && !FIRED.swap(true, Ordering::Relaxed)
 }
 
+/// Background control-plane VRAM cache refresher (#53). Every few seconds,
+/// refreshes each loaded model's `last_free_mb` so `derived_limit` (served
+/// by `GET /models`) reads a cached value and never queries the device
+/// worker on the request path — a live query would queue behind inference
+/// forward jobs on the worker thread, stalling `/models` for seconds and
+/// tripping cortex's health poller into evicting the node from routing.
+/// Holds a `Weak` so a shutting-down harness lets the task exit. The query
+/// itself may queue behind inference, but that only delays this background
+/// refresh — no request-path caller is ever blocked.
+async fn vram_cache_refresh_loop(weak: std::sync::Weak<CandleHarness>) {
+    const REFRESH_INTERVAL: std::time::Duration = std::time::Duration::from_secs(5);
+    loop {
+        tokio::time::sleep(REFRESH_INTERVAL).await;
+        let Some(this) = weak.upgrade() else {
+            return; // harness dropped — exit
+        };
+        // Snapshot handles, then release the read lock before awaiting the
+        // (possibly slow) worker queries so we never hold it across an await.
+        let handles: Vec<LoadedHandle> = this.models.read().await.values().cloned().collect();
+        drop(this);
+        for handle in handles {
+            handle.refresh_free_mb().await;
+        }
+    }
+}
+
 /// Background auto-recovery task (#17). Drains poisoned model ids and
 /// rebuilds each via [`CandleHarness::recover_one`]. Holds a `Weak` so a
 /// shutting-down harness lets the task exit; processes one id at a time,
@@ -1282,25 +1346,67 @@ fn validate_vision_prefill(prompt_len: usize, vram_free_mb: u64) -> Result<(), I
 /// the caller as `max`), or if free VRAM is below the floor. Enforcing
 /// the *derived* cap means a VRAM-tight host rejects a prompt that
 /// wouldn't fit, instead of accepting it and OOMing mid-prefill.
+///
+/// The third VRAM check — the length-aware backstop (#65) — closes the
+/// poll-vs-request snapshot gap #67 leaves open. `max` is
+/// `effective_prompt_cap()`, the input budget derived at **/models poll
+/// time** from the tightest card's free VRAM *then*. If free VRAM has
+/// since dropped (a co-resident model loaded, a concurrent prefill grew
+/// its KV), a prompt at-or-below that now-stale cap still clears the
+/// static floor yet no longer fits — and OOMs mid-prefill, poisoning the
+/// device context (the 2026-05-26 beast incident the #47 work exists to
+/// eliminate). So we re-run the same length×KV-vs-VRAM physics #67 uses
+/// for the cap, but against **request-time** free VRAM, reusing the
+/// model's [`ContextProfile`] rather than re-deriving the KV cost. This
+/// gives the text path the live-VRAM guard the vision path already has
+/// (`validate_vision_prefill`). `profile`/`kv_bytes_per_token_per_card`
+/// are per-card and `vram_free_mb` is the tightest card's free VRAM, so
+/// the two are commensurable on both single-GPU and TP loads.
 fn validate_request(
     prompt_len: usize,
     vram_free_mb: u64,
     max: usize,
+    profile: Option<&super::context_limit::ContextProfile>,
+    cfg: &crate::config::ContextLimitConfig,
 ) -> Result<(), InferenceError> {
     if prompt_len > max {
         return Err(InferenceError::PromptTooLong { prompt_len, max });
     }
-    // VRAM check is skipped on CPU loads (vram_free_mb == 0 sentinel)
+    // VRAM checks are skipped on CPU loads (vram_free_mb == 0 sentinel)
     // because the (0, 0) reply from `query_vram` is also what a missing
     // worker returns. The CPU path has no per-GPU memory limit anyway —
     // host RAM is bounded by the OOM killer, not this check.
+    if vram_free_mb == 0 {
+        return Ok(());
+    }
     let min = min_free_vram_mb();
-    if vram_free_mb != 0 && vram_free_mb < min {
+    if vram_free_mb < min {
         return Err(InferenceError::InsufficientVram {
             free_mb: vram_free_mb,
             required_mb: min,
         });
     }
+    // Length-aware backstop (#65): KV the whole sequence (prompt +
+    // generation reserve) will occupy, plus the prefill activation
+    // headroom, plus the static floor as an additive cushion — all per
+    // card. A degenerate zero-KV profile (no full-attention layers) or a
+    // model with no captured profile skips this and rides the floor
+    // check above, mirroring `derive_limit`'s VRAM-ceiling fallback.
+    if let Some(profile) = profile
+        && profile.kv_bytes_per_token_per_card > 0
+    {
+        let tokens = (prompt_len as u64).saturating_add(cfg.output_reserve_tokens as u64);
+        let kv_mb = profile.kv_bytes_per_token_per_card.saturating_mul(tokens) / (1024 * 1024);
+        let required_mb = kv_mb
+            .saturating_add(cfg.activation_headroom_mb)
+            .saturating_add(min);
+        if required_mb > vram_free_mb {
+            return Err(InferenceError::InsufficientVram {
+                free_mb: vram_free_mb,
+                required_mb,
+            });
+        }
+    }
     Ok(())
 }
 
@@ -1595,6 +1701,11 @@ impl CandleHarness {
         if tokio::runtime::Handle::try_current().is_ok() {
             let weak = Arc::downgrade(&this);
             tokio::spawn(recovery_loop(weak, recovery_rx));
+            // Control-plane VRAM cache refresher (#53): keeps each loaded
+            // model's `last_free_mb` current off the request path, so
+            // `derived_limit` / `GET /models` never query the device worker
+            // (which is saturated during inference) and never stall.
+            tokio::spawn(vram_cache_refresh_loop(Arc::downgrade(&this)));
         }
         this
     }
@@ -2181,7 +2292,13 @@ impl CandleHarness {
                 "chat_completion: starting"
             );
 
-            validate_request(prompt_len, vram_free_mb, loaded.effective_prompt_cap())?;
+            validate_request(
+                prompt_len,
+                vram_free_mb,
+                loaded.effective_prompt_cap(),
+                loaded.context_profile.as_ref(),
+                &self.context_limit_cfg,
+            )?;
             if vision_route.is_some() {
                 validate_vision_prefill(prompt_len, vram_free_mb)?;
             }
@@ -2635,7 +2752,13 @@ impl CandleHarness {
             );
         }
 
-        validate_request(prompt_len, vram_free_mb, loaded.effective_prompt_cap())?;
+        validate_request(
+            prompt_len,
+            vram_free_mb,
+            loaded.effective_prompt_cap(),
+            loaded.context_profile.as_ref(),
+            &self.context_limit_cfg,
+        )?;
         if vision_route.is_some() {
             validate_vision_prefill(prompt_len, vram_free_mb)?;
         }
@@ -2959,7 +3082,7 @@ impl Harness for CandleHarness {
             // physics + live free VRAM + measured prefill rate. `None`
             // for arches without a context profile. `cost` stays
             // operator-set in the catalogue, filled by the gateway.
-            let limit = h.derived_limit(&self.context_limit_cfg).await;
+            let limit = h.derived_limit(&self.context_limit_cfg);
             out.push(ModelInfo {
                 id: h.model_id().into(),
                 harness: "candle".into(),
@@ -3209,6 +3332,7 @@ impl Harness for CandleHarness {
             context_profile,
             prefill_rate: super::context_limit::PrefillRateEma::new(),
             derived_input_cap: AtomicUsize::new(0),
+            last_free_mb: AtomicU64::new(0),
         });
         if loaded.prefix_cache.is_some() {
             tracing::info!(
@@ -3219,6 +3343,14 @@ impl Harness for CandleHarness {
             );
         }
 
+        // Seed the control-plane VRAM cache (#53) while the worker is idle
+        // (load just finished), so `/models` has a value before the
+        // background refresher's first tick and never queries the worker.
+        let (free_mb, _) = loaded.query_vram().await;
+        if free_mb > 0 {
+            loaded.last_free_mb.store(free_mb, Ordering::Release);
+        }
+
         let mut models = self.models.write().await;
         models.insert(spec.model_id.clone(), LoadedHandle::Single(loaded));
         tracing::info!(model = %spec.model_id, "model loaded");
@@ -3469,6 +3601,7 @@ impl CandleHarness {
             ),
             prefill_rate: super::context_limit::PrefillRateEma::new(),
             derived_input_cap: AtomicUsize::new(0),
+            last_free_mb: AtomicU64::new(0),
             next_snapshot_id: std::sync::atomic::AtomicU64::new(1),
         });
         if tp_loaded.prefix_cache.is_some() {
@@ -3480,6 +3613,14 @@ impl CandleHarness {
             );
         }
 
+        // Seed the control-plane VRAM cache (#53) — tightest free across
+        // ranks, while the workers are idle post-load — so `/models` never
+        // fans a query out to the inference-busy TP workers.
+        let free_mb = tp_loaded.query_vram_tightest_free_mb().await;
+        if free_mb > 0 {
+            tp_loaded.last_free_mb.store(free_mb, Ordering::Release);
+        }
+
         let mut models = self.models.write().await;
         models.insert(spec.model_id.clone(), LoadedHandle::Tp(tp_loaded));
         tracing::info!(
@@ -3546,8 +3687,11 @@ impl CandleHarness {
         }
 
         let tp_for_marker = Arc::clone(&tp);
-        let handle =
-            tokio::spawn(chat_completion_tp_inner(tp, request, principal).instrument(span.clone()));
+        let context_limit_cfg = self.context_limit_cfg.clone();
+        let handle = tokio::spawn(
+            chat_completion_tp_inner(tp, request, principal, context_limit_cfg)
+                .instrument(span.clone()),
+        );
         match handle.await {
             Ok(Ok(resp)) => Ok(resp),
             Ok(Err(e)) => {
@@ -3759,7 +3903,13 @@ impl CandleHarness {
             "TP chat_completion (stream): starting"
         );
 
-        validate_request(prompt_len, vram_free_mb, tp.effective_prompt_cap())?;
+        validate_request(
+            prompt_len,
+            vram_free_mb,
+            tp.effective_prompt_cap(),
+            tp.context_profile.as_ref(),
+            &self.context_limit_cfg,
+        )?;
         if vision_route.is_some() {
             validate_vision_prefill(prompt_len, vram_free_mb)?;
         }
@@ -4280,6 +4430,7 @@ async fn chat_completion_tp_inner(
     tp: Arc<TpLoadedModel>,
     request: ChatCompletionRequest,
     principal: Option<String>,
+    context_limit_cfg: crate::config::ContextLimitConfig,
 ) -> Result<ChatCompletionResponse, InferenceError> {
     let req_start = std::time::Instant::now();
     let model_id = request.model.clone();
@@ -4363,7 +4514,13 @@ async fn chat_completion_tp_inner(
         "TP chat_completion: starting"
     );
 
-    validate_request(prompt_len, vram_free_mb, tp.effective_prompt_cap())?;
+    validate_request(
+        prompt_len,
+        vram_free_mb,
+        tp.effective_prompt_cap(),
+        tp.context_profile.as_ref(),
+        &context_limit_cfg,
+    )?;
     if vision_route.is_some() {
         validate_vision_prefill(prompt_len, vram_free_mb)?;
     }
@@ -6680,6 +6837,110 @@ mod tests {
         assert!(validate_vision_prefill(12_960, 12_445).is_ok());
     }
 
+    // ── #65: request-time length-aware VRAM backstop (text prefill) ──
+
+    /// A beast-like profile: 16 full-attn layers, 4 kv heads, head_dim
+    /// 256, f16, TP=2 → 32 KiB/token/card (same numbers as the
+    /// `context_limit` unit tests). At defaults this makes the
+    /// length-aware footprint `(prompt_len + 8192)/32 + 2048 + 1500` MiB
+    /// per card.
+    fn backstop_profile() -> super::super::context_limit::ContextProfile {
+        super::super::context_limit::ContextProfile {
+            max_position_embeddings: 262_144,
+            kv_bytes_per_token_per_card: super::super::context_limit::kv_bytes_per_token(
+                16, 4, 256, 2, 2,
+            ),
+            world_size: 2,
+        }
+    }
+
+    /// A prompt under the cap with ample free VRAM passes; the same
+    /// prompt over the cap is `PromptTooLong` before any VRAM math.
+    #[test]
+    fn validate_request_cap_and_fit() {
+        let cfg = crate::config::ContextLimitConfig::default();
+        let profile = backstop_profile();
+        // Under cap, 40 GB free → fits.
+        assert!(validate_request(8_000, 40_000, 100_000, Some(&profile), &cfg).is_ok());
+        // Over the cap → PromptTooLong, independent of VRAM.
+        assert!(matches!(
+            validate_request(100_001, 40_000, 100_000, Some(&profile), &cfg),
+            Err(InferenceError::PromptTooLong { .. })
+        ));
+    }
+
+    /// The CPU sentinel (`vram_free_mb == 0`) skips every VRAM check,
+    /// including the new length-aware one — host RAM is the OOM killer's
+    /// problem, not this guard's.
+    #[test]
+    fn validate_request_cpu_sentinel_skips_vram() {
+        let cfg = crate::config::ContextLimitConfig::default();
+        let profile = backstop_profile();
+        assert!(validate_request(1_000_000, 0, 2_000_000, Some(&profile), &cfg).is_ok());
+    }
+
+    /// The static floor remains a backstop: free VRAM below
+    /// `min_free_vram_mb()` is rejected before the length-aware estimate
+    /// even runs (so `required_mb` is the floor, not the KV footprint).
+    #[test]
+    fn validate_request_static_floor_still_binds() {
+        let cfg = crate::config::ContextLimitConfig::default();
+        let profile = backstop_profile();
+        assert!(matches!(
+            validate_request(10, 800, 100_000, Some(&profile), &cfg),
+            Err(InferenceError::InsufficientVram {
+                free_mb: 800,
+                required_mb: 1500
+            })
+        ));
+    }
+
+    /// A model with no captured profile (non-qwen3_5 arch) has no
+    /// length-aware physics to apply, so it rides only the static floor —
+    /// a fitting prompt with VRAM above the floor passes.
+    #[test]
+    fn validate_request_no_profile_rides_floor() {
+        let cfg = crate::config::ContextLimitConfig::default();
+        assert!(validate_request(500_000, 5_000, 1_000_000, None, &cfg).is_ok());
+    }
+
+    /// The acceptance test (#65): a cap derived against *ample* free VRAM
+    /// is later applied at request time against *tightened* free VRAM. A
+    /// prompt sized exactly at the now-stale `effective_prompt_cap()`
+    /// clears the cap and the static floor, yet no longer fits — the
+    /// length-aware backstop catches it with a clean `InsufficientVram`
+    /// instead of an OOM-poisoned context. Same prompt with the original
+    /// ample VRAM still passes, proving the guard only bites on staleness.
+    #[test]
+    fn validate_request_catches_poll_vs_request_staleness() {
+        let cfg = crate::config::ContextLimitConfig::default();
+        let profile = backstop_profile();
+
+        // Cap derived at /models poll time with 40 GB free on the tightest
+        // card — throughput binds, giving input = 87040 (the issue's
+        // worked beast figure).
+        let limit = super::super::context_limit::derive_limit(&profile, 40_000, 800.0, None, &cfg);
+        let cap = limit.input.expect("input budget derived");
+        assert_eq!(cap, 87_040);
+
+        // With that same ample VRAM, a prompt at the cap still fits.
+        assert!(validate_request(cap, 40_000, cap, Some(&profile), &cfg).is_ok());
+
+        // Now free VRAM has dropped to 5 GB between the poll and the
+        // request (a co-resident model loaded). The prompt is still ≤ cap
+        // and clears the 1500 MiB floor, but its footprint —
+        // (87040 + 8192)/32 + 2048 + 1500 = 6524 MiB — exceeds 5000 MiB.
+        let err = validate_request(cap, 5_000, cap, Some(&profile), &cfg)
+            .expect_err("stale cap must not let an over-VRAM prompt through");
+        assert!(matches!(
+            err,
+            InferenceError::InsufficientVram {
+                free_mb: 5_000,
+                required_mb: 6_524
+            }
+        ));
+    }
+
     // ── Tool-call body parsing ───────────────────────────────────────
 
     fn weather_schemas() -> ToolSchemas {

crates/neuron/src/harness/context_limit.rs

@@ -100,9 +100,9 @@ pub const KV_CACHE_DTYPE_BYTES: usize = 2;
 /// state, not a growing cache). Sharded across the TP world: per-rank
 /// KV-head count is `n_kv_heads / world_size`.
 ///
-/// `2 ×` accounts for K and V. Shared by the limit derivation here and
-/// the per-rank load-time logging in the TP paths (and, in future, by
-/// #65's length-aware pre-flight guard).
+/// `2 ×` accounts for K and V. Shared by the limit derivation here, the
+/// per-rank load-time logging in the TP paths, and #65's request-time
+/// length-aware pre-flight guard (`candle::validate_request`).
 pub fn kv_bytes_per_token(
     n_full_attn_layers: usize,
     n_kv_heads: usize,

helexa-router.example.toml

@@ -0,0 +1,28 @@
+# helexa-router.example.toml — example configuration
+#
+# Copy to helexa-router.toml and adjust for your environment.
+#
+# Environment variable overrides use the HELEXA_ROUTER_ prefix with __
+# separators:
+#   HELEXA_ROUTER_ROUTER__LISTEN=0.0.0.0:8088
+
+[router]
+# Plaintext listener. Operator/edge nginx terminates client TLS in front of
+# the router — the router never owns an inbound TLS listener.
+listen = "0.0.0.0:8088"
+
+# -- Downstream cortexes -------------------------------------------------
+# Each [[cortexes]] entry is an operator-run cortex the router may dispatch
+# to. The router forwards the client's bearer verbatim (auth stays at
+# cortex) and routes on capacity. Outbound TLS to each cortex is verified.
+#
+# The skeleton only loads this list; capacity/catalogue polling and
+# capacity-aware dispatch arrive in later issues.
+
+# [[cortexes]]
+# name = "lair-cafe"
+# endpoint = "https://cortex.lair.cafe"
+
+# [[cortexes]]
+# name = "example-operator"
+# endpoint = "https://cortex.example.com"

models.example.toml

@@ -26,6 +26,18 @@
 #                        the load to neuron as `scheme:id` so the daemon
 #                        fetches from the right registry. Omit to let
 #                        neuron substitute its own `default_source`.
+#   cost.*             - optional operator-set pricing, surfaced verbatim on
+#                        GET /v1/models for clients (opencode) to display
+#                        spend. USD per 1,000,000 tokens, as numbers:
+#                          cost.input        prompt tokens
+#                          cost.output       completion tokens
+#                          cost.cache_read   cache-hit tokens   (optional tier)
+#                          cost.cache_write  cache-write tokens (optional tier)
+#                        Absent vs zero is intentional (#68): OMIT the whole
+#                        cost block to mean "price not declared / unknown";
+#                        set cost.input/output = 0.0 to mean "intentionally
+#                        free" (self-hosted). The advertised rate must match
+#                        what metering bills against.
 
 # Tensor-parallel target — needs a neuron with at least 2 large GPUs.
 # The example pins to a specific neuron name; adjust or remove the
@@ -41,13 +53,16 @@ pinned_on = ["your-multi-gpu-neuron"]
 limit.context = 32768
 limit.input = 28672
 limit.output = 4096
-# Pricing in USD per 1M tokens — 0.0 for self-hosted.
+# Pricing in USD per 1M tokens. Explicit 0.0 = intentionally free
+# (self-hosted) — distinct from omitting `cost`, which means "not priced".
 cost.input = 0.0
 cost.output = 0.0
 # Static capability hints (unioned with runtime-detected flags).
 capabilities = ["text", "reasoning"]
 
 # Mid-size dense model — fits on any single GPU with ≥16 GB VRAM.
+# No `cost` block here: this model is "not priced" — /v1/models omits the
+# `cost` key for it, so opencode shows spend as unknown rather than $0.
 [[models]]
 id = "Qwen/Qwen3-8B"
 harness = "candle"