@humwick/server 0.0.0-stage → 0.130.0

package/src/task-dispatcher.ts

@@ -0,0 +1,841 @@
+import { isOpenAiApiModel } from "@humwick/sdk";
+// #839 — the declarative task dispatcher.
+//
+// A pure function from (Task work-shape + live system state) → a concrete spawn
+// (provider / model / effort) plus a human-readable rationale. The work-shape is the
+// small, stable taxonomy a coordinator declares on the Task's `dispatch` field
+// ({complexity, type, contextFootprint, criticality}); the routing heuristics that map
+// it onto an agent live as INSPECTABLE, EDITABLE policy (RoutingPolicy.dispatch, with a
+// built-in default) — never hardcoded here, never tribal coordinator knowledge.
+//
+// Guarantees this module is built to keep (the #839 GUARD):
+//   1. Every decision reports WHY (rationale string + structured factors).
+//   2. Every decision is overridable by an explicit model/provider pin.
+//   3. The function is PURE — no DB writes, no spawning. The MCP entrypoint
+//      (mcp-dispatch-tools.ts) consumes the decision; #838 (spawn-with-task) will
+//      hydrate + actually spawn. Auto-review surfaces as a PLAN the caller may enact.
+import type {
+  DispatchAutoReview,
+  DispatchModelTarget,
+  DispatchPolicy,
+  DispatchRule,
+  HostUtilizationSignal,
+  RoutingRule,
+  SpawnProvider,
+  TaskDispatch,
+} from "@humwick/sdk";
+import { isProviderEnabled, type ProviderCatalogEntry, type ProviderModelCatalogEntry } from "@humwick/sdk/provider-catalog";
+import { getAllManifests, getManifest, routingFamilySiblings } from "@humwick/providers";
+import { effectiveProviderCatalogList } from "./provider-catalog-store";
+import { getDispatchPolicy, getRoutingPolicy } from "./routing-policy-store";
+import { rankCandidates, quotaFor, bandRank, markRankingSelected, type DispatchCandidate } from "./task-dispatcher-ranking";
+import { automaticallyRoutable, createRoutingEligibility, routingResolutionError } from "./routing-eligibility";
+import { matchesShape } from "./dispatch-match";
+import { evaluateRoutingPreferences, preferenceExclusions, preferenceRationale, preferenceAdditions, type RoutingPreferenceEvaluation } from "./routing-preferences";
+import { advertisedProviders, providerQuotaBands, type ProviderQuotaBand, type QuotaBand } from "./spawn-targets";
+import { CLAUDE_API_PROVIDER, decideApiOverflow, isClaudeSubscription, type ApiOverflowContext, type ApiOverflowVerdict } from "./claude-api-overflow";
+import { DEFAULT_API_EXPIRY_LEAD_MS, inApiExpiryLeadWindow, decideApiExpiry, type ApiExpiryContext } from "./claude-api-expiry";
+
+import type { SpawnCapOptions } from "./spawn-placement";
+import { dispatchWithLiveContext } from "./task-dispatch-live";
+import { runnableDispatchCatalog, type TargetAdmission, type TargetUncertainty } from "./dispatch-availability";
+
+/** An explicit per-case override. Any field set wins over the policy-derived target. */
+export interface DispatchPin {
+  provider?: SpawnProvider;
+  model?: string;
+  effort?: string;
+}
+
+/**
+ * Live-state inputs. All optional + injectable so the dispatcher is unit-testable without a
+ * running fleet; each defaults to the real source (policy store / quota bands / catalog).
+ */
+export interface DispatchContext {
+  /** Live admission predicate; omitted by catalog-only unit callers. */
+  targetAvailable?: (target: DispatchTarget) => boolean;
+  targetUnavailableReason?: (target: DispatchTarget) => string | undefined;
+  targetAdmission?: (target: DispatchTarget) => TargetAdmission;
+  orchestratorId?: string;
+  spawnCap?: SpawnCapOptions;
+  policy?: DispatchPolicy;
+  bands?: ProviderQuotaBand[];
+  catalog?: ProviderCatalogEntry[];
+  /**
+   * #901 degrade-never-refuse: when true, the dispatcher ALWAYS returns a usable provider —
+   * widening the search through caution → avoid-large → least-utilized blockedNow tiers before
+   * giving up. A loud warning is emitted for each degraded tier used. Non-critical paths (flag
+   * unset or false) keep the existing stricter behaviour (prefer|normal only).
+   */
+  mustResolveAvailable?: boolean;
+  /**
+   * #901 host-placement seam. Shape-only in v1 — no selection logic reads this field yet.
+   * A future host-placement phase will inject live host load here so the dispatcher can
+   * prefer the least-loaded machine when multiple orchestrators are viable.
+   */
+  hosts?: HostUtilizationSignal[];
+  /**
+   * #2516 — providers at least one ONLINE orchestrator advertises (heartbeat-reported
+   * `providers`). Family-sibling candidates are nominated ONLY when advertised: a manifest/
+   * catalog entry alone is not live availability (claude-b is registered on every install),
+   * and routing load onto an unadvertised sibling gets the spawn rejected instead of falling
+   * back to codex/zai. Defaults to the live orchestrator roster; inject `new Set()` in the
+   * pure-function harness to model a host that advertises no sibling.
+   */
+  advertisedProviders?: Set<SpawnProvider>;
+  /** #2754 — subscription-overflow snapshot. Absent = overflow off; only the async shell gathers it. */
+  apiOverflow?: ApiOverflowContext;
+  apiExpiry?: ApiExpiryContext;
+  /** #3105 — prefer any advertised, unblocked provider outside these (and their model family); with none, stay among them. */
+  avoidProviders?: readonly SpawnProvider[];
+  /** #3121 — `advertisedProviders` is a pinned host's: every candidate must be one of them. */
+  onlyAdvertised?: boolean;
+  /** #3327 — routing preferences (RoutingPolicy.rules); defaults to the stored policy's. */
+  preferences?: readonly RoutingRule[];
+  /** Captured once by the async shell; injected in boundary tests. */
+  now?: number;
+  policyRevision?: number;
+}
+
+export interface DispatchTarget {
+  provider: SpawnProvider;
+  model?: string;
+  effort?: string;
+  /**
+   * #901 host-placement seam. Stays undefined in v1 — a future host-placement phase will
+   * populate this with the chosen orchestrator id when multiple hosts are viable.
+   * No selection logic writes or reads this field in v1.
+   */
+  orchestratorId?: string;
+}
+
+/** Structured trace of the inputs that produced the decision (the machine-readable rationale). */
+export interface DispatchFactors {
+  evaluatedAt?: number;
+  policyRevision?: number;
+  pinSources?: Record<string, string>;
+  constraintOverrides?: Array<{ ruleId: string; source: string }>;
+  complexity?: string;
+  type?: string;
+  contextFootprint?: string;
+  criticality?: string;
+  /** Label of the matched rule, or a "fallback"/"pin" marker. */
+  matchedRule: string;
+  /** The final provider's live quota band. */
+  band: QuotaBand;
+  /** Context window of the chosen model, when known. */
+  contextWindowTokens?: number;
+  /** Model was escalated to a bigger-window family member for a large footprint. */
+  escalatedForFootprint?: boolean;
+  /** Provider was rerouted away from a scarce/blocked pool; original provider recorded here. */
+  reroutedFromProvider?: SpawnProvider;
+  /** Which target fields were set by an explicit pin. */
+  pinnedFields?: string[];
+  /** Ranked provider/model candidates considered by the quota-aware resolver. */
+  ranking?: DispatchRankingEntry[];
+  /** Human-readable reason the winning candidate beat same-band alternatives. */
+  rankingReason?: string;
+  /** #2754 — overflow verdict, present when the policy is on and the target was Claude subscription work. */
+  apiOverflow?: ApiOverflowVerdict & { fromProvider?: SpawnProvider };
+  apiExpiry?: ApiOverflowVerdict & { fromProvider?: SpawnProvider; leadTimeMs?: number; skippedRerouteProvider?: SpawnProvider };
+  subscriptionExpiry?: string;
+  /** #3105 — the avoided providers; `fallback`: none other was advertised with quota, so the decision stayed among them. */
+  avoidProviders?: { providers: SpawnProvider[]; fallback: boolean };
+  /** #3327 — matching routing preferences and the per-provider counts they ranked by (within a quota band). */
+  preferences?: RoutingPreferenceEvaluation;
+}
+
+export interface DispatchRankingEntry {
+  provider: SpawnProvider;
+  model?: string;
+  effort?: string;
+  label?: string;
+  band: QuotaBand;
+  quotaPenalty: number;
+  slack: number | null;
+  prefer: boolean;
+  blockedNow: boolean;
+  /** #3327 — net routing-preference count for this provider. */
+  preference?: number;
+  directive?: number;
+  selected?: boolean;
+  dropReason?: string;
+  probeUncertainties?: TargetUncertainty[];
+  rankReason?: string;
+}
+
+/** A dependent review Task the caller may create (high criticality / complex work). */
+export interface ReviewPlan {
+  /** Work-shape for the review Task. */
+  dispatch: TaskDispatch;
+  target: DispatchTarget;
+  rationale: string;
+  /** Why the review was triggered (e.g. "criticality=high"). */
+  reason: string;
+}
+
+export interface DispatchDecision {
+  target: DispatchTarget;
+  /** True when any target field came from an explicit pin. */
+  pinned: boolean;
+  /** Human-readable explanation, e.g. `opus-4.8 high: type=build, complexity=complex; claude band=normal`. */
+  rationale: string;
+  factors: DispatchFactors;
+  /** Non-fatal advisories (e.g. scarce pool, no model meets the footprint). */
+  warnings: string[];
+  /** Present when the policy's auto-review threshold is met. */
+  review?: ReviewPlan;
+}
+
+// ---------------------------------------------------------------------------
+// Public entrypoint
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a work-shape + live state onto a concrete spawn. `pin` overrides any field per-case;
+ * the rationale always explains the choice (including why a pin or reroute happened).
+ */
+export function dispatchTask(shape: TaskDispatch | undefined, pin: DispatchPin = {}, ctx: DispatchContext = {}): DispatchDecision {
+  const policy = ctx.policy ?? getDispatchPolicy();
+  const catalog = runnableDispatchCatalog((ctx.catalog ?? effectiveProviderCatalogList()).map(entry => ({ ...entry, models: entry.models.filter(model => !isOpenAiApiModel(entry.provider, model.alias) || pin?.model === model.alias) })), ctx.targetAvailable);
+  const bands = ctx.bands ?? providerQuotaBands();
+  const advertised = ctx.advertisedProviders ?? advertisedProviders();
+  const work: TaskDispatch = shape ?? {};
+  const warnings: string[] = [];
+
+  // An injected policy snapshot carries its own preferences (or none); only the store default reads them here.
+  const preferences = evaluateRoutingPreferences(ctx.preferences ?? (ctx.policy ? [] : getRoutingPolicy().rules), work, ctx.now ?? Date.now());
+  const controlled = preferences.matched.length > 0;
+  const eligibility = createRoutingEligibility(catalog, bands, advertised, preferences);
+  const policyCandidates = withPreferredCandidates(resolvePolicyCandidates(work, policy, advertised), preferences, catalog, advertised);
+  const avoid = ctx.avoidProviders?.length && !pin.provider ? new Set(ctx.avoidProviders.flatMap(sameModelProviders)) : undefined;
+  // #3121 — a pinned host's spawn also lands on a provider it advertises: its policy candidates there, else its healthiest one.
+  const preference = avoid || ctx.onlyAdvertised ? preferOtherProvider(policyCandidates, avoid ?? new Set(), advertised, bands, catalog, preferences, eligibility) : undefined;
+  const candidates = preference?.candidates ?? policyCandidates;
+  const matched = candidates[0]!;
+  let target: DispatchTarget = { ...matched.target };
+  const factors: DispatchFactors = {
+    ...(ctx.now !== undefined ? { evaluatedAt: ctx.now } : {}),
+    ...(ctx.policyRevision !== undefined ? { policyRevision: ctx.policyRevision } : {}),
+    ...(work.complexity ? { complexity: work.complexity } : {}),
+    ...(work.type ? { type: work.type } : {}),
+    ...(work.contextFootprint ? { contextFootprint: work.contextFootprint } : {}),
+    ...(work.criticality ? { criticality: work.criticality } : {}),
+    matchedRule: matched.label,
+    band: "normal",
+    ...(avoid ? { avoidProviders: { providers: [...avoid], fallback: !preference!.other } } : {}),
+    ...(controlled || preferences.expired.length ? { preferences } : {}),
+  };
+  if (avoid && !preference!.other) warnings.push(`No provider other than ${[...avoid].join("/")} is advertised with quota; staying on that family.`);
+
+  const providerPinnedByInput = Boolean(pin.provider);
+  const modelPinnedByInput = Boolean(pin.model);
+  const effortPinnedByInput = Boolean(pin.effort);
+  let selectedExplicitModel = Boolean(matched.target.model);
+  let selectedExplicitEffort = Boolean(matched.target.effort);
+
+  if (!providerPinnedByInput && !modelPinnedByInput) {
+    const targetAvailable = ctx.targetAvailable && ((t: DispatchModelTarget) => ctx.targetAvailable!({ ...t, model: t.model ?? catalogEntry(catalog, t.provider)?.defaultModel }));
+    const targetAdmission = ctx.targetAdmission && ((t: DispatchModelTarget) => ctx.targetAdmission!({ ...t, model: t.model ?? catalogEntry(catalog, t.provider)?.defaultModel }));
+    const options = { allowBlockedLastResort: !controlled && ctx.mustResolveAvailable === true, preferences, eligibility, targetAvailable, targetAdmission };
+    let ranked = rankCandidates(candidates, bands, options);
+    if (!ranked.winner && ctx.targetAvailable) {
+      ranked = rankCandidates([...candidates, ...runnableAlternatives(catalog, advertised, candidates.length)], bands, options);
+    }
+    factors.ranking = ranked.ranking;
+    if (ranked.winner) {
+      target = { ...ranked.winner.target };
+      factors.matchedRule = ranked.winner.label;
+      factors.rankingReason = ranked.reason;
+      selectedExplicitModel = Boolean(ranked.winner.target.model);
+      selectedExplicitEffort = Boolean(ranked.winner.target.effort);
+    }
+  }
+
+  const pinnedFields = applyPin(target, pin);
+  const providerPinned = pinnedFields.includes("provider");
+  const modelPinned = pinnedFields.includes("model");
+  const effortPinned = pinnedFields.includes("effort");
+  if (pinnedFields.length) factors.pinnedFields = pinnedFields;
+
+  // Footprint escalation (skip when the model is explicitly pinned — respect the human choice).
+  if (!modelPinned) escalateForFootprint(target, work, policy, catalog, factors, warnings);
+
+  // Model finalization: complexity modulation, then the enabled-model guarantee (a pinned model wins).
+  const finalizeModel = (t: DispatchTarget, out: string[], source?: DispatchTarget) => {
+    if (!modelPinned || !effortPinned) {
+      modulateForComplexity(t, work, policy, bands, catalog, out, { modelPinned, effortPinned, explicitModel: source ? Boolean(source.model) : selectedExplicitModel, explicitEffort: source ? Boolean(source.effort) : selectedExplicitEffort });
+    }
+    if (!modelPinned) ensureEnabledModel(t, catalog, out);
+    if (ctx.targetAvailable && !modelPinned && !t.model) t.model = catalogEntry(catalog, t.provider)?.defaultModel;
+    if (ctx.targetAvailable && !effortPinned && !t.effort) {
+      t.effort = catalogEntry(catalog, t.provider)?.models.find((model) => model.alias === (t.model ?? catalogEntry(catalog, t.provider)?.defaultModel))?.defaultEffort;
+    }
+  };
+  // #2754 — opt-in overflow onto claude-api pre-empts leaving the Claude family. It is judged on the
+  // model that would actually run on claude-api, so that target is finalized before the verdict.
+  const paid: DispatchTarget = { ...target, provider: CLAUDE_API_PROVIDER };
+  const paidWarnings: string[] = [];
+  const paidSource = ctx.apiExpiry?.expiryPolicy?.enabled && !isClaudeSubscription(target.provider) && isClaudeSubscription(matched.target.provider) ? matched.target : undefined;
+  if (!providerPinned && (ctx.apiOverflow?.policy?.enabled || ctx.apiExpiry?.expiryPolicy?.enabled)) {
+    if (paidSource) {
+      Object.assign(paid, { ...paidSource, provider: CLAUDE_API_PROVIDER, ...(modelPinned ? { model: pin.model } : {}), ...(effortPinned ? { effort: pin.effort } : {}) });
+      if (!modelPinned) escalateForFootprint(paid, work, policy, catalog, { ...factors }, paidWarnings);
+    }
+    finalizeModel(paid, paidWarnings, paidSource);
+  }
+  const paidDrop = controlled ? eligibility(CLAUDE_API_PROVIDER) ?? (preference?.other && avoid?.has(CLAUDE_API_PROVIDER) ? "cross-provider family partition" : undefined) : undefined;
+  const constrainPaid = (verdict: ApiOverflowVerdict | undefined) => verdict?.selected && paidDrop ? { selected: false, reason: `${verdict.reason}; claude-api excluded: ${paidDrop}` } : verdict;
+  const overflow = providerPinned || !ctx.apiOverflow ? undefined : constrainPaid(decideApiOverflow(target.provider, paid.model, advertised, catalog, ctx.apiOverflow));
+  const expiry = providerPinned || !ctx.apiExpiry ? undefined : constrainPaid(decideApiExpiry(matched.target.provider, paid.model, advertised, catalog, ctx.apiExpiry));
+  if (expiry) factors.apiExpiry = expiry.selected ? { ...expiry, fromProvider: matched.target.provider, leadTimeMs: ctx.apiExpiry?.expiryPolicy?.leadTimeMs ?? DEFAULT_API_EXPIRY_LEAD_MS } : expiry;
+  const expiryWindow = ctx.apiExpiry && inApiExpiryLeadWindow(ctx.apiExpiry.expiryPolicy, ctx.apiExpiry.budget, ctx.apiExpiry.now);
+  if (overflow) factors.apiOverflow = expiryWindow ? { selected: false, reason: `monthly expiry policy takes precedence: ${expiry?.reason}` } : overflow.selected ? { ...overflow, fromProvider: target.provider } : overflow;
+  if (expiry?.selected) {
+    const skipped = { ...target };
+    rerouteForBand(skipped, work, policy, bands, catalog, { ...factors }, [], { effortPinned, mustResolveAvailable: ctx.mustResolveAvailable, advertised, preferences, eligibility });
+    if (!isClaudeSubscription(skipped.provider) && skipped.provider !== CLAUDE_API_PROVIDER) factors.apiExpiry!.skippedRerouteProvider = skipped.provider;
+  }
+  if (expiry?.selected || (overflow?.selected && !expiryWindow)) {
+    Object.assign(target, paid);
+    warnings.push(...paidWarnings);
+  } else {
+    // Band-aware rerouting (skip when the provider is explicitly pinned). Protects scarce pools
+    // and load-shifts large/blocked work onto an abundant one, re-validating footprint + pinned effort.
+    if (!providerPinned) rerouteForBand(target, work, policy, bands, catalog, factors, warnings, { effortPinned, mustResolveAvailable: ctx.mustResolveAvailable, advertised, preferences, eligibility, ...(preference?.other ? { avoid } : {}) });
+    finalizeModel(target, warnings);
+  }
+
+  if (controlled && !providerPinned && !modelPinned) {
+    if (eligibility(target.provider)) throw routingResolutionError(preferences, catalog, eligibility);
+    if (ctx.mustResolveAvailable && bandRank(bandFor(target.provider, bands)) > bandRank("normal")) warnings.push(`[CRITICAL] mustResolveAvailable: degraded to ${target.provider} (${bandFor(target.provider, bands)} band). Contention likely.`);
+  }
+  if (!modelPinned && ctx.targetAvailable && !ctx.targetAvailable(target)) {
+    throw new Error(ctx.targetUnavailableReason?.(target) ?? `No eligible online host runs ${target.provider}/${target.model ?? "default"}${target.effort ? ` at effort ${target.effort}` : ""}.`);
+  }
+  if (factors.preferences) factors.preferences = { ...factors.preferences, excluded: preferenceExclusions(preferences, factors.ranking, (p) => eligibility(p) ?? (!advertised.has(p) ? "not-advertised" : undefined)) };
+  // Record the FINAL provider's band + the chosen model's window for transparency.
+  factors.band = bandFor(target.provider, bands);
+  const subscriptionExpiry = bands.find((b) => b.provider === target.provider)?.expiryPreference;
+  if (subscriptionExpiry) factors.subscriptionExpiry = subscriptionExpiry;
+  const finalWindow = contextWindowOf(catalog, target.provider, target.model);
+  if (finalWindow !== undefined) factors.contextWindowTokens = finalWindow;
+  collectBandWarnings(target.provider, work, bands, providerPinned, warnings);
+
+  const review = planAutoReview(work, policy, bands, catalog, ctx);
+
+  return {
+    target,
+    pinned: pinnedFields.length > 0,
+    rationale: buildRationale(target, factors),
+    factors,
+    warnings,
+    ...(review ? { review } : {}),
+  };
+}
+
+function runnableAlternatives(catalog: ProviderCatalogEntry[], advertised: Set<SpawnProvider>, priority: number): DispatchCandidate[] {
+  return catalog.filter((entry) => advertised.has(entry.provider) && automaticallyRoutable(entry.provider)).map((entry, i) => {
+    const model = entry.models.find((model) => model.alias === entry.defaultModel);
+    return { target: { provider: entry.provider, model: model?.alias, effort: model?.defaultEffort }, label: `${entry.provider} runnable catalog alternative`, priority: priority + i };
+  });
+}
+
+export function dispatchTaskAsync(shape: TaskDispatch | undefined, pin: DispatchPin = {}, ctx: Omit<DispatchContext, "policy" | "bands" | "catalog"> = {}): Promise<DispatchDecision> {
+  return dispatchWithLiveContext(shape, pin, ctx, dispatchTask);
+}
+
+// ---------------------------------------------------------------------------
+// Policy rule matching
+// ---------------------------------------------------------------------------
+
+/**
+ * #2516 — provider families: subscriptions that share one model surface but hold INDEPENDENT
+ * quota windows (#2513/#2514): claude (primary subscription) and claude-b (second subscription,
+ * own credentials + own 5h/7d quota). Family membership is classified canonically by the
+ * provider manifest's launch shim (routingFamilySiblings in @humwick/providers: every
+ * `claude-relay` manifest is one family), NOT by a hardcoded id list — a future claude-c joins
+ * by registering a claude-relay manifest. A policy rule targeting one family member also
+ * nominates the others as trailing candidates, so the quota-aware ranker shifts a scarce
+ * member's load INSIDE the family (near-capped claude → healthy claude-b) before
+ * `rerouteForBand`'s generic healthiest-of-ALL fallback can leave the family for codex/zai.
+ */
+function resolvePolicyCandidates(work: TaskDispatch, policy: DispatchPolicy, advertised: Set<SpawnProvider>): DispatchCandidate[] {
+  const candidates: DispatchCandidate[] = [];
+  for (let i = 0; i < policy.rules.length; i++) {
+    const rule = policy.rules[i]!;
+    if (rule.enabled === false) continue;
+    if (matchesShape(rule.match, work)) {
+      candidates.push({ target: rule.target, label: rule.label ?? "rule", priority: i });
+    }
+  }
+  const base = candidates.length ? candidates : [{ target: policy.fallback, label: "fallback (no rule matched)", priority: policy.rules.length }];
+  return expandFamilyCandidates(base, advertised);
+}
+
+/**
+ * #2516 family expansion — append each candidate's manifest-classified siblings that the policy
+ * didn't already target explicitly AND that at least one online orchestrator advertises (a
+ * catalog entry alone is not live availability — see DispatchContext.advertisedProviders).
+ * Siblings trail their origin rule by half a priority slot: the rule's own target still wins
+ * ties, while the family fallback ranks ahead of later non-family rules.
+ */
+function expandFamilyCandidates(candidates: DispatchCandidate[], advertised: Set<SpawnProvider>): DispatchCandidate[] {
+  const explicit = new Set(candidates.map((candidate) => candidate.target.provider));
+  const expanded: DispatchCandidate[] = [...candidates];
+  for (const candidate of candidates) {
+    for (const sibling of routingFamilySiblings(candidate.target.provider) as SpawnProvider[]) {
+      if (explicit.has(sibling)) continue;
+      explicit.add(sibling);
+      if (!advertised.has(sibling)) continue; // no online host advertises it — never route to it
+      expanded.push({
+        target: { ...candidate.target, provider: sibling },
+        label: `${candidate.label} → ${sibling} (family)`,
+        priority: candidate.priority + 0.5,
+      });
+    }
+  }
+  return expanded;
+}
+
+// #3327 — with a matching preference, eligible catalog providers no work-shape rule seeds are ranked too.
+function withPreferredCandidates(candidates: DispatchCandidate[], preferences: RoutingPreferenceEvaluation, catalog: ProviderCatalogEntry[], advertised: Set<SpawnProvider>): DispatchCandidate[] {
+  const next = Math.max(0, ...candidates.map((candidate) => candidate.priority)) + 1;
+  return [...candidates, ...preferenceAdditions(preferences, candidates.map((c) => c.target.provider), catalog.map((e) => e.provider), (p) => advertised.has(p) && automaticallyRoutable(p))
+    .map((provider, i) => ({ target: { provider }, label: `${provider} catalog alternative (routing preference)`, priority: next + i }))];
+}
+
+// ---------------------------------------------------------------------------
+// Pin application
+// ---------------------------------------------------------------------------
+
+function applyPin(target: DispatchTarget, pin: DispatchPin): string[] {
+  const fields: string[] = [];
+  if (pin.provider) {
+    // A provider change invalidates a provider-specific policy model/effort unless the pin
+    // also restates them; clear them so we fall back to that provider's defaults.
+    if (pin.provider !== target.provider) {
+      if (!pin.model) target.model = undefined;
+      if (!pin.effort) target.effort = undefined;
+    }
+    target.provider = pin.provider;
+    fields.push("provider");
+  }
+  if (pin.model) {
+    target.model = pin.model;
+    fields.push("model");
+  }
+  if (pin.effort) {
+    target.effort = pin.effort;
+    fields.push("effort");
+  }
+  return fields;
+}
+
+// ---------------------------------------------------------------------------
+// Footprint → context-window escalation
+// ---------------------------------------------------------------------------
+
+function escalateForFootprint(
+  target: DispatchTarget,
+  work: TaskDispatch,
+  policy: DispatchPolicy,
+  catalog: ProviderCatalogEntry[],
+  factors: DispatchFactors,
+  warnings: string[],
+): void {
+  const footprint = work.contextFootprint;
+  if (!footprint) return;
+  const minTokens = policy.footprintMinContextTokens?.[footprint];
+  if (!minTokens) return;
+  const entry = catalogEntry(catalog, target.provider);
+  if (!entry) return;
+  const alias = target.model ?? entry.defaultModel;
+  const current = alias ? contextWindowFromEntry(entry, alias) : undefined;
+  if (current !== undefined && current >= minTokens) return; // already big enough
+
+  // Prefer widening the SAME model family (opus-4.8 → opus-4.8[1m]); fall back to any other
+  // sufficient model on this provider before giving up (e.g. after a reroute reset us to a small
+  // default). Smallest sufficient window wins so we don't over-allocate.
+  const pick = biggestSufficient(entry, minTokens, alias);
+  if (pick && pick.alias !== alias) {
+    target.model = pick.alias;
+    factors.escalatedForFootprint = true;
+    return;
+  }
+  if (!pick && current === undefined) return; // unknown window AND no sufficient alternative — can't assert a gap
+  // Nothing on this provider satisfies the footprint — surface it rather than silently downgrade.
+  warnings.push(
+    `contextFootprint=${footprint} wants ≥${minTokens} tokens but ${target.provider}/${alias ?? "default"} offers ${current ?? "unknown"}; no model on ${target.provider} meets it — review the pick.`,
+  );
+}
+
+/**
+ * Validate that `target.model` is enabled on the chosen provider. When it is disabled or
+ * unavailable, replace it with the first enabled model and emit a warning. Callers must skip
+ * this when the model was explicitly pinned (pin takes precedence, even if broken).
+ */
+function ensureEnabledModel(target: DispatchTarget, catalog: ProviderCatalogEntry[], warnings: string[]): void {
+  const entry = catalogEntry(catalog, target.provider);
+  if (!entry) return;
+  const alias = target.model ?? entry.defaultModel;
+  if (!alias) return;
+  const model = entry.models.find((m) => m.alias === alias || m.providerModel === alias);
+  if (model && !model.disabled && !model.unavailable) return;
+  const enabled = entry.models.find((m) => !m.disabled && !m.unavailable);
+  if (enabled) {
+    warnings.push(`Model ${alias} is disabled/unavailable on ${target.provider}; resolved to ${enabled.alias} instead.`);
+    target.model = enabled.alias;
+  } else {
+    warnings.push(`No enabled models on ${target.provider}; spawn may fail.`);
+  }
+}
+
+// The smallest-window model on this provider whose window meets the requirement. Prefers the
+// same model family as `alias` (e.g. opus-4.8 → opus-4.8[1m]) when one qualifies, else any family.
+function biggestSufficient(
+  entry: ProviderCatalogEntry,
+  minTokens: number,
+  alias: string | undefined,
+): ProviderModelCatalogEntry | undefined {
+  const sufficient = entry.models
+    .filter((m) => !m.disabled && !m.unavailable)
+    .map((m) => ({ model: m, window: m.limits?.contextWindowTokens?.value }))
+    .filter((c): c is { model: ProviderModelCatalogEntry; window: number } => typeof c.window === "number" && c.window >= minTokens)
+    .sort((a, b) => a.window - b.window);
+  const base = alias ? familyBase(alias) : undefined;
+  const sameFamily = base ? sufficient.find((c) => familyBase(c.model.alias) === base) : undefined;
+  return (sameFamily ?? sufficient[0])?.model;
+}
+
+function familyBase(alias: string): string {
+  return alias.trim().toLowerCase().replace(/\[[^\]]+\]$/, "");
+}
+
+function modulateForComplexity(
+  target: DispatchTarget,
+  work: TaskDispatch,
+  policy: DispatchPolicy,
+  bands: ProviderQuotaBand[],
+  catalog: ProviderCatalogEntry[],
+  warnings: string[],
+  opts: { modelPinned: boolean; effortPinned: boolean; explicitModel: boolean; explicitEffort: boolean },
+): void {
+  const complexity = work.complexity;
+  const critical = work.criticality === "high";
+  const entry = catalogEntry(catalog, target.provider);
+  if (!entry) return;
+  const minContextTokens = work.contextFootprint ? policy.footprintMinContextTokens?.[work.contextFootprint] : undefined;
+  if (complexity === "trivial" && !critical) {
+    if (!opts.modelPinned && !opts.explicitModel) {
+      const cheaper = cheapestModel(entry, minContextTokens, target.effort);
+      if (cheaper && cheaper.alias !== target.model) target.model = cheaper.alias;
+    }
+    if (!opts.effortPinned && !opts.explicitEffort) {
+      const low = effortIfSupported(entry, target.model, "low");
+      if (low) target.effort = low;
+    }
+    return;
+  }
+  if (complexity === "complex" || critical) {
+    if (!opts.modelPinned && !opts.explicitModel) {
+      const richer = richestModel(entry, minContextTokens, target.effort);
+      if (richer && richer.alias !== target.model) target.model = richer.alias;
+    }
+    if (!opts.effortPinned && !opts.explicitEffort) {
+      const high = effortIfSupported(entry, target.model, "high") ?? effortIfSupported(entry, target.model, "xhigh") ?? effortIfSupported(entry, target.model, "max");
+      if (high) target.effort = high;
+    }
+    return;
+  }
+  if (work.type === "mechanical" && !critical && !opts.effortPinned && !opts.explicitEffort) {
+    const quota = quotaFor(target.provider, bands);
+    if ((quota.band === "caution" || quota.band === "avoid-large") && effortIfSupported(entry, target.model, "low")) {
+      target.effort = "low";
+      warnings.push(`Quota pressure on ${target.provider} bounded ${work.type ?? "trivial"} work to low effort.`);
+    }
+  }
+}
+
+function cheapestModel(entry: ProviderCatalogEntry, minContextTokens?: number, effort?: string): ProviderModelCatalogEntry | undefined {
+  return contextEligibleModels(entry, minContextTokens)
+    .filter((model) => !effort || model.efforts.includes(effort))
+    .sort((a, b) => {
+      const tierDelta = modelTier(a.alias) - modelTier(b.alias);
+      if (tierDelta) return tierDelta;
+      return minContextTokens ? (a.limits?.contextWindowTokens?.value ?? Number.POSITIVE_INFINITY) - (b.limits?.contextWindowTokens?.value ?? Number.POSITIVE_INFINITY) : 0;
+    })[0];
+}
+
+function richestModel(entry: ProviderCatalogEntry, minContextTokens?: number, effort?: string): ProviderModelCatalogEntry | undefined {
+  return contextEligibleModels(entry, minContextTokens)
+    .filter((model) => !effort || model.efforts.includes(effort))
+    .sort((a, b) => {
+      const tierDelta = modelTier(b.alias) - modelTier(a.alias);
+      if (tierDelta) return tierDelta;
+      return minContextTokens ? (b.limits?.contextWindowTokens?.value ?? Number.NEGATIVE_INFINITY) - (a.limits?.contextWindowTokens?.value ?? Number.NEGATIVE_INFINITY) : 0;
+    })[0];
+}
+
+function enabledModels(entry: ProviderCatalogEntry): ProviderModelCatalogEntry[] {
+  return entry.models.filter((m) => !m.disabled && !m.unavailable);
+}
+
+function contextEligibleModels(entry: ProviderCatalogEntry, minContextTokens: number | undefined): ProviderModelCatalogEntry[] {
+  const models = enabledModels(entry);
+  if (!minContextTokens) return models;
+  return models.filter((model) => (model.limits?.contextWindowTokens?.value ?? 0) >= minContextTokens);
+}
+
+function modelTier(alias: string): number {
+  const lower = alias.toLowerCase();
+  if (lower.includes("haiku") || lower.includes("mini") || lower.includes("5.4")) return 0;
+  if (lower.includes("opus") || lower.includes("pro") || lower.includes("[1m]")) return 2;
+  return 1;
+}
+
+// ---------------------------------------------------------------------------
+// Quota-band aware rerouting
+// ---------------------------------------------------------------------------
+
+function rerouteForBand(
+  target: DispatchTarget,
+  work: TaskDispatch,
+  policy: DispatchPolicy,
+  bands: ProviderQuotaBand[],
+  catalog: ProviderCatalogEntry[],
+  factors: DispatchFactors,
+  warnings: string[],
+  opts: { effortPinned: boolean; mustResolveAvailable?: boolean; advertised: Set<SpawnProvider>; avoid?: ReadonlySet<SpawnProvider>; preferences?: RoutingPreferenceEvaluation; eligibility: (provider: SpawnProvider) => string | undefined },
+): void {
+  const band = bandFor(target.provider, bands);
+  const blocked = isBlocked(target.provider, bands);
+  const isLarge = work.contextFootprint === "large";
+  // #2656 — a disabled provider must always be left, regardless of its (stale) band.
+  const disabled = !isProviderEnabled(catalogEntry(catalog, target.provider));
+  // Reroute when the pool is at capacity / hard-avoid, or a large job lands on an avoid-large pool.
+  const controlled = !!opts.preferences?.matched.length;
+  if (controlled && !opts.eligibility(target.provider)) return;
+  const mustMove = (controlled && !!opts.eligibility(target.provider)) || disabled || blocked || band === "hard-avoid" || (isLarge && band === "avoid-large");
+  if (!mustMove) return;
+
+  const alt = healthiestAlternative(new Set([target.provider, ...(opts.avoid ?? [])]), bands, catalog, opts.mustResolveAvailable, opts.advertised, opts.preferences, opts.eligibility);
+  if (!alt) {
+    warnings.push(`${target.provider} band=${band}${blocked ? " (at capacity)" : ""} and no healthier provider is available — keeping it; expect contention.`);
+    return;
+  }
+  if (!disabled && opts.mustResolveAvailable !== true && bandRank(alt.band) >= bandRank(band)) {
+    warnings.push(`${target.provider} band=${band}${blocked ? " (at capacity)" : ""} and no healthier provider is available — keeping it; expect contention.`);
+    return;
+  }
+  if (alt.degraded) {
+    warnings.push(
+      `[CRITICAL] mustResolveAvailable: all prefer/normal providers unavailable; degraded to ${alt.provider} (${alt.degradedReason ?? "degraded tier"}). Contention likely.`,
+    );
+  }
+  const altEntry = catalogEntry(catalog, alt.provider)!;
+  factors.reroutedFromProvider = target.provider;
+  factors.ranking = markRankingSelected(alt.ranking, alt.target, factors.ranking);
+  factors.rankingReason = alt.reason;
+  warnings.push(`Rerouted ${target.provider} (${disabled ? "disabled" : `band=${band}${blocked ? ", at capacity" : ""}`}) → ${alt.provider} (band=${alt.band}) to ${disabled ? "leave the disabled provider" : alt.band === "prefer" ? "use abundant quota" : "avoid the scarce pool"}.`);
+  const prevEffort = target.effort;
+  target.provider = alt.provider;
+  // Provider changed → model is provider-specific; reset to the new provider's default, then
+  // RE-VALIDATE the footprint on the new provider (it may widen to a 1M model, or warn if it
+  // cannot meet the footprint) so a large job is never silently downgraded onto a small window.
+  target.model = altEntry.defaultModel;
+  // Re-derive escalation against the NEW provider — the prior provider's escalation flag is stale.
+  delete factors.escalatedForFootprint;
+  escalateForFootprint(target, work, policy, catalog, factors, warnings);
+  // Effort: a pinned effort is authoritative and survives the reroute (warn if the rerouted model
+  // doesn't list it, rather than silently dropping it). An unpinned effort is kept only if supported.
+  if (opts.effortPinned) {
+    target.effort = prevEffort;
+    if (prevEffort && effortIfSupported(altEntry, target.model, prevEffort) === undefined) {
+      warnings.push(`Pinned effort '${prevEffort}' isn't listed for ${alt.provider}/${target.model ?? "default"}; honoring the pin anyway.`);
+    }
+  } else {
+    target.effort = effortIfSupported(altEntry, target.model, prevEffort);
+  }
+}
+
+// Best advertised, automatically routable provider outside `avoid` — not only those with
+// a quota advisory. A provider with no quota record defaults to the
+// "normal" band (via bandFor), so a healthy catalog provider is never skipped just because it has
+// no burn data yet. Prefer "prefer" band, then "normal"; never a blocked one.
+//
+// When mustResolveAvailable is set (#901 degrade-never-refuse), widens search in tiers when
+// no prefer/normal provider is available: caution → avoid-large → hard-avoid-but-not-blocked
+// → least-utilized blockedNow.
+// A `degraded` flag + `degradedReason` signals to the caller to emit a louder warning.
+//
+// A static catalog registration is not availability or permission to route onto paid API.
+function healthiestAlternative(
+  avoid: ReadonlySet<SpawnProvider>,
+  bands: ProviderQuotaBand[],
+  catalog: ProviderCatalogEntry[],
+  mustResolveAvailable: boolean | undefined,
+  advertised: Set<SpawnProvider>,
+  preferences: RoutingPreferenceEvaluation | undefined,
+  eligibility: (provider: SpawnProvider) => string | undefined,
+): { target: DispatchTarget; provider: SpawnProvider; band: QuotaBand; degraded?: boolean; degradedReason?: string; ranking: DispatchRankingEntry[]; reason: string } | undefined {
+  const entries = catalog.filter((c) => !avoid.has(c.provider) && advertised.has(c.provider) && automaticallyRoutable(c.provider));
+  const candidates = entries.map((entry, priority) => ({
+    target: { provider: entry.provider, ...(entry.defaultModel ? { model: entry.defaultModel } : {}) },
+    label: `${entry.provider} catalog alternative`,
+    priority,
+  }));
+  const ranked = rankCandidates(candidates, bands, { allowBlockedLastResort: !preferences?.matched.length && mustResolveAvailable === true, preferences, eligibility });
+  const winner = ranked.winner;
+  if (!winner) return undefined;
+  const band = bandFor(winner.target.provider, bands);
+  const blocked = isBlocked(winner.target.provider, bands);
+  const degraded = mustResolveAvailable === true && (bandRank(band) > bandRank("normal") || blocked);
+  return {
+    target: winner.target,
+    provider: winner.target.provider,
+    band,
+    ranking: ranked.ranking,
+    reason: ranked.reason,
+    ...(degraded ? { degraded: true, degradedReason: blocked ? "blockedNow provider (tier 4 last-resort — ALL providers at capacity)" : `${band} band degraded tier` } : {}),
+  };
+}
+
+/** #3105 — providers that run the same models: every claude-relay manifest (subscriptions and the API) is Claude. */
+export function sameModelProviders(provider: SpawnProvider): SpawnProvider[] {
+  const claude = getManifest(provider)?.shim?.kind === "claude-relay";
+  return claude ? getAllManifests().filter((m) => m.shim?.kind === "claude-relay").map((m) => m.id as SpawnProvider) : [provider];
+}
+
+/** #3105 — the soft avoid: advertised policy candidates outside `avoid` with a viable rank win, then the healthiest
+ *  advertised provider outside it; with neither it stays inside `avoid`, still on an advertised provider, so the spawn never waits. */
+function preferOtherProvider(candidates: DispatchCandidate[], avoid: ReadonlySet<SpawnProvider>, advertised: Set<SpawnProvider>, bands: ProviderQuotaBand[], catalog: ProviderCatalogEntry[], preferences: RoutingPreferenceEvaluation, eligibility: (provider: SpawnProvider) => string | undefined): { candidates: DispatchCandidate[]; other: boolean } {
+  const live = candidates.filter((candidate) => advertised.has(candidate.target.provider));
+  const others = live.filter((candidate) => !avoid.has(candidate.target.provider));
+  if (rankCandidates(others, bands, { preferences, eligibility }).winner) return { candidates: others, other: true };
+  const alt = healthiestAlternative(avoid, bands, catalog, false, advertised, preferences, eligibility);
+  if (alt) return { candidates: [{ target: alt.target, label: `${alt.provider} (other than ${[...avoid].join("/")})`, priority: 0 }], other: true };
+  if (live.length) return { candidates: live, other: false };
+  const only = healthiestAlternative(new Set(), bands, catalog, false, advertised, preferences, eligibility);
+  return { candidates: only ? [{ target: only.target, label: `${only.provider} (advertised)`, priority: 0 }] : candidates, other: false };
+}
+
+function collectBandWarnings(provider: SpawnProvider, work: TaskDispatch, bands: ProviderQuotaBand[], providerPinned: boolean, warnings: string[]): void {
+  if (!providerPinned) return; // non-pinned scarce pools were already handled by reroute
+  const band = bandFor(provider, bands);
+  if (band === "hard-avoid" || isBlocked(provider, bands)) {
+    warnings.push(`Pinned provider ${provider} is band=${band}${isBlocked(provider, bands) ? " (at capacity)" : ""}; honoring the pin but it may be slow or blocked.`);
+  } else if (band === "avoid-large" && work.contextFootprint === "large") {
+    warnings.push(`Pinned provider ${provider} is band=avoid-large for a large job; honoring the pin.`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auto-review planning
+// ---------------------------------------------------------------------------
+
+function planAutoReview(
+  work: TaskDispatch,
+  policy: DispatchPolicy,
+  bands: ProviderQuotaBand[],
+  catalog: ProviderCatalogEntry[],
+  ctx: DispatchContext,
+): ReviewPlan | undefined {
+  const cfg = policy.autoReview;
+  if (!cfg) return undefined;
+  const reason = autoReviewReason(work, cfg);
+  if (!reason) return undefined;
+  // The review Task's own work-shape: a review, inheriting the parent's criticality. Its target
+  // is resolved through the SAME policy (so review routing stays single-source) — either the
+  // explicit autoReview.target or whatever the review-type rules pick. No pin, no recursion into
+  // auto-review (a review of a review isn't wanted).
+  const reviewShape: TaskDispatch = {
+    type: "review",
+    ...(work.criticality ? { criticality: work.criticality } : {}),
+    ...(work.complexity ? { complexity: work.complexity } : {}),
+  };
+  const reviewPolicy: DispatchPolicy = cfg.target
+    ? { ...policy, rules: [{ label: "auto-review target", match: { type: "review" }, target: cfg.target }, ...policy.rules], autoReview: undefined }
+    : { ...policy, autoReview: undefined };
+  const decision = dispatchTask(reviewShape, {}, { targetAvailable: ctx.targetAvailable, advertisedProviders: ctx.advertisedProviders, mustResolveAvailable: ctx.mustResolveAvailable, policy: reviewPolicy, bands, catalog });
+  return {
+    dispatch: reviewShape,
+    target: decision.target,
+    rationale: decision.rationale,
+    reason,
+  };
+}
+
+function autoReviewReason(work: TaskDispatch, cfg: DispatchAutoReview): string | undefined {
+  if (work.criticality && cfg.whenCriticality?.includes(work.criticality)) return `criticality=${work.criticality}`;
+  if (work.complexity && cfg.whenComplexity?.includes(work.complexity)) return `complexity=${work.complexity}`;
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Rationale rendering
+// ---------------------------------------------------------------------------
+
+export function buildRationale(target: DispatchTarget, factors: DispatchFactors): string {
+  const head = `${target.model ?? `${target.provider} default`}${target.effort ? ` ${target.effort}` : ""}`;
+  const shape = [
+    factors.type ? `type=${factors.type}` : undefined,
+    factors.complexity ? `complexity=${factors.complexity}` : undefined,
+    factors.contextFootprint ? `contextFootprint=${factors.contextFootprint}` : undefined,
+    factors.criticality ? `criticality=${factors.criticality}` : undefined,
+  ].filter(Boolean).join(", ");
+  const parts = [`${head}:`];
+  if (shape) parts.push(shape + ";");
+  parts.push(`matched ${factors.matchedRule};`);
+  parts.push(`${capitalize(target.provider)} band=${factors.band}`);
+  if (factors.escalatedForFootprint) parts.push(`(escalated to ${target.model} for footprint)`);
+  if (factors.reroutedFromProvider) parts.push(`(rerouted from ${factors.reroutedFromProvider})`);
+  if (factors.apiOverflow?.selected) parts.push(`(api overflow from ${factors.apiOverflow.fromProvider}: ${factors.apiOverflow.reason})`);
+  if (factors.apiExpiry) parts.push(`(api expiry${factors.apiExpiry.selected ? ` from ${factors.apiExpiry.fromProvider}` : " declined"}: ${factors.apiExpiry.reason}${factors.apiExpiry.skippedRerouteProvider ? `; cross-family reroute to ${factors.apiExpiry.skippedRerouteProvider} skipped` : ""})`);
+  if (factors.subscriptionExpiry) parts.push(`(subscription expiry: ${factors.subscriptionExpiry})`);
+  if (factors.rankingReason) parts.push(`(${factors.rankingReason})`);
+  const preferences = preferenceRationale(factors.preferences, target.provider);
+  if (preferences) parts.push(`(${preferences})`);
+  if (factors.pinSources) parts.push(`(sources: ${Object.entries(factors.pinSources).map(([field, source]) => `${field}=${source}`).join(", ")})`);
+  if (factors.constraintOverrides?.length) parts.push(`(requirements overridden: ${factors.constraintOverrides.map((override) => `${override.ruleId} by ${override.source}`).join(", ")})`);
+  if (factors.pinnedFields?.length) parts.push(`(pinned: ${factors.pinnedFields.join(", ")})`);
+  return parts.join(" ");
+}
+
+function capitalize(value: string): string {
+  return value ? value[0]!.toUpperCase() + value.slice(1) : value;
+}
+
+// ---------------------------------------------------------------------------
+// Catalog / band helpers
+// ---------------------------------------------------------------------------
+
+function catalogEntry(catalog: ProviderCatalogEntry[], provider: SpawnProvider): ProviderCatalogEntry | undefined {
+  return catalog.find((c) => c.provider === provider);
+}
+
+function contextWindowOf(catalog: ProviderCatalogEntry[], provider: SpawnProvider, model: string | undefined): number | undefined {
+  const entry = catalogEntry(catalog, provider);
+  if (!entry) return undefined;
+  const alias = model ?? entry.defaultModel;
+  return alias ? contextWindowFromEntry(entry, alias) : undefined;
+}
+
+function contextWindowFromEntry(entry: ProviderCatalogEntry, alias: string): number | undefined {
+  const model = entry.models.find((m) => m.alias === alias) ?? entry.models.find((m) => m.providerModel === alias);
+  return model?.limits?.contextWindowTokens?.value;
+}
+
+function effortIfSupported(entry: ProviderCatalogEntry, alias: string | undefined, effort: string | undefined): string | undefined {
+  if (!effort || !alias) return undefined;
+  const model = entry.models.find((m) => m.alias === alias);
+  return model && model.efforts.includes(effort) ? effort : undefined;
+}
+
+function bandFor(provider: SpawnProvider, bands: ProviderQuotaBand[]): QuotaBand {
+  return bands.find((b) => b.provider === provider)?.band ?? "normal";
+}
+
+function isBlocked(provider: SpawnProvider, bands: ProviderQuotaBand[]): boolean {
+  return bands.find((b) => b.provider === provider)?.blockedNow ?? false;
+}