agent-relay-server 0.97.0 → 0.98.0

package/src/routes/index.ts

@@ -8,6 +8,7 @@ import { deleteAutomationById, getAutomationById, getAutomationRuns, getAutomati
 import { deleteCommandById, deleteProviderModelRoute, getProviderConfigRoute, getProviderConfigsRoute, getProvidersRoute, patchProviderModelRoute, postProviderConfigTestRoute, putProviderConfigRoute, putProviderModelRoute } from "./provider-config";
 import { getProviderQuotasRoute, postProviderQuotaLeaseAcquireRoute, postProviderQuotaLeaseReleaseRoute, postProviderQuotaPublisherLeaseAcquireRoute, postProviderQuotaPublisherLeaseReleaseRoute, postProviderQuotaRoute } from "./provider-quotas";
 import { getProviderQuotaConfigRoute, getProviderQuotaConfigsRoute, putProviderQuotaConfigRoute } from "./provider-quota-config";
+import { getRoutingPolicyRoute, putRoutingPolicyRoute } from "./routing-policy";
 import { deleteProvisioningCapabilityRoute, getProvisioningCapabilitiesRoute, getProvisioningCapabilityRoute, patchProvisioningCapabilityRoute, patchProvisioningVariantRoute, postProvisioningCapabilityRoute, postProvisioningVariantImportRoute, postProvisioningVariantMcpRoute, postProvisioningVariantUpdateRoute, postProvisioningVariantValidateRoute } from "./provisioning-registry";
 import { getTeamsConfigRoute, putTeamsConfigRoute } from "./teams-config";
 import { deleteConfigKey, getConfigKey, getConfigKeyHistory, getConfigNamespace, putConfigKey } from "./config";
@@ -281,6 +282,8 @@ const routes: Route[] = [
   route("GET", "/api/providers/quota-config", getProviderQuotaConfigsRoute),
   route("GET", "/api/providers/:provider/quota-config", getProviderQuotaConfigRoute),
   route("PUT", "/api/providers/:provider/quota-config", putProviderQuotaConfigRoute),
+  route("GET", "/api/routing-policy", getRoutingPolicyRoute),
+  route("PUT", "/api/routing-policy", putRoutingPolicyRoute),
   route("PUT", "/api/providers/:provider/models/:alias", putProviderModelRoute),
   route("PATCH", "/api/providers/:provider/models/:alias", patchProviderModelRoute),
   route("DELETE", "/api/providers/:provider/models/:alias", deleteProviderModelRoute),

package/src/routes/routing-policy.ts

@@ -0,0 +1,25 @@
+// Routing-policy routes (#728). GET/PUT for the relay-owned routing-policy document.
+// GET: agent:read (coordinators read the policy to apply rules).
+// PUT: settings:write:routing (admin writes).
+import { ValidationError } from "../db";
+import { error, json, parseBody, type Handler } from "./_shared";
+import { getRoutingPolicy, setRoutingPolicy } from "../routing-policy-store";
+import { isRecord } from "agent-relay-sdk";
+import { cleanString } from "../validation";
+
+export const getRoutingPolicyRoute: Handler = () => {
+  return json(getRoutingPolicy());
+};
+
+export const putRoutingPolicyRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const updatedBy = isRecord(parsed.body) ? cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 }) : undefined;
+    const policy = setRoutingPolicy(parsed.body, { updatedBy });
+    return json(policy);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};

package/src/routing-policy-push.ts

