@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/model-router.test.mjs

@@ -1,1207 +0,0 @@
-/**
- * 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, rmSync, 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";
-// Read-only, to PROVE (not assume) that a provider the SDK does not bundle
-// inherits credential pooling from the catalog rather than needing new code.
-import { loadAuthProfiles, authEnvMapFromCatalog } from "./model-router/auth-profiles.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 },
-  // A CONFIG-DECLARED model map. Deliberately NOT the same ids as
-  // ANTHROPIC_DEFAULT: these tests assert that a config's own map is what
-  // resolveBackend serves, so pinning them to the built-in defaults would make
-  // the assertions vacuous (they would pass even if the config map were being
-  // ignored entirely). The built-in defaults get their own test below.
-  models: {
-    classifier: "claude-haiku-4-5-20251001",
-    default: "config-declared-sonnet",
-    premium: "config-declared-opus",
-    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, "config-declared-opus");
-  assert.equal(sonnet.model, "config-declared-sonnet");
-  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");
-});
-
-// ---------------------------------------------------------------------------
-// Model freshness — the built-in Anthropic defaults (see the provenance block
-// above ANTHROPIC_DEFAULT in model-router.mjs).
-// ---------------------------------------------------------------------------
-
-test("defaultRoutingConfig ships the CURRENT Anthropic ids, not last quarter's", () => {
-  // The floor an agent with no routing config lands on. A stale id here never
-  // reached the wire (anthropic-cli sends the "opus"/"sonnet" shorthand), but it
-  // DID reach resolved.model, which the cost ledger and telemetry store — so a
-  // stale id mis-prices and mis-attributes every unrouted session.
-  const models = defaultRoutingConfig().backends.anthropic.models;
-  assert.equal(models.premium, "claude-opus-5");
-  assert.equal(models.default, "claude-sonnet-5");
-  // The fast/classifier tier did NOT move in the 2026-08-13 refresh.
-  assert.equal(models.fast, "claude-haiku-4-5-20251001");
-  assert.equal(models.classifier, "claude-haiku-4-5-20251001");
-  // Guard the specific regression: no 4.x id survives anywhere in the map.
-  for (const [tier, id] of Object.entries(models)) {
-    assert.ok(!/^claude-(opus|sonnet)-4/.test(id), `${tier} still pinned to a retired id: ${id}`);
-  }
-});
-
-test("resolveBackend serves the current ids through the no-config default path", () => {
-  // End-to-end through the resolver, not just the constant: an agent with no
-  // config file (useDefault) resolves premium/default to the -5 pair.
-  const config = defaultRoutingConfig();
-  assert.equal(resolveBackend({ model_hint: "opus" }, { config }).model, "claude-opus-5");
-  assert.equal(resolveBackend({ model_hint: "sonnet" }, { config }).model, "claude-sonnet-5");
-  // …while the CLI flag stays version-agnostic, which is WHY the stale ids were
-  // survivable on the wire and only corrupted the ledger.
-  assert.equal(modelFlagFor(resolveBackend({ model_hint: "opus" }, { config }), { model_hint: "opus" }), "opus");
-});
-
-test("a config-declared models map still outranks the built-in defaults (the no-PR refresh path)", () => {
-  // Refresh path #2 in the provenance block: when claude-opus-6 ships, a v1
-  // agent adds backends.anthropic.models to config/model-routing.yaml and is
-  // current WITHOUT an SDK release. normaliseConfig only injects the built-in
-  // map when backends.anthropic is absent, so this must win outright.
-  const config = {
-    backends: { anthropic: { ...ANTHROPIC_BACKEND, models: { ...ANTHROPIC_BACKEND.models, premium: "claude-opus-99" } } },
-    routing_policy: [{ default: true, backend: "anthropic" }],
-  };
-  assert.equal(resolveBackend({ model_hint: "opus" }, { config }).model, "claude-opus-99");
-});
-
-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");
-});
-
-// ── safety-net model freshness (pickAnthropicRow's ordered preference) ───────
-//
-// The safety net fires on the three paths that have no chain to walk: the kill
-// switch, "no v2 config", and "nothing survived the gates". It is the ONE place
-// resolve.mjs still names Anthropic model ids, so it is the one place that can
-// go stale. lookupModel is an exact byRef hit (no replaced_by chasing), so the
-// preference list carries the current -5 ids AND the 4-x succession fallback.
-
-/** The bundled catalog plus synthetic claude-*-5 rows (what ships next). */
-const CATALOG_WITH_5 = loadCatalog(MAESTRO_ROOT_FOR_TESTS(), {
-  agentConfig: {
-    catalog_overrides: [
-      {
-        ref: "anthropic/claude-opus-5",
-        status: "available",
-        context_tokens: 950000,
-        max_tokens: 128000,
-        tool_reliability: "A",
-        harness: { session: true, direct: true, batch: true },
-        cost: { input: 5.0, output: 25.0, cache_read: 0.5, cache_write: 10.0 },
-      },
-      {
-        ref: "anthropic/claude-sonnet-5",
-        status: "available",
-        context_tokens: 950000,
-        max_tokens: 64000,
-        tool_reliability: "A",
-        harness: { session: true, direct: true, batch: true },
-        cost: { input: 3.0, output: 15.0, cache_read: 0.3, cache_write: 6.0 },
-      },
-    ],
-  },
-});
-
-test("resolveChain: the safety net prefers claude-opus-5 / claude-sonnet-5 when the catalog has them", () => {
-  const frontier = resolveChain(
-    { task_class: "decision", needs_thinking: true, data_class: "sensitive", token_estimate: 1000 },
-    { catalog: CATALOG_WITH_5, config: V2_CONFIG, env: { MAESTRO_ROUTER_FORCE_ANTHROPIC: "1" }, now: CLOCK }
-  );
-  assert.equal(frontier.chosen.model, "claude-opus-5", "thinking/critical → current frontier, not opus-4-8");
-
-  const workhorse = resolveChain(
-    { task_class: "session.responder", data_class: "sensitive", token_estimate: 1000 },
-    { catalog: CATALOG_WITH_5, config: V2_CONFIG, env: { MAESTRO_ROUTER_FORCE_ANTHROPIC: "1" }, now: CLOCK }
-  );
-  assert.equal(workhorse.chosen.model, "claude-sonnet-5", "ordinary work → current workhorse, not sonnet-4-6");
-});
-
-test("resolveChain: the safety net falls back through succession when the catalog has no -5 rows", () => {
-  // This is why the 4-x refs stay in the preference list. Delete them and this
-  // does NOT fail loudly — it degrades to `models.find()` over the bundled rows,
-  // i.e. whatever sits first in anthropic.yaml (opus-4-8), which would hand
-  // ORDINARY work the frontier model and quietly quadruple its cost.
-  const d = resolveChain(
-    { task_class: "session.responder", data_class: "sensitive", token_estimate: 1000 },
-    { catalog: CATALOG, config: V2_CONFIG, env: { MAESTRO_ROUTER_FORCE_ANTHROPIC: "1" }, now: CLOCK }
-  );
-  assert.equal(d.chosen.model, "claude-sonnet-4-6", "succession fallback, ordered — NOT the first row in the file");
-  // Flip this to claude-sonnet-5 (and drop the 4-x refs from pickAnthropicRow)
-  // the day lib/model-router/catalog/anthropic.yaml carries the -5 rows.
-});
-
-test("the SHIPPED catalog is what decides the wire value — the -5 refresh is NOT done", () => {
-  // THE HONEST STATE OF THIS REFRESH, pinned so it cannot be mistaken for
-  // finished. The test above asserts `chosen.model`, which reads as bookkeeping.
-  // This one asserts `spawnArgs.modelFlag` — the string spawn.mjs pushes as
-  // `--model` — against the catalog the SDK actually ships, with `config: null`,
-  // which is the DEFAULT state of every agent because this repo contains no
-  // config/model-routing.yaml at all.
-  //
-  // Unlike the v1 lane (model-router.mjs's modelFlagFor sends the version-
-  // agnostic "opus"/"sonnet" shorthand), resolve.mjs's modelFlagFor returns
-  // row.id verbatim. So on v2 a stale catalog row is a stale id ON THE WIRE, not
-  // merely a mis-stamped ledger entry.
-  //
-  // WHEN THIS FAILS: someone added the -5 rows to anthropic.yaml. Good — that is
-  // the missing step. Update the expectations here, and DELETE the 4-x refs from
-  // pickAnthropicRow's preference lists in the same change, or the museum the
-  // provenance block warns about starts accumulating.
-  const cases = [
-    ["session.responder", {}, "claude-sonnet-4-6"],
-    ["decision", { needs_thinking: true }, "claude-opus-4-8"],
-  ];
-  for (const [task_class, extra, expected] of cases) {
-    const req = { task_class, data_class: "sensitive", token_estimate: 1000, ...extra };
-    for (const [label, env] of [
-      ["kill switch", { MAESTRO_ROUTER_FORCE_ANTHROPIC: "1" }],
-      ["no v2 config", {}],
-    ]) {
-      const d = resolveChain(req, { catalog: CATALOG, config: null, env, now: CLOCK });
-      assert.equal(
-        d.spawnArgs.modelFlag,
-        expected,
-        `${label}/${task_class}: --model is the literal catalog id, and the bundled catalog is still 4-x`
-      );
-      // Not the shorthand: nothing downstream re-resolves this to a current build.
-      assert.ok(!["opus", "sonnet", "haiku"].includes(d.spawnArgs.modelFlag));
-    }
-  }
-});
-
-test("resolveChain: with NO catalog rows at all, the synthetic row's id and ref agree", () => {
-  // The last-ditch path: no catalog, so the id goes straight onto `claude
-  // --model`. It used to emit {model: "claude-opus-4-8", ref:
-  // "anthropic/claude-sonnet-4-6"} for a thinking request — and ref is what
-  // feeds cacheAffinityKey and chain[0].ref, so the pin and the audit trail
-  // both named a different model than the one that ran.
-  const emptyDir = join(tmpdir(), `model-router-empty-catalog-${process.pid}-${Date.now()}`);
-  mkdirSync(emptyDir, { recursive: true });
-  try {
-    const EMPTY = loadCatalog(emptyDir, { bundledDir: emptyDir });
-    assert.equal(EMPTY.models.length, 0, "fixture really is an empty catalog");
-
-    const d = resolveChain(
-      { task_class: "decision", needs_thinking: true, data_class: "sensitive", token_estimate: 1000 },
-      { catalog: EMPTY, config: null, env: {}, now: CLOCK }
-    );
-    assert.equal(d.chosen.model, "claude-opus-5");
-    assert.equal(d.chain[0].ref, "anthropic/claude-opus-5", "ref tracks id");
-    assert.match(d.cacheAffinityKey, /anthropic\/claude-opus-5$/);
-
-    const ordinary = resolveChain(
-      { task_class: "session.responder", data_class: "sensitive", token_estimate: 1000 },
-      { catalog: EMPTY, config: null, env: {}, now: CLOCK }
-    );
-    assert.equal(ordinary.chosen.model, "claude-sonnet-5");
-    assert.equal(ordinary.chain[0].ref, "anthropic/claude-sonnet-5");
-  } finally {
-    rmSync(emptyDir, { recursive: true, force: true });
-  }
-});
-
-// ── cheap tier: an UNBUNDLED provider (xAI/Grok) is routable end to end ──────
-//
-// The SDK bundles catalog rows for anthropic/deepseek/moonshot/qwen only. Grok
-// is NOT bundled — but "not bundled" is not "not routable": catalog.mjs's
-// highest authority layer (config/model-routing.yaml `catalog_overrides:`) may
-// introduce a whole provider, and resolveChain gates it exactly like a bundled
-// one. These tests prove the full path — row → alias → chain → credential gate
-// → chosen — so the remaining work is a bundled YAML file, not plumbing.
-
-const XAI_PROVIDER_DOC = {
-  provider: "xai",
-  auth_env: "XAI_API_KEY",
-  endpoints: { openai: "https://api.x.ai/v1", anthropic: "https://api.x.ai/anthropic" },
-  data_residency: "us",
-  models: [
-    {
-      id: "grok-4-fast",
-      status: "available",
-      context_window: 2000000,
-      context_tokens: 1900000,
-      max_tokens: 30000,
-      cost: { input: 0.2, output: 0.5 },
-      cost_provenance: { source: "unverified", fetched: "2026-08-13", volatile: true },
-      compat: { thinking_format: "openai", cache_control: "implicit" },
-      // Grade B like every other third-party row: good enough for the direct
-      // lane, structurally barred from hosting a tool-using session (§6.6).
-      tool_reliability: "B",
-      harness: { session: true, direct: true, batch: false },
-    },
-  ],
-};
-
-const CATALOG_WITH_XAI = loadCatalog(MAESTRO_ROOT_FOR_TESTS(), {
-  agentConfig: { catalog_overrides: XAI_PROVIDER_DOC },
-});
-
-const XAI_CONFIG = Object.freeze({
-  schema_version: 2,
-  aliases: { cheap: "xai/grok-4-fast", default: "anthropic/claude-sonnet-4-6" },
-  defaults: { needs_tool_use_for_sessions: true, data_class: "sensitive", cache_ttl: "1h" },
-  backends: {
-    anthropic: { allowed_data_classes: ["public", "internal", "sensitive"] },
-    xai: { allowed_data_classes: ["public"] },
-  },
-  routing_policy: [
-    { match: { task_class: "lookup.web" }, harness: "direct", chain: ["cheap", "default"], needs_tool_use: false },
-    { default: true, chain: ["default"] },
-  ],
-  fallback_to_anthropic: true,
-});
-
-test("catalog_overrides can introduce xAI/Grok — loudly, as a warning, never silently", () => {
-  const row = CATALOG_WITH_XAI.byRef.get("xai/grok-4-fast");
-  assert.ok(row, "grok row present after the agent-config merge");
-  assert.equal(row.provider, "xai");
-  assert.equal(row.auth_env, "XAI_API_KEY", "carries its OWN auth env, not a borrowed one");
-  assert.equal(row.endpoints.anthropic, "https://api.x.ai/anthropic");
-  assert.ok(
-    CATALOG_WITH_XAI.warnings.some((w) => /non-bundled provider "xai"/.test(w.warning)),
-    "introducing an unbundled provider warns (typo guard) — it does not fail"
-  );
-});
-
-test("resolveChain routes a cheap-tier task to Grok when its own key is present", () => {
-  const d = resolveChain(
-    { task_class: "lookup.web", data_class: "public", token_estimate: 2000 },
-    { catalog: CATALOG_WITH_XAI, config: XAI_CONFIG, env: { XAI_API_KEY: "xai-k" }, now: CLOCK }
-  );
-  assert.equal(d.chosen.provider, "xai");
-  assert.equal(d.chosen.model, "grok-4-fast");
-  assert.equal(d.chosen.wire, "openai", "third-party direct call speaks the openai wire");
-});
-
-test("resolveChain skips Grok without XAI_API_KEY (key-absence-as-enforcement, §7.1)", () => {
-  const d = resolveChain(
-    { task_class: "lookup.web", data_class: "public", token_estimate: 2000 },
-    { catalog: CATALOG_WITH_XAI, config: XAI_CONFIG, env: {}, now: CLOCK }
-  );
-  const skipped = d.tried.find((t) => t.ref === "xai/grok-4-fast");
-  assert.ok(skipped, "grok recorded in tried[]");
-  assert.equal(skipped.reason, "missing_credential");
-  assert.notEqual(d.chosen.provider, "xai");
-});
-
-test("Grok inherits auth-profile key rotation from the catalog, with no per-provider code", () => {
-  // auth-profiles derives provider → auth_env from the CATALOG, so a provider
-  // the SDK has never heard of gets pooled multi-key rotation for free. This is
-  // the "their own auth profiles" half of the cheap-tier requirement.
-  const profiles = loadAuthProfiles(null, {
-    configDoc: null, // bypass the FS
-    env: { XAI_API_KEY: "k1", XAI_API_KEY_2: "k2", DEEPSEEK_API_KEY: "d1" },
-    authEnvByProvider: authEnvMapFromCatalog(CATALOG_WITH_XAI),
-  });
-  assert.deepEqual(profiles.keysFor("xai"), ["k1", "k2"]);
-  assert.equal(profiles.isPooled("xai"), true, "two keys ⇒ rotation is live");
-  assert.equal(profiles.isPooled("deepseek"), false, "single key ⇒ unchanged single-key behaviour");
-});
-
-test("a session on Grok is still barred by the grade gate, exactly like DeepSeek/Kimi", () => {
-  // Not a bug to fix: §6.6 says a tool-using session needs grade A, and no
-  // third-party row is graded A until the probe ledger earns it. Cheap-tier
-  // reachability must NOT quietly become cheap-tier session hosting.
-  const sessionCfg = {
-    ...XAI_CONFIG,
-    routing_policy: [{ default: true, chain: ["cheap", "default"] }],
-  };
-  const d = resolveChain(
-    { task_class: "session.responder", data_class: "public", token_estimate: 2000 },
-    { catalog: CATALOG_WITH_XAI, config: sessionCfg, env: { XAI_API_KEY: "xai-k" }, now: CLOCK }
-  );
-  const skipped = d.tried.find((t) => t.ref === "xai/grok-4-fast");
-  assert.equal(skipped?.reason, "grade_too_low");
-  assert.equal(d.chosen.provider, "anthropic");
-});
-
-// ── 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);
-});