@cohortapp/agent-sdk 2.3.0

package/lib/model-router.test.mjs

@@ -0,0 +1,907 @@
+/**
+ * model-router.test.mjs — node:test coverage for the model router.
+ *
+ * Tests write configs to a temp dir + load them via loadRoutingConfig so
+ * we exercise the full file-system path. No real network, no real Claude.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "fs";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { fileURLToPath } from "node:url";
+
+import {
+  loadRoutingConfig,
+  defaultRoutingConfig,
+  resolveBackend,
+  estimateCost,
+  listBackends,
+  describeBackend,
+  modelFlagFor,
+  requestFromClassifierResult,
+  CONFIG_RELATIVE_PATH,
+  resolveChain,
+  validateRoutingConfig,
+} from "./model-router.mjs";
+import { loadCatalog } from "./model-router/catalog.mjs";
+
+async function makeAgentRoot() {
+  const path = join(
+    tmpdir(),
+    `model-router-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  );
+  await fsp.mkdir(join(path, "config"), { recursive: true });
+  return path;
+}
+
+async function rmRoot(path) {
+  try { await fsp.rm(path, { recursive: true, force: true }); } catch { /* */ }
+}
+
+function writeJsonConfig(root, body) {
+  // We write JSON (not YAML) so the tests don't depend on js-yaml being
+  // installed in CI. The loader treats .json identically.
+  writeFileSync(join(root, "config/model-routing.json"), JSON.stringify(body, null, 2));
+}
+
+const ANTHROPIC_BACKEND = {
+  transport: "anthropic-cli",
+  base_url: "https://api.anthropic.com",
+  capabilities: ["thinking", "vision", "prompt_cache_1h", "tool_use", "parallel_tools", "long_context_1m"],
+  pricing: { input_per_m: 3.0, output_per_m: 15.0 },
+  models: {
+    classifier: "claude-haiku-4-5-20251001",
+    default: "claude-sonnet-4-6",
+    premium: "claude-opus-4-7",
+    fast: "claude-haiku-4-5-20251001",
+  },
+};
+
+const MOONSHOT_BACKEND = {
+  transport: "anthropic-native",
+  base_url: "https://api.moonshot.ai/anthropic",
+  auth_env: "MOONSHOT_API_KEY",
+  capabilities: ["tool_use", "prompt_cache_hit", "long_context_262k"],
+  pricing: { input_per_m: 0.95, output_per_m: 4.0, cache_hit_per_m: 0.16 },
+  models: { default: "kimi-k2.6", fast: "kimi-k2.6" },
+};
+
+const QWEN_BACKEND = {
+  transport: "openai-compat",
+  base_url: "https://openrouter.ai/api/v1",
+  auth_env: "OPENROUTER_API_KEY",
+  capabilities: ["tool_use", "long_context_262k", "degraded_tool_use"], // mimic real-world OR bug
+  pricing: { input_per_m: 0.22, output_per_m: 1.8 },
+  models: { default: "qwen/qwen3-coder", fast: "qwen/qwen3-coder-flash" },
+};
+
+// ---------------------------------------------------------------------------
+// loadRoutingConfig
+// ---------------------------------------------------------------------------
+
+test("loadRoutingConfig returns null when no config exists", async () => {
+  const root = await makeAgentRoot();
+  try {
+    assert.equal(loadRoutingConfig(root), null);
+  } finally { await rmRoot(root); }
+});
+
+test("loadRoutingConfig parses JSON and synthesizes anthropic fallback", async () => {
+  const root = await makeAgentRoot();
+  try {
+    writeJsonConfig(root, {
+      backends: { moonshot: MOONSHOT_BACKEND },
+      routing_policy: [{ default: true, backend: "moonshot" }],
+    });
+    const cfg = loadRoutingConfig(root);
+    assert.ok(cfg, "config should load");
+    // Anthropic synthesised because fallback_to_anthropic defaulted to true.
+    assert.ok(cfg.backends.anthropic, "anthropic synthesised");
+    assert.equal(cfg.backends.moonshot.base_url, "https://api.moonshot.ai/anthropic");
+    assert.equal(cfg.routing_policy[0].backend, "moonshot");
+    assert.equal(cfg.fallback_to_anthropic, true);
+  } finally { await rmRoot(root); }
+});
+
+test("loadRoutingConfig respects explicit fallback_to_anthropic: false", async () => {
+  const root = await makeAgentRoot();
+  try {
+    writeJsonConfig(root, {
+      backends: { moonshot: MOONSHOT_BACKEND },
+      routing_policy: [{ default: true, backend: "moonshot" }],
+      fallback_to_anthropic: false,
+    });
+    const cfg = loadRoutingConfig(root);
+    assert.equal(cfg.backends.anthropic, undefined, "anthropic NOT synthesised");
+    assert.equal(cfg.fallback_to_anthropic, false);
+  } finally { await rmRoot(root); }
+});
+
+test("loadRoutingConfig throws on malformed JSON", async () => {
+  const root = await makeAgentRoot();
+  try {
+    writeFileSync(join(root, "config/model-routing.json"), "{ not valid json");
+    assert.throws(() => loadRoutingConfig(root), /not valid|JSON|parse/);
+  } finally { await rmRoot(root); }
+});
+
+test("loadRoutingConfig accepts $MAESTRO_ROUTING_CONFIG override", async () => {
+  const root = await makeAgentRoot();
+  const alt = await makeAgentRoot();
+  try {
+    const altPath = join(alt, "config/model-routing.json");
+    writeFileSync(altPath, JSON.stringify({
+      backends: { moonshot: MOONSHOT_BACKEND },
+      routing_policy: [{ default: true, backend: "moonshot" }],
+    }));
+    const prev = process.env.MAESTRO_ROUTING_CONFIG;
+    process.env.MAESTRO_ROUTING_CONFIG = altPath;
+    try {
+      const cfg = loadRoutingConfig(root);
+      assert.ok(cfg.backends.moonshot);
+    } finally {
+      if (prev === undefined) delete process.env.MAESTRO_ROUTING_CONFIG;
+      else process.env.MAESTRO_ROUTING_CONFIG = prev;
+    }
+  } finally {
+    await rmRoot(root);
+    await rmRoot(alt);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// resolveBackend
+// ---------------------------------------------------------------------------
+
+test("resolveBackend returns null when no config is loaded", () => {
+  const r = resolveBackend({ agent_role: "responder" }, { config: null });
+  assert.equal(r, null, "no config → no resolution (callers preserve current behaviour)");
+});
+
+test("resolveBackend picks default rule when nothing else matches", () => {
+  const config = {
+    backends: { anthropic: ANTHROPIC_BACKEND, moonshot: MOONSHOT_BACKEND },
+    routing_policy: [{ default: true, backend: "moonshot" }],
+    fallback_to_anthropic: true,
+    strip_attribution_header: true,
+    disable_experimental_betas: true,
+  };
+  const r = resolveBackend({ agent_role: "responder", tier: "default" }, { config, env: { MOONSHOT_API_KEY: "msk-test" } });
+  assert.equal(r.name, "moonshot");
+  assert.equal(r.model, "kimi-k2.6");
+  assert.equal(r.envForSpawn.ANTHROPIC_BASE_URL, "https://api.moonshot.ai/anthropic");
+  assert.equal(r.envForSpawn.ANTHROPIC_AUTH_TOKEN, "msk-test");
+  // Critical: API_KEY must be explicit empty string, not unset.
+  assert.equal(r.envForSpawn.ANTHROPIC_API_KEY, "");
+  assert.equal(r.envForSpawn.ANTHROPIC_MODEL, "kimi-k2.6");
+  assert.equal(r.envForSpawn.CLAUDE_CODE_ATTRIBUTION_HEADER, "0");
+  assert.equal(r.envForSpawn.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS, "1");
+});
+
+test("resolveBackend forces anthropic for sensitive roles via agent_role_in", () => {
+  const config = {
+    backends: { anthropic: ANTHROPIC_BACKEND, moonshot: MOONSHOT_BACKEND, qwen: QWEN_BACKEND },
+    routing_policy: [
+      { match: { agent_role_in: ["ceo_pre_pass", "audit", "decision_writer"] }, backend: "anthropic" },
+      { default: true, backend: "qwen" },
+    ],
+  };
+  const sensitive = resolveBackend({ agent_role: "ceo_pre_pass" }, { config });
+  assert.equal(sensitive.name, "anthropic");
+  assert.equal(sensitive.transport, "anthropic-cli");
+  // anthropic-cli mode injects no env — current CLI behaviour preserved.
+  assert.deepEqual(sensitive.envForSpawn, {});
+
+  const routine = resolveBackend({ agent_role: "log_triage" }, { config, env: { OPENROUTER_API_KEY: "or-test" } });
+  assert.equal(routine.name, "qwen");
+  assert.equal(routine.envForSpawn.ANTHROPIC_AUTH_TOKEN, "or-test");
+});
+
+test("resolveBackend falls through when backend lacks capability (no_thinking)", () => {
+  const config = {
+    backends: { anthropic: ANTHROPIC_BACKEND, qwen: QWEN_BACKEND },
+    routing_policy: [
+      { match: { needs_thinking: true }, backend: "qwen", fallback: ["anthropic"] },
+      { default: true, backend: "qwen" },
+    ],
+    fallback_to_anthropic: true,
+  };
+  const r = resolveBackend({ agent_role: "responder", needs_thinking: true }, { config });
+  // Qwen has no `thinking` cap → falls back to anthropic.
+  assert.equal(r.name, "anthropic");
+  assert.equal(r.tried[0].backend, "qwen");
+  assert.equal(r.tried[0].reason, "no_thinking");
+});
+
+test("resolveBackend rejects degraded_tool_use when caller needs reliable tools", () => {
+  const config = {
+    backends: { anthropic: ANTHROPIC_BACKEND, qwen: QWEN_BACKEND },
+    routing_policy: [
+      { match: { needs_tool_use: true }, backend: "qwen", fallback: ["anthropic"] },
+    ],
+    fallback_to_anthropic: true,
+  };
+  const r = resolveBackend({ agent_role: "responder", needs_tool_use: true }, { config });
+  assert.equal(r.name, "anthropic");
+  assert.equal(r.tried[0].backend, "qwen");
+  assert.equal(r.tried[0].reason, "degraded_tool_use");
+});
+
+test("resolveBackend honours token_estimate_gte for long-context routing", () => {
+  const config = {
+    backends: { anthropic: ANTHROPIC_BACKEND, moonshot: MOONSHOT_BACKEND },
+    routing_policy: [
+      { match: { token_estimate_gte: 60000 }, backend: "moonshot" },
+      { default: true, backend: "anthropic" },
+    ],
+  };
+  const short = resolveBackend({ token_estimate: 20000 }, { config });
+  const long = resolveBackend({ token_estimate: 120000 }, { config, env: { MOONSHOT_API_KEY: "msk" } });
+  assert.equal(short.name, "anthropic");
+  assert.equal(long.name, "moonshot");
+});
+
+test("resolveBackend honours model_hint legacy values (opus/sonnet/haiku)", () => {
+  const config = {
+    backends: { anthropic: ANTHROPIC_BACKEND },
+    routing_policy: [{ default: true, backend: "anthropic" }],
+  };
+  const opus = resolveBackend({ model_hint: "opus" }, { config });
+  const sonnet = resolveBackend({ model_hint: "sonnet" }, { config });
+  const haiku = resolveBackend({ model_hint: "haiku" }, { config });
+  assert.equal(opus.model, "claude-opus-4-7");
+  assert.equal(sonnet.model, "claude-sonnet-4-6");
+  assert.equal(haiku.model, "claude-haiku-4-5-20251001");
+  assert.equal(modelFlagFor(opus, { model_hint: "opus" }), "opus");
+  assert.equal(modelFlagFor(sonnet, { model_hint: "sonnet" }), "sonnet");
+  assert.equal(modelFlagFor(haiku, { model_hint: "haiku" }), "haiku");
+});
+
+test("resolveBackend returns null when no backend satisfies request and fallback disabled", () => {
+  const config = {
+    backends: { qwen: QWEN_BACKEND },
+    routing_policy: [{ default: true, backend: "qwen" }],
+    fallback_to_anthropic: false,
+  };
+  const r = resolveBackend({ needs_thinking: true }, { config });
+  assert.equal(r, null, "no fallback and no compatible backend → null");
+});
+
+test("resolveBackend tags fallback_reason when falling through to anthropic safety net", () => {
+  const config = {
+    backends: { anthropic: ANTHROPIC_BACKEND, qwen: QWEN_BACKEND },
+    routing_policy: [{ default: true, backend: "qwen" }],
+    fallback_to_anthropic: true,
+  };
+  const r = resolveBackend({ needs_thinking: true }, { config });
+  assert.equal(r.name, "anthropic");
+  assert.equal(r.fallback_reason, "no_compatible_backend");
+});
+
+// ---------------------------------------------------------------------------
+// estimateCost
+// ---------------------------------------------------------------------------
+
+test("estimateCost returns null without pricing data", () => {
+  const fake = { pricing: {} };
+  assert.equal(estimateCost({ token_estimate: 1000 }, fake), null);
+});
+
+test("estimateCost computes per-million-token cost without cache hits", () => {
+  const fake = { pricing: { input_per_m: 3.0, output_per_m: 15.0 } };
+  const cost = estimateCost({ token_estimate: 1_000_000, token_estimate_out: 500_000 }, fake);
+  // 1M input @ $3 + 0.5M output @ $15 = $3 + $7.5 = $10.5
+  assert.equal(cost, 10.5);
+});
+
+test("estimateCost honours cache_hit_per_m for Moonshot-style caching", () => {
+  const fake = { pricing: { input_per_m: 0.95, output_per_m: 4.0, cache_hit_per_m: 0.16 } };
+  // 1M tokens, 80% cache hit, no explicit output → defaults to 0.5M output
+  const cost = estimateCost({ token_estimate: 1_000_000, cache_hit_ratio: 0.8 }, fake);
+  // input: 200k @ 0.95 + 800k @ 0.16 = 0.19 + 0.128 = 0.318
+  // output: 500k @ 4.0 = 2.0
+  // total: 2.318
+  assert.ok(Math.abs(cost - 2.318) < 0.001, `got ${cost}`);
+});
+
+// ---------------------------------------------------------------------------
+// listBackends / describeBackend
+// ---------------------------------------------------------------------------
+
+test("listBackends defaults to ['anthropic'] when no config", () => {
+  assert.deepEqual(listBackends({ config: null }), ["anthropic"]);
+});
+
+test("listBackends returns all configured backend keys", () => {
+  const config = {
+    backends: { anthropic: ANTHROPIC_BACKEND, moonshot: MOONSHOT_BACKEND, qwen: QWEN_BACKEND },
+    routing_policy: [],
+  };
+  assert.deepEqual(listBackends({ config }).sort(), ["anthropic", "moonshot", "qwen"]);
+});
+
+test("describeBackend returns model/transport/pricing for a backend", () => {
+  const config = {
+    backends: { moonshot: MOONSHOT_BACKEND },
+    routing_policy: [],
+  };
+  const d = describeBackend("moonshot", { config });
+  assert.equal(d.name, "moonshot");
+  assert.equal(d.transport, "anthropic-native");
+  assert.equal(d.base_url, "https://api.moonshot.ai/anthropic");
+  assert.equal(d.models.default, "kimi-k2.6");
+});
+
+// ---------------------------------------------------------------------------
+// requestFromClassifierResult
+// ---------------------------------------------------------------------------
+
+test("requestFromClassifierResult preserves priority + model hint", () => {
+  const req = requestFromClassifierResult(
+    { priority: "critical", model: "opus", summary: "CEO request" },
+    { role: "responder", source: "inbox" }
+  );
+  assert.equal(req.priority, "critical");
+  assert.equal(req.model_hint, "opus");
+  assert.equal(req.needs_thinking, true);
+  assert.equal(req.needs_tool_use, true);
+  assert.equal(req.agent_role, "responder");
+});
+
+test("requestFromClassifierResult does NOT set needs_thinking for routine sonnet items", () => {
+  const req = requestFromClassifierResult(
+    { priority: "normal", model: "sonnet" },
+    { role: "responder" }
+  );
+  assert.equal(req.needs_thinking, undefined);
+  assert.equal(req.model_hint, "sonnet");
+});
+
+// ---------------------------------------------------------------------------
+// Foot-gun fixes (audit W5 / W8 + kill switch)
+// ---------------------------------------------------------------------------
+
+test("W5: session work defaults needs_tool_use=true even for routine items", () => {
+  // A normal-priority backlog item is still a full agent session — it must
+  // declare tool use so a degraded_tool_use backend is rejected.
+  const req = requestFromClassifierResult(
+    { priority: "normal", model: "sonnet" },
+    { role: "responder", source: "backlog" }
+  );
+  assert.equal(req.needs_tool_use, true, "session work needs tool use by default");
+});
+
+test("W5: one-shot lookups may opt out of needs_tool_use", () => {
+  const req = requestFromClassifierResult(
+    { priority: "normal", model: "sonnet" },
+    { role: "lookup", oneShot: true }
+  );
+  assert.equal(req.needs_tool_use, false, "one-shot lookups opt out");
+});
+
+test("W5: shipped-example backlog item is kept off the degraded_tool_use backend", () => {
+  // Mirrors scaffold/config/model-routing.yaml.example: a normal backlog item
+  // matched `source: backlog → openrouter_qwen` (degraded_tool_use). With
+  // needs_tool_use defaulting true, the capability gate now fires and the
+  // request falls through to a tool-capable backend.
+  const config = {
+    backends: { anthropic: ANTHROPIC_BACKEND, moonshot: MOONSHOT_BACKEND, qwen: QWEN_BACKEND },
+    routing_policy: [
+      { match: { source: "backlog" }, backend: "qwen", fallback: ["moonshot", "anthropic"] },
+      { default: true, backend: "moonshot", fallback: ["anthropic"] },
+    ],
+    fallback_to_anthropic: true,
+  };
+  const req = requestFromClassifierResult(
+    { priority: "normal", model: "sonnet" },
+    { role: "responder", source: "backlog" }
+  );
+  const r = resolveBackend(req, { config, env: { MOONSHOT_API_KEY: "msk" } });
+  assert.notEqual(r.name, "qwen", "must NOT route a tool-using session to degraded_tool_use backend");
+  assert.equal(r.name, "moonshot");
+  assert.equal(r.tried[0].backend, "qwen");
+  assert.equal(r.tried[0].reason, "degraded_tool_use");
+});
+
+test("W8: candidate with missing auth env is skipped, not spawned with empty token", () => {
+  const config = {
+    backends: { anthropic: ANTHROPIC_BACKEND, moonshot: MOONSHOT_BACKEND },
+    routing_policy: [{ default: true, backend: "moonshot", fallback: ["anthropic"] }],
+    fallback_to_anthropic: true,
+  };
+  // MOONSHOT_API_KEY deliberately absent from env.
+  const r = resolveBackend({ agent_role: "responder", tier: "default" }, { config, env: {} });
+  assert.equal(r.name, "anthropic", "skips moonshot, lands on anthropic safety net");
+  assert.equal(r.tried[0].backend, "moonshot");
+  assert.equal(r.tried[0].reason, "missing_auth_env");
+  // The anthropic-cli safety net injects no empty credential.
+  assert.deepEqual(r.envForSpawn, {});
+});
+
+test("W8: empty/whitespace auth env counts as absent and is skipped", () => {
+  const config = {
+    backends: { anthropic: ANTHROPIC_BACKEND, moonshot: MOONSHOT_BACKEND },
+    routing_policy: [{ default: true, backend: "moonshot", fallback: ["anthropic"] }],
+    fallback_to_anthropic: true,
+  };
+  const r = resolveBackend({ agent_role: "responder" }, { config, env: { MOONSHOT_API_KEY: "   " } });
+  assert.equal(r.name, "anthropic");
+  assert.equal(r.tried[0].reason, "missing_auth_env");
+});
+
+test("W8: all candidates missing auth + no fallback → null (never empty spawn)", () => {
+  const config = {
+    backends: { moonshot: MOONSHOT_BACKEND },
+    routing_policy: [{ default: true, backend: "moonshot" }],
+    fallback_to_anthropic: false,
+  };
+  const r = resolveBackend({ agent_role: "responder" }, { config, env: {} });
+  assert.equal(r, null, "no creds anywhere and no fallback → no resolution");
+});
+
+test("W8: present auth env still resolves normally (no regression)", () => {
+  const config = {
+    backends: { anthropic: ANTHROPIC_BACKEND, moonshot: MOONSHOT_BACKEND },
+    routing_policy: [{ default: true, backend: "moonshot", fallback: ["anthropic"] }],
+    fallback_to_anthropic: true,
+  };
+  const r = resolveBackend({ agent_role: "responder" }, { config, env: { MOONSHOT_API_KEY: "msk-ok" } });
+  assert.equal(r.name, "moonshot");
+  assert.equal(r.envForSpawn.ANTHROPIC_AUTH_TOKEN, "msk-ok");
+});
+
+test("kill switch: MAESTRO_ROUTER_FORCE_ANTHROPIC=1 short-circuits to stock behaviour", () => {
+  const config = {
+    backends: { anthropic: ANTHROPIC_BACKEND, moonshot: MOONSHOT_BACKEND },
+    routing_policy: [{ default: true, backend: "moonshot" }],
+    fallback_to_anthropic: true,
+  };
+  // Even with a valid Moonshot key and a default-moonshot policy, the kill
+  // switch returns null — the same path as no config, so callers preserve
+  // the legacy keychain-OAuth `claude --print` behaviour.
+  const r = resolveBackend(
+    { agent_role: "responder" },
+    { config, env: { MAESTRO_ROUTER_FORCE_ANTHROPIC: "1", MOONSHOT_API_KEY: "msk" } }
+  );
+  assert.equal(r, null, "kill switch → null (stock Anthropic CLI behaviour)");
+});
+
+test("kill switch: accepts 'true' as well as '1'", () => {
+  const config = {
+    backends: { anthropic: ANTHROPIC_BACKEND, moonshot: MOONSHOT_BACKEND },
+    routing_policy: [{ default: true, backend: "moonshot" }],
+  };
+  const r = resolveBackend(
+    { agent_role: "responder" },
+    { config, env: { MAESTRO_ROUTER_FORCE_ANTHROPIC: "true", MOONSHOT_API_KEY: "msk" } }
+  );
+  assert.equal(r, null);
+});
+
+test("kill switch: any other value does NOT short-circuit", () => {
+  const config = {
+    backends: { anthropic: ANTHROPIC_BACKEND, moonshot: MOONSHOT_BACKEND },
+    routing_policy: [{ default: true, backend: "moonshot" }],
+  };
+  const r = resolveBackend(
+    { agent_role: "responder" },
+    { config, env: { MAESTRO_ROUTER_FORCE_ANTHROPIC: "0", MOONSHOT_API_KEY: "msk" } }
+  );
+  assert.equal(r.name, "moonshot", "0/unset → routing still active");
+});
+
+// ---------------------------------------------------------------------------
+// defaultRoutingConfig wiring (audit L21)
+// ---------------------------------------------------------------------------
+
+test("defaultRoutingConfig returns a usable Anthropic-only config", () => {
+  const cfg = defaultRoutingConfig();
+  assert.ok(cfg, "default config should be an object");
+  assert.ok(cfg.backends.anthropic, "default config has an anthropic backend");
+  assert.equal(cfg.backends.anthropic.transport, "anthropic-cli");
+  assert.equal(cfg.fallback_to_anthropic, true);
+  // resolveBackend must accept it and preserve current CLI behaviour (no env).
+  const r = resolveBackend({ agent_role: "responder" }, { config: cfg });
+  assert.equal(r.name, "anthropic");
+  assert.equal(r.transport, "anthropic-cli");
+  assert.deepEqual(r.envForSpawn, {}, "anthropic-cli default injects no env");
+});
+
+test("defaultRoutingConfig returns a fresh, mutation-safe copy each call", () => {
+  const a = defaultRoutingConfig();
+  const b = defaultRoutingConfig();
+  assert.notEqual(a, b, "each call returns a distinct object");
+  a.backends.anthropic.models.default = "MUTATED";
+  assert.notEqual(
+    b.backends.anthropic.models.default,
+    "MUTATED",
+    "mutating one copy must not affect another",
+  );
+});
+
+test("loadRoutingConfig still returns null with no config and no useDefault flag", async () => {
+  const root = await makeAgentRoot();
+  try {
+    assert.equal(loadRoutingConfig(root), null, "default contract preserved");
+  } finally { await rmRoot(root); }
+});
+
+test("loadRoutingConfig({ useDefault: true }) returns the default when no file exists", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const cfg = loadRoutingConfig(root, { useDefault: true });
+    assert.ok(cfg, "useDefault yields a config instead of null");
+    assert.ok(cfg.backends.anthropic, "it is the anthropic default");
+    assert.equal(cfg.fallback_to_anthropic, true);
+  } finally { await rmRoot(root); }
+});
+
+test("loadRoutingConfig prefers a real file over the useDefault fallback", async () => {
+  const root = await makeAgentRoot();
+  try {
+    writeJsonConfig(root, {
+      backends: { moonshot: MOONSHOT_BACKEND },
+      routing_policy: [{ default: true, backend: "moonshot" }],
+    });
+    const cfg = loadRoutingConfig(root, { useDefault: true });
+    assert.ok(cfg.backends.moonshot, "real config wins over the default fallback");
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// Constants exported
+// ---------------------------------------------------------------------------
+
+test("CONFIG_RELATIVE_PATH points at config/model-routing.yaml", () => {
+  assert.equal(CONFIG_RELATIVE_PATH, "config/model-routing.yaml");
+});
+
+// ===========================================================================
+// resolveChain — the v2 policy brain (additive; v1 above stays byte-compatible)
+// ===========================================================================
+
+// One shared bundled catalog snapshot (read-only) for the resolve tests. Loaded
+// from the framework's own lib/model-router/catalog/*.yaml so the refs are real.
+// This file lives at <root>/lib/, so the framework root is one dir up.
+const MAESTRO_ROOT_FOR_TESTS = () =>
+  join(fileURLToPath(new URL(".", import.meta.url)), "..");
+const CATALOG = loadCatalog(MAESTRO_ROOT_FOR_TESTS(), {});
+
+const V2_CONFIG = Object.freeze({
+  schema_version: 2,
+  aliases: {
+    frontier: "anthropic/claude-opus-4-8",
+    default: "anthropic/claude-sonnet-4-6",
+    fast: "anthropic/claude-haiku-4-5",
+    cheap: "deepseek/deepseek-v4-flash",
+    "cheap-session": "moonshot/kimi-k2.6",
+  },
+  defaults: { needs_tool_use_for_sessions: true, data_class: "sensitive", cache_ttl: "1h" },
+  backends: {
+    anthropic: { allowed_data_classes: ["public", "internal", "sensitive"] },
+    deepseek: { allowed_data_classes: ["public"] },
+    moonshot: { allowed_data_classes: ["public"] },
+  },
+  routing_policy: [
+    { match: { agent_role_in: ["regulatory", "audit"] }, chain: ["frontier", "default"], pin: true },
+    { match: { task_class: "classify.inbox" }, harness: "direct", chain: ["fast", "cheap", "rules"], needs_tool_use: false },
+    { match: { task_class: "lookup.gmail" }, harness: "direct", chain: ["fast", "cheap"], needs_tool_use: false },
+    { match: { source: "backlog", data_class: "public" }, chain: ["cheap", "default"] },
+    { match: { token_estimate_gte: 250000 }, chain: ["default", "frontier"] },
+    { default: true, chain: ["default", "fast"] },
+  ],
+  budget_ladder: {
+    "75": { downgrade_tiers: 1 },
+    "90": { force_alias: "cheap_or_fast" },
+    "100": { essential_only: true },
+  },
+  fallback_to_anthropic: true,
+});
+
+const CLOCK = () => 1_718_000_000_000;
+function rc(req, extra = {}) {
+  return resolveChain(req, { catalog: CATALOG, config: V2_CONFIG, env: {}, now: CLOCK, ...extra });
+}
+
+// ── rule match + chain build ───────────────────────────────────────────────
+
+test("resolveChain: default rule routes a session to the default workhorse", () => {
+  const d = rc({ task_class: "session.responder", source: "inbox", data_class: "sensitive", token_estimate: 5000 });
+  assert.equal(d.chosen.provider, "anthropic");
+  assert.equal(d.chosen.model, "claude-sonnet-4-6");
+  assert.equal(d.chosen.harness, "session");
+  assert.ok(d.decision_id, "every decision has an id");
+  assert.ok(d.explain && typeof d.explain === "string", "explain is mandatory");
+});
+
+test("resolveChain: first-match picks the regulatory pin rule (frontier)", () => {
+  const d = rc({ agent_role: "regulatory", task_class: "decision.writer", data_class: "sensitive", token_estimate: 1000 });
+  assert.equal(d.chosen.model, "claude-opus-4-8", "regulatory → frontier");
+  // The visible chain leads with the matched rule's first alias.
+  assert.equal(d.chain[0].ref, "anthropic/claude-opus-4-8");
+});
+
+test("resolveChain: classify.inbox resolves direct harness + tool-less", () => {
+  // Anthropic direct needs the key; with a key present, fast (haiku) is chosen.
+  const d = resolveChain(
+    { task_class: "classify.inbox", source: "inbox", data_class: "public", token_estimate: 1500 },
+    { catalog: CATALOG, config: V2_CONFIG, env: { ANTHROPIC_API_KEY: "ak" }, now: CLOCK }
+  );
+  assert.equal(d.chosen.harness, "direct");
+  assert.equal(d.chosen.model, "claude-haiku-4-5");
+});
+
+test("resolveChain: the chain[] carries the failover tail, not just the winner", () => {
+  const d = rc({ task_class: "session.responder", data_class: "sensitive", token_estimate: 1000 });
+  // default chain is [default, fast]; both Anthropic session rows survive.
+  const refs = d.chain.map((c) => c.ref);
+  assert.deepEqual(refs, ["anthropic/claude-sonnet-4-6", "anthropic/claude-haiku-4-5"]);
+});
+
+// ── credential gate (key-absence-as-enforcement, §7.1) ──────────────────────
+
+test("resolveChain: a third-party row without its key is skipped (missing_credential)", () => {
+  // lookup.gmail is harness:direct, needs_tool_use:false so deepseek (grade B)
+  // clears the capability gate — the ONLY reason left to skip it is the absent
+  // DEEPSEEK_API_KEY (key-absence-as-enforcement, §7.1). Anthropic haiku direct
+  // also needs its key (absent) so the chain ends on the Anthropic safety net.
+  const d = rc({ task_class: "lookup.gmail", data_class: "public", token_estimate: 1000 });
+  const skipped = d.tried.find((t) => t.ref === "deepseek/deepseek-v4-flash");
+  assert.ok(skipped, "deepseek recorded in tried[]");
+  assert.equal(skipped.reason, "missing_credential");
+});
+
+test("resolveChain: present third-party key still gated by grade for sessions (B<A)", () => {
+  // deepseek is grade B; a session needing tools requires grade A (§6.6), so even
+  // WITH the key it is skipped grade_too_low and we fall to Anthropic.
+  const d = resolveChain(
+    { task_class: "backlog.work", source: "backlog", data_class: "public", token_estimate: 1000 },
+    { catalog: CATALOG, config: V2_CONFIG, env: { DEEPSEEK_API_KEY: "dk" }, now: CLOCK }
+  );
+  assert.equal(d.chosen.provider, "anthropic");
+  const skipped = d.tried.find((t) => t.ref === "deepseek/deepseek-v4-flash");
+  assert.equal(skipped.reason, "grade_too_low");
+});
+
+test("resolveChain: grade-B row IS reachable on the direct (tool-less) lane", () => {
+  // lookup.gmail is harness:direct, needs_tool_use:false; deepseek (B) is fine.
+  // Anthropic haiku (direct) needs ANTHROPIC_API_KEY (absent) so it is skipped,
+  // landing on deepseek with its key present.
+  const d = resolveChain(
+    { task_class: "lookup.gmail", data_class: "public", token_estimate: 1000 },
+    { catalog: CATALOG, config: V2_CONFIG, env: { DEEPSEEK_API_KEY: "dk" }, now: CLOCK }
+  );
+  assert.equal(d.chosen.provider, "deepseek");
+  assert.equal(d.chosen.harness, "direct");
+});
+
+// ── data_class gate (deny-by-default, §7.6) ─────────────────────────────────
+
+test("resolveChain: sensitive data never routes to a public-only backend", () => {
+  // Even with the key AND a direct lane, deepseek (allowed: public) is denied for
+  // a sensitive request and recorded as data_class_denied.
+  const cfg = { ...V2_CONFIG, routing_policy: [{ match: { task_class: "lookup.gmail" }, harness: "direct", chain: ["cheap", "fast"], needs_tool_use: false }, { default: true, chain: ["default"] }] };
+  const d = resolveChain(
+    { task_class: "lookup.gmail", data_class: "sensitive", token_estimate: 1000 },
+    { catalog: CATALOG, config: cfg, env: { DEEPSEEK_API_KEY: "dk", ANTHROPIC_API_KEY: "ak" }, now: CLOCK }
+  );
+  assert.equal(d.chosen.provider, "anthropic", "sensitive falls back to anthropic");
+  const denied = d.tried.find((t) => t.ref === "deepseek/deepseek-v4-flash");
+  assert.equal(denied.reason, "data_class_denied");
+});
+
+// ── breaker gate (health.isOpen) ────────────────────────────────────────────
+
+test("resolveChain: an open breaker skips the candidate (breaker_open in tried[])", () => {
+  // Inject an isOpen that reports the sonnet model breaker open; chain falls to
+  // the next survivor (haiku).
+  const isOpen = (key) => ({
+    open: key === "anthropic:claude-sonnet-4-6",
+    until: 1_718_000_100_000,
+    reason: "rate_limit",
+    strikes: 1,
+  });
+  const d = resolveChain(
+    { task_class: "session.responder", data_class: "sensitive", token_estimate: 1000 },
+    { catalog: CATALOG, config: V2_CONFIG, env: {}, now: CLOCK, isOpen }
+  );
+  assert.equal(d.chosen.model, "claude-haiku-4-5", "skips open sonnet, lands on haiku");
+  const skipped = d.tried.find((t) => t.ref === "anthropic/claude-sonnet-4-6");
+  assert.equal(skipped.reason, "breaker_open");
+});
+
+// ── context gate ────────────────────────────────────────────────────────────
+
+test("resolveChain: a too-large request skips a small-context row (context_overflow)", () => {
+  // haiku context_tokens is 190000; a 250k request matches the long-context rule
+  // [default, frontier] (both 950k) and never even tries a small row. To assert
+  // the gate directly, force a chain through haiku for a huge prompt.
+  const cfg = { ...V2_CONFIG, routing_policy: [{ default: true, chain: ["fast", "default"] }] };
+  const d = resolveChain(
+    { task_class: "session.responder", data_class: "sensitive", token_estimate: 500000 },
+    { catalog: CATALOG, config: cfg, env: {}, now: CLOCK }
+  );
+  assert.equal(d.chosen.model, "claude-sonnet-4-6", "haiku too small → sonnet");
+  const skipped = d.tried.find((t) => t.ref === "anthropic/claude-haiku-4-5");
+  assert.equal(skipped.reason, "context_overflow");
+});
+
+test("resolveChain: long-context rule routes 250k+ to a 1M-ctx row", () => {
+  const d = rc({ task_class: "session.responder", data_class: "sensitive", token_estimate: 300000 });
+  assert.equal(d.chosen.model, "claude-sonnet-4-6");
+});
+
+// ── envForSpawn (session retarget for Kimi/DeepSeek) ─────────────────────────
+
+test("resolveChain: a third-party SESSION row builds the ANTHROPIC_BASE_URL retarget env", () => {
+  // Allow a grade override so kimi (B) can host a session, and route public work
+  // to it with the key present.
+  const cfg = {
+    ...V2_CONFIG,
+    catalog_overrides: undefined,
+    routing_policy: [{ match: { source: "backlog" }, chain: ["cheap-session", "default"] }, { default: true, chain: ["default"] }],
+  };
+  // Override kimi grade to A via catalog_overrides so the session grade gate passes.
+  const cat = loadCatalog(MAESTRO_ROOT_FOR_TESTS(), {
+    agentConfig: { catalog_overrides: [{ ref: "moonshot/kimi-k2.6", tool_reliability: "A" }] },
+  });
+  const d = resolveChain(
+    { task_class: "backlog.work", source: "backlog", data_class: "public", token_estimate: 1000 },
+    { catalog: cat, config: cfg, env: { MOONSHOT_API_KEY: "mk-test" }, now: CLOCK }
+  );
+  assert.equal(d.chosen.provider, "moonshot");
+  assert.equal(d.chosen.transport, "anthropic-native");
+  assert.equal(d.envForSpawn.ANTHROPIC_BASE_URL, "https://api.moonshot.ai/anthropic");
+  assert.equal(d.envForSpawn.ANTHROPIC_AUTH_TOKEN, "mk-test");
+  assert.equal(d.envForSpawn.ANTHROPIC_API_KEY, "", "empty string, NOT unset (keychain-fallthrough guard)");
+  assert.equal(d.envForSpawn.ANTHROPIC_MODEL, "kimi-k2.6");
+});
+
+test("resolveChain: an Anthropic session injects NO retarget env (stock CLI)", () => {
+  const d = rc({ task_class: "session.responder", data_class: "sensitive", token_estimate: 1000 });
+  assert.deepEqual(d.envForSpawn, {});
+});
+
+// ── budget ladder ────────────────────────────────────────────────────────────
+
+test("resolveChain: band ≥75 downgrades one tier (default→fast) for non-pinned work", () => {
+  const d = rc({ task_class: "session.responder", data_class: "sensitive", token_estimate: 1000, budget_band: 75 });
+  assert.equal(d.chosen.model, "claude-haiku-4-5", "default downgraded to fast at band 75");
+  assert.match(d.explain, /band 75/);
+});
+
+test("resolveChain: a pinned rule is exempt from the budget ladder", () => {
+  // regulatory rule sets pin:true on the request indirectly via the rule pin flag;
+  // pass pin on the request to exercise the exemption path.
+  const d = rc({ agent_role: "regulatory", task_class: "decision", data_class: "sensitive", token_estimate: 1000, budget_band: 90, pin: { ref: "anthropic/claude-opus-4-8" } });
+  assert.equal(d.chosen.model, "claude-opus-4-8", "pin beats the band-90 downgrade");
+});
+
+// ── affinity pin ─────────────────────────────────────────────────────────────
+
+test("resolveChain: a live affinity pin is moved to the chain head when it passes gates", () => {
+  const d = rc({ task_class: "session.responder", data_class: "sensitive", token_estimate: 1000, session_key: "thread-1", pin: { ref: "anthropic/claude-haiku-4-5" } });
+  assert.equal(d.chosen.model, "claude-haiku-4-5");
+  assert.equal(d.chain[0].ref, "anthropic/claude-haiku-4-5", "pin at head");
+  assert.match(d.explain, /pin /);
+});
+
+test("resolveChain: a pin that fails a gate emits pin_overridden and routes normally", () => {
+  // Pin a public-only deepseek for sensitive work → data_class_denied → overridden.
+  const d = resolveChain(
+    { task_class: "session.responder", data_class: "sensitive", token_estimate: 1000, pin: { ref: "deepseek/deepseek-v4-flash" } },
+    { catalog: CATALOG, config: V2_CONFIG, env: { DEEPSEEK_API_KEY: "dk" }, now: CLOCK }
+  );
+  assert.equal(d.chosen.provider, "anthropic", "overridden pin falls to normal routing");
+  const overridden = d.tried.find((t) => String(t.reason).startsWith("pin_overridden"));
+  assert.ok(overridden, "pin_overridden recorded in tried[]");
+});
+
+// ── kill switch ──────────────────────────────────────────────────────────────
+
+test("resolveChain: MAESTRO_ROUTER_FORCE_ANTHROPIC forces an Anthropic-only chain", () => {
+  const d = resolveChain(
+    { task_class: "backlog.work", source: "backlog", data_class: "public", token_estimate: 1000 },
+    { catalog: CATALOG, config: V2_CONFIG, env: { MAESTRO_ROUTER_FORCE_ANTHROPIC: "1", DEEPSEEK_API_KEY: "dk" }, now: CLOCK }
+  );
+  assert.equal(d.chosen.provider, "anthropic");
+  assert.equal(d.audit.fallback_reason, "kill_switch");
+  assert.match(d.explain, /kill switch/);
+  // No third-party retarget env under the kill switch.
+  assert.deepEqual(d.envForSpawn, {});
+});
+
+test("resolveChain: kill switch picks frontier for critical/thinking work", () => {
+  const d = resolveChain(
+    { task_class: "decision", needs_thinking: true, data_class: "sensitive", token_estimate: 1000 },
+    { catalog: CATALOG, config: V2_CONFIG, env: { MAESTRO_ROUTER_FORCE_ANTHROPIC: "true" }, now: CLOCK }
+  );
+  assert.equal(d.chosen.model, "claude-opus-4-8");
+});
+
+// ── inert / no-config collapse ───────────────────────────────────────────────
+
+test("resolveChain: no v2 config collapses to the Anthropic safety net", () => {
+  const d = resolveChain(
+    { task_class: "session.responder", data_class: "sensitive", token_estimate: 1000 },
+    { catalog: CATALOG, config: null, env: {}, now: CLOCK }
+  );
+  assert.equal(d.chosen.provider, "anthropic");
+  assert.equal(d.audit.fallback_reason, "no_v2_config");
+});
+
+// ── estCostUSD + ledger join fields ──────────────────────────────────────────
+
+test("resolveChain: stamps a finite estCostUSD and a decision_id for the ledger join", () => {
+  const d = rc({ task_class: "session.responder", data_class: "sensitive", token_estimate: 100000, token_estimate_out: 20000 });
+  assert.ok(typeof d.estCostUSD === "number" && d.estCostUSD > 0, "priced from the catalog row");
+  assert.ok(/^[0-9a-z]{18}$/.test(d.decision_id), "ulid-ish decision_id");
+  assert.equal(d.spawnArgs.bare, true);
+  assert.ok(d.spawnArgs.maxTurns > 0);
+});
+
+// ── deterministic "rules" fallback ───────────────────────────────────────────
+
+test("resolveChain: falls to the deterministic rules member when no model survives", () => {
+  // classify.inbox chain is [fast, cheap, rules]; with no keys at all, both
+  // model rows are unreachable and the caller's deterministic fallback wins.
+  const d = rc({ task_class: "classify.inbox", source: "inbox", data_class: "public", token_estimate: 1000 });
+  assert.equal(d.chosen.provider, "rules");
+  assert.equal(d.chosen.harness, "direct");
+});
+
+// ===========================================================================
+// validateRoutingConfig — strict v2 config validation
+// ===========================================================================
+
+test("validateRoutingConfig: a clean v2 config has zero errors", () => {
+  const { errors } = validateRoutingConfig(V2_CONFIG, { catalog: CATALOG, env: {} });
+  assert.equal(errors.length, 0, JSON.stringify(errors));
+});
+
+test("validateRoutingConfig: unknown match key is an error (capability typo)", () => {
+  const cfg = { ...V2_CONFIG, routing_policy: [{ match: { taks_class: "x" }, chain: ["default"] }, { default: true, chain: ["default"] }] };
+  const { errors } = validateRoutingConfig(cfg, { catalog: CATALOG });
+  assert.ok(errors.some((e) => /unknown match key "taks_class"/.test(e.error)));
+});
+
+test("validateRoutingConfig: a chain ref not in the catalog is an error", () => {
+  const cfg = { ...V2_CONFIG, aliases: { ...V2_CONFIG.aliases, ghost: "ghost/model-x" }, routing_policy: [{ default: true, chain: ["ghost"] }] };
+  const { errors } = validateRoutingConfig(cfg, { catalog: CATALOG });
+  assert.ok(errors.some((e) => /not in catalog/.test(e.error)));
+});
+
+test("validateRoutingConfig: a chain member that is neither alias nor ref is an error", () => {
+  const cfg = { ...V2_CONFIG, routing_policy: [{ default: true, chain: ["notanalias"] }] };
+  const { errors } = validateRoutingConfig(cfg, { catalog: CATALOG });
+  assert.ok(errors.some((e) => /neither a known alias nor/.test(e.error)));
+});
+
+test("validateRoutingConfig: an unknown harness is an error", () => {
+  const cfg = { ...V2_CONFIG, routing_policy: [{ match: { task_class: "x" }, harness: "telepathy", chain: ["default"] }, { default: true, chain: ["default"] }] };
+  const { errors } = validateRoutingConfig(cfg, { catalog: CATALOG });
+  assert.ok(errors.some((e) => /unknown harness "telepathy"/.test(e.error)));
+});
+
+test("validateRoutingConfig: an overlay-excluded backend in config is an error (tighten-only)", () => {
+  const overlay = { version: "t1", constraints: { backends_allowed: ["anthropic", "deepseek"] } };
+  // config declares a moonshot backend the overlay does not permit.
+  const { errors } = validateRoutingConfig(V2_CONFIG, { catalog: CATALOG, overlay });
+  assert.ok(errors.some((e) => /not in the org overlay's backends_allowed/.test(e.error)));
+});
+
+test("validateRoutingConfig: a missing third-party key is a WARNING, not an error", () => {
+  const { errors, warnings } = validateRoutingConfig(V2_CONFIG, { catalog: CATALOG, env: {} });
+  assert.equal(errors.length, 0);
+  assert.ok(warnings.some((w) => /DEEPSEEK_API_KEY/.test(w.warning)));
+  // Anthropic's key is never warned (session rides keychain OAuth).
+  assert.ok(!warnings.some((w) => /ANTHROPIC_API_KEY/.test(w.warning)));
+});
+
+test("validateRoutingConfig: a v1 config is not strict-validated (returns clean)", () => {
+  const { errors } = validateRoutingConfig({ backends: {}, routing_policy: [] }, { catalog: CATALOG });
+  assert.equal(errors.length, 0);
+});