@@ -0,0 +1,82 @@
+// Live delta push for routing-policy saves (#732). When the policy is updated via
+// PUT /api/routing-policy, all live spawn-capable agents (coordinators) receive an
+// in-band routing.policy.changed notification so the change takes effect mid-session
+// without respawn.
+//
+// Delivery mechanism: same emitRelayEvent + routeNotification path as agent.ready /
+// agent.exited (#308/#239). emitRelayEvent writes to the durable bus outbox (so bus
+// clients subscribed to routing.* receive it immediately); routeNotification sends a
+// message.new push to each spawn-capable agent's inbox so connected coordinators
+// that are subscribed only to message.* are also woken with the delta in-band.
+//
+// Spawn-capable = live token carries command:spawn (or command:* / admin:* / *).
+// The same token-scope check used by quota-advisory.ts (isSpawnCapableAgent).
+import { getDb } from "./db";
+import { emitRelayEvent } from "./events";
+import { routeNotification } from "./notification-router";
+import { parseJson } from "./utils";
+import { isRecord } from "agent-relay-sdk";
+import type { RoutingPolicy } from "agent-relay-sdk";
+
+const PUSH_TTL_MS = 15 * 60 * 1000;
+
+/**
+ * Emit a durable `routing.policy.changed` event and push the delta to every
+ * live spawn-capable agent so coordinators ingest the new policy mid-session.
+ * Called by setRoutingPolicy on every successful save.
+ */
+export function notifyRoutingPolicyChanged(policy: RoutingPolicy, opts: { updatedBy?: string } = {}): void {
+  emitRelayEvent({
+    type: "routing.policy.changed",
+    source: "server",
+    subject: "routing-policy:default",
+    data: { policy: policy as unknown as Record<string, unknown>, updatedBy: opts.updatedBy ?? null },
+  });
+
+  const recipients = getSpawnCapableAgentIds();
+  if (recipients.length === 0) return;
+
+  routeNotification({
+    type: "routing.policy.changed",
+    scope: {},
+    recipients,
+    ttlMs: PUSH_TTL_MS,
+    message: {
+      subject: "Routing policy updated",
+      body: `🗺 Routing policy updated${opts.updatedBy ? ` by ${opts.updatedBy}` : ""}. Ingest this delta now — spawn routing decisions take effect immediately without respawn. Re-read relay_spawn_targets for live provider/model options.`,
+      payload: { kind: "routing.policy.changed", policy: policy as unknown as Record<string, unknown>, updatedBy: opts.updatedBy ?? null },
+      replyExpected: false,
+    },
+  });
+}
+
+type AgentRow = { id: string; meta: string | null };
+
+function getSpawnCapableAgentIds(): string[] {
+  const now = Date.now();
+  const candidates = getDb().query(`
+    SELECT id, meta FROM agents
+    WHERE ready = 1 AND status NOT IN ('offline', 'stale')
+  `).all() as AgentRow[];
+  return candidates.filter((agent) => isSpawnCapable(agent, now)).map((a) => a.id);
+}
+
+function isSpawnCapable(agent: AgentRow, now: number): boolean {
+  const meta = parseJson<Record<string, unknown>>(agent.meta ?? "{}", {});
+  const auth = isRecord(meta.auth) ? meta.auth : undefined;
+  const jti = typeof auth?.jti === "string" ? auth.jti : undefined;
+  if (!jti) return false;
+  const row = getDb().query(
+    "SELECT scope, revoked_at, expires_at FROM tokens WHERE jti = ?",
+  ).get(jti) as { scope: string; revoked_at?: number | null; expires_at?: number | null } | undefined;
+  if (!row || row.revoked_at) return false;
+  const nowSeconds = Math.floor(now / 1000);
+  if (row.expires_at !== null && row.expires_at !== undefined && row.expires_at <= nowSeconds) return false;
+  const scopes = parseJson<string[]>(row.scope, []);
+  return (
+    scopes.includes("command:spawn") ||
+    scopes.includes("command:*") ||
+    scopes.includes("admin:*") ||
+    scopes.includes("*")
+  );
+}

package/src/routing-policy-store.ts

