feat(usage): the live footer warns about the Claude subscription wall

The Anthropic OAuth headers — unified 5h/7d utilisation, which window is
binding, the subscription status, the reset — were already captured from
every response into rateLimits, but only `/usage quota` ever showed them.
A Pro/Max user learned about the weekly or 5-hour wall when a turn
stalled. Now updateFooter looks up the active provider's snapshot and
appends footerQuotaSegment(snap): `⚠ 7d 8% · resets 14:05` once the
binding window is below 15% (FOOTER_WARN_FRACTION), or whenever the status
is anything but "allowed" (named, e.g. "allowed warning"); empty while
healthy, and always empty for providers that carry no such headers.
shortReset renders Anthropic's epoch-seconds reset as HH:MM today or
MM-DD HH:MM later, and leaves unwieldy raw values out of the footer.
No slow-lane retry loop — awareness only.

From the can1357/oh-my-pi study (session/anthropic-slow-mode.ts).

Author: hypnguyen1209

README.md

@@ -20,6 +20,8 @@ Folded from each message's `usage.cost`, which pi already computes. It survives
 
 When [`@pify/subagent`](https://github.com/pifydev/subagent), [`@pify/swarm`](https://github.com/pifydev/swarm) or [`@pify/workflow`](https://github.com/pifydev/workflow) run child agents, those children are separate in-memory sessions whose spend never reaches this branch — a session that delegates used to look cheaper than it was. Those packages now add every child message's cost to a process-wide tally, and the footer shows it as a separate ` · agents $0.12` beside the session's own figure (the `/usage` session block has the same line, with tokens). It is kept apart on purpose: the session numbers stay what the branch says, and the agents figure is what the delegation cost on top. The tally survives `/reload` and starts over with a new session.
 
+On a Claude subscription (OAuth Pro/Max) the footer also carries the wall you are approaching: the headers `/usage quota` reads were already captured on every response, but only that command showed them, so the weekly or 5-hour limit used to arrive as a stalled turn. Now a `⚠ 7d 8% · resets 14:05` segment appears once the binding window is below 15%, or whenever Anthropic marks the subscription as anything but allowed, and stays out of the way otherwise. Other providers carry no such headers, so they never show it.
+
 The gauge on the right is how full the context window is — the third mid-session question, next to tokens and cost. It was computed for the `/usage` dashboard but shown only there; now it is live. It appears once there is a window to measure against (so not under `-p`) and turns to `⚠` past 90%, the point where "how full" stops being trivia and becomes a decision. For the breakdown of what filled it, run `/context`.
 
 ## `/usage`

extensions/usage.ts

@@ -35,7 +35,7 @@ import { childSpendTotal, onChildSpend, resetChildSpend } from "../src/child-cos
 import { QUOTA_PROVIDERS, fetchQuota, quotaReport, type QuotaResult } from "../src/quota.ts";
 import { redact } from "../src/redact.ts";
 import { scanSessions } from "../src/sessions.ts";
-import { parseRateLimit, formatRateLimit, type RateLimitSnapshot } from "../src/ratelimit.ts";
+import { parseRateLimit, formatRateLimit, type RateLimitSnapshot, footerQuotaSegment } from "../src/ratelimit.ts";
 import { emptyTotals, isRecord, type UsageTotals } from "../src/types.ts";
 
 type UiContext = ExtensionContext;
@@ -83,7 +83,10 @@ export default function usage(pi: ExtensionAPI) {
       return;
     }
     const gauge = contextGauge(contextInfo(ctx).pct);
-    ctx.ui.setStatus("usage", gauge ? `${base} · ${gauge}` : base);
+    // The subscription wall, from the headers already captured for this
+    // provider: quiet while healthy, a short warning once it is close.
+    const quota = footerQuotaSegment(rateLimits.get((ctx.model as { provider?: string } | null)?.provider ?? ""));
+    ctx.ui.setStatus("usage", [base, gauge, quota].filter(Boolean).join(" · "));
   }
 
   /**

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/usage",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Token and cost reporting for pi sessions: live footer, local-history dashboard with per-project costs, opt-in provider quota",
   "keywords": [
     "pi-package",

src/ratelimit.ts

@@ -166,6 +166,46 @@ function formatReset(snap: RateLimitSnapshot): string {
   return raw;
 }
 
+/** A reset time short enough for the footer: HH:MM today, otherwise MM-DD HH:MM; "" when unknown or unwieldy. */
+export function shortReset(snap: RateLimitSnapshot, now: number = Date.now()): string {
+  const raw = snap.resets;
+  if (!raw) return "";
+  if (snap.source === "anthropic" && /^\d{9,}$/.test(raw)) {
+    const d = new Date(Number.parseInt(raw, 10) * 1000);
+    if (!Number.isFinite(d.getTime())) return "";
+    const hm = `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+    const sameDay = new Date(now).toDateString() === d.toDateString();
+    return sameDay ? hm : `${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")} ${hm}`;
+  }
+  return raw.length <= 12 ? raw : "";
+}
+
+/** Below this share of the binding window left, the footer starts warning. */
+export const FOOTER_WARN_FRACTION = 0.15;
+
+/**
+ * The footer's quota warning, or "" while the session is healthy. A Claude
+ * subscription user used to learn about the 5h/7d wall only when a turn
+ * stalled, or by opening `/usage quota` — the headers were captured either
+ * way. This shows the binding window once it is nearly gone, or whenever
+ * Anthropic marks the subscription as anything but "allowed". Non-Anthropic
+ * providers carry none of these fields, so it stays empty for them.
+ */
+export function footerQuotaSegment(snap: RateLimitSnapshot | null | undefined, now: number = Date.now()): string {
+  if (!snap) return "";
+  const binding =
+    snap.unifiedBinding ?? (snap.unified7dRemaining !== null ? "7d" : snap.unified5hRemaining !== null ? "5h" : null);
+  const remaining = binding === "7d" ? snap.unified7dRemaining : binding === "5h" ? snap.unified5hRemaining : null;
+  const walled = Boolean(snap.unifiedStatus && snap.unifiedStatus !== "allowed");
+  const low = remaining !== null && remaining < FOOTER_WARN_FRACTION;
+  if (!walled && !low) return "";
+  const parts = [`⚠ ${binding ?? "subscription"}`];
+  if (remaining !== null) parts.push(`${Math.max(0, Math.round(remaining * 100))}%`);
+  if (walled) parts.push(snap.unifiedStatus!.replace(/_/g, " "));
+  const reset = shortReset(snap, now);
+  return reset ? `${parts.join(" ")} · resets ${reset}` : parts.join(" ");
+}
+
 /** One human line for the /usage quota report; null when nothing was captured. */
 export function formatRateLimit(snap: RateLimitSnapshot | null): string | null {
   if (!snap) return null;

test/usage.test.ts

@@ -22,6 +22,7 @@ import {
   quotaReport,
 } from "../src/quota.ts";
 import { checkUrl, controlledGetJson } from "../src/http.ts";
+import { footerQuotaSegment, parseRateLimit, shortReset } from "../src/ratelimit.ts";
 import { redact } from "../src/redact.ts";
 import { emptyTotals, type UsageRecord } from "../src/types.ts";
 
@@ -449,3 +450,50 @@ test("footer and session block show what child agent sessions spent, apart from
   assert.match(block, /agents   \$0\.12 · 30\.0k tok in child sessions, on top of the above/);
   assert.ok(!sessionBlock(totals, null).includes("agents"));
 });
+
+test("the footer warns about the subscription wall only when it is close or the status is not allowed", () => {
+  const now = Date.UTC(2026, 8, 26, 10, 0, 0);
+  const at = (h: Record<string, string>) => parseRateLimit("anthropic", h, now);
+  // Healthy: plenty of both windows, status allowed → silence.
+  const healthy = at({
+    "anthropic-ratelimit-unified-5h-utilization": "0.2",
+    "anthropic-ratelimit-unified-7d-utilization": "0.4",
+    "anthropic-ratelimit-unified-representative-claim": "7d",
+    "anthropic-ratelimit-unified-status": "allowed",
+  });
+  assert.equal(footerQuotaSegment(healthy, now), "");
+  // The binding 7d window nearly gone → a short warning with its share left.
+  const low = at({
+    "anthropic-ratelimit-unified-5h-utilization": "0.2",
+    "anthropic-ratelimit-unified-7d-utilization": "0.92",
+    "anthropic-ratelimit-unified-representative-claim": "7d",
+    "anthropic-ratelimit-unified-status": "allowed",
+  });
+  assert.equal(footerQuotaSegment(low, now), "⚠ 7d 8%");
+  // A non-allowed status warns whatever the numbers say, and names it.
+  const walled = at({
+    "anthropic-ratelimit-unified-7d-utilization": "0.5",
+    "anthropic-ratelimit-unified-status": "allowed_warning",
+  });
+  assert.equal(footerQuotaSegment(walled, now), "⚠ 7d 50% allowed warning");
+  // Nothing captured, or another provider's snapshot, stays quiet.
+  assert.equal(footerQuotaSegment(null), "");
+  assert.equal(footerQuotaSegment(parseRateLimit("openai", { "x-ratelimit-remaining-requests": "5" }, now)), "");
+});
+
+test("shortReset renders Anthropic's epoch seconds compactly and leaves long values out of the footer", () => {
+  const now = Date.UTC(2026, 8, 26, 10, 0, 0);
+  const soon = parseRateLimit(
+    "anthropic",
+    { "anthropic-ratelimit-unified-7d-utilization": "0.9", "anthropic-ratelimit-unified-reset": String(Math.floor(now / 1000) + 3600) },
+    now,
+  )!;
+  assert.match(shortReset(soon, now), /^\d{2}:\d{2}$/);
+  const later = parseRateLimit(
+    "anthropic",
+    { "anthropic-ratelimit-unified-7d-utilization": "0.9", "anthropic-ratelimit-unified-reset": String(Math.floor(now / 1000) + 3 * 86400) },
+    now,
+  )!;
+  assert.match(shortReset(later, now), /^\d{2}-\d{2} \d{2}:\d{2}$/);
+  assert.match(footerQuotaSegment(soon, now), /^⚠ 7d 10% · resets \d{2}:\d{2}$/);
+});