agent-relay-server 0.100.0 → 0.101.0

package/src/db/provider-quota-burn.ts

@@ -1,8 +1,20 @@
-import { quotaWindowMetrics } from "agent-relay-sdk/provider-quota";
+import { DEFAULT_QUOTA_TARGET_UTILIZATION, quotaPaceMetrics, quotaWindowMetrics } from "agent-relay-sdk/provider-quota";
 import type { ProviderQuotaBurn, ProviderQuotaBurnRole, ProviderQuotaBurnWindow, ProviderQuotaSnapshot, QuotaState } from "../types";
 
 const QUOTA_BURN_MIN_SAMPLE_SPAN_MS = 10 * 60_000;
 
+// #760 — nominal window length per role, used to scale the recency half-life.
+const WINDOW_NOMINAL_MS: Record<ProviderQuotaBurnRole, number> = {
+  "5h": 5 * 3_600_000,
+  "7d": 7 * 24 * 3_600_000,
+};
+
+// #760 — recency half-life as a fraction of the window length. 0.25 → ~75min for the 5h
+// window (within the issue's ~60–90min trailing-window guidance) and ~42h for the 7d window.
+// A burst at the START of the history span decays out as it ages, so an idle stretch pulls the
+// observed rate (and burnRatio) back toward 0 instead of freezing the endpoint slope.
+const RECENCY_HALFLIFE_FRACTION = 0.25;
+
 type QuotaWindow = QuotaState["windows"][number];
 
 // Provider-agnostic: window role is expressed by name only. Each adapter uses the
@@ -36,9 +48,38 @@ function lowConfidenceBurnWindow(role: ProviderQuotaBurnRole, window: QuotaWindo
     timeToWallMs: null,
     projectedWallAt: null,
     earlyWallMs: null,
+    observedRatePerMs: null,
+    projectedUtilAtReset: null,
+    slack: null,
+    target: null,
   };
 }
 