@@ -0,0 +1,148 @@
+// Routing-policy storage (#728). One relay-owned policy document per instance,
+// backed by the existing `config` table (namespace "routing-policy", key "default")
+// so history + config.changed SSE come for free at no schema cost.
+//
+// The policy covers routing rules (task-type/capability → provider/model/effort)
+// and quota tuning (band thresholds + per-provider hardBackstopUtilization /
+// burnPenaltyUtilizationFloor). #730 will wire quota fields into spawn-targets.ts;
+// this module only stores and retrieves them.
+import { ValidationError } from "./db";
+import { getConfig, setConfig } from "./config-store";
+import { notifyRoutingPolicyChanged } from "./routing-policy-push";
+import { isRecord, SPAWN_PROVIDERS } from "agent-relay-sdk";
+import type { ProviderQuotaRoutingConfig, QuotaBandThresholds, RoutingPolicy, RoutingRule } from "agent-relay-sdk";
+
+export const ROUTING_POLICY_NAMESPACE = "routing-policy";
+export const ROUTING_POLICY_KEY = "default";
+
+/** Default policy — preserves current spawn-targets.ts behaviour when unset. */
+export const DEFAULT_ROUTING_POLICY: RoutingPolicy = {
+  schemaVersion: 1,
+  rules: [],
+};
+
+/** Retrieve the stored routing policy, falling back to the default when absent. */
+export function getRoutingPolicy(): RoutingPolicy {
+  const entry = getConfig<RoutingPolicy>(ROUTING_POLICY_NAMESPACE, ROUTING_POLICY_KEY);
+  return entry ? normalizeRoutingPolicy(entry.value) : { ...DEFAULT_ROUTING_POLICY };
+}
+
+/**
+ * Persist the routing policy. The incoming value is normalized so partial bodies
+ * still produce a valid document. Emits `config.changed` via `setConfig` so the
+ * dashboard + any live listeners pick it up immediately.
+ */
+export function setRoutingPolicy(value: unknown, opts: { updatedBy?: string } = {}): RoutingPolicy {
+  const normalized = normalizeRoutingPolicy(value);
+  setConfig(ROUTING_POLICY_NAMESPACE, ROUTING_POLICY_KEY, normalized, opts.updatedBy);
+  notifyRoutingPolicyChanged(normalized, opts);
+  return normalized;
+}
+
+// ---------------------------------------------------------------------------
+// Normalizer — coerces arbitrary input into a valid RoutingPolicy, defaulting
+// missing fields so a partial PUT is safe and a missing policy is a no-op.
+// ---------------------------------------------------------------------------
+
+export function normalizeRoutingPolicy(value: unknown): RoutingPolicy {
+  const input = isRecord(value) ? value : {};
+  return {
+    schemaVersion: 1,
+    rules: normalizeRules(input.rules),
+    ...(input.quotaBands !== undefined ? { quotaBands: normalizeQuotaBands(input.quotaBands) } : {}),
+    ...(input.providerQuota !== undefined ? { providerQuota: normalizeProviderQuota(input.providerQuota) } : {}),
+  };
+}
+
+function normalizeRules(raw: unknown): RoutingRule[] {
+  if (!Array.isArray(raw)) return [];
+  const rules: RoutingRule[] = [];
+  for (let i = 0; i < raw.length; i++) {
+    rules.push(normalizeRule(raw[i], i));
+  }
+  return rules;
+}
+
+function normalizeRule(raw: unknown, idx: number): RoutingRule {
+  if (!isRecord(raw)) throw new ValidationError(`rules[${idx}] must be an object`);
+  const match = isRecord(raw.match) ? raw.match : {};
+  if (!isRecord(raw.match)) throw new ValidationError(`rules[${idx}].match must be an object`);
+  if (match.taskType === undefined && match.capability === undefined) {
+    throw new ValidationError(`rules[${idx}].match must set at least one of: taskType, capability`);
+  }
+  const target = isRecord(raw.target) ? raw.target : {};
+  if (!isRecord(raw.target)) throw new ValidationError(`rules[${idx}].target must be an object`);
+  if (typeof target.provider !== "string" || !(SPAWN_PROVIDERS as readonly string[]).includes(target.provider)) {
+    throw new ValidationError(`rules[${idx}].target.provider must be one of: ${SPAWN_PROVIDERS.join(", ")}`);
+  }
+  const rule: RoutingRule = {
+    match: {
+      ...(typeof match.taskType === "string" && match.taskType ? { taskType: match.taskType } : {}),
+      ...(typeof match.capability === "string" && match.capability ? { capability: match.capability } : {}),
+    },
+    target: {
+      provider: target.provider as RoutingRule["target"]["provider"],
+      ...(typeof target.model === "string" && target.model ? { model: target.model } : {}),
+      ...(typeof target.effort === "string" && target.effort ? { effort: target.effort } : {}),
+    },
+  };
+  if (typeof raw.label === "string" && raw.label) rule.label = raw.label;
+  if (typeof raw.enabled === "boolean") rule.enabled = raw.enabled;
+  return rule;
+}
+
+function normalizeQuotaBands(raw: unknown): Partial<QuotaBandThresholds> {
+  if (!isRecord(raw)) throw new ValidationError("quotaBands must be an object");
+  const result: Partial<QuotaBandThresholds> = {};
+  if (raw.cautionAt !== undefined) result.cautionAt = cleanQuotaFraction(raw.cautionAt, "quotaBands.cautionAt");
+  if (raw.avoidLargeAt !== undefined) result.avoidLargeAt = cleanQuotaFraction(raw.avoidLargeAt, "quotaBands.avoidLargeAt");
+  if (raw.hardAvoidAt !== undefined) result.hardAvoidAt = cleanQuotaFraction(raw.hardAvoidAt, "quotaBands.hardAvoidAt");
+  const orderedPairs: Array<[string, number]> = [];
+  if (result.cautionAt !== undefined) orderedPairs.push(["cautionAt", result.cautionAt]);
+  if (result.avoidLargeAt !== undefined) orderedPairs.push(["avoidLargeAt", result.avoidLargeAt]);
+  if (result.hardAvoidAt !== undefined) orderedPairs.push(["hardAvoidAt", result.hardAvoidAt]);
+  for (let i = 0; i < orderedPairs.length - 1; i++) {
+    const cur = orderedPairs[i]!;
+    const next = orderedPairs[i + 1]!;
+    if (cur[1] >= next[1]) {
+      throw new ValidationError(`quotaBands.${cur[0]} must be less than quotaBands.${next[0]}`);
+    }
+  }
+  return result;
+}
+
+function normalizeProviderQuota(raw: unknown): Partial<Record<string, ProviderQuotaRoutingConfig>> {
+  if (!isRecord(raw)) throw new ValidationError("providerQuota must be an object");
+  const result: Partial<Record<string, ProviderQuotaRoutingConfig>> = {};
+  for (const provider of SPAWN_PROVIDERS) {
+    if (!(provider in raw)) continue;
+    result[provider] = normalizeProviderQuotaConfig(raw[provider], provider);
+  }
+  return result;
+}
+
+function normalizeProviderQuotaConfig(raw: unknown, provider: string): ProviderQuotaRoutingConfig {
+  if (!isRecord(raw)) throw new ValidationError(`providerQuota.${provider} must be an object`);
+  const cfg: ProviderQuotaRoutingConfig = {};
+  if (raw.hardBackstopUtilization !== undefined) {
+    cfg.hardBackstopUtilization = cleanFraction(raw.hardBackstopUtilization, `providerQuota.${provider}.hardBackstopUtilization`);
+  }
+  if (raw.burnPenaltyUtilizationFloor !== undefined) {
+    cfg.burnPenaltyUtilizationFloor = cleanFraction(raw.burnPenaltyUtilizationFloor, `providerQuota.${provider}.burnPenaltyUtilizationFloor`);
+  }
+  return cfg;
+}
+
+function cleanQuotaFraction(value: unknown, field: string): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new ValidationError(`${field} must be a non-negative finite number`);
+  }
+  return value;
+}
+
+function cleanFraction(value: unknown, field: string): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+    throw new ValidationError(`${field} must be a number between 0 and 1`);
+  }
+  return value;
+}

