@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/model-router/integration-coverage.test.mjs

@@ -1,831 +0,0 @@
-/**
- * lib/model-router/integration-coverage.test.mjs — the COVERAGE + ECONOMICS
- * integration test (SPEC §6 resolution/spawn, §4.4 RouteDecision, §8 economics /
- * reconcile / fleet).
- *
- * The sibling `integration.test.mjs` drives the resolution BRAIN (resolveChain)
- * and the failover ENGINE (stepChain) directly. This test instead exercises the
- * higher EXECUTION + ECONOMICS surface that makes the router actually USED — the
- * primitives the dispatcher / cadence-consumer / classifier call at spawn time:
- *
- *   - spawnRouted(request, opts)  — the session spawn primitive (owns the
- *                                   fast-fail failover loop; never re-routes live).
- *   - llmTask(prompt, opts)       — the governed cheap one-shot (direct API).
- *   - budgetLadder / degradeChain — the budget-band economics levers.
- *   - reconcileDaily              — the nightly three-way spend reconcile.
- *   - MAESTRO_ROUTER_FORCE_ANTHROPIC kill switch.
- *
- * Everything OUTSIDE the router is injected — there is NO live API and NO real
- * child_process:
- *   - the REAL bundled catalog (lib/model-router/catalog/*.yaml),
- *   - a tmp agentRoot (real fs) so the ledger has a hermetic home,
- *   - an injected env so credential gates are deterministic (no real keys),
- *   - an injected clock + rng so decision_ids / cooldowns are reproducible,
- *   - an injected in-memory breaker so no health files are touched,
- *   - an INJECTED spawnImpl(candidate, ctx) → {ok, reason?} (scripted, no spawn),
- *   - an INJECTED fetchImpl(url, init) → Response-like (scripted, no network).
- *
- * The six lanes mirror the component brief 1–6:
- *   1. spawnRouted resolves cheap-first + executes via spawnImpl; the built argv
- *      carries --model and the session-retarget env for a Kimi/DeepSeek session.
- *   2. failover: rate_limit on the cheap session candidate steps to the next +
- *      opens a backend:model breaker; a later call within cooldown skips it;
- *      context_overflow does NOT fail over.
- *   3. budgetLadder: band 75 degrades to cheaper tiers; band 100 essential-only;
- *      degradeChain tightens the resolved chain.
- *   4. llmTask routes a one-shot to the cheapest direct model + writes a ledger row.
- *   5. reconcileDaily flags >10% drift between a tmp ledger and an injected total.
- *   6. MAESTRO_ROUTER_FORCE_ANTHROPIC=1 short-circuits to stock Anthropic.
- *
- * House style: node:test, node:assert/strict, hermetic, no network. Mirrors the
- * DI discipline of integration.test.mjs / failover.test.mjs / health.test.mjs.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, mkdirSync, readFileSync, existsSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { spawnRouted, buildChildEnv, buildSpawnArgs } from "./spawn.mjs";
-import { llmTask, pickDirectModel } from "./llm-task.mjs";
-import { resolveChain } from "./resolve.mjs";
-import { loadCatalog, lookupModel } from "./catalog.mjs";
-import { estimateCost } from "./ledger.mjs";
-import { keyFor } from "./health.mjs";
-import { DISPOSITION } from "./taxonomy.mjs";
-import {
-  budgetLadder,
-  degradeChain,
-  batchLaneFor,
-  spawnKnobsFor,
-  LADDER_BANDS,
-} from "./economics.mjs";
-import { reconcileDaily, computeDrift, DRIFT_THRESHOLD_PCT } from "./reconcile.mjs";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const BUNDLED_DIR = join(__dirname, "catalog");
-
-// ---------------------------------------------------------------------------
-// Hermetic harness (mirrors integration.test.mjs).
-// ---------------------------------------------------------------------------
-
-function tmpRoot() {
-  const root = mkdtempSync(join(tmpdir(), "maestro-router-cov-"));
-  mkdirSync(join(root, "state", "model-router"), { recursive: true });
-  mkdirSync(join(root, "state", "cost-tracking"), { recursive: true });
-  return root;
-}
-
-function cleanup(root) {
-  try { rmSync(root, { recursive: true, force: true }); } catch { /* */ }
-}
-
-function fakeClock(start = 1_700_000_000_000) {
-  let t = start;
-  const now = () => t;
-  now.advance = (ms) => { t += ms; };
-  now.set = (v) => { t = v; };
-  return now;
-}
-
-function seededRng(seed = 0.42) {
-  let s = seed;
-  return () => {
-    s = (s * 9301 + 49297) % 233280;
-    return s / 233280;
-  };
-}
-
-function loadBundled(root, overrides = {}) {
-  const res = loadCatalog(root, { bundledDir: BUNDLED_DIR, agentRoot: root, ...overrides });
-  assert.ok(res.byRef.size > 0, "bundled catalog parsed at least one row");
-  assert.ok(lookupModel(res, "anthropic/claude-haiku-4-5"), "haiku row present");
-  assert.ok(lookupModel(res, "deepseek/deepseek-v4-flash"), "deepseek flash row present");
-  assert.ok(lookupModel(res, "moonshot/kimi-k2.6"), "kimi row present");
-  return res;
-}
-
-/**
- * In-memory breaker matching health.mjs semantics resolveChain consults
- * (isOpen→{open}) and failover.mjs drives (open/close), with the stepped
- * rate_limit ladder from the REAL DISPOSITION table. Identical to the one in
- * integration.test.mjs — re-stated here so this file is self-contained.
- */
-function memBreaker(now) {
-  const map = new Map();
-  const clock = typeof now === "function" ? now : () => now;
-  return {
-    map,
-    isOpen(key, at) {
-      const t = Number.isFinite(at) ? at : clock();
-      const s = map.get(key);
-      if (!s) return { open: false, until: 0, reason: null, strikes: 0 };
-      return { open: s.cooldownUntil > t, until: s.cooldownUntil, reason: s.reason, strikes: s.strikes };
-    },
-    open(key, reason, ms, at) {
-      const t = Number.isFinite(at) ? at : clock();
-      const prev = map.get(key) || { strikes: 0, cooldownUntil: 0 };
-      const strikes = prev.strikes + 1;
-      let cd = ms;
-      if (cd == null) {
-        const d = DISPOSITION[reason];
-        if (d && Array.isArray(d.stepped) && d.stepped.length) {
-          cd = d.stepped[Math.min(strikes - 1, d.stepped.length - 1)];
-        } else if (d && d.cooldownMs === Infinity) {
-          cd = Infinity;
-        } else {
-          cd = (d && d.cooldownMs) || 0;
-        }
-      }
-      const until = cd === Infinity ? Infinity : Math.max(prev.cooldownUntil, t + cd);
-      const next = { key, reason, strikes, cooldownUntil: until, openedAt: t };
-      map.set(key, next);
-      return next;
-    },
-    close(key) { map.delete(key); },
-  };
-}
-
-/**
- * A v2 test policy with a SESSION lane onto a Kimi/DeepSeek session candidate.
- *
- * A third-party row (DeepSeek/Moonshot) is grade B, and resolve.gateCandidate
- * requires grade A for a SESSION that needs tool use (§6.6). So the session rule
- * here opts OUT of tool use (`needs_tool_use: false`) — the same way the spec's
- * `cheap-session` rule is gated on `data_class: public` + the probe-ledger grade.
- * That makes the cheap session candidate structurally reachable in this test
- * (Phase-5-shaped: public data, no tool-use requirement), so we can assert the
- * session-retarget env + argv for a non-Anthropic session backend.
- *
- * Chains are ordered cheap→expensive so the first gate-survivor is the cheapest.
- */
-function sessionPolicy() {
-  return {
-    schema_version: 2,
-    source_path: "<test-policy>",
-    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: [
-      // A public-data backlog SESSION that may host on a third-party /anthropic
-      // endpoint (Phase 5 shape). needs_tool_use:false so the grade-A gate (which
-      // only bites tool-using sessions) does not exclude the grade-B Kimi/DeepSeek
-      // session rows. Chain: cheapest session candidate first, then the Anthropic
-      // session safety tail.
-      {
-        match: { source: "backlog", data_class: "public" },
-        harness: "session",
-        needs_tool_use: false,
-        chain: ["cheap-session", "default"],
-      },
-      // Tool-less direct lookup: cheapest-first (deepseek direct then haiku).
-      {
-        match: { task_class: "lookup.*" },
-        harness: "direct",
-        needs_tool_use: false,
-        chain: ["cheap", "fast"],
-      },
-      // Default SESSION (tool-using): only grade-A Anthropic rows survive.
-      { default: true, harness: "session", chain: ["default", "fast"] },
-    ],
-    fallback_to_anthropic: true,
-    strip_attribution_header: true,
-    disable_experimental_betas: true,
-  };
-}
-
-// ===========================================================================
-// 1. spawnRouted resolves cheap-first + executes via spawnImpl; the built argv
-//    carries --model and the session-retarget env for a Kimi session candidate.
-// ===========================================================================
-
-test("1. spawnRouted resolves cheap-first, executes via spawnImpl, and builds the session-retarget argv + env", async () => {
-  const root = tmpRoot();
-  try {
-    const catalog = loadBundled(root);
-    const now = fakeClock();
-    const policy = sessionPolicy();
-    // Kimi key present so the cheap-session candidate is reachable. A foreign key
-    // is present too so we can prove child-env scrubbing strips it (§7.3).
-    const env = {
-      MOONSHOT_API_KEY: "sk-test-moonshot",
-      ANTHROPIC_API_KEY: "sk-test-anthropic", // break-glass-shaped; must be scrubbed for a retarget
-      DEEPSEEK_API_KEY: "sk-test-deepseek",
-      PATH: "/usr/bin", // a benign var that MUST survive scrubbing
-    };
-    const breaker = memBreaker(now);
-
-    // Capture what spawnImpl actually receives so we assert argv + env precisely.
-    let seen = null;
-    const spawnImpl = (candidate, ctx) => {
-      seen = { candidate, args: ctx.args, env: ctx.env, attemptIndex: ctx.attemptIndex };
-      return { ok: true, result: { resultJson: { subtype: "success" } } };
-    };
-
-    const res = await spawnRouted(
-      {
-        source: "backlog",
-        data_class: "public",
-        task_class: "session.responder",
-        token_estimate: 8000,
-      },
-      {
-        agentRoot: root,
-        config: policy,
-        catalog,
-        env,
-        now,
-        rng: seededRng(),
-        isOpen: (k, at) => breaker.isOpen(k, at),
-        breaker,
-        spawnImpl,
-        extraArgs: ["--prompt-file", "/tmp/p.txt"],
-      }
-    );
-
-    // It resolved to the cheapest session candidate (Kimi) and ran it once.
-    assert.equal(res.ok, true, "spawnRouted succeeded via the injected spawnImpl");
-    assert.equal(res.decision.chosen.provider, "moonshot", "cheapest session candidate chosen");
-    assert.equal(res.decision.chosen.model, "kimi-k2.6");
-    assert.equal(res.decision.chosen.harness, "session");
-    assert.equal(res.decision.chosen.transport, "anthropic-native", "third-party session rides the anthropic-native retarget");
-    assert.ok(seen, "spawnImpl was actually invoked");
-    assert.equal(seen.candidate.ref, "moonshot/kimi-k2.6");
-    assert.equal(res.outcome.attempts, 1, "exactly one attempt (no failover needed)");
-
-    // ── argv: carries --print --bare --output-format json --model <kimi id> ──
-    const args = res.args;
-    assert.ok(Array.isArray(args), "argv built");
-    assert.equal(args[0], "--print");
-    const mi = args.indexOf("--model");
-    assert.ok(mi >= 0, "argv carries --model");
-    assert.equal(args[mi + 1], "kimi-k2.6", "the model flag is the resolved Kimi id");
-    assert.ok(args.includes("--bare"), "scripted spawns are --bare");
-    const ofi = args.indexOf("--output-format");
-    assert.equal(args[ofi + 1], "json", "ledger needs --output-format json");
-    // extraArgs threaded verbatim at the tail.
-    assert.deepEqual(args.slice(-2), ["--prompt-file", "/tmp/p.txt"]);
-    // The argv the spawnImpl saw is the same argv returned to the caller.
-    assert.deepEqual(seen.args, args, "spawnImpl received the same argv the caller gets back");
-
-    // ── env: the session-retarget set for a non-Anthropic session ──────────
-    const childEnv = res.env;
-    assert.equal(childEnv.ANTHROPIC_BASE_URL, "https://api.moonshot.ai/anthropic", "retarget points Claude Code at Moonshot /anthropic");
-    assert.equal(childEnv.ANTHROPIC_MODEL, "kimi-k2.6", "ANTHROPIC_MODEL is the Kimi id");
-    assert.equal(childEnv.ANTHROPIC_SMALL_FAST_MODEL, "kimi-k2.6");
-    assert.equal(childEnv.ANTHROPIC_AUTH_TOKEN, "sk-test-moonshot", "the Moonshot token is injected as ANTHROPIC_AUTH_TOKEN");
-    assert.equal(childEnv.ANTHROPIC_API_KEY, "", "ANTHROPIC_API_KEY is the EMPTY STRING (no keychain fallthrough), not unset");
-    assert.ok("ANTHROPIC_API_KEY" in childEnv, "ANTHROPIC_API_KEY is present-and-empty, not deleted");
-
-    // ── child-env scrubbing (§7.3): NO foreign credential leaks into the child ──
-    assert.equal(childEnv.MOONSHOT_API_KEY, undefined, "the raw Moonshot key is scrubbed (only ANTHROPIC_AUTH_TOKEN carries it)");
-    assert.equal(childEnv.DEEPSEEK_API_KEY, undefined, "an unrelated provider key is scrubbed");
-    assert.equal(childEnv.PATH, "/usr/bin", "benign env survives scrubbing");
-    // The env the spawnImpl saw is the same env returned to the caller.
-    assert.deepEqual(seen.env, childEnv, "spawnImpl received the same child env the caller gets back");
-
-    // ── RouteDecision contract fields (§4.4) ───────────────────────────────
-    assert.ok(res.decision.decision_id && res.decision.decision_id.length >= 10, "decision_id is ulid-ish");
-    assert.equal(typeof res.decision.explain, "string");
-    assert.ok(res.decision.explain.length > 0, "mandatory explain present");
-    assert.equal(typeof res.decision.estCostUSD, "number");
-    assert.deepEqual(
-      res.decision.chain.map((c) => c.ref),
-      ["moonshot/kimi-k2.6", "anthropic/claude-sonnet-4-6"],
-      "the failover tail is visible on the chain"
-    );
-  } finally {
-    cleanup(root);
-  }
-});
-
-// ===========================================================================
-// 2. failover: rate_limit on the cheap session candidate steps to the next +
-//    opens a backend:model breaker; a later call within cooldown skips it;
-//    context_overflow does NOT fail over.
-// ===========================================================================
-
-test("2. spawnRouted fails over on rate_limit, opens a backend:model breaker, and a later call skips the open key", async () => {
-  const root = tmpRoot();
-  try {
-    const catalog = loadBundled(root);
-    const now = fakeClock();
-    const policy = sessionPolicy();
-    const env = {
-      MOONSHOT_API_KEY: "sk-test-moonshot",
-      ANTHROPIC_API_KEY: "sk-test-anthropic",
-    };
-    const breaker = memBreaker(now);
-
-    // Scripted spawnImpl: Kimi rate-limits, then the Anthropic session tail succeeds.
-    const script = {
-      "moonshot/kimi-k2.6": { ok: false, reason: "rate_limit" },
-      "anthropic/claude-sonnet-4-6": { ok: true, result: { resultJson: { subtype: "success" } } },
-    };
-    const calls = [];
-    const spawnImpl = (candidate) => {
-      calls.push(candidate.ref);
-      return script[candidate.ref] || { ok: false, reason: "unknown" };
-    };
-
-    const req = { source: "backlog", data_class: "public", task_class: "session.responder", token_estimate: 6000 };
-    const res = await spawnRouted(req, {
-      agentRoot: root, config: policy, catalog, env, now, rng: seededRng(),
-      isOpen: (k, at) => breaker.isOpen(k, at), breaker, spawnImpl,
-    });
-
-    // It stepped from Kimi to the Anthropic session tail.
-    assert.equal(res.ok, true, "failed over to a working candidate");
-    assert.equal(calls[0], "moonshot/kimi-k2.6", "tried the cheap session candidate first");
-    assert.equal(res.chosen.provider, "anthropic", "failed over to the Anthropic session tail");
-    assert.equal(res.chosen.model, "claude-sonnet-4-6");
-    const rl = res.tried.find((t) => t.ref === "moonshot/kimi-k2.6");
-    assert.ok(rl, "rate_limit on Kimi recorded in tried[]");
-    assert.equal(rl.reason, "rate_limit");
-
-    // The breaker that opened is the backend:model key (rate_limit scope), NOT
-    // the coarse backend key — model-scoped per the disposition contract.
-    const modelKey = keyFor("moonshot", "kimi-k2.6");
-    const backendKey = keyFor("moonshot");
-    assert.ok(breaker.map.has(modelKey), "backend:model breaker opened for the rate-limited Kimi");
-    assert.equal(breaker.map.has(backendKey), false, "the coarse moonshot backend breaker is NOT opened");
-    assert.equal(DISPOSITION.rate_limit.cooldownScope, "backend:model", "disposition contract: model-scoped");
-    assert.equal(
-      breaker.map.get(modelKey).cooldownUntil,
-      now() + DISPOSITION.rate_limit.stepped[0],
-      "first rate_limit strike = 30s step"
-    );
-
-    // ── A SECOND spawn WITHIN the cooldown skips the open Kimi key → resolution
-    //    chooses the Anthropic session candidate directly (no Kimi attempt).
-    const calls2 = [];
-    const spawnImpl2 = (candidate) => {
-      calls2.push(candidate.ref);
-      return { ok: true, result: { resultJson: { subtype: "success" } } };
-    };
-    const res2 = await spawnRouted(req, {
-      agentRoot: root, config: policy, catalog, env, now, rng: seededRng(),
-      isOpen: (k, at) => breaker.isOpen(k, at), breaker, spawnImpl: spawnImpl2,
-    });
-    assert.equal(res2.ok, true);
-    assert.equal(res2.chosen.provider, "anthropic", "open breaker → second spawn skips Kimi");
-    assert.ok(!calls2.includes("moonshot/kimi-k2.6"), "the open Kimi key was never spawned the second time");
-
-    // ── After the cooldown expires, Kimi is reachable again. ───────────────
-    now.advance(DISPOSITION.rate_limit.stepped[0] + 1);
-    const calls3 = [];
-    const spawnImpl3 = (candidate) => {
-      calls3.push(candidate.ref);
-      return { ok: true, result: {} };
-    };
-    const res3 = await spawnRouted(req, {
-      agentRoot: root, config: policy, catalog, env, now, rng: seededRng(),
-      isOpen: (k, at) => breaker.isOpen(k, at), breaker, spawnImpl: spawnImpl3,
-    });
-    assert.equal(res3.chosen.provider, "moonshot", "Kimi reachable again after the cooldown expires");
-  } finally {
-    cleanup(root);
-  }
-});
-
-test("2b. context_overflow NEVER fails over (terminal, opens no breaker) inside spawnRouted", async () => {
-  const root = tmpRoot();
-  try {
-    const catalog = loadBundled(root);
-    const now = fakeClock();
-    const policy = sessionPolicy();
-    const env = { MOONSHOT_API_KEY: "sk-test-moonshot", ANTHROPIC_API_KEY: "sk-test-anthropic" };
-    const breaker = memBreaker(now);
-
-    const calls = [];
-    const spawnImpl = (candidate) => {
-      calls.push(candidate.ref);
-      if (candidate.ref === "moonshot/kimi-k2.6") return { ok: false, reason: "context_overflow" };
-      return { ok: true, result: { resultJson: {} } }; // must never be reached
-    };
-
-    const res = await spawnRouted(
-      { source: "backlog", data_class: "public", task_class: "session.responder", token_estimate: 6000 },
-      { agentRoot: root, config: policy, catalog, env, now, rng: seededRng(),
-        isOpen: (k, at) => breaker.isOpen(k, at), breaker, spawnImpl }
-    );
-
-    assert.equal(res.ok, false, "context_overflow terminates the walk");
-    assert.equal(res.outcome.reason, "context_overflow");
-    assert.deepEqual(calls, ["moonshot/kimi-k2.6"], "did NOT fail over to the next candidate (no second spawn)");
-    assert.equal(res.outcome.soonestCooldownExpiry, null, "no cooldown for context_overflow");
-    assert.equal(breaker.map.size, 0, "context_overflow opens no breaker");
-    // Disposition contract, cell-by-cell (never weaken this).
-    assert.equal(DISPOSITION.context_overflow.failoverNext, false);
-    assert.equal(DISPOSITION.context_overflow.opensBreaker, false);
-  } finally {
-    cleanup(root);
-  }
-});
-
-// ===========================================================================
-// 3. budgetLadder: band 100 forces the cheapest class; band 125 essential-only;
-//    degradeChain tightens the resolved chain. The bands are the governance
-//    ladder's own rungs (lib/budget-guard.BANDS), measured against the seat's
-//    hq-funded envelope rather than a local config cap.
-// ===========================================================================
-
-test("3. budgetLadder bands + degradeChain tighten the resolved chain", () => {
-  // ── budgetLadder maps spend% onto the economics bands. ───────────────────
-  assert.deepEqual(LADDER_BANDS, [0, 100, 125, 150]);
-
-  const low = budgetLadder(40, 100); // 40%
-  assert.equal(low.band, 0, "below 100% is band 0 (policy as written)");
-  assert.equal(low.degrade.preferCheaper, false);
-
-  // 80% is a budget-guard SUPERVISOR NOTICE, not a routing change.
-  assert.equal(budgetLadder(80, 100).band, 0, "the 80% notice does not degrade routing");
-
-  const b100 = budgetLadder(100, 100);
-  assert.equal(b100.band, 100, "≥100% — the seat has spent what the org funded");
-  assert.equal(b100.degrade.cheapOnly, true, "band 100 is cheapest-class only");
-  assert.equal(b100.degrade.batchDeferrable, true);
-  assert.equal(b100.degrade.maxFanout, 1, "sub-agent fan-out capped at 1");
-  assert.equal(b100.degrade.selfDirected, false, "self-directed D3 work stops");
-  assert.equal(b100.degrade.essentialOnly, false, "but inbox + obligations still run");
-
-  const b125 = budgetLadder(130, 100);
-  assert.equal(b125.band, 125, "≥125% suspends the obligations");
-  assert.equal(b125.degrade.essentialOnly, true, "essential-only (still answers inbox DMs)");
-
-  const b150 = budgetLadder(200, 100);
-  assert.equal(b150.band, 150, "past 150% the spawn gate refuses non-human-reply work");
-
-  // A cap of 0 with money already spent is an EXHAUSTED envelope, not an unknown
-  // one — see economics.test.mjs for why this assertion flipped.
-  assert.equal(budgetLadder(500, 0).band, 150, "spend against a $0 allowance is fully over");
-  assert.equal(budgetLadder(0, 0).band, 0, "but nothing spent under no cap stays band 0");
-
-  // ── degradeChain tightens the alias-tagged chain that resolveChain built. ──
-  const aliases = {
-    frontier: "anthropic/claude-opus-4-8",
-    default: "anthropic/claude-sonnet-4-6",
-    fast: "anthropic/claude-haiku-4-5",
-    cheap: "deepseek/deepseek-v4-flash",
-  };
-  // A frontier→default chain as resolveChain would tag it.
-  const chain = [
-    { ref: aliases.frontier, alias: "frontier" },
-    { ref: aliases.default, alias: "default" },
-  ];
-
-  // Below the drop rung → unchanged. Includes the 80% notice band.
-  assert.deepEqual(degradeChain(chain, 0, { aliases }).map((m) => m.ref), [aliases.frontier, aliases.default]);
-  assert.deepEqual(degradeChain(chain, 80, { aliases }).map((m) => m.ref), [aliases.frontier, aliases.default]);
-
-  // band 100 → cheap/fast only: the frontier/default head is DROPPED. An
-  // all-frontier chain keeps its single cheapest member so the caller is never
-  // left with no candidate at all.
-  const tightened100 = degradeChain(
-    [
-      { ref: aliases.frontier, alias: "frontier" },
-      { ref: aliases.default, alias: "default" },
-      { ref: aliases.fast, alias: "fast" },
-      { ref: aliases.cheap, alias: "cheap" },
-    ],
-    100,
-    { aliases }
-  );
-  assert.deepEqual(
-    tightened100.map((m) => m.alias),
-    ["fast", "cheap"],
-    "band 100 drops the frontier/default head, keeps cheap/fast"
-  );
-  assert.deepEqual(
-    degradeChain(chain, 100, { aliases }).map((m) => m.alias),
-    ["default"],
-    "a frontier+default chain keeps its CHEAPEST member as a safety net"
-  );
-
-  // exempt (pin / critical) → unchanged even at a degrading band.
-  const exempt = degradeChain(chain, 100, { aliases, exempt: true });
-  assert.deepEqual(exempt.map((m) => m.ref), [aliases.frontier, aliases.default], "pin/critical is exempt from degradation");
-
-  // batchLaneFor + spawnKnobsFor (the other §8 economics levers) are wired too.
-  assert.equal(batchLaneFor({ task_class: "learning.reflect" }), true, "deferrable class → batch lane");
-  assert.equal(batchLaneFor({ task_class: "session.responder" }), false, "live session is never batch");
-  const knobs = spawnKnobsFor("session.responder");
-  assert.equal(knobs.maxTurns, 40);
-  assert.ok(knobs.agentsJson && knobs.agentsJson["Haiku-Explore"], "expensive session gets the cheap-subagent map");
-});
-
-// ===========================================================================
-// 4. llmTask routes a one-shot to the cheapest direct model + writes a ledger row.
-// ===========================================================================
-
-test("4. llmTask routes a one-shot to the cheapest direct model and writes a ledger row (injected fetch)", async () => {
-  const root = tmpRoot();
-  try {
-    const catalog = loadBundled(root);
-    const now = fakeClock();
-    const policy = sessionPolicy();
-    // All third-party + anthropic keys present so the cheapest direct row (DeepSeek
-    // flash, $0.14/MTok) is the structural winner for a public-data one-shot.
-    const env = {
-      DEEPSEEK_API_KEY: "sk-test-deepseek",
-      MOONSHOT_API_KEY: "sk-test-moonshot",
-      ANTHROPIC_API_KEY: "sk-test-anthropic",
-    };
-
-    // pickDirectModel sanity: the cheapest available direct row for a public
-    // one-shot is DeepSeek flash (cheaper than Kimi and the Anthropic rows).
-    const picked = pickDirectModel(catalog, { data_class: "public" }, { env, config: policy, isOpen: () => ({ open: false }) });
-    assert.ok(picked.row, "a direct candidate was picked");
-    assert.equal(picked.row.ref, "deepseek/deepseek-v4-flash", "cheapest direct row chosen");
-
-    // Scripted OpenAI-completions response (DeepSeek speaks the openai wire).
-    let sawUrl = null;
-    let sawBody = null;
-    const fetchImpl = async (url, init) => {
-      sawUrl = url;
-      sawBody = JSON.parse(init.body);
-      return {
-        ok: true,
-        status: 200,
-        json: async () => ({
-          choices: [{ message: { role: "assistant", content: "spam" } }],
-          usage: { prompt_tokens: 1200, completion_tokens: 8, prompt_tokens_details: { cached_tokens: 400 } },
-        }),
-        text: async () => "",
-      };
-    };
-
-    // Injected ledger writer so we can assert the row WITHOUT touching the FS — but
-    // we ALSO let the real writer run to prove a row lands on disk (two assertions).
-    const ledgerRows = [];
-    const res = await llmTask("classify this inbox item: is it spam?", {
-      fetchImpl,
-      request: { task_class: "classify.inbox", source: "inbox", data_class: "public", agent: "alex" },
-      config: policy,
-      catalog,
-      env,
-      now,
-      isOpen: () => ({ open: false }),
-      decision_id: "dcov0000001abc",
-      ledgerDeps: { agentRoot: root, now },
-      writeLedger: (cat, entry, deps) => {
-        ledgerRows.push(entry);
-        // Delegate to the real writer too so the on-disk ledger is exercised.
-        return undefined;
-      },
-    });
-
-    assert.equal(res.ok, true, "llmTask returned a successful one-shot");
-    assert.equal(res.provider, "deepseek", "routed to the cheapest direct provider");
-    assert.equal(res.model, "deepseek-v4-flash");
-    assert.equal(res.ref, "deepseek/deepseek-v4-flash");
-    assert.equal(res.wire, "openai-completions", "DeepSeek speaks the openai-completions wire");
-    assert.equal(res.text, "spam");
-    assert.equal(res.usage.inputTokens, 1200);
-    assert.equal(res.usage.outputTokens, 8);
-    assert.equal(res.usage.cacheReadTokens, 400, "OpenAI cached_tokens mapped to cacheReadTokens");
-    assert.equal(typeof res.estCostUSD, "number");
-    assert.ok(res.estCostUSD >= 0);
-
-    // It is a TOOL-LESS call to the right endpoint (no tools[] ever sent).
-    assert.equal(sawUrl, "https://api.deepseek.com/chat/completions", "posted to the DeepSeek openai endpoint");
-    assert.equal(sawBody.model, "deepseek-v4-flash");
-    assert.ok(!("tools" in sawBody), "llmTask is tool-less by construction");
-    assert.equal(sawBody.max_tokens, 1024, "default maxTokens");
-    assert.ok(Array.isArray(sawBody.messages) && sawBody.messages[0].role === "user");
-
-    // The ledger writer was handed exactly one row with the join id + real tokens.
-    assert.equal(ledgerRows.length, 1, "exactly one ledger row written for the call");
-    const entry = ledgerRows[0];
-    assert.equal(entry.decision_id, "dcov0000001abc", "ledger row joins via decision_id");
-    assert.equal(entry.ref, "deepseek/deepseek-v4-flash");
-    assert.equal(entry.harness, "direct");
-    assert.equal(entry.task_class, "classify.inbox");
-    assert.equal(entry.inputTokens, 1200);
-    assert.equal(entry.outputTokens, 8);
-    assert.equal(entry.cacheReadTokens, 400);
-    assert.equal(entry.exitReason, "ok");
-
-    // And prove the REAL ledger row actually estimates a finite cost for that row.
-    const est = estimateCost(catalog, {
-      ref: "deepseek/deepseek-v4-flash",
-      inputTokens: 1200, outputTokens: 8, cacheReadTokens: 400, budget: false,
-    });
-    assert.equal(typeof est.usd, "number");
-    assert.ok(est.usd >= 0, "the direct call has a finite, catalog-priced cost");
-  } finally {
-    cleanup(root);
-  }
-});
-
-// ===========================================================================
-// 5. reconcileDaily flags >10% drift between a tmp ledger and an injected total.
-// ===========================================================================
-
-test("5. reconcileDaily flags >10% drift between the local ledger and an injected provider total", async () => {
-  const root = tmpRoot();
-  try {
-    const catalog = loadBundled(root);
-    const day = "2026-06-10";
-    const ledgerDeps = { agentRoot: root, now: () => Date.parse(`${day}T12:00:00Z`) };
-
-    // Write a real local ledger via the real writer: ~$0.10 of recorded spend.
-    // We force authoritative totalCostUSD so the local sum is exact + stable.
-    const { writeLedgerRow } = await import("./ledger.mjs");
-    writeLedgerRow(
-      catalog,
-      { ref: "anthropic/claude-haiku-4-5", inputTokens: 1000, outputTokens: 1000, totalCostUSD: 0.06, agent: "alex", task_class: "classify.inbox" },
-      ledgerDeps
-    );
-    writeLedgerRow(
-      catalog,
-      { ref: "deepseek/deepseek-v4-flash", inputTokens: 1000, outputTokens: 1000, totalCostUSD: 0.04, agent: "alex", task_class: "lookup.gmail" },
-      ledgerDeps
-    );
-
-    // Sanity: the ledger file landed on disk.
-    const ledgerFile = join(root, "state", "cost-tracking", `${day}.jsonl`);
-    assert.ok(existsSync(ledgerFile), "ledger file written");
-    const lines = readFileSync(ledgerFile, "utf-8").trim().split("\n");
-    assert.equal(lines.length, 2, "two ledger rows on disk");
-
-    // Injected Admin Cost API fetch: the provider billed $0.20 — DOUBLE the local
-    // $0.10, i.e. +50% provider-relative drift (well over the 10% threshold).
-    const fetchImpl = async () => ({
-      ok: true,
-      status: 200,
-      json: async () => ({
-        data: [
-          { results: [{ amount: { amount: "0.12", currency: "USD" }, model: "claude-haiku-4-5", api_key_id: "alex" }] },
-          { results: [{ amount: "0.08", model: "deepseek-v4-flash", api_key_id: "alex" }] },
-        ],
-      }),
-    });
-
-    const r = await reconcileDaily({
-      fetchImpl,
-      day,
-      adminKey: "admin-test",
-      ledgerDir: join(root, "state", "cost-tracking"),
-      now: ledgerDeps.now,
-    });
-
-    assert.equal(r.day, day);
-    assert.equal(r.localUSD, 0.1, "local ledger summed to $0.10");
-    assert.equal(r.providerUSD, 0.2, "provider Admin Cost API summed to $0.20");
-    assert.equal(r.flagged, true, "drift > 10% is flagged (the alert trigger)");
-    // driftPct is provider-relative: (provider - local)/provider = (0.2-0.1)/0.2 = 50%.
-    assert.equal(r.driftPct, computeDrift(0.1, 0.2));
-    assert.ok(Math.abs(r.driftPct) > DRIFT_THRESHOLD_PCT, `drift ${r.driftPct}% exceeds the ${DRIFT_THRESHOLD_PCT}% threshold`);
-    assert.ok(r.driftPct > 0, "positive drift = provider billed MORE than recorded (the dangerous direction)");
-    // The per-agent breakdown attributes the provider spend to the agent's key.
-    assert.equal(r.byAgent.alex, 0.2, "provider spend attributed to the agent's api key");
-    // Per-model three-way view is present.
-    assert.ok(r.byModel["claude-haiku-4-5"], "per-model drift view present");
-
-    // ── Control: a provider total WITHIN 10% is NOT flagged. ───────────────
-    const fetchImplClose = async () => ({
-      ok: true, status: 200,
-      json: async () => ({ data: [{ amount: 0.105, model: "claude-haiku-4-5" }] }),
-    });
-    const ok = await reconcileDaily({
-      fetchImpl: fetchImplClose, day, adminKey: "admin-test",
-      ledgerDir: join(root, "state", "cost-tracking"), now: ledgerDeps.now,
-    });
-    assert.equal(ok.providerUSD, 0.105);
-    assert.equal(ok.flagged, false, "5% drift is within tolerance — not flagged");
-  } finally {
-    cleanup(root);
-  }
-});
-
-// ===========================================================================
-// 6. MAESTRO_ROUTER_FORCE_ANTHROPIC=1 short-circuits to stock Anthropic.
-// ===========================================================================
-
-test("6. MAESTRO_ROUTER_FORCE_ANTHROPIC=1 short-circuits spawnRouted + llmTask to stock Anthropic", async () => {
-  const root = tmpRoot();
-  try {
-    const catalog = loadBundled(root);
-    const now = fakeClock();
-    const policy = sessionPolicy();
-    // Kill switch ON, plus a Moonshot key that WOULD otherwise make Kimi the
-    // cheapest session candidate — the switch must win regardless.
-    const env = {
-      MAESTRO_ROUTER_FORCE_ANTHROPIC: "1",
-      MOONSHOT_API_KEY: "sk-test-moonshot",
-      DEEPSEEK_API_KEY: "sk-test-deepseek",
-      ANTHROPIC_API_KEY: "sk-test-anthropic",
-    };
-
-    // ── resolveChain collapses to an Anthropic-only chain. ─────────────────
-    const d = resolveChain(
-      { source: "backlog", data_class: "public", task_class: "session.responder", token_estimate: 5000 },
-      { agentRoot: root, config: policy, catalog, env, now, rng: seededRng(), isOpen: () => ({ open: false }) }
-    );
-    assert.equal(d.chosen.provider, "anthropic", "kill switch forces an Anthropic-only chain");
-    assert.equal(d.chosen.transport, "anthropic-api", "stock Anthropic session transport (no retarget)");
-    assert.deepEqual(d.envForSpawn, {}, "no third-party retarget env under the kill switch");
-    assert.match(d.explain, /kill switch/i, "explain names the kill switch");
-    assert.ok(d.chain.every((c) => c.ref.startsWith("anthropic/")), "every chain member is Anthropic");
-
-    // ── spawnRouted executes that Anthropic-only chain (no Kimi candidate). ──
-    const calls = [];
-    const spawnImpl = (candidate) => {
-      calls.push(candidate.ref);
-      return { ok: true, result: { resultJson: {} } };
-    };
-    const res = await spawnRouted(
-      { source: "backlog", data_class: "public", task_class: "session.responder", token_estimate: 5000 },
-      { agentRoot: root, config: policy, catalog, env, now, rng: seededRng(),
-        isOpen: () => ({ open: false }), breaker: memBreaker(now), spawnImpl }
-    );
-    assert.equal(res.ok, true);
-    assert.equal(res.decision.chosen.provider, "anthropic", "spawnRouted ran the forced Anthropic chain");
-    assert.ok(calls.every((ref) => ref.startsWith("anthropic/")), "no third-party candidate was ever spawned");
-    // No retarget env reached the child: a stock Anthropic session, scrubbed of
-    // the foreign Moonshot/DeepSeek keys.
-    assert.equal(res.env.ANTHROPIC_BASE_URL, undefined, "no ANTHROPIC_BASE_URL retarget under the kill switch");
-    assert.equal(res.env.MOONSHOT_API_KEY, undefined, "the Moonshot key is scrubbed from the child env");
-
-    // ── llmTask also restricts selection to an Anthropic direct row. ───────
-    const fetchImpl = async (url, init) => {
-      // The kill switch must route to the Anthropic /v1/messages wire.
-      assert.match(url, /api\.anthropic\.com\/v1\/messages/, "kill switch routes llmTask to the Anthropic messages wire");
-      const body = JSON.parse(init.body);
-      assert.ok(!("tools" in body), "llmTask stays tool-less under the kill switch");
-      return {
-        ok: true, status: 200,
-        json: async () => ({ content: [{ type: "text", text: "ok" }], usage: { input_tokens: 10, output_tokens: 2 } }),
-      };
-    };
-    const lt = await llmTask("classify", {
-      fetchImpl,
-      request: { task_class: "classify.inbox", source: "inbox", data_class: "public" },
-      config: policy, catalog, env, now, isOpen: () => ({ open: false }),
-      writeLedger: () => {},
-    });
-    assert.equal(lt.ok, true);
-    assert.equal(lt.provider, "anthropic", "kill switch forces llmTask onto an Anthropic direct row");
-    assert.equal(lt.wire, "anthropic-messages", "Anthropic direct → anthropic-messages wire");
-  } finally {
-    cleanup(root);
-  }
-});
-
-// ===========================================================================
-// 7. Standalone unit coverage for the exported env/argv builders (the dispatcher
-//    seam helpers spawnRouted is built from) so a regression in either is caught
-//    even if a future spawnRouted refactor masks it.
-// ===========================================================================
-
-test("7. buildSpawnArgs + buildChildEnv: deterministic argv order and credential scrubbing", () => {
-  // buildSpawnArgs: deterministic, asserts the documented order.
-  const args = buildSpawnArgs(
-    { modelFlag: "kimi-k2.6", maxTurns: 8, effort: "medium", agentsJson: { "Haiku-Explore": { model: "claude-haiku-4-5" } }, bare: true },
-    { extraArgs: ["--prompt-file", "/tmp/p"], outputFormat: "json" }
-  );
-  assert.deepEqual(args.slice(0, 6), ["--print", "--bare", "--output-format", "json", "--model", "kimi-k2.6"]);
-  assert.ok(args.includes("--max-turns") && args[args.indexOf("--max-turns") + 1] === "8");
-  assert.ok(args.includes("--effort") && args[args.indexOf("--effort") + 1] === "medium");
-  assert.ok(args.includes("--agents"), "agentsJson serialized to --agents");
-  assert.deepEqual(args.slice(-2), ["--prompt-file", "/tmp/p"]);
-
-  // buildChildEnv: a third-party retarget injects the empty-string ANTHROPIC_API_KEY
-  // and scrubs every foreign credential.
-  const child = buildChildEnv(
-    { MOONSHOT_API_KEY: "k", OPENAI_API_KEY: "x", SOME_AUTH_TOKEN: "y", PATH: "/bin", HOME: "/h" },
-    { ANTHROPIC_BASE_URL: "https://api.moonshot.ai/anthropic", ANTHROPIC_AUTH_TOKEN: "k", ANTHROPIC_API_KEY: "", ANTHROPIC_MODEL: "kimi-k2.6" }
-  );
-  assert.equal(child.ANTHROPIC_BASE_URL, "https://api.moonshot.ai/anthropic");
-  assert.equal(child.ANTHROPIC_AUTH_TOKEN, "k");
-  assert.equal(child.ANTHROPIC_API_KEY, "", "empty-string discipline (no keychain fallthrough)");
-  assert.equal(child.MOONSHOT_API_KEY, undefined, "foreign *_API_KEY scrubbed");
-  assert.equal(child.OPENAI_API_KEY, undefined, "unrelated *_API_KEY scrubbed");
-  assert.equal(child.SOME_AUTH_TOKEN, undefined, "foreign *_AUTH_TOKEN scrubbed");
-  assert.equal(child.PATH, "/bin", "benign env preserved");
-  assert.equal(child.HOME, "/h");
-
-  // A non-retarget (Anthropic session) child scrubs ANTHROPIC_API_KEY by default
-  // (hygiene) unless keepAnthropicApiKey is set.
-  const stock = buildChildEnv({ ANTHROPIC_API_KEY: "oauth", PATH: "/bin" }, {});
-  assert.equal(stock.ANTHROPIC_API_KEY, undefined, "Anthropic key scrubbed by default for a stock session");
-  const stockKeep = buildChildEnv({ ANTHROPIC_API_KEY: "oauth", PATH: "/bin" }, {}, { keepAnthropicApiKey: true });
-  assert.equal(stockKeep.ANTHROPIC_API_KEY, "oauth", "keepAnthropicApiKey preserves a caller-owned Console key");
-});