talon-agent 5.4.1 → 5.5.0

package/src/core/engine/backend-router/router.ts

@@ -0,0 +1,322 @@
+/**
+ * Plan-aware backend routing for background work.
+ *
+ * Background work — `spawn_agent` sub-agents, cron `query` jobs, the
+ * heartbeat — used to inherit whichever backend the chat happened to be on.
+ * On a multi-subscription install that is a good way to burn one plan to its
+ * ceiling while another sits idle. When nothing is pinned, this picks the
+ * backend with the most headroom instead.
+ *
+ * The rules, in order:
+ *
+ *   1. An explicit backend (or a model, which pins its backend) always wins.
+ *      Routing is what happens in the *absence* of a choice, never over one.
+ *   2. `config.router.enabled: false` returns the caller's own backend —
+ *      byte-identical to pre-router Talon.
+ *   3. Otherwise: rank the candidates by headroom, skip anyone at or above
+ *      `ceilingPercent`, and take the top one.
+ *
+ * Only backends that can actually host an isolated run are candidates, and
+ * routing never boots a cold provider to find out: a backend qualifies when
+ * it is pooled with a `background` slot, or when the operator gave it a local
+ * budget (`backendBudgets`), which is both an opt-in and the only way it
+ * would have a headroom signal. The caller's own backend is always in the
+ * running, so there is always an answer.
+ */
+
+import type { TalonConfig } from "../../config/index.js";
+import type { ReasoningEffortLevel } from "../../types.js";
+import { log } from "../../../util/log.js";
+import {
+  acquireBackendInstance,
+  getPoolConfig,
+  getPooledBackend,
+  listAvailableBackends,
+} from "../backend-controller/index.js";
+import {
+  formatHeadroom,
+  getBackendHeadroom,
+  hasBudget,
+  type BackendHeadroom,
+} from "./headroom.js";
+
+/** Default for `config.router.ceilingPercent`. */
+export const DEFAULT_CEILING_PERCENT = 85;
+
+/** Which background subsystem is asking. Logged, and nothing else — yet. */
+export type RoutePurpose = "subagent" | "cron" | "heartbeat";
+
+/**
+ * A coarse shape-of-work hint. It never outranks headroom: a class either
+ * *vetoes* backends that cannot do the job at all, or breaks a tie.
+ */
+export type TaskClass = "coding" | "mechanical" | "reasoning";
+
+/**
+ * The one place the task-class opinions live. `require` is a veto (applied
+ * only when at least one required backend is a candidate, so a deployment
+ * without it still gets an answer); `prefer` is tie-break order.
+ *
+ *   - coding      — agentic edit/test loops; Codex and Claude are the two
+ *                   with real harnesses behind them.
+ *   - mechanical  — sweeps and reformatting; cheapest first (agy's flash
+ *                   tier, then Claude's haiku tier).
+ *   - reasoning   — deep thinking (also where `xhigh` effort lands); Claude
+ *                   is the only backend Talon drives an opus-class model on.
+ */
+const TASK_CLASS_RULES: Record<
+  TaskClass,
+  { readonly prefer: readonly string[]; readonly require?: readonly string[] }
+> = {
+  coding: { prefer: ["codex", "claude"] },
+  mechanical: { prefer: ["agy", "claude"] },
+  reasoning: { prefer: ["claude"], require: ["claude"] },
+};
+
+/** Ranking priority of a headroom source — measured beats unmeasured. */
+const SOURCE_RANK: Record<BackendHeadroom["source"], number> = {
+  plan: 0,
+  ledger: 1,
+  none: 2,
+};
+
+export interface RouteHints {
+  readonly taskClass?: TaskClass;
+  readonly effort?: ReasoningEffortLevel;
+}
+
+export interface RouteRequest {
+  readonly purpose: RoutePurpose;
+  /** An explicit backend from the caller. Wins outright. */
+  readonly requestedBackendId?: string;
+  /** An explicit model. Pins whatever backend is serving it. */
+  readonly requestedModel?: string;
+  /** The backend the caller would have used before routing existed. */
+  readonly chatBackendId: string;
+  /** Defaults to the config the backend pool was initialised with. */
+  readonly config?: TalonConfig;
+  readonly hints?: RouteHints;
+}
+
+export interface RouteDecision {
+  readonly backendId: string;
+  /** Only set when the caller pinned one — model choice stays downstream. */
+  readonly model?: string;
+  /** Human-readable: `pinned`, `disabled`, or why this backend won. */
+  readonly reason: string;
+  /** True when headroom actually chose this, rather than a pin or a default. */
+  readonly routed: boolean;
+  /** What the decision saw, for the spawn reply and the log line. */
+  readonly headroom?: BackendHeadroom;
+}
+
+/** The task class a reasoning-effort level implies, if any. */
+export function taskClassForEffort(
+  effort: ReasoningEffortLevel | undefined,
+): TaskClass | undefined {
+  return effort === "xhigh" || effort === "high" ? "reasoning" : undefined;
+}
+
+/** `config.router`, with the documented defaults filled in. */
+function routerSettings(config: TalonConfig | undefined): {
+  enabled: boolean;
+  ceilingPercent: number;
+} {
+  return {
+    enabled: config?.router?.enabled ?? true,
+    ceilingPercent: config?.router?.ceilingPercent ?? DEFAULT_CEILING_PERCENT,
+  };
+}
+
+/**
+ * Can this backend host an isolated run, without booting it to find out?
+ * A pooled instance answers from its capability slots; a cold one qualifies
+ * only on an explicit local budget (see the module comment).
+ */
+function isCandidate(
+  id: string,
+  config: TalonConfig | undefined,
+  chatBackendId: string,
+): boolean {
+  if (id === chatBackendId) return true;
+  const pooled = getPooledBackend(id);
+  if (pooled) return Boolean(pooled.background);
+  return hasBudget(config, id);
+}
+
+/** Percent of the tightest window — what the ceiling is applied to. */
+function limitingPercent(entry: BackendHeadroom): number {
+  return entry.limiting?.percent ?? 0;
+}
+
+/** Comparator: headroom first, then the documented tie-breaks. */
+function rank(
+  a: BackendHeadroom,
+  b: BackendHeadroom,
+  chatBackendId: string,
+  prefer: readonly string[],
+): number {
+  // Headroom to 3dp: two backends a thousandth apart are a tie, not a winner.
+  const byHeadroom =
+    Math.round(b.headroom * 1000) - Math.round(a.headroom * 1000);
+  if (byHeadroom !== 0) return byHeadroom;
+  const bySource = SOURCE_RANK[a.source] - SOURCE_RANK[b.source];
+  if (bySource !== 0) return bySource;
+  const preferIndex = (id: string): number => {
+    const i = prefer.indexOf(id);
+    return i === -1 ? prefer.length : i;
+  };
+  const byPrefer = preferIndex(a.id) - preferIndex(b.id);
+  if (byPrefer !== 0) return byPrefer;
+  // Cache warmth: a sub-agent is isolated, but the caller's backend is
+  // already up and its MCP servers are already spawned.
+  if (a.id === chatBackendId) return -1;
+  if (b.id === chatBackendId) return 1;
+  return a.id.localeCompare(b.id);
+}
+
+/**
+ * Apply a task class's hard requirement, when a candidate still satisfies it.
+ * Runs on the post-ceiling set, so a spent required backend is already gone.
+ */
+function applyVeto(
+  entries: BackendHeadroom[],
+  required: readonly string[] | undefined,
+): BackendHeadroom[] {
+  if (!required || required.length === 0) return entries;
+  const kept = entries.filter((e) => required.includes(e.id));
+  return kept.length > 0 ? kept : entries;
+}
+
+/** Drop candidates at or above the ceiling — unless that drops all of them. */
+function applyCeiling(
+  entries: BackendHeadroom[],
+  ceilingPercent: number,
+): { kept: BackendHeadroom[]; allOverCeiling: boolean } {
+  const kept = entries.filter((e) => limitingPercent(e) < ceilingPercent);
+  if (kept.length > 0) return { kept, allOverCeiling: false };
+  // Everything is spent. Running the least-bad one beats running nothing:
+  // the background subsystems have no queue to defer into.
+  return { kept: entries, allOverCeiling: true };
+}
+
+function decisionFor(
+  winner: BackendHeadroom,
+  allOverCeiling: boolean,
+): RouteDecision {
+  const reason = allOverCeiling
+    ? `every backend is over the ceiling — least spent: ${formatHeadroom(winner)}`
+    : `most headroom ${Math.round(winner.headroom * 100)}%`;
+  return {
+    backendId: winner.id,
+    reason,
+    routed: true,
+    headroom: winner,
+  };
+}
+
+function logDecision(
+  request: RouteRequest,
+  decision: RouteDecision,
+  candidates: BackendHeadroom[],
+): void {
+  const seen = candidates.map((c) => `${c.id}=${formatHeadroom(c)}`).join(", ");
+  log(
+    "router",
+    `${request.purpose}: → ${decision.backendId} (${decision.reason})` +
+      (seen ? ` | candidates: ${seen}` : ""),
+  );
+}
+
+/**
+ * Choose the backend a piece of background work should run on.
+ *
+ * Never throws and never returns nothing: every path ends at a real backend
+ * id, falling back to the caller's own.
+ */
+export async function chooseBackend(
+  request: RouteRequest,
+): Promise<RouteDecision> {
+  const { chatBackendId, purpose } = request;
+
+  if (request.requestedBackendId || request.requestedModel) {
+    const decision: RouteDecision = {
+      backendId: request.requestedBackendId ?? chatBackendId,
+      reason: "pinned",
+      routed: false,
+      ...(request.requestedModel ? { model: request.requestedModel } : {}),
+    };
+    log("router", `${purpose}: → ${decision.backendId} (pinned)`);
+    return decision;
+  }
+
+  const config = request.config ?? getPoolConfig() ?? undefined;
+  const settings = routerSettings(config);
+  if (!settings.enabled) {
+    return { backendId: chatBackendId, reason: "disabled", routed: false };
+  }
+
+  const ids = listAvailableBackends(config)
+    .filter(({ id }) => isCandidate(id, config, chatBackendId))
+    .map(({ id, label }) => ({ id, label }));
+  if (ids.length === 0) {
+    return { backendId: chatBackendId, reason: "no candidates", routed: false };
+  }
+
+  const measured = await Promise.all(
+    ids.map(({ id, label }) => getBackendHeadroom(id, label, config)),
+  );
+
+  const rules = request.hints?.taskClass
+    ? TASK_CLASS_RULES[request.hints.taskClass]
+    : undefined;
+  // Ceiling first, THEN the veto: a hard task-class requirement must not be
+  // able to send work to a backend that is out of plan. A lesser model that
+  // runs beats the right one that rate-limits.
+  const { kept, allOverCeiling } = applyCeiling(
+    measured,
+    settings.ceilingPercent,
+  );
+  const eligible = applyVeto(kept, rules?.require);
+  const ordered = [...eligible].sort((a, b) =>
+    rank(a, b, chatBackendId, rules?.prefer ?? []),
+  );
+  const winner = ordered[0];
+  if (!winner) {
+    return { backendId: chatBackendId, reason: "no candidates", routed: false };
+  }
+
+  const decision = decisionFor(winner, allOverCeiling);
+  logDecision(request, decision, measured);
+  return decision;
+}
+
+/**
+ * The default model for a backend the router just picked.
+ *
+ * A routed run cannot carry the caller's model across — a model id is
+ * backend-specific. Config's `backendDefaults` wins (it is the operator's
+ * answer to "what should this provider run"), then the backend's own
+ * canonical default. Resolves `null` when neither exists, which the call
+ * sites read as "stay where you were".
+ */
+export async function resolveRoutedModel(
+  backendId: string,
+  config?: TalonConfig,
+): Promise<string | null> {
+  const settings = config ?? getPoolConfig() ?? undefined;
+  const configured = settings?.backendDefaults?.[backendId];
+  if (configured) return configured;
+  try {
+    const pooled = getPooledBackend(backendId);
+    if (pooled) return (await pooled.models?.getDefaultModelId()) ?? null;
+    const acquired = await acquireBackendInstance(backendId);
+    try {
+      return (await acquired.backend.models?.getDefaultModelId()) ?? null;
+    } finally {
+      await acquired.release();
+    }
+  } catch {
+    return null;
+  }
+}