package/src/routing-rule-resolver.ts

@@ -0,0 +1,87 @@
+// Declarative routing-rules engine (#729).
+//
+// Resolves the first matching enabled rule from RoutingPolicy.rules, given a task-type
+// and/or capability. Rules are ADVISORY — they surface a recommended target to the
+// coordinator; they never override an explicit per-spawn argument or block a spawn.
+//
+// Precedence (highest → lowest):
+//  1. Explicit per-spawn args (provider/model/effort in relay_spawn_agent / SpawnAgentInput).
+//  2. This resolver — the recommendation when no explicit arg is given.
+//  3. Profile default — fallback when no rule matches.
+//
+// The quota band / gate is a parallel SAFETY layer that composes on top of the resolved
+// target (it may advise a cheaper effort or healthier provider; a hard block still blocks).
+// It is NOT part of rule resolution and is NOT consulted here.
+import type { RoutingRule } from "agent-relay-sdk";
+
+/** Input criteria for rule matching. At least one field should be set. */
+export interface RoutingMatchInput {
+  /** Task-type to match against rule.match.taskType (prefix semantics). */
+  taskType?: string;
+  /** Capability tag to match against rule.match.capability (exact match). */
+  capability?: string;
+}
+
+/**
+ * The resolved target recommendation from a matching rule.
+ * Mirrors RoutingRule["target"] so callers never import the full rule.
+ */
+export interface RoutingResolution {
+  /** Recommended provider. */
+  provider: RoutingRule["target"]["provider"];
+  /** Recommended model alias, if the rule specifies one. */
+  model?: string;
+  /** Recommended effort level, if the rule specifies one. */
+  effort?: string;
+  /** Human-readable label from the matched rule, for logging/display. */
+  matchedRuleLabel?: string;
+}
+
+/**
+ * Evaluate the rules array in order and return the first matching enabled rule's target.
+ *
+ * Match semantics:
+ * - `taskType`: the rule's taskType is a prefix of the input (e.g. rule "gui" matches
+ *   input "gui" and "gui/ux", but not "gui2" or "xgui"). Case-sensitive.
+ * - `capability`: exact match. Case-sensitive.
+ * - When a rule sets both taskType AND capability, both must match (AND semantics).
+ * - A rule with `enabled: false` is skipped.
+ *
+ * Returns null when no rule matches or the rules array is empty.
+ */
+export function resolveRoutingRule(
+  rules: RoutingRule[],
+  input: RoutingMatchInput,
+): RoutingResolution | null {
+  for (const rule of rules) {
+    if (rule.enabled === false) continue;
+    if (!matchesCriteria(rule.match, input)) continue;
+    return {
+      provider: rule.target.provider,
+      ...(rule.target.model ? { model: rule.target.model } : {}),
+      ...(rule.target.effort ? { effort: rule.target.effort } : {}),
+      ...(rule.label ? { matchedRuleLabel: rule.label } : {}),
+    };
+  }
+  return null;
+}
+
+function matchesCriteria(criteria: RoutingRule["match"], input: RoutingMatchInput): boolean {
+  if (!criteria.taskType && !criteria.capability) return false;
+  if (criteria.taskType !== undefined) {
+    if (!input.taskType) return false;
+    if (!isPrefixMatch(input.taskType, criteria.taskType)) return false;
+  }
+  if (criteria.capability !== undefined) {
+    if (input.capability !== criteria.capability) return false;
+  }
+  return true;
+}
+
+/**
+ * True if `value` equals `prefix` or starts with `prefix + "/"`.
+ * Guards against substring-only matches (e.g. "gui" must not match "gui2").
+ */
+function isPrefixMatch(value: string, prefix: string): boolean {
+  return value === prefix || value.startsWith(prefix + "/");
+}

