agent-relay-server 0.99.1 → 0.101.0

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/routes/agent-sessions.ts

@@ -13,6 +13,7 @@ import { emitAgentStatus, emitDashboardPresence, emitNewMessage } from "../sse";
 import { getAgentProfile, getSpawnPolicy } from "../config-store";
 import { listManagedOrchestratorsForAgent } from "../orchestrator-lookup";
 import { runnerRuntimeTokenEnv } from "../runtime-tokens";
+import { agentProviderState } from "../provider-state";
 import { authContextFromRequest } from "../services/auth-context";
 import { ShutdownAuthError, ShutdownTargetError, shutdownAgent } from "../services/shutdown-agent";
 import { type AgentCard, type SpawnApprovalMode } from "../types";
@@ -414,8 +415,9 @@ export const postAgentPermissionDecision: Handler = async (req, params) => {
     const arb = arbitrateDrive(requestUserId(req), agent.id);
     if (!arb.allowed) return driveBlockedResponse(arb);
     if (!agentIsControlEligible(agent)) return error("agent cannot receive permission decisions", 400);
-    const pendingApproval = isRecord(agent.meta?.providerState) && isRecord(agent.meta.providerState.pendingApproval)
-      ? agent.meta.providerState.pendingApproval
+    const providerState = agentProviderState(agent);
+    const pendingApproval = isRecord(providerState?.pendingApproval)
+      ? providerState.pendingApproval
       : null;
     const pendingId = typeof pendingApproval?.id === "string" ? pendingApproval.id : "";
     if (pendingId && pendingId !== approvalId) return error("approval request is no longer current", 409);

package/src/services/issue-lifecycle.ts

@@ -15,7 +15,7 @@ import { defaultIssueRepo } from "../config";
 // existing importers and tests keep their entry point.
 import { parseOwnerRepoFromRemote, repoFromGitRemote, __resetRemoteRepoCacheForTests } from "./git-remote";
 export { parseOwnerRepoFromRemote, repoFromGitRemote, __resetRemoteRepoCacheForTests };
-import type { IssueTrackerAdapter } from "../issue-tracker";
+import type { IssueTrackerAdapter, IssueTrackerIssueSummary } from "../issue-tracker";
 import { recordAndEmitIssueActivity } from "./issue-activity";
 import type { IssueAssociationEntityType, IssueProvider, IssueRef, WorkspaceRecord } from "../types";
 
@@ -208,14 +208,41 @@ function closeAuditComment(input: LandedIssueLifecycleInput): string {
   return `Closed by \`${commit}\` on merge to \`main\` - reopen if release surfaces more work.`;
 }
 
-function issueLabel(ref: IssueRef, parent: IssueRef): string {
+function issueLabel(ref: Pick<IssueRef, "repo" | "externalKey">, parent: IssueRef): string {
   return ref.repo === parent.repo ? `#${ref.externalKey}` : `${ref.repo}#${ref.externalKey}`;
 }
 
-function backlinkProgressComment(input: LandedIssueLifecycleInput, parent: IssueRef, openSubIssues: IssueRef[]): string {
+function openSubIssuesComment(input: LandedIssueLifecycleInput, parent: IssueRef, openSubIssues: IssueTrackerIssueSummary[]): string {
   const commit = input.mergedSha ? input.mergedSha.slice(0, 12) : input.workspace.branch ?? input.workspace.id;
   const childList = openSubIssues.map((ref) => issueLabel(ref, parent)).join(", ");
-  return `Linked landed slice \`${commit}\` to this parent issue, but Agent Relay left it open because these sub-issues are still open: ${childList}.`;
+  return `Referenced by landed commit \`${commit}\`; left open because these sub-issues are still open: ${childList}.`;
+}
+
+function issueSummaryKey(ref: Pick<IssueTrackerIssueSummary, "provider" | "repo" | "externalKey">): string {
+  return `${ref.provider}:${ref.repo}#${ref.externalKey}`;
+}
+
+async function listOpenSubIssuesForLand(issueRef: IssueRef, opts: IssueLifecycleOptions): Promise<IssueTrackerIssueSummary[]> {
+  const open = new Map<string, IssueTrackerIssueSummary>();
+  const adapter = adapterFor(issueRef, opts);
+  if (adapter.listOpenSubIssues) {
+    for (const ref of await adapter.listOpenSubIssues(issueRef)) {
+      if (ref.status === "open") open.set(issueSummaryKey(ref), ref);
+    }
+  }
+  for (const item of listIssuesForEntity("epic", issueRef.id)) {
+    const ref = item.issueRef;
+    if (ref.status !== "open") continue;
+    open.set(issueSummaryKey(ref), {
+      provider: ref.provider,
+      repo: ref.repo,
+      externalKey: ref.externalKey,
+      url: ref.url,
+      title: ref.title,
+      status: "open",
+    });
+  }
+  return [...open.values()];
 }
 
 async function reconcileClosedIssueRefBeforeSkip(issueRef: IssueRef, opts: IssueLifecycleOptions): Promise<{
@@ -250,11 +277,30 @@ async function closeIssueRefForLand(
     if (reconciled.liveStatus !== "open") return { issueRef: latest, action: "skipped", reason: "already-closed", landKey: key };
   }
 
-  const openSubIssues = source === "backlink"
-    ? listIssuesForEntity("epic", latest.id).map((item) => item.issueRef).filter((ref) => ref.status === "open")
-    : [];
+  let openSubIssues: IssueTrackerIssueSummary[];
+  try {
+    openSubIssues = await listOpenSubIssuesForLand(latest, opts);
+  } catch (error) {
+    const message = `sub-issue lookup failed: ${errMessage(error)}`;
+    upsertIssueLifecycleAction({
+      issueRefId: latest.id,
+      action: "close",
+      landKey: key,
+      workspaceId: input.workspace.id,
+      branch: input.workspace.branch,
+      baseRef: input.workspace.baseRef ?? "main",
+      commitSha: input.mergedSha,
+      commitSubject: input.subject,
+      agentId: input.workspace.ownerAgentId,
+      source,
+      status: "failed",
+      error: message,
+    });
+    logFailure(opts, `issue lifecycle sub-issue lookup failed for ${latest.id} on ${key}: ${errMessage(error)}`);
+    return { issueRef: latest, action: "failed", error: message, landKey: key };
+  }
   if (openSubIssues.length > 0) {
-    const comment = backlinkProgressComment(input, latest, openSubIssues);
+    const comment = openSubIssuesComment(input, latest, openSubIssues);
     try {
       await adapterFor(latest, opts).comment(latest, comment);
     } catch (error) {

package/src/services/provider-state-audit.ts

@@ -1,6 +1,6 @@
 import { createActivityEvent } from "../db";
 import { routeNotification } from "../notification-router";
-import { agentProviderState } from "../provider-state";
+import { agentProviderState, type ProviderState } from "../provider-state";
 import type { AgentCard } from "../types";
 
 export function auditProviderStateTransition(agentId: string, before: AgentCard | null | undefined, after: AgentCard | null | undefined): void {
@@ -46,7 +46,7 @@ export function auditProviderStateTransition(agentId: string, before: AgentCard
   }
 }
 
-function providerStateKey(state: Record<string, unknown> | null): string | null {
+function providerStateKey(state: ProviderState | null): string | null {
   if (!state) return null;
-  return [state.state, typeof state.reason === "string" ? state.reason : ""].join(":");
+  return [state.state, state.reason ?? ""].join(":");
 }

package/src/services/rate-limit-resume.ts

@@ -6,6 +6,7 @@ import {
   agentProviderState,
   isRateLimitHold,
   isTransientRateLimitHold,
+  type ProviderState,
   rateLimitResumeAt,
   transientRateLimitAttempt,
   transientRateLimitExhausted,
@@ -46,7 +47,7 @@ export function resetRateLimitResumeTrackerForTests(): void {
 const RESUME_BODY =
   "Your provider limit/overload hold is ready to retry — resuming. Continue the task you were working on when the provider interrupted you. If you had already finished, no action is needed.";
 
-function nextTransientState(state: Record<string, unknown>, now: number, attempts: number): Record<string, unknown> {
+function nextTransientState(state: ProviderState, now: number, attempts: number): ProviderState {
   const nextAttempts = attempts + 1;
   const nextDelay = TRANSIENT_RATE_LIMIT_BACKOFF_MS[nextAttempts];
   return {
@@ -58,7 +59,7 @@ function nextTransientState(state: Record<string, unknown>, now: number, attempt
   };
 }
 
-function notifyTransientExhausted(agent: { id: string; label?: string | null; spawnedBy?: string | null }, state: Record<string, unknown>, now: number): void {
+function notifyTransientExhausted(agent: { id: string; label?: string | null; spawnedBy?: string | null }, state: ProviderState, now: number): void {
   mergeAgentMeta(agent.id, { providerState: { ...state, exhaustedAt: now, updatedAt: now } });
   if (!agent.spawnedBy) return;
   routeNotification({
@@ -88,6 +89,7 @@ export function resumeRateLimitedAgents(): Record<string, unknown> {
     seen.add(agent.id);
 
     const state = agentProviderState(agent);
+    if (!state) continue;
     const resumeAt = rateLimitResumeAt(state);
     if (resumeAt !== null && now < resumeAt) { waiting.push(agent.id); continue; }
 
@@ -96,7 +98,7 @@ export function resumeRateLimitedAgents(): Record<string, unknown> {
     const attempts = transient ? Math.max(transientRateLimitAttempt(state), tracked.attempts ?? 0) : 0;
     if (transient && (attempts >= TRANSIENT_RATE_LIMIT_BACKOFF_MS.length || transientRateLimitExhausted(state))) {
       if (!tracked.exhaustedNotified) {
-        notifyTransientExhausted(agent, state as Record<string, unknown>, now);
+        notifyTransientExhausted(agent, state, now);
         resumeTracker.set(agent.id, { ...tracked, attempts, exhaustedNotified: true });
       }
       waiting.push(agent.id);
@@ -133,7 +135,7 @@ export function resumeRateLimitedAgents(): Record<string, unknown> {
       continue;
     }
 
-    if (transient) mergeAgentMeta(agent.id, { providerState: nextTransientState(state as Record<string, unknown>, now, attempts) });
+    if (transient) mergeAgentMeta(agent.id, { providerState: nextTransientState(state, now, attempts) });
 
     // #416 — flush messages queued while the agent was rate-limited.
     flushQueuedDirectMessages(agent.id);

package/src/services/register-agent.ts

@@ -13,6 +13,7 @@ import { isReservedAgentId } from "agent-relay-sdk";
 import { ValidationError, createActivityEvent, getAgent, seedSpawnPromptMirror, seedSpawnReplyObligation, upsertAgent } from "../db";
 import { emitAgentStatus, emitNewMessage } from "../sse";
 import { noteAgentTimelineEvent } from "../compaction-watch";
+import { agentProviderTimelineEvent } from "../provider-timeline-event";
 import { notifyAgentReady } from "../agent-lifecycle-events";
 import { resolveSpawnLineage, resolveTeamLineage } from "../security";
 import { flushQueuedDirectMessages, markManagedAgentRunning } from "./managed-running";
@@ -65,7 +66,7 @@ export function registerAgent(input: RegisterAgentInput, ctx: AuthContext): Agen
   // PreCompact/SessionStart hook arrives as a latched meta.timelineEvent — clears any
   // pending stall watch; the timestamp guard inside ignores stale latched events.
   emitAgentStatus(agent.id);
-  noteAgentTimelineEvent(agent.id, agent.meta?.timelineEvent);
+  noteAgentTimelineEvent(agent.id, agentProviderTimelineEvent(agent));
 
   // #308/#351 — a spawned child registering already-ready (the common isolated-worktree
   // case) wakes its block-polling parent. Fire on the first-ever ready, regardless of

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.";
 }
 
@@ -306,6 +375,7 @@ function spawnProfilesSummary(): Array<Record<string, unknown>> {
   return listAgentProfiles().map(({ key, value }) => ({
     name: value.name ?? key,
     description: value.description,
+    ...(value.icon ? { icon: value.icon } : {}),
     provider: value.provider,
     approvalMode: value.permissions?.mode,
     ...(value.maxSpawnedAgents !== undefined ? { maxSpawnedAgents: value.maxSpawnedAgents } : {}),