@cohortapp/agent-sdk 2.3.0

package/lib/model-router/economics.test.mjs

@@ -0,0 +1,344 @@
+/**
+ * Tests for lib/model-router/economics.mjs — the router economics levers:
+ *   - budgetLadder transitions at 75 / 90 / 100 (a ladder, not a cliff)
+ *   - degradeChain tightens a candidate chain per band
+ *   - batchLaneFor classifies deferrable vs realtime work
+ *   - cacheAffinity pin / lookupPin / resolvePin override (+ pin_overridden audit)
+ *   - spawnKnobsFor task-class defaults incl. the cheap-subagent map
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  budgetLadder,
+  degradeChain,
+  batchLaneFor,
+  pin,
+  lookupPin,
+  resolvePin,
+  spawnKnobsFor,
+  ttlMs,
+  hashSessionKey,
+  _internals,
+} from "./economics.mjs";
+
+// ---------------------------------------------------------------------------
+// budgetLadder — transitions at 75/90/100
+// ---------------------------------------------------------------------------
+
+test("budgetLadder: below 75% is band 0, no degradation", () => {
+  for (const spent of [0, 10, 37, 74.9]) {
+    const r = budgetLadder(spent, 100);
+    assert.equal(r.band, 0, `spent ${spent} → band 0`);
+    assert.equal(r.degrade.preferCheaper, false);
+    assert.equal(r.degrade.cheapOnly, false);
+    assert.equal(r.degrade.essentialOnly, false);
+  }
+});
+
+test("budgetLadder: 50% notice does NOT degrade routing (band 0)", () => {
+  // budget-guard notifies at 50%, but the economics ladder's first rung is 75%.
+  const r = budgetLadder(50, 100);
+  assert.equal(r.band, 0);
+  assert.equal(r.degrade.downgradeTiers, 0);
+});
+
+test("budgetLadder: 75% → prefer cheaper (downgrade one tier)", () => {
+  const r = budgetLadder(75, 100);
+  assert.equal(r.band, 75);
+  assert.equal(r.degrade.preferCheaper, true);
+  assert.equal(r.degrade.cheapOnly, false);
+  assert.equal(r.degrade.batchDeferrable, false);
+  assert.equal(r.degrade.essentialOnly, false);
+  assert.equal(r.degrade.downgradeTiers, 1);
+});
+
+test("budgetLadder: 90% → cheap-only + batch deferrable", () => {
+  const r = budgetLadder(90, 100);
+  assert.equal(r.band, 90);
+  assert.equal(r.degrade.preferCheaper, true);
+  assert.equal(r.degrade.cheapOnly, true);
+  assert.equal(r.degrade.batchDeferrable, true);
+  assert.equal(r.degrade.essentialOnly, false);
+});
+
+test("budgetLadder: 100% → essential-only", () => {
+  const r = budgetLadder(100, 100);
+  assert.equal(r.band, 100);
+  assert.equal(r.degrade.essentialOnly, true);
+  assert.equal(r.degrade.cheapOnly, true);
+  // over-cap also stays band 100
+  assert.equal(budgetLadder(250, 100).band, 100);
+});
+
+test("budgetLadder: no cap (cap<=0) collapses to band 0", () => {
+  assert.equal(budgetLadder(500, 0).band, 0);
+  assert.equal(budgetLadder(500, -1).band, 0);
+  assert.equal(budgetLadder(500, NaN).band, 0);
+});
+
+test("budgetLadder: pct is rounded and exposed", () => {
+  const r = budgetLadder(33.333, 100);
+  assert.equal(r.pct, 33.33);
+  assert.equal(r.capUSD, 100);
+});
+
+// ---------------------------------------------------------------------------
+// degradeChain — tighten per band
+// ---------------------------------------------------------------------------
+
+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",
+};
+
+function aliasChain(...names) {
+  return names.map((n) => ({ ref: ALIASES[n] || n, alias: ALIASES[n] ? n : null }));
+}
+
+test("degradeChain: band < 75 returns the chain unchanged", () => {
+  const chain = aliasChain("frontier", "default");
+  const out = degradeChain(chain, 0, { aliases: ALIASES });
+  assert.deepEqual(out, chain);
+  assert.notEqual(out, chain, "returns a copy, not the same reference");
+});
+
+test("degradeChain: band 75 downgrades each tier one rung", () => {
+  const chain = aliasChain("frontier", "default");
+  const out = degradeChain(chain, 75, { aliases: ALIASES });
+  // frontier→default, default→fast
+  assert.equal(out[0].alias, "default");
+  assert.equal(out[0].ref, ALIASES.default);
+  assert.equal(out[1].alias, "fast");
+  assert.equal(out[1].ref, ALIASES.fast);
+});
+
+test("degradeChain: band 90 drops frontier/default head, keeps cheap/fast", () => {
+  const chain = aliasChain("frontier", "default", "fast", "cheap");
+  const out = degradeChain(chain, 90, { aliases: ALIASES });
+  const aliasesOut = out.map((m) => m.alias);
+  assert.ok(!aliasesOut.includes("frontier"));
+  assert.ok(!aliasesOut.includes("default"));
+  assert.deepEqual(aliasesOut, ["fast", "cheap"]);
+});
+
+test("degradeChain: band 90 with an all-frontier chain keeps the single cheapest as a safety net", () => {
+  const chain = aliasChain("frontier", "default");
+  const out = degradeChain(chain, 90, { aliases: ALIASES });
+  assert.equal(out.length, 1);
+  // 'default' is cheaper than 'frontier', so it's the safety-net survivor.
+  assert.equal(out[0].alias, "default");
+});
+
+test("degradeChain: exempt (pin/critical) bypasses degradation", () => {
+  const chain = aliasChain("frontier", "default");
+  const out = degradeChain(chain, 100, { aliases: ALIASES, exempt: true });
+  assert.deepEqual(out.map((m) => m.alias), ["frontier", "default"]);
+});
+
+test("degradeChain: preserves a rules sentinel as a tail at any band", () => {
+  const chain = [...aliasChain("frontier"), { ref: "rules", isRules: true }];
+  const out90 = degradeChain(chain, 90, { aliases: ALIASES });
+  assert.ok(out90.some((m) => m.ref === "rules"));
+});
+
+test("degradeChain: infers tier from literal refs without alias tags", () => {
+  const chain = [{ ref: "anthropic/claude-opus-4-8" }, { ref: "anthropic/claude-haiku-4-5" }];
+  const out = degradeChain(chain, 90, { aliases: ALIASES });
+  // opus (frontier) dropped; haiku (fast) kept.
+  assert.equal(out.length, 1);
+  assert.match(out[0].ref, /haiku/);
+});
+
+test("degradeChain: de-dupes refs that collapse onto the same model", () => {
+  // default + fast at band 75 → fast + cheap; but if both map to fast they dedupe.
+  const chain = aliasChain("fast", "fast");
+  const out = degradeChain(chain, 75, { aliases: ALIASES });
+  assert.equal(out.length, 1);
+});
+
+// ---------------------------------------------------------------------------
+// batchLaneFor — classify deferrable vs realtime
+// ---------------------------------------------------------------------------
+
+test("batchLaneFor: explicit lane wins", () => {
+  assert.equal(batchLaneFor({ lane: "batch", task_class: "classify.inbox" }), true);
+  assert.equal(batchLaneFor({ lane: "realtime", task_class: "learning.reflect" }), false);
+});
+
+test("batchLaneFor: deferrable task classes default to batch", () => {
+  assert.equal(batchLaneFor({ task_class: "learning.reflect" }), true);
+  assert.equal(batchLaneFor({ task_class: "learning.curate" }), true);
+  assert.equal(batchLaneFor({ task_class: "digest.daily" }), true);
+  assert.equal(batchLaneFor({ task_class: "index.sessions" }), true);
+  assert.equal(batchLaneFor({ task_class: "curate.skills" }), true);
+  assert.equal(batchLaneFor({ task_class: "enrich" }), true);
+});
+
+test("batchLaneFor: realtime classes never defer", () => {
+  assert.equal(batchLaneFor({ task_class: "classify.inbox" }), false);
+  assert.equal(batchLaneFor({ task_class: "session.responder" }), false);
+  assert.equal(batchLaneFor({ task_class: "huddle" }), false);
+  assert.equal(batchLaneFor({ task_class: "voice.brief" }), false);
+});
+
+test("batchLaneFor: high/critical priority never defers even a learning task", () => {
+  assert.equal(batchLaneFor({ task_class: "learning.reflect", priority: "critical" }), false);
+  assert.equal(batchLaneFor({ task_class: "learning.reflect", priority: "high" }), false);
+});
+
+test("batchLaneFor: unknown class defaults to realtime (never silently defers user work)", () => {
+  assert.equal(batchLaneFor({ task_class: "lookup.gmail" }), false);
+  assert.equal(batchLaneFor({}), false);
+});
+
+// ---------------------------------------------------------------------------
+// cacheAffinity — pin / lookupPin / resolvePin override
+// ---------------------------------------------------------------------------
+
+test("ttlMs: parses lane cache_ttl strings", () => {
+  assert.equal(ttlMs("1h"), 3600_000);
+  assert.equal(ttlMs("5m"), 300_000);
+  assert.equal(ttlMs("30s"), 30_000);
+  assert.equal(ttlMs("0"), 0);
+  assert.equal(ttlMs("none"), 0);
+  assert.equal(ttlMs(60_000), 60_000);
+  assert.equal(ttlMs(undefined), 3600_000);
+});
+
+test("cacheAffinity: pin then lookupPin within TTL", () => {
+  const store = {};
+  let clock = 1_000_000;
+  const deps = { store, now: () => clock };
+  const r = pin("slack:C1:thread", "anthropic/claude-sonnet-4-6", "1h", { ...deps, decisionId: "d1" });
+  assert.equal(r.pinned, true);
+  assert.equal(r.expires_at, 1_000_000 + 3600_000);
+
+  const live = lookupPin("slack:C1:thread", deps);
+  assert.ok(live);
+  assert.equal(live.ref, "anthropic/claude-sonnet-4-6");
+  assert.equal(live.decision_id, "d1");
+});
+
+test("cacheAffinity: pin expires after TTL", () => {
+  const store = {};
+  let clock = 0;
+  const deps = { store, now: () => clock };
+  pin("k", "anthropic/claude-haiku-4-5", "5m", deps);
+  clock = 4 * 60_000;
+  assert.ok(lookupPin("k", deps), "live at 4m");
+  clock = 6 * 60_000;
+  assert.equal(lookupPin("k", deps), null, "expired at 6m");
+});
+
+test("cacheAffinity: ttl 0 does not pin", () => {
+  const store = {};
+  const r = pin("k", "anthropic/x", "0", { store, now: () => 0 });
+  assert.equal(r.pinned, false);
+  assert.equal(lookupPin("k", { store, now: () => 0 }), null);
+});
+
+test("cacheAffinity: on-disk store hashes the session_key (no raw PII)", () => {
+  const store = {};
+  pin("dm:+15551234567", "anthropic/x", "1h", { store, now: () => 0 });
+  const keys = Object.keys(store);
+  assert.equal(keys.length, 1);
+  assert.equal(keys[0], hashSessionKey("dm:+15551234567"));
+  assert.ok(!keys[0].includes("5551234567"));
+});
+
+test("resolvePin: honors a live pin that passes the gate", () => {
+  const store = {};
+  const deps = { store, now: () => 0 };
+  pin("k", "anthropic/claude-sonnet-4-6", "1h", deps);
+  const r = resolvePin("k", () => ({ ok: true }), deps);
+  assert.equal(r.ref, "anthropic/claude-sonnet-4-6");
+  assert.equal(r.overridden, false);
+});
+
+test("resolvePin: drops a pin the gate rejects and emits pin_overridden", () => {
+  const store = {};
+  const audit = [];
+  const deps = { store, now: () => 0, audit: (row) => audit.push(row), decisionId: "d9" };
+  pin("k", "moonshot/kimi-k2.6", "1h", deps);
+
+  const r = resolvePin("k", () => ({ ok: false, reason: "breaker_open" }), deps);
+  assert.equal(r.ref, null);
+  assert.equal(r.overridden, true);
+  assert.equal(r.reason, "breaker_open");
+
+  assert.equal(audit.length, 1);
+  assert.equal(audit[0].kind, "pin_overridden");
+  assert.equal(audit[0].ref, "moonshot/kimi-k2.6");
+  assert.equal(audit[0].reason, "breaker_open");
+  // The raw session_key is hashed in the audit row, not stored verbatim.
+  assert.equal(audit[0].session_key_hash, hashSessionKey("k"));
+});
+
+test("resolvePin: no live pin returns a clean null result", () => {
+  const r = resolvePin("absent", () => ({ ok: true }), { store: {}, now: () => 0 });
+  assert.equal(r.ref, null);
+  assert.equal(r.overridden, false);
+});
+
+test("resolvePin: a throwing gate is treated as a rejection (fail-closed for the pin)", () => {
+  const store = {};
+  const audit = [];
+  const deps = { store, now: () => 0, audit: (row) => audit.push(row) };
+  pin("k", "anthropic/x", "1h", deps);
+  const r = resolvePin("k", () => { throw new Error("boom"); }, deps);
+  assert.equal(r.overridden, true);
+  assert.equal(r.reason, "gate_error");
+  assert.equal(audit.length, 1);
+});
+
+// ---------------------------------------------------------------------------
+// spawnKnobsFor — per-task-class defaults incl. cheap-subagent map
+// ---------------------------------------------------------------------------
+
+test("spawnKnobsFor: heavy session classes get the Haiku-Explore subagent map", () => {
+  const k = spawnKnobsFor("session.responder");
+  assert.equal(k.maxTurns, 40);
+  assert.ok(k.agentsJson);
+  assert.ok(k.agentsJson["Haiku-Explore"]);
+  assert.match(k.agentsJson["Haiku-Explore"].model, /haiku/);
+});
+
+test("spawnKnobsFor: cheap one-shot classes get no subagent map", () => {
+  assert.equal(spawnKnobsFor("classify.inbox").agentsJson, null);
+  assert.equal(spawnKnobsFor("classify.inbox").maxTurns, 1);
+  assert.equal(spawnKnobsFor("lookup.gmail").maxTurns, 2); // prefix match
+  assert.equal(spawnKnobsFor("lookup.gmail").agentsJson, null);
+});
+
+test("spawnKnobsFor: learning.reflect uses medium effort", () => {
+  assert.equal(spawnKnobsFor("learning.reflect").effort, "medium");
+});
+
+test("spawnKnobsFor: prefix match for cadence.* ", () => {
+  const k = spawnKnobsFor("cadence.daily-digest");
+  assert.equal(k.maxTurns, 20);
+  assert.ok(k.agentsJson);
+});
+
+test("spawnKnobsFor: unknown class falls back to the generic ceiling", () => {
+  const k = spawnKnobsFor("totally.unknown");
+  assert.equal(k.maxTurns, 40);
+  assert.equal(k.agentsJson, null);
+});
+
+test("spawnKnobsFor: returns a fresh agentsJson clone (safe to mutate)", () => {
+  const a = spawnKnobsFor("session.responder");
+  const b = spawnKnobsFor("session.responder");
+  assert.notEqual(a.agentsJson, b.agentsJson);
+  a.agentsJson["Haiku-Explore"].model = "tampered";
+  assert.notEqual(b.agentsJson["Haiku-Explore"].model, "tampered");
+});
+
+test("internals exposed for cross-layer integration", () => {
+  assert.ok(Array.isArray(_internals.DEFERRABLE_PREFIXES));
+  assert.ok(_internals.TIER_RANK.frontier < _internals.TIER_RANK.cheap);
+});

package/lib/model-router/failover.mjs

@@ -0,0 +1,298 @@
+/**
+ * lib/model-router/failover.mjs — chain-stepping / cooldown engine.
+ *
+ * `stepChain(chain, opts)` walks an ordered candidate chain, applying the
+ * `DISPOSITION` table from taxonomy.mjs to each attempt's outcome: retry the
+ * same candidate where allowed, skip candidates whose breaker is on cooldown,
+ * advance to the next candidate, and STOP without failing over for the
+ * disposition rows that say so (context_overflow, payload_too_large,
+ * content_policy-on-same-content, network/DEFER). When the chain is spent it
+ * returns an exhaustion summary: `tried[]`, the final reason, and the soonest
+ * cooldown expiry so the caller can re-queue with a wake time (never hot-loop).
+ *
+ * Pure-ish by design (SPEC §5 DI discipline): the attempt fn, clock, and
+ * breaker accessors are all injected, so this module performs no real spawn, no
+ * fetch, no fs, no Date.now of its own. It NEVER throws — an attempt fn that
+ * throws is caught and classified `unknown`.
+ *
+ * House style: ESM, Node built-ins only, mirrors rate-guard's deps-injection.
+ */
+
+import { DISPOSITION, asFailoverReason, cooldownMsFor } from "./taxonomy.mjs";
+
+/**
+ * @typedef {object} Candidate
+ * @property {string} ref            catalog ref, e.g. "anthropic/claude-sonnet-4-6"
+ * @property {string} [breakerKey]   the health.mjs key to consult/cool (backend or backend:model)
+ * @property {string} [backendKey]   coarser backend key (for backend-scoped cooldowns)
+ * @property {*}      [*]            opaque — passed through to the attempt fn
+ */
+
+/**
+ * @typedef {object} AttemptResult
+ * @property {boolean} ok            true ⇒ success; failover stops, summary.ok=true
+ * @property {string}  [reason]      a FailoverReason when ok===false
+ * @property {*}       [value]       opaque success payload returned to the caller
+ * @property {object}  [meta]        opaque diagnostics threaded into tried[]
+ */
+
+const noopBreaker = {
+  isOpen: () => ({ open: false, until: 0, reason: null, strikes: 0 }),
+  open: () => {},
+  close: () => {},
+};
+
+function defaultClock() {
+  return Date.now();
+}
+
+/**
+ * Resolve the breaker key to consult/cool for a candidate given the cooldown
+ * scope. `backend:model` and `model-id` cool the fine key; `backend`/`operator`
+ * cool the coarse backend key; `none` cools nothing.
+ */
+function cooldownKey(candidate, scope) {
+  if (scope === "none" || !scope) return null;
+  if (scope === "backend" || scope === "operator") {
+    return candidate.backendKey || candidate.breakerKey || candidate.ref;
+  }
+  // backend:model | model-id → the fine-grained key.
+  return candidate.breakerKey || candidate.ref;
+}
+
+/**
+ * Walk `chain`, attempting each candidate per the disposition table.
+ *
+ * opts:
+ *   attempt(candidate, ctx) → AttemptResult | Promise<AttemptResult>
+ *       The injected work. ctx = { attemptIndex, retryOfRef, now }.
+ *   now()                   → epoch ms (injected clock; default Date.now)
+ *   breaker                 → { isOpen(key,now), open(key,reason,ms,now), close(key,now) }
+ *                             default: a no-op breaker (failover still walks)
+ *   onAttempt(record)       → optional side-channel called after every attempt
+ *   allowContentReroute     → bool; when true, a single content_policy failure
+ *                             may advance ONCE (the "one Anthropic-only re-route
+ *                             permitted" rule). Default false (sticky refusal).
+ *   maxAttempts             → hard cap on total attempts (safety net; default 32)
+ *
+ * @param {Candidate[]} chain
+ * @param {object} opts
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   value?: *,
+ *   chosen?: Candidate,
+ *   reason: string|null,           // final reason (null on success)
+ *   tried: Array<{ref, reason, retry?:boolean, meta?:object}>,
+ *   soonestCooldownExpiry: number|null,  // epoch ms to re-queue at, or null
+ *   attempts: number
+ * }>}
+ */
+export async function stepChain(chain, opts = {}) {
+  const now = typeof opts.now === "function" ? opts.now : defaultClock;
+  const breaker = opts.breaker || noopBreaker;
+  const attempt = typeof opts.attempt === "function" ? opts.attempt : null;
+  const onAttempt = typeof opts.onAttempt === "function" ? opts.onAttempt : null;
+  const allowContentReroute = opts.allowContentReroute === true;
+  const maxAttempts = Number.isFinite(opts.maxAttempts) ? opts.maxAttempts : 32;
+
+  const tried = [];
+  const candidates = Array.isArray(chain) ? chain.filter(Boolean) : [];
+  let soonestCooldownExpiry = null;
+  let lastReason = null;
+  let attempts = 0;
+  let contentRerouted = false;
+
+  const noteCooldown = (until) => {
+    if (until == null || !Number.isFinite(until)) return; // Infinity ⇒ not a wake time
+    if (soonestCooldownExpiry == null || until < soonestCooldownExpiry) {
+      soonestCooldownExpiry = until;
+    }
+  };
+
+  if (!attempt) {
+    return {
+      ok: false,
+      reason: "unknown",
+      tried: [{ ref: candidates[0]?.ref ?? null, reason: "no_attempt_fn" }],
+      soonestCooldownExpiry: null,
+      attempts: 0,
+    };
+  }
+
+  for (let i = 0; i < candidates.length; i++) {
+    const candidate = candidates[i];
+
+    // ── Skip candidates whose breaker is already open ────────────────────
+    const probeKey = candidate.breakerKey || candidate.ref;
+    const backendKey = candidate.backendKey || null;
+    const t0 = now();
+    const fineOpen = breaker.isOpen(probeKey, t0);
+    const backendOpen = backendKey ? breaker.isOpen(backendKey, t0) : { open: false };
+    if (fineOpen.open || backendOpen.open) {
+      const which = fineOpen.open ? fineOpen : backendOpen;
+      tried.push({
+        ref: candidate.ref,
+        reason: `breaker_open:${which.reason || "unknown"}`,
+        skipped: true,
+      });
+      noteCooldown(which.until);
+      lastReason = which.reason || lastReason;
+      continue;
+    }
+
+    // ── Attempt this candidate, with same-candidate retry where allowed ──
+    let advanced = false;
+    let retriedThisCandidate = false;
+    while (attempts < maxAttempts) {
+      attempts++;
+      let res;
+      try {
+        res = await attempt(candidate, {
+          attemptIndex: attempts - 1,
+          retryOfRef: retriedThisCandidate ? candidate.ref : null,
+          now: now(),
+        });
+      } catch (err) {
+        res = { ok: false, reason: "unknown", meta: { thrown: String(err && err.message || err) } };
+      }
+      res = res || { ok: false, reason: "unknown" };
+
+      if (res.ok) {
+        const t1 = now();
+        // Clear the breaker for this key on a clean success.
+        try { breaker.close(probeKey, t1); } catch { /* */ }
+        const record = { ref: candidate.ref, reason: "ok", meta: res.meta };
+        tried.push(record);
+        if (onAttempt) safeCall(onAttempt, record);
+        return {
+          ok: true,
+          value: res.value,
+          chosen: candidate,
+          reason: null,
+          tried,
+          soonestCooldownExpiry: null,
+          attempts,
+        };
+      }
+
+      const reason = asFailoverReason(res.reason);
+      lastReason = reason;
+      const d = DISPOSITION[reason];
+
+      const record = {
+        ref: candidate.ref,
+        reason,
+        retry: retriedThisCandidate || undefined,
+        meta: res.meta,
+      };
+      tried.push(record);
+      if (onAttempt) safeCall(onAttempt, record);
+
+      // ── Open / advance the breaker per disposition ───────────────────
+      if (d.opensBreaker) {
+        const scopeKey = cooldownKey(candidate, d.cooldownScope);
+        if (scopeKey) {
+          const t1 = now();
+          // Let health.mjs derive the stepped/flat cooldown from the table
+          // (pass null) so the ladder advances by the breaker's own strikes.
+          let result;
+          try {
+            result = breaker.open(scopeKey, reason, null, t1);
+          } catch { /* fail-open */ }
+          // If the breaker reports a concrete cooldownUntil, use it; else fall
+          // back to the table's flat value so the summary still has a wake time.
+          const until =
+            result && Number.isFinite(result.cooldownUntil)
+              ? result.cooldownUntil
+              : result && result.cooldownUntil === Infinity
+                ? Infinity
+                : tableCooldownUntil(reason, t1, result && result.strikes);
+          noteCooldown(until);
+        }
+      }
+
+      // ── retry-same? ──────────────────────────────────────────────────
+      const canRetrySame =
+        !retriedThisCandidate &&
+        d.retrySame &&
+        d.retrySame !== "cli"; // "cli" means the CLI already retried internally
+      if (canRetrySame) {
+        retriedThisCandidate = true;
+        continue; // retry the SAME candidate once
+      }
+
+      // ── failover-next? ───────────────────────────────────────────────
+      if (!d.failoverNext) {
+        // Special carve-out: content_policy may re-route ONCE if the caller
+        // opted in (one Anthropic-only re-route permitted), but only across
+        // CONTENT — never a same-content retry.
+        if (reason === "content_policy" && allowContentReroute && !contentRerouted) {
+          contentRerouted = true;
+          advanced = true;
+          break; // advance to next candidate
+        }
+        // No failover for this reason (context_overflow / payload_too_large /
+        // network / sticky content_policy). Terminate the whole walk.
+        return {
+          ok: false,
+          reason,
+          tried,
+          soonestCooldownExpiry, // null for network/overflow (no cooldown)
+          attempts,
+          chosen: undefined,
+        };
+      }
+
+      advanced = true;
+      break; // advance to the next candidate
+    }
+
+    if (!advanced && attempts >= maxAttempts) break;
+  }
+
+  // ── Chain exhausted ──────────────────────────────────────────────────
+  return {
+    ok: false,
+    reason: lastReason || "unknown",
+    tried,
+    soonestCooldownExpiry,
+    attempts,
+    chosen: undefined,
+  };
+}
+
+/** Compute a wake time from the disposition table directly (breaker fallback). */
+function tableCooldownUntil(reason, now, strikes) {
+  const ms = cooldownMsFor(reason, Number.isFinite(strikes) ? Math.max(0, strikes - 1) : 0);
+  if (ms === Infinity) return Infinity;
+  if (!ms) return null;
+  return now + ms;
+}
+
+function safeCall(fn, arg) {
+  try { fn(arg); } catch { /* side-channel must never break the walk */ }
+}
+
+/**
+ * Build a one-line human exhaustion summary string for logs/audit. Mirrors the
+ * mandatory `explain` discipline elsewhere in the router.
+ *
+ * @param {{reason:string, tried:Array, soonestCooldownExpiry:number|null}} summary
+ * @returns {string}
+ */
+export function summarizeExhaustion(summary) {
+  if (!summary) return "no attempts";
+  if (summary.ok) {
+    return `succeeded on ${summary.chosen?.ref ?? "?"} after ${summary.attempts} attempt(s)`;
+  }
+  const trail = (summary.tried || [])
+    .map((t) => `${t.ref ?? "?"}=${t.reason}`)
+    .join(" → ");
+  const wake =
+    summary.soonestCooldownExpiry == null
+      ? "no cooldown (re-queue immediately / DEFER)"
+      : `wake at ${new Date(summary.soonestCooldownExpiry).toISOString()}`;
+  return `chain exhausted (final=${summary.reason}): ${trail}; ${wake}`;
+}
+
+export const _internals = { cooldownKey, tableCooldownUntil, noopBreaker };