package/src/security.ts

@@ -199,6 +199,7 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname.startsWith("/api/pairs")) return method === "GET" ? "pairs:read" : "pairs:write";
   if (pathname === "/api/provider-quota-leases/acquire" || pathname === "/api/provider-quota-leases/release") return "quota:write";
   if (pathname === "/api/provider-quotas") return method === "GET" ? "agent:read" : "quota:write";
+  if (pathname === "/api/routing-policy") return method === "GET" ? "agent:read" : "settings:write:routing";
   if (pathname === "/api/teams/config") return method === "GET" ? "teams:read" : "settings:write:teams";
   if (pathname.startsWith("/api/teams")) return method === "GET" ? "teams:read" : "teams:write";
   if (pathname.startsWith("/api/blackboard")) return method === "GET" ? "blackboard:read" : "blackboard:write";
@@ -288,6 +289,11 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   if (pathname === "/api/providers/quota-config" || pathname.match(/^\/api\/providers\/[^/]+\/quota-config$/)) {
     return method === "GET" ? "agent:read" : "settings:write:provider";
   }
+  // Routing policy (#728): reads are agent:read (coordinators read to apply rules);
+  // writes are settings:write:routing (admin-scoped).
+  if (pathname === "/api/routing-policy") {
+    return method === "GET" ? "agent:read" : "settings:write:routing";
+  }
   if (pathname === "/api/teams/config") return method === "GET" ? "teams:read" : "settings:write:teams";
   if (pathname.startsWith("/api/messages") || pathname.startsWith("/api/inbox")) return method === "GET" ? "message:read" : "message:send";
   if (pathname.startsWith("/api/agent-profiles")) return method === "GET" ? "agent:read" : "agent:write";

package/src/spawn-targets.ts

@@ -1,8 +1,10 @@
 import { countLiveSpawnedAgents, getAgent, getOrchestrator, listOrchestrators, listProviderQuotas, ValidationError } from "./db";
 import { DEFAULT_SPAWN_PROFILE_NAME, listAgentProfiles } from "./config-store";
 import { effectiveProviderCatalogList } from "./provider-catalog-store";