+// #760 — recency-weighted consumption rate (utilization-fraction per ms). A weighted slope:
+// each consecutive interval contributes its actual Δutilization and Δt, decayed by the age of
+// its midpoint with the given half-life. A recent idle interval (large Δt, ~0 Δutil, high
+// weight) dominates the denominator and drives the rate toward 0; an old burst is down-weighted.
+function recencyWeightedRatePerMs(
+  samples: Array<{ capturedAt: number; utilization: number }>,
+  now: number,
+  halfLifeMs: number,
+): number {
+  let weightedDelta = 0;
+  let weightedDt = 0;
+  for (let i = 1; i < samples.length; i++) {
+    const prev = samples[i - 1]!;
+    const cur = samples[i]!;
+    const dt = cur.capturedAt - prev.capturedAt;
+    if (dt <= 0) continue;
+    const midAge = Math.max(0, now - (prev.capturedAt + cur.capturedAt) / 2);
+    const weight = Math.pow(0.5, midAge / halfLifeMs);
+    weightedDelta += weight * (cur.utilization - prev.utilization);
+    weightedDt += weight * dt;
+  }
+  if (weightedDt <= 0) return 0;
+  return Math.max(0, weightedDelta / weightedDt);
+}
+
 function deriveProviderQuotaBurnWindow(input: {
   provider: string;
   currentWindow: QuotaWindow;
@@ -82,13 +123,39 @@ function deriveProviderQuotaBurnWindow(input: {
   const remainingQuota = quotaWindowMetrics(input.currentWindow).remaining;
   const timeToResetMs = resetAt - input.now;
   if (remainingQuota <= 0 || timeToResetMs <= 0) return low;
-  const observedRatePerMs = Math.max(0, (utilizationNow - oldest.utilization) / (current.capturedAt - oldest.capturedAt));
-  const optimalRatePerMs = remainingQuota / timeToResetMs;
-  if (observedRatePerMs <= 0 || optimalRatePerMs <= 0) {
+
+  // #760 (Defect 1) — recency-weighted rate so an old burst decays and idle relaxes toward 0,
+  // instead of a frozen two-point endpoint slope over the whole span.
+  //
+  // Idle is invisible in the raw samples: identical utilization snapshots are deduped, so during
+  // an idle stretch no new rows arrive and the latest sample stays frozen at the last CHANGE
+  // (this is why codex sat at burn×6.3 — a stale burst slope). We make idle observable by
+  // appending a synthetic "utilization is still X as of now" point, which adds a recent
+  // zero-delta interval [lastSample, now] that the recency weighting lets dominate as it grows.
+  const halfLifeMs = WINDOW_NOMINAL_MS[role] * RECENCY_HALFLIFE_FRACTION;
+  const rateSamples = input.now > current.capturedAt
+    ? [...samples, { capturedAt: input.now, utilization: utilizationNow }]
+    : samples;
+  const observedRatePerMs = recencyWeightedRatePerMs(rateSamples, input.now, halfLifeMs);
+  // #760 (Defect 2) — pace against a configurable target (<100%); slack carries the underburn
+  // signal. The query layer (spawn-targets) may re-derive these against a per-provider target;
+  // the ingest-time values use the default so direct burn consumers (dashboard) have a number.
+  const pace = quotaPaceMetrics({
+    utilization: utilizationNow,
+    observedRatePerMs,
+    timeToResetMs,
+    target: DEFAULT_QUOTA_TARGET_UTILIZATION,
+  });
+  if (observedRatePerMs <= 0) {
+    // Idle (or decayed-to-idle): no projected wall, but slack still flags the headroom.
     return {
       ...low,
       confidence: "high",
       burnRatio: 0,
+      observedRatePerMs: 0,
+      projectedUtilAtReset: pace.projectedUtilAtReset,
+      slack: pace.slack,
+      target: pace.target,
     };
   }
   const timeToWallMs = remainingQuota / observedRatePerMs;
@@ -96,10 +163,15 @@ function deriveProviderQuotaBurnWindow(input: {
   return {
     ...low,
     confidence: "high",
-    burnRatio: observedRatePerMs / optimalRatePerMs,
+    burnRatio: pace.burnRatio,
+    observedRatePerMs,
     timeToWallMs,
     projectedWallAt,
-    earlyWallMs: Math.max(0, resetAt - projectedWallAt),
+    // #760 (Defect 2) — symmetric: negative means the wall lands AFTER reset (headroom left).
+    earlyWallMs: resetAt - projectedWallAt,
+    projectedUtilAtReset: pace.projectedUtilAtReset,
+    slack: pace.slack,
+    target: pace.target,
   };
 }
 

package/src/quota-band-transition.ts

@@ -7,6 +7,13 @@
 // prevents rapid flapping from bursty burn rates. Low-confidence windows
 // (burnRatio: null) are skipped entirely.
 //
+// #756 — asymmetric hysteresis deadband: recovery (improving) direction
+// requires the penalty to drop HYSTERESIS_MARGIN below the band entry
+// threshold before the transition is recognised, so a penalty parked on a
+// boundary can't ping-pong. Recovery notifications are also rate-limited to
+// at most one per RECOVERY_MIN_INTERVAL_MS — degradation is the actionable
+// signal; fleet-wake on recovery churn is suppressed.
+//
 // Called from handleProviderQuotaAdvisory in quota-advisory.ts so the check
 // runs on the same event hook as the utilization-threshold advisory — no
 // parallel delivery channel.
@@ -14,15 +21,27 @@ import { emitRelayEvent } from "./events";
 import { routeNotification } from "./notification-router";
 import { getSpawnCapableAgentIds } from "./routing-policy-push";
 import { getProviderBandInfo } from "./spawn-targets";
-import type { ProviderBandWindow, QuotaBand } from "./spawn-targets";
+import type { ProviderBandInfo, ProviderBandWindow, QuotaBand } from "./spawn-targets";
 import type { ProviderQuotaAdvisoryInput } from "./db/provider-quotas";
 
 const DEBOUNCE_SAMPLES = 3;
+// Penalty must drop this far below the band entry threshold before recovery is recognised.
+// #760: widened 0.05 → 0.10. Live evidence (Claude 7d parked at avoidLargeAt with burn×1.4)
+// showed the 0.05 deadband was too tight for real penalty jitter — it still ping-ponged
+// avoid-large → caution → avoid-large. Degradation stays faster-to-fire than recovery
+// (recovery alone carries the rate-limit), so the actionable direction is unaffected.
+const HYSTERESIS_MARGIN = 0.1;
+// #760 — slack must fall this far below preferSlackAt before "prefer" is released, so a provider
+// parked near the prefer boundary doesn't ping-pong normal↔prefer.
+const PREFER_HYSTERESIS_MARGIN = 0.05;
+// Minimum ms between recovery notifications — degradation fires immediately; recovery is rate-limited.
+const RECOVERY_MIN_INTERVAL_MS = 5 * 60_000;
 
 interface TransitionState {
   lastNotifiedBand: QuotaBand;
   pendingBand: QuotaBand | null;
   pendingCount: number;
+  lastTransitionAt: number;
 }
 
 const bandState = new Map<string, TransitionState>();
@@ -31,36 +50,63 @@ export function _resetBandTransitionStateForTesting(): void {
   bandState.clear();
 }
 
+// Test hook: supply a controlled band-info function to exercise hysteresis logic
+// without a full DB setup. Set to null to restore the real implementation.
+let _bandInfoSupplier: ((provider: string, now: number) => ProviderBandInfo | undefined) | null = null;
+export function _setBandInfoSupplierForTesting(fn: (provider: string, now: number) => ProviderBandInfo | undefined): void {
+  _bandInfoSupplier = fn;
+}
+export function _clearBandInfoSupplierForTesting(): void {
+  _bandInfoSupplier = null;
+}
+
 export function processBandTransitions(input: ProviderQuotaAdvisoryInput): void {
-  const info = getProviderBandInfo(input.provider, input.now);
+  const info = (_bandInfoSupplier ?? getProviderBandInfo)(input.provider, input.now);
   if (!info) return;
 
   for (const window of info.windows) {
     if (window.confidence === "low" || window.burnRatio === null) continue;
 
     const key = `${input.provider}:${window.role}`;
-    const state: TransitionState = bandState.get(key) ?? { lastNotifiedBand: "normal", pendingBand: null, pendingCount: 0 };
-    const currentBand = window.band;
-
-    if (currentBand === state.lastNotifiedBand) {
+    const state: TransitionState = bandState.get(key) ?? {
+      lastNotifiedBand: "normal",
+      pendingBand: null,
+      pendingCount: 0,
+      lastTransitionAt: 0,
+    };
+
+    // #756: asymmetric hysteresis — recovery needs penalty HYSTERESIS_MARGIN below the entry
+    // threshold of the current band to prevent ping-pong at a boundary. #760 extends this with a
+    // slack deadband for the "prefer" boundary.
+    const effectiveBand = applyHysteresis(window.band, window.penalty, window.slack, state.lastNotifiedBand, info.quotaBands, info.preferSlackAt);
+
+    if (effectiveBand === state.lastNotifiedBand) {
       if (state.pendingBand !== null) {
         bandState.set(key, { ...state, pendingBand: null, pendingCount: 0 });
       }
       continue;
     }
 
-    if (currentBand === state.pendingBand) {
+    if (effectiveBand === state.pendingBand) {
       state.pendingCount += 1;
     } else {
-      state.pendingBand = currentBand;
+      state.pendingBand = effectiveBand;
       state.pendingCount = 1;
     }
 
     if (state.pendingCount >= DEBOUNCE_SAMPLES) {
+      // #756: rate-limit recovery — it is not an actionable signal for coordinators.
+      const isRecovery = bandRank(effectiveBand) < bandRank(state.lastNotifiedBand);
+      if (isRecovery && input.now - state.lastTransitionAt < RECOVERY_MIN_INTERVAL_MS) {
+        bandState.set(key, state);
+        continue;
+      }
+
       const previousBand = state.lastNotifiedBand;
-      state.lastNotifiedBand = currentBand;
+      state.lastNotifiedBand = effectiveBand;
       state.pendingBand = null;
       state.pendingCount = 0;
+      state.lastTransitionAt = input.now;
       bandState.set(key, state);
       emitBandTransition({
         provider: input.provider,
@@ -75,6 +121,43 @@ export function processBandTransitions(input: ProviderQuotaAdvisoryInput): void
   }
 }
 
+// Asymmetric hysteresis: degradation uses the normal (entry) threshold; recovery requires
+// the penalty to fall HYSTERESIS_MARGIN below the entry threshold of the last notified band.
+// #760: the "prefer" boundary uses a slack deadband instead (penalty is 0 throughout prefer).
+function applyHysteresis(
+  rawBand: QuotaBand,
+  penalty: number,
+  slack: number | null,
+  lastNotifiedBand: QuotaBand,
+  quotaBands: { cautionAt: number; avoidLargeAt: number; hardAvoidAt: number },
+  preferSlackAt: number,
+): QuotaBand {
+  // #760 — hold "prefer" until slack falls PREFER_HYSTERESIS_MARGIN below the entry threshold;
+  // a real over-pace penalty (rawBand worse than normal) exits prefer immediately.
+  if (lastNotifiedBand === "prefer") {
+    if (rawBand === "prefer") return "prefer";
+    if (rawBand === "normal" && slack !== null && slack >= preferSlackAt - PREFER_HYSTERESIS_MARGIN) return "prefer";
+    return rawBand;
+  }
+  // #760 — entering prefer: the slack entry threshold is already applied upstream (window.prefer).
+  // Debounce + recovery rate-limit downstream keep prefer from fleet-spamming.
+  if (rawBand === "prefer") return "prefer";
+  if (bandRank(rawBand) >= bandRank(lastNotifiedBand)) return rawBand;
+  const exitThreshold = bandEntryThreshold(lastNotifiedBand, quotaBands) - HYSTERESIS_MARGIN;
+  if (penalty >= exitThreshold) return lastNotifiedBand;
+  return rawBand;
+}
+
+function bandEntryThreshold(
+  band: QuotaBand,
+  quotaBands: { cautionAt: number; avoidLargeAt: number; hardAvoidAt: number },
+): number {
+  if (band === "hard-avoid") return quotaBands.hardAvoidAt;
+  if (band === "avoid-large") return quotaBands.avoidLargeAt;
+  if (band === "caution") return quotaBands.cautionAt;
+  return 0;
+}
+
 function emitBandTransition(input: {
   provider: string;
   window: ProviderBandWindow;
@@ -95,6 +178,9 @@ function emitBandTransition(input: {
     utilization: window.utilization,
     burnRatio: window.burnRatio,
     projectedWallAt: window.projectedWallAt,
+    // #760 — carry the symmetric underburn signal so coordinators see "prefer", not just "avoid".
+    slack: window.slack,
+    prefer: window.band === "prefer",
     recommendedAction,
   };
 
@@ -134,11 +220,15 @@ function buildBody(input: {
   const proj = window.projectedWallAt !== null
     ? ` (wall ~${new Date(window.projectedWallAt).toISOString()})`
     : "";
-  return `${providerLabel(provider)} ${window.role} quota band: ${previousBand} → ${window.band}. Utilization ${util}%${burn}${proj}. ${recommendedAction}`;
+  // #760 — for the prefer band there is no early wall; surface the projected unused headroom instead.
+  const slackHint = window.band === "prefer" && window.slack !== null ? ` slack ${Math.round(window.slack * 100)}%` : "";
+  return `${providerLabel(provider)} ${window.role} quota band: ${previousBand} → ${window.band}. Utilization ${util}%${burn}${proj}${slackHint}. ${recommendedAction}`;
 }
 
 function bandRank(band: QuotaBand): number {
-  const ranks: Record<QuotaBand, number> = { "normal": 0, "caution": 1, "avoid-large": 2, "hard-avoid": 3 };
+  // #760 — "prefer" is the best state, ranked below "normal", so normal→prefer reads as a
+  // recovery (rate-limited; no fleet-spam) and prefer→normal reads as a degradation.
+  const ranks: Record<QuotaBand, number> = { "prefer": 0, "normal": 1, "caution": 2, "avoid-large": 3, "hard-avoid": 4 };
   return ranks[band];
 }
 

package/src/settings/registry.ts

@@ -234,6 +234,29 @@ const DISPLAY_PREFS_SCHEMA: JSONSchema = {
   },
 };
 
+// Per-conversation chat scroll memory (#759), tier:"user" so a human's reading position +
+// sticky-bottom intent follow them across devices instead of dying in per-browser module state.
+// The value is a MAP keyed by conversation/agent id — one user-settings row holds every
+// conversation's anchor, so this is ONE descriptor (not a per-agent descriptor explosion).
+// Each entry is a LOGICAL anchor, never a pixel scrollTop: `topKey` is the timeline entry key
+// (`msg-<id>` — a server-stable id), `offset` the within-row pixel offset, `stick` the
+// follow-the-bottom intent. `maxProperties` bounds unbounded conversation growth; the dashboard
+// store evicts oldest-touched before it can be hit.
+const CHAT_SCROLL_SCHEMA: JSONSchema = {
+  type: "object",
+  maxProperties: 200,
+  additionalProperties: {
+    type: "object",
+    additionalProperties: false,
+    required: ["stick", "topKey", "offset"],
+    properties: {
+      stick: { type: "boolean" },
+      topKey: { type: ["string", "null"], maxLength: 200 },
+      offset: { type: "number", minimum: 0, maximum: 10_000_000 },
+    },
+  },
+};
+
 const VOICE_PREFS_SCHEMA: JSONSchema = {
   type: "object",
   additionalProperties: false,
@@ -404,6 +427,17 @@ function seedBuiltInSettings(): void {
     display: { group: "Preferences", label: "Display", description: "Per-user theme and reasoning visibility (follows you across devices).", order: 70 },
   });
 
+  // Per-conversation chat scroll memory (#759) — one row per user, keyed internally by agent id.
+  registerSetting({
+    namespace: "chat",
+    key: "scroll",
+    schema: CHAT_SCROLL_SCHEMA,
+    defaults: {},
+    scope: { read: "settings:read:chat", write: "settings:write:chat" },
+    tier: "user",
+    display: { group: "Preferences", label: "Chat scroll", description: "Per-conversation scroll position and sticky-bottom flag (follows you across devices).", order: 72 },
+  });
+
   registerSetting({
     namespace: "voice",
     key: "default",

package/src/spawn-targets.ts

@@ -4,6 +4,7 @@ import { effectiveProviderCatalogList } from "./provider-catalog-store";
 import { getRoutingPolicy } from "./routing-policy-store";
 import { isPathWithinBase } from "./utils";
 import { McpNotFoundError } from "./mcp-errors";
+import { DEFAULT_QUOTA_PREFER_SLACK_AT, DEFAULT_QUOTA_TARGET_UTILIZATION, quotaPaceMetrics } from "agent-relay-sdk/provider-quota";
 import type { ProviderQuotaRoutingConfig } from "agent-relay-sdk";
 import type { Orchestrator, ProviderCatalogSummary, ProviderQuotaBurnRole, ProviderQuotaBurnWindow, ProviderQuotaRecord, QuotaState, SpawnProvider } from "./types";
 
@@ -64,7 +65,8 @@ interface SpawnCatalogish {
   models: Array<{ alias: string; providerModel: string; efforts: readonly string[]; defaultEffort?: string; disabled?: boolean; unavailable?: string }>;
 }
 
-type SpawnQuotaBurnBand = "normal" | "caution" | "avoid-large" | "hard-avoid";
+// #760 — "prefer" is the underburn counterpart to the over-pace penalty ladder.
+type SpawnQuotaBurnBand = "prefer" | "normal" | "caution" | "avoid-large" | "hard-avoid";
 
 interface SpawnQuotaBurnWindow {
   role: ProviderQuotaBurnRole;
@@ -79,6 +81,11 @@ interface SpawnQuotaBurnWindow {
   projectedWallAt: number | null;
   earlyWallMs: number | null;
   earlyFraction: number | null;
+  // #760 — symmetric underburn signal (see ProviderQuotaBurnWindow.slack), re-derived against
+  // the per-provider target, plus the "prefer" flag for this window.
+  projectedUtilAtReset: number | null;
+  slack: number | null;
+  prefer: boolean;
   weight: 1 | 3;
   penalty: number;
   blockedNow: boolean;
@@ -88,6 +95,9 @@ interface SpawnQuotaAdvisory {
   quotaBurn: { windows: SpawnQuotaBurnWindow[] };
   quotaPenalty: number;
   quotaPenaltyBand: SpawnQuotaBurnBand;
+  // #760 — provider underburn: every selected window projects ≥ preferSlackAt headroom at reset.
+  prefer: boolean;
+  slack: number | null;
   blockedNow: boolean;
   recommendedAction: string;
 }
@@ -96,6 +106,8 @@ const DEFAULT_QUOTA_ADVISORY: SpawnQuotaAdvisory = {
   quotaBurn: { windows: [] },
   quotaPenalty: 0,
   quotaPenaltyBand: "normal",
+  prefer: false,
+  slack: null,
   blockedNow: false,
   recommendedAction: "No quota burn projection available; spawn normally.",
 };
@@ -173,13 +185,23 @@ function quotaAdvisoryFor(
   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, quotaBands);
+  const penaltyBand = quotaPenaltyBandFor(quotaPenalty, quotaBands);
+  // #760 — provider-level "prefer": no over-pace penalty AND every selected window is projected
+  // to land ≥ preferSlackAt below target. The binding constraint is the LEAST-slack window, so a
+  // tight 5h window vetoes prefer even if 7d is wide open.
+  const preferSlackAt = providerCfg?.preferSlackAt ?? DEFAULT_QUOTA_PREFER_SLACK_AT;
+  const slacks = windows.map((window) => window.slack).filter((slack): slack is number => slack !== null);
+  const minSlack = slacks.length === windows.length && slacks.length > 0 ? Math.min(...slacks) : null;
+  const prefer = !blockedNow && penaltyBand === "normal" && minSlack !== null && minSlack >= preferSlackAt;
+  const quotaPenaltyBand: SpawnQuotaBurnBand = prefer ? "prefer" : penaltyBand;
   return {
     quotaBurn: { windows },
     quotaPenalty,
     quotaPenaltyBand,
+    prefer,
+    slack: minSlack,
     blockedNow,
-    recommendedAction: recommendedAction({ quotaPenaltyBand, blockedNow, windows }),
+    recommendedAction: recommendedAction({ quotaPenaltyBand, blockedNow, prefer, slack: minSlack, windows }),
   };
 }
 
@@ -199,14 +221,37 @@ function spawnQuotaWindow(
 ): SpawnQuotaBurnWindow | undefined {
   if (!quotaWindow) return undefined;
   const timeToResetMs = typeof quotaWindow.resetsAt === "number" ? Math.max(0, quotaWindow.resetsAt - now) : null;
+  // earlyWallMs may be negative (#760 symmetric); the over-pace penalty only sees the positive half.
   const earlyFraction = burnWindow.earlyWallMs !== null && timeToResetMs && timeToResetMs > 0
     ? 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;
+  // #760 — floor default is now 0 (off). The projection/pace gate (earlyFraction≈0 when the
+  // recency-weighted rate projects no early wall) replaces the blunt utilization floor, which
+  // used to hide a legitimate low-util-high-burst alarm. Operators may still opt back in.
+  const utilizationFloor = providerCfg?.burnPenaltyUtilizationFloor ?? 0;
   const rawPenalty = (earlyFraction ?? 0) * weight;
   const penalty = quotaWindow.utilization < utilizationFloor ? 0 : rawPenalty;
+
+  // #760 — re-derive the pace projection against the PER-PROVIDER target (the stored burn used
+  // the default). Slack is the symmetric underburn signal; prefer flags a window with no
+  // over-pace penalty and ≥ preferSlackAt projected headroom at reset.
+  const target = providerCfg?.targetUtilization ?? DEFAULT_QUOTA_TARGET_UTILIZATION;
+  const preferSlackAt = providerCfg?.preferSlackAt ?? DEFAULT_QUOTA_PREFER_SLACK_AT;
+  const blockedNow = quotaWindow.utilization >= hardBackstop;
+  let burnRatio = burnWindow.burnRatio;
+  let projectedUtilAtReset = burnWindow.projectedUtilAtReset;
+  let slack = burnWindow.slack;
+  if (burnWindow.observedRatePerMs !== null && timeToResetMs !== null && timeToResetMs > 0) {
+    const pace = quotaPaceMetrics({ utilization: quotaWindow.utilization, observedRatePerMs: burnWindow.observedRatePerMs, timeToResetMs, target });
+    burnRatio = pace.burnRatio;
+    projectedUtilAtReset = pace.projectedUtilAtReset;
+    slack = pace.slack;
+  }
+  const prefer = !blockedNow && penalty === 0
+    && quotaPenaltyBandFor(penalty) === "normal"
+    && slack !== null && slack >= preferSlackAt;
   return {
     role: burnWindow.role,
     name: burnWindow.name,
@@ -215,27 +260,34 @@ function spawnQuotaWindow(
     resetsAt: quotaWindow.resetsAt ?? null,
     timeToResetMs,
     confidence: burnWindow.confidence,
-    burnRatio: burnWindow.burnRatio,
+    burnRatio,
     timeToWallMs: burnWindow.timeToWallMs,
     projectedWallAt: burnWindow.projectedWallAt,
     earlyWallMs: burnWindow.earlyWallMs,
     earlyFraction,
+    projectedUtilAtReset,
+    slack,
+    prefer,
     weight,
     penalty,
-    blockedNow: quotaWindow.utilization >= hardBackstop,
+    blockedNow,
   };
 }
 
 // === Public band-info API for quota-band-transition (#738) ===
 
-export type QuotaBand = "normal" | "caution" | "avoid-large" | "hard-avoid";
+// #760 — "prefer" ranks below "normal" (it is the BEST state): see bandRank in quota-band-transition.
+export type QuotaBand = "prefer" | "normal" | "caution" | "avoid-large" | "hard-avoid";
 
 export interface ProviderBandWindow {
   role: ProviderQuotaBurnRole;
   band: QuotaBand;
+  penalty: number;
   utilization: number;
   burnRatio: number | null;
   projectedWallAt: number | null;
+  // #760 — symmetric underburn signal; the band-transition deadband uses it for the prefer boundary.
+  slack: number | null;
   confidence: "high" | "low";
 }
 
@@ -243,6 +295,9 @@ export interface ProviderBandInfo {
   windows: ProviderBandWindow[];
   providerBand: QuotaBand;
   recommendedAction: string;
+  quotaBands: { cautionAt: number; avoidLargeAt: number; hardAvoidAt: number };
+  // #760 — slack threshold at which a window enters "prefer"; the deadband holds it preferMargin below.
+  preferSlackAt: number;
 }
 
 /**
@@ -255,15 +310,24 @@ export function getProviderBandInfo(provider: string, now: number): ProviderBand
   const records = listProviderQuotas({ provider, historyLimit: 0, now }).quotas;
   if (records.length === 0) return undefined;
   const advisory = quotaAdvisoryFor(records, now, policy.quotaBands, policy.providerQuota?.[provider as SpawnProvider]);
+  const quotaBands = {
+    cautionAt: policy.quotaBands?.cautionAt ?? 0.15,
+    avoidLargeAt: policy.quotaBands?.avoidLargeAt ?? 0.5,
+    hardAvoidAt: policy.quotaBands?.hardAvoidAt ?? 1.0,
+  };
   const windows: ProviderBandWindow[] = advisory.quotaBurn.windows.map((w) => ({
     role: w.role,
-    band: quotaPenaltyBandFor(w.penalty, policy.quotaBands),
+    // #760 — per-window prefer overlay: w.prefer already encodes "no penalty + ≥ preferSlackAt slack".
+    band: w.prefer ? "prefer" : quotaPenaltyBandFor(w.penalty, policy.quotaBands),
+    penalty: w.penalty,
     utilization: w.utilization,
     burnRatio: w.burnRatio,
     projectedWallAt: w.projectedWallAt,
+    slack: w.slack,
     confidence: w.confidence,
   }));
-  return { windows, providerBand: advisory.quotaPenaltyBand, recommendedAction: advisory.recommendedAction };
+  const preferSlackAt = policy.providerQuota?.[provider as SpawnProvider]?.preferSlackAt ?? DEFAULT_QUOTA_PREFER_SLACK_AT;
+  return { windows, providerBand: advisory.quotaPenaltyBand, recommendedAction: advisory.recommendedAction, quotaBands, preferSlackAt };
 }
 
 function compareQuotaWindows(a: SpawnQuotaBurnWindow, b: SpawnQuotaBurnWindow): number {
@@ -285,7 +349,7 @@ function quotaPenaltyBandFor(
   return "normal";
 }
 
-function recommendedAction(input: { quotaPenaltyBand: SpawnQuotaBurnBand; blockedNow: boolean; windows: SpawnQuotaBurnWindow[] }): string {
+function recommendedAction(input: { quotaPenaltyBand: SpawnQuotaBurnBand; blockedNow: boolean; prefer: boolean; slack: number | null; windows: SpawnQuotaBurnWindow[] }): string {
   if (input.blockedNow) {
     const hasSevenDayBlock = input.windows.some((window) => window.role === "7d" && window.blockedNow);
     return hasSevenDayBlock
@@ -295,6 +359,11 @@ function recommendedAction(input: { quotaPenaltyBand: SpawnQuotaBurnBand; blocke
   if (input.quotaPenaltyBand === "hard-avoid") return "Hard avoid unless explicitly requested or no healthier alternate exists.";
   if (input.quotaPenaltyBand === "avoid-large") return "Avoid large jobs if a healthier alternate exists.";
   if (input.quotaPenaltyBand === "caution") return "Caution: prefer cheaper effort/model when practical.";
+  // #760 — surface the underburn signal so coordinators load-shift big/deferrable jobs here.
+  if (input.quotaPenaltyBand === "prefer") {
+    const headroom = input.slack !== null ? ` (~${Math.round(input.slack * 100)}% quota would otherwise go unused at reset)` : "";
+    return `Prefer for large or deferrable jobs${headroom}.`;
+  }
   return "Spawn normally.";
 }