omp-conductor 0.3.25 → 0.4.0

package/src/usage.ts

@@ -0,0 +1,726 @@
+/**
+ * The plan-allowance guard: a second economic control beside `dailySpendUsd`.
+ *
+ * `dailySpendUsd` meters money, which is the only thing an API-billed account
+ * can run out of. A fixed-price subscription cannot be expressed that way at
+ * all — the fleet this package was written for burns a *weekly token
+ * allowance* whose marginal dollar cost is zero and whose exhaustion stops
+ * every session on the host. Pricing that allowance to fit the dollar meter
+ * would mean inventing a number, and a ceiling built on an invented number is
+ * worse than no ceiling (#110).
+ *
+ * So the guard reads the provider's own figures — `omp usage --json`, which is
+ * the structured form of the harness `/usage` view — and normalises them into
+ * windows the admission gate compares. Three properties of the real payload
+ * shape every decision in this file, and each of them is a way an obvious
+ * implementation gets it wrong:
+ *
+ * - **`limits` is a list, not a scalar.** Anthropic alone reports
+ *   `anthropic:5h`, `anthropic:7d` and the tier-scoped `anthropic:7d:fable` in
+ *   one reply, and other providers add their own. A gate that read "the first
+ *   limit" would bind a config that meant the weekly window to whichever entry
+ *   the provider happened to serialise first, and would rebind itself silently
+ *   when that order changed. The cap therefore names its window.
+ * - **`unit` is not comparable across providers.** Anthropic reports
+ *   `unit: "percent"` with `used: 5`; `xai-oauth` reports `unit: "unknown"`
+ *   with `used: 4709` against a limit of 20000. A threshold compared against
+ *   `used` reads the second account as 4709% spent. Nothing here ever compares
+ *   a raw count: the only number the gate looks at is `usedFraction`.
+ * - **A source can legitimately report nothing.** A provider with no readable
+ *   allowance simply contributes no limits. That is the honest origin of
+ *   "unmetered/unavailable", and it is why no code path here manufactures a
+ *   zero to fill the gap: a fabricated `0% used` renders as a guard that is
+ *   working when it is in fact blind.
+ *
+ * Availability policy — which way each failure falls — is decided in
+ * {@link planUsageStatus} and documented beside it.
+ */
+
+import type { PlanUsageCap } from "./types.ts";
+
+/** Bounded so a wedged provider call cannot hold a dispatch tick open. A warm
+ *  `omp usage --json` answers in well under a second; this leaves room for a
+ *  cold fetch across several provider endpoints without becoming a stall. */
+export const USAGE_PROBE_TIMEOUT_MS = 15_000;
+
+/** How long one reading serves every caller. One admission pass asks the gate
+ *  once, but `status` and `board` re-render far faster than any allowance
+ *  moves, so the provider is asked at most once a minute per process. */
+export const USAGE_TTL_MS = 60_000;
+
+/** A failed read is retried sooner than a good one is refreshed. The guard is
+ *  open while the source is unreadable (see below), so sitting on a stale
+ *  failure keeps the fleet unguarded for longer than the failure lasted. */
+export const USAGE_ERROR_TTL_MS = 15_000;
+
+/**
+ * How long an unreadable source is tolerated before the guard stops claiming.
+ *
+ * This is the whole of the "which way does it fail" question. A short outage —
+ * a token refresh, a provider 502, `omp` briefly absent mid-upgrade — must not
+ * stall a fleet: the other ceilings (spend, turns, wall clock, concurrency)
+ * are all still enforced, so admitting through a blip costs at most one extra
+ * worker. A source that has been unreadable for half an hour is not an outage,
+ * it is a broken meter, and running a plan-capped fleet on a broken meter is
+ * exactly how the allowance gets spent to zero with nobody watching.
+ */
+export const USAGE_BLIND_GRACE_MS = 30 * 60_000;
+
+/** Past this age a rendered reading says how old it is. Anything an operator
+ *  reads as current has to actually be current — a stale figure presented as
+ *  live is the dishonesty this guard was specified to avoid. */
+export const USAGE_STALE_MS = 10 * 60_000;
+
+/** Bound on how many allowance ids an error message lists back at an operator. */
+const NAMED_WINDOW_LIMIT = 12;
+
+/**
+ * One allowance window, normalised away from any single provider's shape.
+ *
+ * `id` is the primary key and `windowId` deliberately is not: `anthropic:7d`
+ * and `anthropic:7d:fable` share the window key `7d` and are different
+ * allowances with different numbers.
+ */
+export interface UsageWindow {
+  /** Fully-qualified allowance id, unique within a reading (`anthropic:7d`). */
+  id: string;
+  provider: string;
+  /** Provider-scoped window key (`7d`, `1mo`). Not unique — see above. */
+  windowId?: string;
+  /** The provider's own name for the window, for display only. */
+  label?: string;
+  used: number;
+  limit?: number;
+  remaining?: number;
+  /**
+   * Consumed share of the allowance. The only figure the gate compares, and
+   * absent when the provider gave nothing a fraction can be derived from —
+   * which is a state the guard reports rather than papers over.
+   */
+  usedFraction?: number;
+  remainingFraction?: number;
+  /** The provider's word for the counts (`percent`, `unknown`). Display only:
+   *  treating it as a scale is the bug this field exists to warn about. */
+  unit: string;
+  /** Derived from the provider's reset instant and window length when both are
+   *  reported; the payload carries no explicit start. */
+  windowStart?: number;
+  /** The provider's own reset instant. Never a locally assumed calendar week:
+   *  a weekly plan resets on the account's clock, not on Monday. */
+  resetsAt?: number;
+  /** Per-limit health the provider attached. Carried and displayed, never
+   *  turned into arithmetic — the vocabulary is the provider's, not ours. */
+  status?: string;
+  /** When the provider fetched this figure (its `fetchedAt`, not our clock). */
+  observedAt: number;
+}
+
+/**
+ * One reading of the whole source.
+ *
+ * `ok` carries at least one window by construction: a payload that parsed but
+ * yielded no allowances is `unavailable`, because "nothing is metered" and
+ * "the meter is fine and reads zero" are different facts and only one of them
+ * may be displayed as a percentage.
+ */
+export type UsageReading =
+  | { kind: "ok"; observedAt: number; windows: UsageWindow[] }
+  | {
+      kind: "unavailable";
+      observedAt: number;
+      /** Operator-facing cause, already bounded for a status line. */
+      reason: string;
+      /**
+       * Start of the current unbroken run of unreadable results. A single
+       * failure and a fortnight of failures are the same object otherwise, and
+       * the grace period in {@link USAGE_BLIND_GRACE_MS} needs to tell them
+       * apart.
+       */
+      since: number;
+    };
+
+/**
+ * A source of readings. The one contract that matters: `read` never throws. An
+ * unreadable provider is a *reading* the caller applies policy to, not an
+ * exception that aborts a dispatch tick.
+ */
+export interface UsageProvider {
+  read(now: number): Promise<UsageReading>;
+}
+
+/** A provider with a cache in front of it. */
+export interface UsageSource {
+  read(now?: number): Promise<UsageReading>;
+  /** Drop the cached reading so the next `read` asks the provider. The
+   *  operator-facing half of the same idea is `omp usage invalidate`. */
+  invalidate(): void;
+}
+
+// ------------------------------------------------------------------ normalising
+
+function asObject(v: unknown): Record<string, unknown> | undefined {
+  return typeof v === "object" && v !== null && !Array.isArray(v)
+    ? (v as Record<string, unknown>)
+    : undefined;
+}
+
+function asNumber(v: unknown): number | undefined {
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+function asString(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+/**
+ * The single place a threshold-comparable number is produced.
+ *
+ * Preference order is deliberate. `usedFraction` is what the provider itself
+ * computed. `remainingFraction` is the same statement inverted. `used/limit`
+ * is our own arithmetic and only valid when the limit is a positive count — a
+ * limit of `0` divides to `Infinity`/`NaN`, which would render as a plausible
+ * percentage and hold a fleet on nonsense.
+ */
+function usedFractionOf(amount: Record<string, unknown>): number | undefined {
+  const direct = asNumber(amount["usedFraction"]);
+  if (direct !== undefined) return direct;
+  const remaining = asNumber(amount["remainingFraction"]);
+  if (remaining !== undefined) return 1 - remaining;
+  const used = asNumber(amount["used"]);
+  const limit = asNumber(amount["limit"]);
+  if (used !== undefined && limit !== undefined && limit > 0) return used / limit;
+  return undefined;
+}
+
+/**
+ * `omp usage --json` → normalised windows.
+ *
+ * Pure and exported so the traps in the real payload can be pinned without a
+ * provider on the machine running the tests. Unrecognisable input is never
+ * partially believed: it becomes `unavailable` with a reason an operator can
+ * act on.
+ */
+export function normalizeUsagePayload(payload: unknown, observedAt: number): UsageReading {
+  const root = asObject(payload);
+  const reports = root?.["reports"];
+  if (root === undefined || !Array.isArray(reports)) {
+    return {
+      kind: "unavailable",
+      observedAt,
+      reason: "usage payload has no reports array",
+      since: observedAt,
+    };
+  }
+
+  const windows: UsageWindow[] = [];
+  reports.forEach((entry: unknown, reportIndex) => {
+    const report = asObject(entry);
+    if (report === undefined) return;
+    const provider = asString(report["provider"]) ?? "unknown";
+    const fetchedAt = asNumber(report["fetchedAt"]) ?? observedAt;
+    const limits = report["limits"];
+    // A provider that contributes no limits is not an error. It is the
+    // ordinary shape of "this account exposes no readable allowance", and it
+    // must reach the caller as absence rather than as a zero.
+    if (!Array.isArray(limits)) return;
+
+    limits.forEach((limitEntry: unknown, limitIndex) => {
+      const limit = asObject(limitEntry);
+      const amount = asObject(limit?.["amount"]);
+      if (limit === undefined || amount === undefined) return;
+      const scope = asObject(limit["scope"]);
+      const window = asObject(limit["window"]);
+      const windowId = asString(scope?.["windowId"]) ?? asString(window?.["id"]);
+      const resetsAt = asNumber(window?.["resetsAt"]);
+      const durationMs = asNumber(window?.["durationMs"]);
+      const normalized: UsageWindow = {
+        // Synthesised only as a last resort, and deterministically: a window
+        // nothing can name is a window a config can never select.
+        id: asString(limit["id"]) ?? `${provider}:${windowId ?? String(reportIndex)}.${String(limitIndex)}`,
+        provider,
+        unit: asString(amount["unit"]) ?? "unknown",
+        used: asNumber(amount["used"]) ?? 0,
+        observedAt: fetchedAt,
+      };
+      if (windowId !== undefined) normalized.windowId = windowId;
+      const label = asString(limit["label"]) ?? asString(window?.["label"]);
+      if (label !== undefined) normalized.label = label;
+      const limitAmount = asNumber(amount["limit"]);
+      if (limitAmount !== undefined) normalized.limit = limitAmount;
+      const remaining = asNumber(amount["remaining"]);
+      if (remaining !== undefined) normalized.remaining = remaining;
+      const usedFraction = usedFractionOf(amount);
+      if (usedFraction !== undefined) normalized.usedFraction = usedFraction;
+      const remainingFraction = asNumber(amount["remainingFraction"]);
+      if (remainingFraction !== undefined) normalized.remainingFraction = remainingFraction;
+      if (resetsAt !== undefined) normalized.resetsAt = resetsAt;
+      if (resetsAt !== undefined && durationMs !== undefined) {
+        normalized.windowStart = resetsAt - durationMs;
+      }
+      const status = asString(limit["status"]);
+      if (status !== undefined) normalized.status = status;
+      windows.push(normalized);
+    });
+  });
+
+  if (windows.length === 0) {
+    return {
+      kind: "unavailable",
+      observedAt,
+      reason: "no provider reported a readable allowance",
+      since: observedAt,
+    };
+  }
+  return { kind: "ok", observedAt, windows };
+}
+
+// -------------------------------------------------------------------- adapters
+
+export type UsageCommandResult =
+  | { kind: "completed"; exitCode: number; stdout: string; stderr: string }
+  | { kind: "timeout" }
+  | { kind: "unavailable"; reason: string };
+
+async function runOmpUsage(timeoutMs: number): Promise<UsageCommandResult> {
+  try {
+    const proc = Bun.spawn(["omp", "usage", "--json"], {
+      // Closed stdin: a command that never reads it sees EOF instead of an
+      // open pipe nobody ends.
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      proc.kill("SIGKILL");
+    }, timeoutMs);
+    try {
+      const [exitCode, stdout, stderr] = await Promise.all([
+        proc.exited,
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+      ]);
+      if (timedOut) return { kind: "timeout" };
+      return { kind: "completed", exitCode, stdout, stderr };
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch (err) {
+    // `omp` missing from PATH lands here, and it is a perfectly ordinary state
+    // for a conductor CLI invoked from a bare shell.
+    return { kind: "unavailable", reason: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/** Bounded so a provider that dumps a stack trace cannot own the status line. */
+function firstLine(text: string, max = 120): string {
+  const line = text.replace(/\s+/g, " ").trim();
+  return line.length > max ? `${line.slice(0, max - 1)}…` : line;
+}
+
+/**
+ * The first adapter: `omp usage --json`.
+ *
+ * The command is injectable because every interesting case — a non-zero exit,
+ * a truncated stdout, a provider that reports three windows for one account —
+ * has to be pinned without the machine running the tests owning a
+ * subscription.
+ */
+export function ompUsageProvider(
+  run: (timeoutMs: number) => Promise<UsageCommandResult> = runOmpUsage,
+  timeoutMs = USAGE_PROBE_TIMEOUT_MS,
+): UsageProvider {
+  return {
+    async read(now: number): Promise<UsageReading> {
+      const result = await run(timeoutMs);
+      if (result.kind === "timeout") {
+        return {
+          kind: "unavailable",
+          observedAt: now,
+          reason: `omp usage --json did not answer within ${String(Math.round(timeoutMs / 1000))}s`,
+          since: now,
+        };
+      }
+      if (result.kind === "unavailable") {
+        return {
+          kind: "unavailable",
+          observedAt: now,
+          reason: `omp usage --json could not run: ${firstLine(result.reason)}`,
+          since: now,
+        };
+      }
+      if (result.exitCode !== 0) {
+        const detail = firstLine(result.stderr);
+        return {
+          kind: "unavailable",
+          observedAt: now,
+          reason: `omp usage --json exited ${String(result.exitCode)}${detail === "" ? "" : `: ${detail}`}`,
+          since: now,
+        };
+      }
+      let payload: unknown;
+      try {
+        payload = JSON.parse(result.stdout);
+      } catch (err) {
+        return {
+          kind: "unavailable",
+          observedAt: now,
+          reason: `omp usage --json returned unparseable output: ${firstLine(err instanceof Error ? err.message : String(err))}`,
+          since: now,
+        };
+      }
+      return normalizeUsagePayload(payload, now);
+    },
+  };
+}
+
+// ----------------------------------------------------------------------- cache
+
+/**
+ * TTL cache with explicit invalidation, plus one rule the TTL alone cannot
+ * express: a reading whose window has already reset is stale regardless of its
+ * age. That is what makes "admission resumes once the allowance rolls over"
+ * true at the rollover rather than up to a TTL after it.
+ *
+ * Concurrent callers share one in-flight request. An admission pass and a
+ * board repaint landing in the same second must cost one provider call, not
+ * two — "do not make every candidate trigger a provider request" is an
+ * acceptance criterion of #110, not an optimisation.
+ */
+export function cacheUsage(
+  provider: UsageProvider,
+  opts: { ttlMs?: number; errorTtlMs?: number } = {},
+): UsageSource {
+  const ttlMs = opts.ttlMs ?? USAGE_TTL_MS;
+  const errorTtlMs = opts.errorTtlMs ?? USAGE_ERROR_TTL_MS;
+  let cached: UsageReading | undefined;
+  let inFlight: Promise<UsageReading> | undefined;
+  let unreadableSince: number | undefined;
+
+  const usable = (reading: UsageReading, now: number): boolean => {
+    const ttl = reading.kind === "ok" ? ttlMs : errorTtlMs;
+    if (now - reading.observedAt >= ttl) return false;
+    if (reading.kind === "ok") {
+      return !reading.windows.some((w) => w.resetsAt !== undefined && w.resetsAt <= now);
+    }
+    return true;
+  };
+
+  return {
+    async read(now = Date.now()): Promise<UsageReading> {
+      if (cached !== undefined && usable(cached, now)) return cached;
+      inFlight ??= provider
+        .read(now)
+        .catch(
+          (err: unknown): UsageReading => ({
+            kind: "unavailable",
+            observedAt: now,
+            // The provider contract says it never throws. If one ever does,
+            // the tick still has to survive it as data.
+            reason: `usage provider threw: ${firstLine(err instanceof Error ? err.message : String(err))}`,
+            since: now,
+          }),
+        )
+        .then((reading) => {
+          if (reading.kind === "unavailable") {
+            unreadableSince ??= reading.since;
+            cached = { ...reading, since: unreadableSince };
+          } else {
+            unreadableSince = undefined;
+            cached = reading;
+          }
+          return cached;
+        })
+        .finally(() => {
+          inFlight = undefined;
+        });
+      return inFlight;
+    },
+    invalidate(): void {
+      cached = undefined;
+      // The unreadable streak deliberately survives. An operator asking for a
+      // re-read has not repaired anything, and forgetting how long the meter
+      // has been broken is how a permanently blind guard stays open forever.
+    },
+  };
+}
+
+let shared: UsageSource | undefined;
+
+/** One cache per process. `status`, `board` and the dispatch tick all want the
+ *  same reading, and three caches would mean three provider calls. */
+export function sharedUsageSource(): UsageSource {
+  shared ??= cacheUsage(ompUsageProvider());
+  return shared;
+}
+
+// -------------------------------------------------------------------- decision
+
+/**
+ * Every distinguishable answer the guard can give. They exist separately
+ * because each one sends an operator somewhere different: `at-cap` is normal
+ * flow control, `window-missing` is a config edit, `blind` is a broken host.
+ * Collapsing them into a boolean is how "the fleet is not claiming" becomes
+ * unexplainable.
+ */
+export type PlanUsageState =
+  | "unmetered"
+  | "ok"
+  | "at-cap"
+  | "window-missing"
+  | "window-ambiguous"
+  | "window-uncomparable"
+  | "unreadable"
+  | "blind";
+
+export interface PlanUsageStatus {
+  state: PlanUsageState;
+  /**
+   * Whether new claims are held. Stated once, here, so no renderer and no gate
+   * re-derives the availability policy and disagrees with the other.
+   */
+  blocking: boolean;
+  cap?: PlanUsageCap;
+  window?: UsageWindow;
+  /** Present only when a real figure was read. Never a filled-in zero. */
+  usedFraction?: number;
+  resetsAt?: number;
+  /** When the underlying reading was taken. */
+  observedAt?: number;
+  /** The operator-facing sentence `status` and `board` render verbatim. */
+  detail: string;
+}
+
+/** Where a configured window id landed in a reading. */
+export type WindowSelection =
+  | { kind: "found"; window: UsageWindow }
+  | { kind: "missing"; available: string[] }
+  | { kind: "ambiguous"; candidates: string[] };
+
+/**
+ * Resolve a configured window id against a reading.
+ *
+ * Exact `id` first, because that is the only unique key the payload has. A
+ * bare window key (`7d`) is accepted as a convenience, but *only* when it
+ * resolves to exactly one allowance: on an Anthropic account `7d` matches both
+ * `anthropic:7d` and the tier-scoped `anthropic:7d:fable`, and picking either
+ * is the silent binding this guard was specified to refuse.
+ */
+export function selectUsageWindow(
+  windows: readonly UsageWindow[],
+  windowId: string,
+): WindowSelection {
+  const exact = windows.filter((w) => w.id === windowId);
+  if (exact.length === 1) return { kind: "found", window: exact[0]! };
+  if (exact.length > 1) return { kind: "ambiguous", candidates: exact.map((w) => w.id) };
+
+  const byWindow = windows.filter((w) => w.windowId === windowId);
+  if (byWindow.length === 1) return { kind: "found", window: byWindow[0]! };
+  if (byWindow.length > 1) return { kind: "ambiguous", candidates: byWindow.map((w) => w.id) };
+
+  return { kind: "missing", available: windows.slice(0, NAMED_WINDOW_LIMIT).map((w) => w.id) };
+}
+
+function percent(fraction: number): string {
+  const whole = Math.round(fraction * 100);
+  // A live reading of 0.4% must not render as `0%`: that is character-for-
+  // character the fabricated zero this guard refuses to display (#110).
+  if (whole === 0 && fraction > 0) return "<1%";
+  return `${String(whole)}%`;
+}
+
+function duration(ms: number): string {
+  const minutes = Math.max(0, Math.floor(ms / 60_000));
+  if (minutes < 1) return "<1m";
+  if (minutes < 60) return `${String(minutes)}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${String(hours)}h ${String(minutes % 60)}m`;
+  return `${String(Math.floor(hours / 24))}d ${String(hours % 24)}h`;
+}
+
+function resetsText(resetsAt: number | undefined, now: number): string {
+  if (resetsAt === undefined) return "no reset time reported";
+  return resetsAt <= now ? "resetting now" : `resets in ${duration(resetsAt - now)}`;
+}
+
+/** Appended only when the figure is old enough that calling it current would
+ *  be a lie. Silence below the threshold keeps the common line short. */
+function ageSuffix(observedAt: number, now: number): string {
+  const age = now - observedAt;
+  return age >= USAGE_STALE_MS ? ` · stale, read ${duration(age)} ago` : "";
+}
+
+function unmeteredStatus(): PlanUsageStatus {
+  return {
+    state: "unmetered",
+    blocking: false,
+    detail: "unmetered — no plan allowance cap configured",
+  };
+}
+
+/**
+ * The whole availability policy, in one pure function.
+ *
+ * | state | holds new claims | why |
+ * | --- | --- | --- |
+ * | `unmetered` | no | the operator did not ask for this guard |
+ * | `ok` | no | below the threshold |
+ * | `at-cap` | **yes** | the guard doing its job |
+ * | `window-missing` | **yes** | fail closed on config, like the rest of this package |
+ * | `window-ambiguous` | **yes** | as above; never guess which allowance was meant |
+ * | `window-uncomparable` | **yes** | the window exists and cannot be compared |
+ * | `unreadable` | no | a transient read error must not stall a fleet |
+ * | `blind` | **yes** | unreadable for longer than {@link USAGE_BLIND_GRACE_MS} |
+ *
+ * The split that matters is between the last two rows and the config rows. A
+ * *read error* is transient by nature, so it is tolerated for a bounded time
+ * and then stops being tolerated. A *successful read that does not contain the
+ * configured window* is not a read error: the source answered, and it says the
+ * operator named something that is not there. That is a config fault, and this
+ * package fails closed on config faults everywhere else (see
+ * `normalizeAuthority` in `config.ts`). It recovers by itself the moment a
+ * reading contains the window again, so one bad tick costs one tick.
+ */
+export function planUsageStatus(
+  cap: PlanUsageCap | null,
+  reading: UsageReading,
+  now: number,
+  graceMs = USAGE_BLIND_GRACE_MS,
+): PlanUsageStatus {
+  if (cap === null) return unmeteredStatus();
+
+  if (reading.kind === "unavailable") {
+    const blindFor = now - reading.since;
+    if (blindFor >= graceMs) {
+      return {
+        state: "blind",
+        blocking: true,
+        cap,
+        observedAt: reading.observedAt,
+        detail: `unavailable for ${duration(blindFor)} — ${reading.reason}; holding new claims`,
+      };
+    }
+    return {
+      state: "unreadable",
+      blocking: false,
+      cap,
+      observedAt: reading.observedAt,
+      detail: `unavailable — ${reading.reason}; retrying, guard open for up to ${duration(graceMs - blindFor)}`,
+    };
+  }
+
+  const selection = selectUsageWindow(reading.windows, cap.windowId);
+  if (selection.kind === "missing") {
+    return {
+      state: "window-missing",
+      blocking: true,
+      cap,
+      observedAt: reading.observedAt,
+      detail:
+        `window "${cap.windowId}" is not in this reading — holding new claims. ` +
+        `Reported: ${selection.available.join(", ")}`,
+    };
+  }
+  if (selection.kind === "ambiguous") {
+    return {
+      state: "window-ambiguous",
+      blocking: true,
+      cap,
+      observedAt: reading.observedAt,
+      detail:
+        `window "${cap.windowId}" matches ${selection.candidates.join(", ")} — ` +
+        "holding new claims until the cap names exactly one",
+    };
+  }
+
+  const window = selection.window;
+  const threshold = percent(cap.maxUsedFraction);
+  if (window.usedFraction === undefined) {
+    return {
+      state: "window-uncomparable",
+      blocking: true,
+      cap,
+      window,
+      observedAt: window.observedAt,
+      detail:
+        `window "${window.id}" reports no comparable fraction ` +
+        `(unit ${window.unit}, used ${String(window.used)}, limit ${window.limit === undefined ? "unreported" : String(window.limit)}) — ` +
+        "holding new claims",
+    };
+  }
+
+  const used = percent(window.usedFraction);
+  const statusNote = window.status === undefined || window.status === "ok" ? "" : ` · ${window.status}`;
+  const base: PlanUsageStatus = {
+    state: window.usedFraction >= cap.maxUsedFraction ? "at-cap" : "ok",
+    blocking: window.usedFraction >= cap.maxUsedFraction,
+    cap,
+    window,
+    usedFraction: window.usedFraction,
+    observedAt: window.observedAt,
+    detail: "",
+  };
+  if (window.resetsAt !== undefined) base.resetsAt = window.resetsAt;
+  base.detail =
+    base.state === "at-cap"
+      ? `${used} / ${threshold} of ${window.id} used — holding new claims · ${resetsText(window.resetsAt, now)}${statusNote}${ageSuffix(window.observedAt, now)}`
+      : `${used} / ${threshold} of ${window.id} used · ${resetsText(window.resetsAt, now)}${statusNote}${ageSuffix(window.observedAt, now)}`;
+  return base;
+}
+
+/**
+ * Read and decide in one call. An unmetered project never spawns the provider:
+ * a fleet that does not use this guard must not pay a subprocess for it every
+ * time somebody runs `status`.
+ */
+export async function readPlanUsage(
+  cap: PlanUsageCap | null,
+  source: UsageSource,
+  now = Date.now(),
+): Promise<PlanUsageStatus> {
+  if (cap === null) return unmeteredStatus();
+  return planUsageStatus(cap, await source.read(now), now);
+}
+
+/**
+ * The compact form for the board's admission line, where the whole fleet has
+ * to fit on one row. Derived from the same status object as the long form so
+ * the two cannot disagree about whether the guard is active.
+ */
+export function planUsageBadge(status: PlanUsageStatus | undefined): string {
+  if (status === undefined) return "plan not read";
+  let core: string;
+  switch (status.state) {
+    case "unmetered":
+      core = "plan unmetered";
+      break;
+    case "ok":
+    case "at-cap":
+      // No `?? 0` fallback anywhere on this path. Both fields are always set
+      // in these two states, and a default would put the one number this
+      // guard must never invent — a zero — on an operator's screen (#110).
+      core =
+        status.usedFraction === undefined || status.cap === undefined
+          ? "plan read incomplete"
+          : `plan ${percent(status.usedFraction)}/${percent(status.cap.maxUsedFraction)}`;
+      break;
+    case "unreadable":
+    case "blind":
+      core = "plan unavailable";
+      break;
+    default:
+      // Every remaining state is "the configured window did not resolve", and
+      // naming it is the point: an operator who sees `plan unmetered` when
+      // they configured a cap will not go looking for a typo.
+      core = `plan window "${status.cap?.windowId ?? "?"}" ${status.state.replace("window-", "")}`;
+      break;
+  }
+  return status.blocking ? `${core} · HELD` : core;
+}
+
+/** The long form for `status`. Absent means nobody read the source on this
+ *  path, which is its own honest answer and not "0% used". */
+export function planUsageLine(status: PlanUsageStatus | undefined): string {
+  return status?.detail ?? "not read";
+}