package/src/core/engine/backend-router/usage.ts

@@ -0,0 +1,80 @@
+/**
+ * One usage snapshot per backend — what `/usage`, the `plan_usage` tool and
+ * `list_backends` all read.
+ *
+ * It lives in core rather than in the frontend presentation layer because
+ * the gateway tools need it too, and core cannot import a frontend. The
+ * split is: this module *gathers* (plan windows, headroom, and the reason
+ * there is nothing to show), renderers *format*.
+ *
+ * Nothing here boots a backend. Reading a number should never cost a
+ * subprocess per idle provider, so a backend that isn't running is listed
+ * with a reason instead of being woken or omitted.
+ */
+
+import type { PlanUsage } from "../../agent-runtime/capabilities.js";
+import type { TalonConfig } from "../../config/index.js";
+import {
+  getPooledBackend,
+  listAvailableBackends,
+} from "../backend-controller/index.js";
+import { getBackendHeadroom, type BackendHeadroom } from "./headroom.js";
+
+export interface BackendUsageSnapshot {
+  readonly id: string;
+  readonly label: string;
+  /** Raw plan windows, when this backend reported any. */
+  readonly plan?: PlanUsage;
+  /** Always present — every backend gets a comparable headroom figure. */
+  readonly headroom: BackendHeadroom;
+  /** Why there is no `plan`. Absent when there is one. */
+  readonly note?: string;
+}
+
+/** The reason a backend has no plan windows to show. */
+function noteFor(id: string, headroom: BackendHeadroom): string {
+  const backend = getPooledBackend(id);
+  if (!backend) return "not running";
+  if (!backend.usage?.getPlanUsage) return "no plan limits on this backend";
+  if (headroom.source === "ledger") return "tracked against a local budget";
+  return "no usage information available";
+}
+
+/**
+ * Every exposed backend, in config order, with its plan (where it has one)
+ * and its headroom (always).
+ *
+ * `force` skips the 60s headroom cache — a person looking at `/usage` wants
+ * the number now, where a routing decision a second after another one does
+ * not.
+ */
+export async function collectBackendUsage(
+  config: TalonConfig | undefined,
+  options?: { force?: boolean },
+): Promise<BackendUsageSnapshot[]> {
+  const backends = listAvailableBackends(config);
+  return Promise.all(
+    backends.map(async ({ id, label }) => {
+      const headroom = await getBackendHeadroom(id, label, config, options);
+      if (headroom.plan && headroom.plan.windows.length > 0) {
+        return { id, label, headroom, plan: headroom.plan };
+      }
+      return { id, label, headroom, note: noteFor(id, headroom) };
+    }),
+  );
+}
+
+/**
+ * Reorder a snapshot list so one backend comes first, everything else
+ * keeping config order. The `plan_usage` tool leads with the chat's own
+ * backend so callers that only read the first entry see what they used to.
+ */
+export function leadWith(
+  entries: BackendUsageSnapshot[],
+  id: string,
+): BackendUsageSnapshot[] {
+  const index = entries.findIndex((e) => e.id === id);
+  if (index <= 0) return entries;
+  const lead = entries[index] as BackendUsageSnapshot;
+  return [lead, ...entries.filter((_, i) => i !== index)];
+}

