feat(acp): per-turn model routing — OpenRouter catalog, ModelPicker, policy editor, harness decline data model

.gitignore

@@ -67,8 +67,14 @@ identity.key
 # Claude Code worktrees
 .claude/worktrees/
 
+# Claude Code runtime state (machine-local locks, not durable)
+.claude/scheduled_tasks.lock
+
 # mesh-llm build cache
 .cache/
 
 # Helm dependency tarballs — regenerable from Chart.lock via `helm dependency build`
 deploy/charts/*/charts/*.tgz
+
+# Claude Code context
+.claude_context_tree

crates/buzz-acp/src/acp.rs

@@ -2750,6 +2750,50 @@ mod tests {
         assert!(super::extract_model_config_options(&result).is_empty());
     }
 
+    /// Regression guard for the OpenRouter model-catalog seam.
+    ///
+    /// `switch_model` (kind:24200) resolves the requested model against the
+    /// `availableModels` a provider advertises in `session/new`. buzz-agent used to
+    /// advertise a single-entry catalog for every non-Databricks provider, so an
+    /// OpenRouter switch could never resolve. The payload below is the real shape
+    /// buzz-agent now returns for `BUZZ_AGENT_PROVIDER=openrouter` (trimmed): an
+    /// account-eligible, tools-capable slate.
+    #[test]
+    fn openrouter_catalog_resolves_a_switch_and_rejects_an_ineligible_model() {
+        let session_new = serde_json::json!({
+            "sessionId": "sess-openrouter",
+            "models": {
+                "currentModelId": "openai/gpt-5.6-luna",
+                "availableModels": [
+                    { "modelId": "openai/gpt-5.6-luna", "name": "OpenAI: GPT-5.6 Luna" },
+                    { "modelId": "openai/gpt-5.6-luna-pro", "name": "OpenAI: GPT-5.6 Luna Pro" },
+                    { "modelId": "z-ai/glm-5.2", "name": "Z.ai: GLM 5.2" },
+                    { "modelId": "deepseek/deepseek-v4-flash-0731", "name": "DeepSeek: DeepSeek V4 Flash 0731" },
+                ]
+            }
+        });
+
+        // A model in the advertised catalog resolves to a live set_model switch.
+        let method = super::resolve_model_switch_method(&session_new, "z-ai/glm-5.2")
+            .expect("a catalog model must resolve");
+        match method {
+            super::ModelSwitchMethod::SetModel { model_id } => {
+                assert_eq!(model_id, "z-ai/glm-5.2");
+            }
+            other => panic!("expected SetModel, got {other:?}"),
+        }
+
+        // A model absent from the catalog must NOT resolve. gpt-5.6-terra is the
+        // real case: it exists in OpenRouter's global catalog but is not on this
+        // account's eligibility allowlist, so requesting it returns HTTP 404.
+        // Refusing it here turns that into an up-front unsupported_model rather
+        // than a confusing mid-request failure.
+        assert!(
+            super::resolve_model_switch_method(&session_new, "openai/gpt-5.6-terra").is_none(),
+            "a model outside the advertised catalog must not resolve"
+        );
+    }
+
     #[test]
     fn extract_model_state_returns_models_object() {
         let result = serde_json::json!({

crates/buzz-acp/src/config.rs

@@ -728,6 +728,22 @@ pub(crate) fn normalize_agent_command_identity(command: &str) -> String {
         .collect()
 }
 
+/// Canonical harness *class* for a spawn command — the coarse bucket a harness
+/// dispatcher compares against, stable across binary-name variants.
+/// UNWIRED (decline-gate caller reverted 2026-08-08); kept for the dispatcher.
+#[allow(dead_code)]
+pub(crate) fn harness_class(command: &str) -> String {
+    let id = normalize_agent_command_identity(command);
+    match id.as_str() {
+        "codex" | "codex-acp" => "codex".to_string(),
+        "opencode" | "opencode-acp" => "opencode".to_string(),
+        "claude-agent-acp" | "claude-code-acp" | "claude-code" | "claudecode" => {
+            "claude".to_string()
+        }
+        _ => id, // goose, buzz-agent, hermes, custom -> class == identity
+    }
+}
+
 fn default_agent_args(command: &str) -> Option<Vec<String>> {
     match normalize_agent_command_identity(command).as_str() {
         "goose" => Some(vec!["acp".to_string()]),
@@ -1675,6 +1691,14 @@ mod tests {
         assert_eq!(normalize_agent_command_identity("///"), "");
     }
 
+    #[test]
+    fn harness_class_folds_variants() {
+        assert_eq!(harness_class("codex-acp"), "codex");
+        assert_eq!(harness_class("/usr/local/bin/opencode"), "opencode");
+        assert_eq!(harness_class("claude-code-acp"), "claude");
+        assert_eq!(harness_class("goose"), "goose");
+    }
+
     #[test]
     fn default_agent_env_recognizes_hermes_identities() {
         for command in [

crates/buzz-acp/src/lib.rs

@@ -9,6 +9,7 @@ mod pool;
 mod pool_lifecycle;
 mod queue;
 mod relay;
+mod routing;
 mod setup_mode;
 mod usage;
 

crates/buzz-acp/src/pool.rs

@@ -1780,6 +1780,34 @@ pub async fn run_prompt_task(
         Some(b) => PromptSource::Channel(b.channel_id),
         None => PromptSource::Heartbeat,
     };
+
+    // Per-turn model routing (opt-in via BUZZ_ROUTING_POLICY; see routing.rs).
+    //
+    // Deliberately does NOT override a live `switch_model`: if the operator (or
+    // the desktop ModelPicker) explicitly pinned a model for this agent,
+    // `model_overridden` is set and a router silently changing it would make the
+    // UI lie about what is running. Explicit human choice outranks the policy.
+    //
+    // The decision is expressed as `desired_model`, which the existing
+    // session-creation path validates against the agent's advertised catalog and
+    // applies — so a policy naming a model the provider does not offer degrades
+    // to the agent default with a warning rather than failing the turn.
+    if !agent.model_overridden {
+        if let Some(policy) = crate::routing::Policy::from_env() {
+            let routed_text = prompt_text.as_deref().unwrap_or_default();
+            if let Some(decision) = policy.decide(routed_text).await {
+                if agent.desired_model.as_deref() != Some(decision.model.as_str()) {
+                    tracing::info!(
+                        target: "acp::routing",
+                        model = %decision.model,
+                        reason = ?decision.reason,
+                        "routing selected a model for this turn"
+                    );
+                    agent.desired_model = Some(decision.model);
+                }
+            }
+        }
+    }
     let observer_channel_id = match &source {
         PromptSource::Channel(channel_id) => Some(*channel_id),
         PromptSource::Heartbeat => None,