+import { getRoutingPolicy } from "./routing-policy-store";
 import { isPathWithinBase } from "./utils";
 import { McpNotFoundError } from "./mcp-errors";
+import type { ProviderQuotaRoutingConfig } from "agent-relay-sdk";
 import type { Orchestrator, ProviderCatalogSummary, ProviderQuotaBurnRole, ProviderQuotaBurnWindow, ProviderQuotaRecord, QuotaState, SpawnProvider } from "./types";
 
 // #308 — spawn discovery + target selection. Home for the live capability matrix that
@@ -22,6 +24,8 @@ export function buildSpawnTargets(input: { callerId?: string; quota: number }):
   const self = preferHost ? orchestrators.find((o) => o.hostname === preferHost || o.id === preferHost) : undefined;
   const liveChildren = input.callerId ? countLiveSpawnedAgents(input.callerId) : 0;
   const quotaAdvisories = providerQuotaAdvisories();
+  const policy = getRoutingPolicy();
+  const enabledRules = policy.rules.filter((r) => r.enabled !== false);
 
   return {
     self: {
@@ -39,6 +43,14 @@ export function buildSpawnTargets(input: { callerId?: string; quota: number }):
         providers: providerMatrixFor(o, quotaAdvisories),
       })),
     profiles: spawnProfilesSummary(),
+    // #729 — declarative routing rules advisory. Rules are evaluated in array order;
+    // first matching enabled rule wins. Precedence: explicit per-spawn args > matching rule >
+    // profile default. Quota gate (blockedNow / quotaPenaltyBand above) is a parallel safety
+    // layer applied AFTER target resolution — it advises on the resolved target but does not
+    // pick it. Resolve programmatically with resolveRoutingRule() from routing-rule-resolver.ts.
+    routing: {
+      rules: enabledRules,
+    },
     guidance:
       `Default to your own host (isSelf:true); only set orchestratorId to spawn onto another host that runs a provider/model yours doesn't. Omitting profile applies ${DEFAULT_SPAWN_PROFILE_NAME}; omitting model/effort uses the provider default (marked below). Prefer a named profile over assembling raw knobs; set spawnRequestId for idempotency. After spawning you'll be pushed agent.ready / agent.exited / agent.spawn_failed — don't block-poll.`,
   };
@@ -132,19 +144,28 @@ function providerMatrixFor(o: Orchestrator, quotaAdvisories: Map<SpawnProvider,
 }
 
 function providerQuotaAdvisories(now = Date.now()): Map<SpawnProvider, SpawnQuotaAdvisory> {
+  const policy = getRoutingPolicy();
   const byProvider = new Map<SpawnProvider, ProviderQuotaRecord[]>();
   for (const record of listProviderQuotas({ historyLimit: 0, now }).quotas) {
     if (record.provider !== "claude" && record.provider !== "codex") continue;
     const provider = record.provider;
     byProvider.set(provider, [...(byProvider.get(provider) ?? []), record]);
   }
-  return new Map([...byProvider.entries()].map(([provider, records]) => [provider, quotaAdvisoryFor(records, now)]));
+  return new Map([...byProvider.entries()].map(([provider, records]) => [
+    provider,
+    quotaAdvisoryFor(records, now, policy.quotaBands, policy.providerQuota?.[provider]),
+  ]));
 }
 