package/src/core/engine/gateway-actions/agents/control.ts

@@ -208,7 +208,8 @@ export const agentControlHandlers: SharedActionHandlers = {
       ok: true,
       text:
         `Spawned agent "${parsed.label}" (id: ${outcome.agentId})\n` +
-        `Backend: ${outcome.backendId}/${outcome.model}\n` +
+        `Backend: ${outcome.backendId}/${outcome.model}` +
+        `${outcome.routing ? ` (routed: ${outcome.routing})` : ""}\n` +
         `Timeout: ${timeoutS}s\n` +
         `It runs in the background. You will be woken with its report — ` +
         `carry on with what you were doing.`,

package/src/core/engine/gateway-actions/models.ts

@@ -10,11 +10,33 @@ import {
   getBackendForChat,
   getBackendIdForChat,
   getAvailableBackends,
+  getPoolConfig,
   getPooledBackend,
   acquireBackendInstance,
 } from "../backend-controller/index.js";
+import {
+  collectBackendUsage,
+  formatHeadroom,
+  leadWith,
+  type BackendUsageSnapshot,
+} from "../backend-router/index.js";
 import type { SharedActionHandlers } from "./types.js";
 
+/** One `plan_usage` block: the headroom line, then any plan windows. */
+function usageLines(entry: BackendUsageSnapshot): string[] {
+  const head = `- ${entry.label || entry.id}: ${formatHeadroom(entry.headroom)}`;
+  if (!entry.plan) {
+    return [`${head}${entry.note ? ` (${entry.note})` : ""}`];
+  }
+  return [
+    `${head}${entry.plan.plan ? ` · ${entry.plan.plan}` : ""}`,
+    ...entry.plan.windows.map(
+      (w) =>
+        `    ${w.label}: ${w.percent}% used${w.resetsAt ? `, resets ${w.resetsAt}` : ""}`,
+    ),
+  ];
+}
+
 export const modelHandlers: SharedActionHandlers = {
   list_models: async (body, chatId, _backend, chatKey) => {
     const chatIdStr = chatKey;
@@ -98,52 +120,67 @@ export const modelHandlers: SharedActionHandlers = {
     }
   },
 
-  // Account-level, so it falls back to the pooled Claude backend when
-  // another provider is serving this chat.
+  // Account-level and fleet-wide: every exposed backend, with the headroom
+  // figure the plan-aware router ranks on — a backend with no usage API
+  // still answers, from its local budget ledger. The chat's own backend
+  // leads so a caller reading only the first entry sees what it used to.
   plan_usage: async (_body, chatId, _backend, chatKey) => {
-    const current = getPooledBackend(getBackendIdForChat(chatKey));
-    const source = current?.usage?.getPlanUsage
-      ? current
-      : getPooledBackend("claude");
-    if (!source?.usage?.getPlanUsage)
-      return {
-        ok: false,
-        error: "No configured backend reports subscription rate limits.",
-      };
-
-    const usage = await source.usage.getPlanUsage();
-    if (!usage)
-      return {
-        ok: false,
-        error:
-          "Plan usage is unavailable — no subscription credentials, or this session authenticates with an API key.",
-      };
-
-    const lines = usage.windows.map(
-      (w) =>
-        `- ${w.label}: ${w.percent}% used${w.resetsAt ? `, resets ${w.resetsAt}` : ""}`,
+    const currentId = getBackendIdForChat(chatKey);
+    const entries = leadWith(
+      await collectBackendUsage(getPoolConfig() ?? undefined, { force: true }),
+      currentId,
     );
+    if (entries.length === 0)
+      return { ok: false, error: "No backends are available." };
+
+    const lead = entries[0] as BackendUsageSnapshot;
     return {
       ok: true,
-      plan: usage.plan ?? null,
-      windows: usage.windows,
-      text: `Plan usage${usage.plan ? ` (${usage.plan})` : ""}:\n${lines.join("\n")}`,
+      // Kept for callers written against the single-backend shape.
+      plan: lead.plan?.plan ?? null,
+      windows: lead.plan?.windows ?? [],
+      backends: entries.map((entry) => ({
+        id: entry.id,
+        label: entry.label,
+        current: entry.id === currentId,
+        headroom: Math.round(entry.headroom.headroom * 100) / 100,
+        source: entry.headroom.source,
+        limiting: entry.headroom.limiting ?? null,
+        stale: entry.headroom.stale ?? false,
+        plan: entry.plan?.plan ?? null,
+        windows: entry.plan?.windows ?? [],
+        ...(entry.note ? { note: entry.note } : {}),
+      })),
+      text: `Plan usage and headroom by backend:\n${entries.flatMap(usageLines).join("\n")}`,
     };
   },
 
-  list_backends: (body, chatId, _backend, chatKey) => {
+  list_backends: async (body, chatId, _backend, chatKey) => {
     const currentId = getBackendIdForChat(chatKey);
-    const backends = getAvailableBackends().map((b) => ({
-      id: b.id,
-      label: b.label,
-      current: b.id === currentId,
-    }));
-    if (backends.length === 0)
+    const available = getAvailableBackends();
+    if (available.length === 0)
       return { ok: true, backends: [], text: "No backends are available." };
-    const lines = backends.map(
-      (b) =>
-        `- ${b.id}${b.label && b.label !== b.id ? ` (${b.label})` : ""}${b.current ? " — current" : ""}`,
-    );
+    // Headroom comes off the router's 60s cache, so listing backends is
+    // cheap even though it now answers "which one has room?" as well.
+    const usage = await collectBackendUsage(getPoolConfig() ?? undefined);
+    const byId = new Map(usage.map((entry) => [entry.id, entry]));
+    const backends = available.map((b) => {
+      const entry = byId.get(b.id);
+      return {
+        id: b.id,
+        label: b.label,
+        current: b.id === currentId,
+        headroom: entry
+          ? Math.round(entry.headroom.headroom * 100) / 100
+          : null,
+        headroomSource: entry?.headroom.source ?? null,
+      };
+    });
+    const lines = backends.map((b) => {
+      const entry = byId.get(b.id);
+      const room = entry ? ` — ${formatHeadroom(entry.headroom)} free` : "";
+      return `- ${b.id}${b.label && b.label !== b.id ? ` (${b.label})` : ""}${b.current ? " — current" : ""}${room}`;
+    });
     return {
       ok: true,
       backends,

package/src/core/tools/ops/models.ts

@@ -31,7 +31,7 @@ export const modelTools: ToolDefinition[] = [
   {
     name: "plan_usage",
     description:
-      "Read your own subscription usage: how much of the 5-hour, weekly, and per-model rate-limit windows is spent, and when each resets. Use it before starting long or expensive work, or when deciding whether to defer something. Only answers on a subscription-backed Anthropic backend; other providers report no plan limits.",
+      "Read usage and headroom for EVERY configured backend, not just this chat's: how much of each subscription's rate-limit windows is spent, when they reset, and one comparable headroom figure per backend. A backend with no usage API reports headroom from Talon's own local token ledger against its configured budget (marked 'local budget'), and one with neither says so. Use it before starting long or expensive work, when deciding whether to defer something, or to see which backend background work will be routed to.",
     schema: {},
     execute: (_params, bridge) => bridge("plan_usage", {}),
     tag: "models",
@@ -40,7 +40,7 @@ export const modelTools: ToolDefinition[] = [
   {
     name: "list_backends",
     description:
-      "List the available backends (providers) and which one this chat is currently using. Useful for understanding the model/provider landscape. Note: a per-job `model` override must stay on this chat's current backend, so use list_models (no argument) to pick a model for a trigger or cron job.",
+      "List the available backends (providers), which one this chat is currently using, and how much plan headroom each has left. Useful for understanding the model/provider landscape and for seeing where unpinned background work (sub-agents, cron query jobs, the heartbeat) will be routed. Note: a per-job `model` override must stay on this chat's current backend, so use list_models (no argument) to pick a model for a trigger or cron job.",
     schema: {},
     execute: (_params, bridge) => bridge("list_backends", {}),
     tag: "models",

package/src/frontend/presentation/plan-usage-report.ts

@@ -6,15 +6,21 @@
  * through whichever provider it fronts, and an API-key install pays per
  * token with no window to be near the end of. Those are listed with a
  * reason rather than omitted, so the answer to "am I close to a limit?" is
- * never silence.
+ * never silence — and since the plan-aware router landed they carry a
+ * headroom figure too, derived from a local token budget where one is
+ * configured, so "which backend has room?" is answerable for all of them.
+ *
+ * The gathering itself lives in core (`engine/backend-router/usage.ts`),
+ * because the gateway tools need the same data and core cannot import a
+ * frontend. This module is the rendering adapter over it.
  */
 
 import type { TalonConfig } from "../../core/config/index.js";
-import type { PlanUsage } from "../../core/agent-runtime/capabilities.js";
 import {
-  listAvailableBackends,
-  getPooledBackend,
-} from "../../core/engine/backend-controller/index.js";
+  collectBackendUsage,
+  formatHeadroom,
+  type BackendHeadroom,
+} from "../../core/engine/backend-router/index.js";
 import { buildPlanDisplay, type PlanDisplay } from "./status-context.js";
 
 export interface BackendUsageEntry {
@@ -24,6 +30,10 @@ export interface BackendUsageEntry {
   plan: PlanDisplay | null;
   /** Why there is nothing to show. Absent when `plan` is set. */
   note?: string;
+  /** Comparable "how much is left", present for every backend. */
+  headroom: BackendHeadroom;
+  /** One-line rendering of `headroom`, ready to print. */
+  headroomLabel: string;
 }
 
 /**
@@ -36,37 +46,18 @@ export interface BackendUsageEntry {
 export async function collectPlanUsage(
   config: TalonConfig,
 ): Promise<BackendUsageEntry[]> {
-  const entries: BackendUsageEntry[] = [];
-
-  for (const { id, label } of listAvailableBackends(config)) {
-    const backend = getPooledBackend(id);
-    if (!backend) {
-      entries.push({ id, label, plan: null, note: "not running" });
-      continue;
-    }
-    if (!backend.usage?.getPlanUsage) {
-      entries.push({
-        id,
-        label,
-        plan: null,
-        note: "no plan limits on this backend",
-      });
-      continue;
-    }
-
-    let usage: PlanUsage | undefined;
-    try {
-      usage = await backend.usage.getPlanUsage();
-    } catch {
-      usage = undefined;
-    }
-    const plan = buildPlanDisplay(usage);
-    entries.push(
-      plan
-        ? { id, label, plan }
-        : { id, label, plan: null, note: "no usage information available" },
-    );
-  }
-
-  return entries;
+  const snapshots = await collectBackendUsage(config, { force: true });
+  return snapshots.map((snapshot) => {
+    const plan = buildPlanDisplay(snapshot.plan);
+    return {
+      id: snapshot.id,
+      label: snapshot.label,
+      plan,
+      headroom: snapshot.headroom,
+      headroomLabel: formatHeadroom(snapshot.headroom),
+      ...(plan
+        ? {}
+        : { note: snapshot.note ?? "no usage information available" }),
+    };
+  });
 }

package/src/frontend/presentation/reports.ts

@@ -443,10 +443,14 @@ export function renderUsageMessage(
 
   for (const entry of entries) {
     const name = fmt.escape(entry.label || entry.id);
+    // Headroom is the one figure every backend can answer, so it goes on
+    // every block — including the ones with no plan windows to draw.
+    const headroom = `  ${fmt.bold("Headroom:")} ${fmt.escape(entry.headroomLabel)}`;
     if (!entry.plan) {
       lines.push(
         "",
         `${fmt.bold(name)} — ${fmt.italic(fmt.escape(entry.note ?? ""))}`,
+        headroom,
       );
       continue;
     }
@@ -454,7 +458,7 @@ export function renderUsageMessage(
       ? ` ${fmt.emphasis(`(${entry.plan.ageLabel})`)}`
       : "";
     const plan = entry.plan.plan ? ` · ${fmt.escape(entry.plan.plan)}` : "";
-    lines.push("", `${fmt.bold(name)}${plan}${age}`);
+    lines.push("", `${fmt.bold(name)}${plan}${age}`, headroom);
     if (entry.plan.resetsAvailable) {
       const n = entry.plan.resetsAvailable;
       const resets = `usage limit reset${n === 1 ? "" : "s"} available`;