-function quotaAdvisoryFor(records: ProviderQuotaRecord[], now: number): SpawnQuotaAdvisory {
+function quotaAdvisoryFor(
+  records: ProviderQuotaRecord[],
+  now: number,
+  quotaBands?: Partial<{ cautionAt: number; avoidLargeAt: number; hardAvoidAt: number }>,
+  providerCfg?: ProviderQuotaRoutingConfig,
+): SpawnQuotaAdvisory {
   const selected = new Map<ProviderQuotaBurnRole, SpawnQuotaBurnWindow>();
   for (const record of records) {
-    for (const window of quotaWindowsFor(record, now)) {
+    for (const window of quotaWindowsFor(record, now, providerCfg)) {
       const existing = selected.get(window.role);
       if (!existing || compareQuotaWindows(window, existing) > 0) selected.set(window.role, window);
     }
@@ -152,7 +173,7 @@ function quotaAdvisoryFor(records: ProviderQuotaRecord[], now: number): SpawnQuo
   const windows = [...selected.values()].sort((a, b) => roleSort(a.role) - roleSort(b.role));
   const quotaPenalty = Math.max(0, ...windows.map((window) => window.penalty));
   const blockedNow = windows.some((window) => window.blockedNow);
-  const quotaPenaltyBand = quotaPenaltyBandFor(quotaPenalty);
+  const quotaPenaltyBand = quotaPenaltyBandFor(quotaPenalty, quotaBands);
   return {
     quotaBurn: { windows },
     quotaPenalty,
@@ -162,10 +183,10 @@ function quotaAdvisoryFor(records: ProviderQuotaRecord[], now: number): SpawnQuo
   };
 }
 
-function quotaWindowsFor(record: ProviderQuotaRecord, now: number): SpawnQuotaBurnWindow[] {
+function quotaWindowsFor(record: ProviderQuotaRecord, now: number, providerCfg?: ProviderQuotaRoutingConfig): SpawnQuotaBurnWindow[] {
   const quotaByName = new Map((record.quota?.windows ?? []).map((window) => [window.name, window]));
   return (record.burn?.windows ?? [])
-    .map((burnWindow) => spawnQuotaWindow(record, burnWindow, quotaByName.get(burnWindow.name), now))
+    .map((burnWindow) => spawnQuotaWindow(record, burnWindow, quotaByName.get(burnWindow.name), now, providerCfg))
     .filter((window): window is SpawnQuotaBurnWindow => Boolean(window));
 }
 
@@ -174,6 +195,7 @@ function spawnQuotaWindow(
   burnWindow: ProviderQuotaBurnWindow,
   quotaWindow: QuotaState["windows"][number] | undefined,
   now: number,
+  providerCfg?: ProviderQuotaRoutingConfig,
 ): SpawnQuotaBurnWindow | undefined {
   if (!quotaWindow) return undefined;
   const timeToResetMs = typeof quotaWindow.resetsAt === "number" ? Math.max(0, quotaWindow.resetsAt - now) : null;
@@ -181,6 +203,10 @@ function spawnQuotaWindow(
     ? Math.max(0, burnWindow.earlyWallMs) / timeToResetMs
     : null;
   const weight = burnWindow.role === "7d" ? 3 : 1;
+  const hardBackstop = providerCfg?.hardBackstopUtilization ?? 0.99;
+  const utilizationFloor = providerCfg?.burnPenaltyUtilizationFloor ?? 0.5;
+  const rawPenalty = (earlyFraction ?? 0) * weight;
+  const penalty = quotaWindow.utilization < utilizationFloor ? 0 : rawPenalty;
   return {
     role: burnWindow.role,
     name: burnWindow.name,
@@ -195,8 +221,8 @@ function spawnQuotaWindow(
     earlyWallMs: burnWindow.earlyWallMs,
     earlyFraction,
     weight,
-    penalty: (earlyFraction ?? 0) * weight,
-    blockedNow: quotaWindow.utilization >= 0.99,
+    penalty,
+    blockedNow: quotaWindow.utilization >= hardBackstop,
   };
 }
 
@@ -206,10 +232,16 @@ function compareQuotaWindows(a: SpawnQuotaBurnWindow, b: SpawnQuotaBurnWindow):
   return a.utilization - b.utilization;
 }
 
-function quotaPenaltyBandFor(quotaPenalty: number): SpawnQuotaBurnBand {
-  if (quotaPenalty >= 1) return "hard-avoid";
-  if (quotaPenalty >= 0.5) return "avoid-large";
-  if (quotaPenalty >= 0.15) return "caution";
+function quotaPenaltyBandFor(
+  quotaPenalty: number,
+  quotaBands?: Partial<{ cautionAt: number; avoidLargeAt: number; hardAvoidAt: number }>,
+): SpawnQuotaBurnBand {
+  const hardAvoidAt = quotaBands?.hardAvoidAt ?? 1.0;
+  const avoidLargeAt = quotaBands?.avoidLargeAt ?? 0.5;
+  const cautionAt = quotaBands?.cautionAt ?? 0.15;
+  if (quotaPenalty >= hardAvoidAt) return "hard-avoid";
+  if (quotaPenalty >= avoidLargeAt) return "avoid-large";
+  if (quotaPenalty >= cautionAt) return "caution";
   return "normal";
 }