@pify/usage 0.8.0 → 0.9.0

package/README.md

@@ -40,7 +40,7 @@ By project (all time)
   D--project-shop-api       $6.60 · 3.6M tok
 ```
 
-History counts every usage-bearing entry in pi's session JSONL — assistant turns plus the tool-result and compaction usage pi persists — so a session's total matches what you were billed rather than what the visible messages add up to. Negative and NaN fields clamp to zero, days are your **local** calendar days, and a per-file mtime cache keeps repeat scans instant.
+History counts every usage-bearing entry in pi's session JSONL — assistant turns plus the tool-result usage pi persists, and the summariser's own call, which pi records on the compaction and branch-summary entries themselves rather than on a message. Those summary calls are among the most expensive in a session, so counting them is what makes a session's total match what you were billed rather than what the visible messages add up to; they have no model of their own, so they group under a `compaction` / `branch_summary` label in the by-model view. The live footer and session totals fold the same summariser usage in as it happens (on compaction and tree navigation), so the number does not jump only after a reload. Negative and NaN fields clamp to zero, days are your **local** calendar days, and a per-file mtime cache keeps repeat scans instant.
 
 Per-project totals come for free: pi stores sessions one directory per project, so the dashboard can show where the money actually went.
 
@@ -60,7 +60,11 @@ Context window: 22.6k of 200.0k used (11%)
 
 Computed entirely from what pi already holds: the assembled system prompt, the files and skills embedded in it, the enabled tool definitions, and the entries that would be sent. No network, no model call.
 
-Context files and skills are counted only when their text is genuinely embedded in the prompt, and the system-prompt row is the remainder after subtracting them, so the rows sum to the whole instead of double-counting. When the provider reports more than can be attributed, the difference is shown as **Other** rather than quietly dropped.
+Context files and skills are counted only when their text is genuinely embedded in the prompt, and the system-prompt row is the remainder after subtracting them, so the rows sum to the whole instead of double-counting. When the provider reports more than can be attributed, the difference is shown as **Other** rather than quietly dropped. Image blocks (a `read` of a screenshot, a pasted image) are charged at pi's flat 4,800 chars each, not at the size of their base64 bytes, so one screenshot no longer reads as hundreds of thousands of tokens.
+
+The "used" figure and the footer gauge are reconciled across three signals — pi's own `getContextUsage()` reading, the provider's last-request report, and the local content estimate — so a backend that reports a wrong number (a cumulative or cache-inflated total, or an implausibly small one) can't throw the gauge off: the provider's report is used when it agrees with pi's percent×window, pi's reading is trusted when they diverge beyond tolerance, and the figure is never allowed below the tokens visibly in context, nor above the window. The provider figure uses pi's own definition of context size — `totalTokens`, or `input + output + cacheRead + cacheWrite` — so it agrees with pi's footer rather than sitting low by the cache-write and output of each turn. (The reconciliation rule is from minuque/pi-cc-extensions.)
+
+Right after `/compact`, pi reports the context as unknown until the next response, and the gauge follows: the pre-compaction figure is dropped so `/context` shows the fresh local estimate instead of the old near-full number, and the gauge reappears once the next reply lands.
 
 Reasoning gets its own **Thinking** row rather than hiding inside Conversation — on keep-thinking models it is a large, otherwise-invisible share (the opaque signature bytes are never counted or stored). And when pi's auto-compaction is on, the tokens it holds back appear as a **Compaction reserve** row and are subtracted from **Free space**, so the headroom shown is what you can actually use before compaction fires.
 
@@ -79,7 +83,7 @@ Quota (DeepSeek · granted 10 · topped up 100)
 
 **Documented endpoints only.** OpenRouter's `/api/v1/key` and DeepSeek's `/user/balance` are published APIs that report a real balance. The subscription-quota endpoints available for some other providers are undocumented private APIs reverse-engineered from vendor CLIs — they break without notice and were never offered to third parties, so this package does not call them. A provider you have not configured is simply not shown; that is not a failure.
 
-**Rate limits, for free.** OpenAI, Anthropic and Gemini publish no balance API, but every completion response carries rate-limit headers, and pi hands them to extensions through `after_provider_response` — before the stream is read, at no cost when unsubscribed. So `/usage quota` also shows what the current provider reported on its last call — requests and tokens left in the window, and for an Anthropic OAuth subscription the unified-window percentage — captured passively from calls the session already made, with no extra request and no credential to handle.
+**Rate limits, for free.** OpenAI, Anthropic and Gemini publish no balance API, but every completion response carries rate-limit headers, and pi hands them to extensions through `after_provider_response` — before the stream is read, at no cost when unsubscribed. So `/usage quota` also shows what the current provider reported on its last call — requests and tokens left in the window, and for an Anthropic OAuth (Pro/Max) subscription the two unified windows it actually reports: the fraction of the 5-hour and 7-day windows still free (from the `-5h-utilization` / `-7d-utilization` headers, which state the fraction *used*), which of the two is currently binding, an `allowed_warning` / `rejected` status when the window is under pressure, and the reset time. All captured passively from calls the session already made, with no extra request and no credential to handle.
 
 **A credentialed request is pinned down**, because it carries your provider key:
 
@@ -95,7 +99,7 @@ Quota (DeepSeek · granted 10 · topped up 100)
 
 ### `usage_status`
 
-No parameters. Returns session and today's totals, so the agent can check the cost before committing to expensive work — a wide subagent fan-out, a large read — instead of finding out afterwards.
+No parameters. Returns session and today's totals plus how full the context window is (`~N% of the … window used`, with a `/compact` hint past 80%), so the agent can check both cost and remaining room before committing to expensive work — a wide subagent fan-out, a large read — instead of finding out afterwards.
 
 ## License
 

package/extensions/usage.ts

@@ -29,7 +29,7 @@ import { join } from "node:path";
 import { readFileSync } from "node:fs";
 
 import { addRecord, aggregate, recordFromEntry, windowTotals } from "../src/aggregate.ts";
-import { buildBreakdown, formatBreakdown } from "../src/context.ts";
+import { buildBreakdown, contextTokensFromUsage, formatBreakdown, resolveUsedTokens } from "../src/context.ts";
 import { contextGauge, footerText, formatCost, formatTokens, historyBlock, sessionBlock } from "../src/format.ts";
 import { QUOTA_PROVIDERS, fetchQuota, quotaReport, type QuotaResult } from "../src/quota.ts";
 import { redact } from "../src/redact.ts";
@@ -41,7 +41,12 @@ type UiContext = ExtensionContext;
 
 export default function usage(pi: ExtensionAPI) {
   let session: UsageTotals = emptyTotals();
-  /** input+cacheRead of the most recent assistant message ≈ context size. */
+  /**
+   * The most recent assistant turn's context size, via pi's own
+   * calculateContextTokens (totalTokens, or input+output+cacheRead+cacheWrite).
+   * Cleared on compaction until the next post-compaction response, matching
+   * what pi's getContextUsage reports.
+   */
   let lastPromptTokens = 0;
   /**
    * The latest rate-limit headers seen per provider — passive quota, captured
@@ -68,14 +73,31 @@ export default function usage(pi: ExtensionAPI) {
       ctx.ui.setStatus("usage", undefined);
       return;
     }
-    const gauge = contextGauge(contextPct(ctx));
+    const gauge = contextGauge(contextInfo(ctx).pct);
     ctx.ui.setStatus("usage", gauge ? `${base} · ${gauge}` : base);
   }
 
-  function contextPct(ctx: UiContext): number | null {
-    const window = (ctx.model as { contextWindow?: number } | null)?.contextWindow;
-    if (!window || lastPromptTokens === 0) return null;
-    return Math.min(100, (lastPromptTokens / window) * 100);
+  /**
+   * The context fill percentage and the window it is measured against. The
+   * window is returned alongside the percentage so callers (the usage_status
+   * tool) can name the window without recomputing it. `pct` is null when there
+   * is nothing to measure (no window, or nothing known about usage).
+   */
+  function contextInfo(ctx: UiContext): { pct: number | null; window: number } {
+    const usage = (
+      ctx as { getContextUsage?: () => { tokens?: number | null; contextWindow?: number; percent?: number | null } | undefined }
+    ).getContextUsage?.();
+    const window = usage?.contextWindow ?? (ctx.model as { contextWindow?: number } | null)?.contextWindow ?? 0;
+    // Reconcile pi's own reading with the provider's last-request report, rather
+    // than trusting the provider number blind (some backends report it wrong).
+    const used = resolveUsedTokens({
+      hostTokens: usage?.tokens ?? null,
+      hostPercent: usage?.percent ?? null,
+      window,
+      providerTokens: lastPromptTokens || null,
+    });
+    if (used === null || window <= 0) return { pct: null, window };
+    return { pct: Math.min(100, (used / window) * 100), window };
   }
 
   function dashboard(ctx: UiContext): string {
@@ -83,7 +105,7 @@ export default function usage(pi: ExtensionAPI) {
       const scan = scanSessions(join(getAgentDir(), "sessions"));
       return [scan.records, scan.files] as const;
     })());
-    return [sessionBlock(session, contextPct(ctx)), historyBlock(history, Date.now())].join("\n\n");
+    return [sessionBlock(session, contextInfo(ctx).pct), historyBlock(history, Date.now())].join("\n\n");
   }
 
   // ── Live tracking ────────────────────────────────────────────────────
@@ -94,10 +116,10 @@ export default function usage(pi: ExtensionAPI) {
     addRecord(session, record);
     const message = (event as { message?: { role?: string; usage?: unknown } }).message;
     if (message?.role === "assistant" && isRecord(message.usage)) {
-      const input = message.usage.input;
-      const cacheRead = message.usage.cacheRead;
-      lastPromptTokens =
-        (typeof input === "number" ? input : 0) + (typeof cacheRead === "number" ? cacheRead : 0);
+      // Use pi's own formula so the gauge cannot drift below pi's reading —
+      // input+cacheRead alone dropped cacheWrite and output, a real slice of
+      // every Anthropic prompt-cached turn.
+      lastPromptTokens = contextTokensFromUsage(message.usage);
     }
     updateFooter(ctx);
   });
@@ -113,6 +135,31 @@ export default function usage(pi: ExtensionAPI) {
     updateFooter(ctx);
   });
 
+  pi.on("session_compact", async (event, ctx) => {
+    // pi's getContextUsage returns {tokens:null} until the first post-compaction
+    // response, so the stale pre-compaction figure would otherwise keep the
+    // gauge and /context at the old ~90% right after /compact. Drop it and let
+    // the local estimate drive the number until the next assistant reply.
+    lastPromptTokens = 0;
+    // The summariser's own call is one of the priciest turns in a session and
+    // fires no message_end (it is a direct completion, not the agent loop), so
+    // fold its usage — carried on the compaction entry itself — into the live
+    // footer and session totals here.
+    const record = recordFromEntry((event as { compactionEntry?: unknown }).compactionEntry);
+    if (record) addRecord(session, record);
+    updateFooter(ctx);
+  });
+
+  pi.on("session_tree", async (event, ctx) => {
+    // A branch summary is generated the same way (a direct completion), with its
+    // usage on the summary entry; count it so tree navigation is not free.
+    const record = recordFromEntry((event as { summaryEntry?: unknown }).summaryEntry);
+    if (record) {
+      addRecord(session, record);
+      updateFooter(ctx);
+    }
+  });
+
   pi.on("session_shutdown", async (_event, ctx) => {
     if (ctx.hasUI) ctx.ui.setStatus("usage", undefined);
   });
@@ -173,7 +220,7 @@ export default function usage(pi: ExtensionAPI) {
         skills?: unknown[];
         selectedTools?: string[];
       };
-      getContextUsage?: () => { contextWindow?: number; used?: number; total?: number } | undefined;
+      getContextUsage?: () => { tokens?: number | null; contextWindow?: number; percent?: number | null } | undefined;
       sessionManager?: { buildContextEntries?: () => unknown[]; getBranch?: () => unknown[] };
     };
 
@@ -204,7 +251,17 @@ export default function usage(pi: ExtensionAPI) {
       contextWindow,
       reserveTokens: compactionReserve(ctx),
     });
-    const reported = typeof usage?.used === "number" ? usage.used : lastPromptTokens || null;
+    // The provider's real last-request number is the primary "used" figure (it
+    // makes the "Other" row — what the provider counts that we can't attribute —
+    // meaningful), reconciled against pi's own reading and floored by the local
+    // estimate so a wrong provider total can't over- or under-state the window.
+    const reported = resolveUsedTokens({
+      hostTokens: usage?.tokens ?? null,
+      hostPercent: usage?.percent ?? null,
+      window: contextWindow,
+      providerTokens: lastPromptTokens || null,
+      estimate: breakdown.attributed,
+    });
     return formatBreakdown(breakdown, reported);
   }
 
@@ -268,21 +325,30 @@ export default function usage(pi: ExtensionAPI) {
     label: "Usage status",
     promptSnippet: "Tokens, cost, and context used so far this session",
     description:
-      "Current session token/cost totals plus today's local aggregate. Use when deciding whether " +
-      "an expensive approach (large reads, many subagents) is proportionate.",
+      "Current session token/cost totals, today's local aggregate, and how full the context " +
+      "window is. Use when deciding whether an expensive approach (large reads, many subagents) " +
+      "is proportionate, or whether to /compact first.",
     parameters: Type.Object({}),
     async execute(_id, _params, _signal, _onUpdate, ctx) {
       const scan = scanSessions(join(getAgentDir(), "sessions"));
       const history = aggregate(scan.records, scan.files);
       const today = windowTotals(history.byDay, 1, Date.now());
-      const text = [
+      const lines = [
         `Session: ${formatTokens(session.totalTokens)} tokens, ${formatCost(session.cost)} across ${session.messages} responses.`,
         `Today (all sessions): ${formatTokens(today.totalTokens)} tokens, ${formatCost(today.cost)}.`,
-      ].join("\n");
-      void ctx;
+      ];
+      // The snippet promises "context used", and the skill tells the model to
+      // call this before large reads — so return the one number that decides
+      // whether the read fits, with a hint to compact when the window is tight.
+      const { pct, window } = contextInfo(ctx);
+      const contextPercent = pct === null ? null : Math.round(pct);
+      if (pct !== null) {
+        const hint = pct >= 80 ? " — consider /compact before large reads" : "";
+        lines.push(`Context: ~${contextPercent}% of the ${formatTokens(window)} window used${hint}.`);
+      }
       return {
-        content: [{ type: "text", text }],
-        details: { session, today },
+        content: [{ type: "text", text: lines.join("\n") }],
+        details: { session, today, contextPercent, contextWindow: window },
       };
     },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/usage",
-  "version": "0.8.0",
+  "version": "0.9.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",

package/src/aggregate.ts

@@ -71,16 +71,27 @@ export function windowTotals(byDay: Map<string, UsageTotals>, days: number, now:
 }
 
 /**
- * Extract a usage record from one parsed session-JSONL entry. Counts any
- * entry whose message carries a usage block (assistant turns dominate; pi
- * 0.81+ also persists tool-result/compaction usage the same way). Returns
- * null for entries without usage. Negative/NaN fields clamp to 0.
+ * Extract a usage record from one parsed session-JSONL entry. Assistant turns
+ * and tool results carry their usage on `entry.message.usage`. pi stores the
+ * summariser's usage one level up, on the compaction / branch_summary entry
+ * itself (these entries have no `message`), so those are read from
+ * `entry.usage` — otherwise the most expensive calls in a session go
+ * uncounted. Returns null for entries without usage; negative/NaN fields clamp
+ * to 0.
  */
 export function recordFromEntry(entry: unknown): UsageRecord | null {
   if (!isRecord(entry)) return null;
-  const message = entry.message;
-  if (!isRecord(message) || !isRecord(message.usage)) return null;
-  const usage = message.usage;
+  const message = isRecord(entry.message) ? entry.message : null;
+  const entryType = typeof entry.type === "string" ? entry.type : "";
+  const isSummary = entryType === "compaction" || entryType === "branch_summary";
+  const usage =
+    message && isRecord(message.usage)
+      ? message.usage
+      : isSummary && isRecord(entry.usage)
+        ? entry.usage
+        : null;
+  if (!usage) return null;
+
   const total = finite(usage.totalTokens);
   const cost = isRecord(usage.cost) ? finite(usage.cost.total) : 0;
   if (total === 0 && cost === 0) return null;
@@ -88,14 +99,20 @@ export function recordFromEntry(entry: unknown): UsageRecord | null {
   const ts =
     typeof entry.timestamp === "string"
       ? Date.parse(entry.timestamp)
-      : typeof message.timestamp === "number"
+      : message && typeof message.timestamp === "number"
         ? message.timestamp
         : Number.NaN;
 
+  // A summary entry has no model/provider of its own; label the bucket by the
+  // entry type rather than threading a running "last model" through the scan.
+  const model =
+    message && typeof message.model === "string" ? message.model : isSummary ? entryType : "unknown";
+  const provider = message && typeof message.provider === "string" ? message.provider : "unknown";
+
   return {
     timestamp: Number.isFinite(ts) ? ts : 0,
-    model: typeof message.model === "string" ? message.model : "unknown",
-    provider: typeof message.provider === "string" ? message.provider : "unknown",
+    model,
+    provider,
     project: "",
     input: finite(usage.input),
     output: finite(usage.output),

package/src/context.ts

@@ -37,6 +37,58 @@ export function estimateTextTokens(value: unknown): number {
   return Math.max(0, Math.ceil(text.length / 4));
 }
 
+function nonNegNumber(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+
+/**
+ * The context size pi itself derives from a usage block — its own
+ * calculateContextTokens: `totalTokens` when present, else the sum of input +
+ * output + cacheRead + cacheWrite. Kept identical here so the footer gauge and
+ * /context agree with pi's reading; the earlier input+cacheRead formula dropped
+ * cacheWrite and output, which on Anthropic prompt caching are a real slice of
+ * every turn, leaving the gauge systematically low.
+ */
+export function contextTokensFromUsage(usage: unknown): number {
+  if (!isRecord(usage)) return 0;
+  const total = nonNegNumber(usage.totalTokens);
+  if (total > 0) return total;
+  return (
+    nonNegNumber(usage.input) +
+    nonNegNumber(usage.output) +
+    nonNegNumber(usage.cacheRead) +
+    nonNegNumber(usage.cacheWrite)
+  );
+}
+
+/** pi's fixed per-image charge; a base64 blob is never billed as its bytes. */
+const ESTIMATED_IMAGE_CHARS = 4800;
+
+/**
+ * Character count of message content the way pi's compaction estimator counts
+ * it (estimateTextAndImageContentChars): a string is its own length; a content
+ * array charges each text block's text and a flat 4800 chars per image block,
+ * ignoring every other field. Without this, JSON.stringify would bill an
+ * ImageContent block's base64 `data` at chars/4 — one screenshot then reads as
+ * hundreds of k tokens and pins /context at 100%.
+ */
+export function contentChars(content: unknown): number {
+  if (typeof content === "string") return content.length;
+  if (!Array.isArray(content)) return 0;
+  let chars = 0;
+  for (const block of content) {
+    if (!isRecord(block)) continue;
+    if (block.type === "text" && typeof block.text === "string") chars += block.text.length;
+    else if (block.type === "image") chars += ESTIMATED_IMAGE_CHARS;
+  }
+  return chars;
+}
+
+/** contentChars in tokens (chars/4), matching pi's estimateTokens. */
+function contentTokens(content: unknown): number {
+  return Math.ceil(contentChars(content) / 4);
+}
+
 /** Count a chunk only when the assembled prompt really contains it. */
 export function embeddedTokens(systemPrompt: string, chunk: string): number {
   if (!chunk || !systemPrompt.includes(chunk)) return 0;
@@ -78,7 +130,10 @@ function foldEntries(entries: unknown[]): { conversation: number; toolResults: n
     const role = typeof message.role === "string" ? message.role : null;
 
     if (role === "toolResult" || role === "bashExecution") {
-      toolResults += estimateTextTokens(message.content ?? message.output ?? message);
+      // Tool results carry image blocks (pi's read tool returns them); charge
+      // those at pi's flat rate rather than the base64 bytes' chars/4.
+      const content = message.content ?? message.output;
+      toolResults += content === undefined ? estimateTextTokens(message) : contentTokens(content);
       continue;
     }
     if (role === "assistant" && Array.isArray(message.content)) {
@@ -102,10 +157,14 @@ function foldEntries(entries: unknown[]): { conversation: number; toolResults: n
       continue;
     }
     if (typeof entry.content === "string" || Array.isArray(entry.content)) {
-      conversation += estimateTextTokens(entry.content);
+      // A raw user message; its content may hold a pasted screenshot.
+      conversation += contentTokens(entry.content);
       continue;
     }
-    if (role) conversation += estimateTextTokens(message.content ?? message);
+    if (role) {
+      conversation +=
+        message.content === undefined ? estimateTextTokens(message) : contentTokens(message.content);
+    }
   }
 
   return { conversation, toolResults, thinking };
@@ -149,6 +208,62 @@ export function buildBreakdown(input: BreakdownInput): ContextBreakdown {
   };
 }
 
+export interface UsedTokensInput {
+  /** pi's own estimate of context tokens (getContextUsage().tokens), or null. */
+  hostTokens: number | null;
+  /** pi's own percent-of-window (getContextUsage().percent), or null. */
+  hostPercent: number | null;
+  /** The context window; 0 when unknown. */
+  window: number;
+  /**
+   * The provider's report for the last request, via pi's own
+   * calculateContextTokens (totalTokens, or input+output+cacheRead+cacheWrite),
+   * or null.
+   */
+  providerTokens: number | null;
+  /** A local content estimate (a hard lower bound), when one is available. */
+  estimate?: number;
+}
+
+/**
+ * Reconcile the several "how full is the window" signals into one used-tokens
+ * figure, so the gauge does not blindly trust a provider number that some
+ * backends report wrong (cumulative totals, cache-inflated counts, or an
+ * implausibly small figure). The rule — from minuque/pi-cc-extensions'
+ * resolveUsedTokens:
+ *
+ *  - the provider's report is the primary signal (it is the real last request),
+ *  - but when it diverges beyond tolerance from pi's own percent×window reading
+ *    (what pi itself uses for the gauge and for compaction), trust pi's number,
+ *  - and never report fewer tokens than the content visibly in context.
+ *
+ * Returns null only when nothing is known (so the gauge can hide itself).
+ */
+export function resolveUsedTokens(input: UsedTokensInput): number | null {
+  const w = input.window > 0 ? input.window : 0;
+  const fromPercent = input.hostPercent !== null && w > 0 ? (input.hostPercent / 100) * w : null;
+  const host = input.hostTokens !== null ? input.hostTokens : fromPercent;
+  const provider = input.providerTokens !== null && input.providerTokens > 0 ? input.providerTokens : null;
+  const estimate = typeof input.estimate === "number" && input.estimate > 0 ? input.estimate : null;
+
+  let used = provider ?? host ?? estimate;
+  if (used === null || used === undefined) return null;
+
+  // Trust pi's own reading when the provider's number diverges beyond tolerance
+  // (25% of the host reading, or 2k tokens, whichever is larger).
+  if (provider !== null && host !== null) {
+    const tolerance = Math.max(2000, host * 0.25);
+    if (Math.abs(provider - host) > tolerance) used = host;
+  }
+
+  // A content estimate is a hard floor: you cannot be using fewer tokens than
+  // the text that is demonstrably in context.
+  if (estimate !== null && estimate > used) used = estimate;
+
+  if (w > 0) used = Math.min(used, w);
+  return Math.max(0, Math.round(used));
+}
+
 const BAR_WIDTH = 28;
 
 function bar(fraction: number): string {
@@ -176,7 +291,10 @@ function formatTokens(n: number): string {
  */
 export function formatBreakdown(breakdown: ContextBreakdown, reportedUsed: number | null): string {
   const window = breakdown.contextWindow;
-  const used = Math.max(reportedUsed ?? 0, breakdown.attributed);
+  // Clamp to the window so a stale or odd figure can never print above 100%
+  // (resolveUsedTokens already clamps its own result, but `attributed` does not).
+  const raw = Math.max(reportedUsed ?? 0, breakdown.attributed);
+  const used = window > 0 ? Math.min(window, raw) : raw;
   const other = Math.max(0, used - breakdown.attributed);
   // pi holds back a reserve for auto-compaction; real headroom excludes it, so
   // show it as its own row and subtract it from free space rather than letting

package/src/ratelimit.ts

@@ -23,8 +23,14 @@ export interface RateLimitSnapshot {
   tokensRemaining: number | null;
   /** When the window resets — provider's own string (seconds, ISO, or duration). */
   resets: string | null;
-  /** A unified subscription-window fraction 0..1 remaining, Anthropic OAuth only. */
-  unifiedRemaining: number | null;
+  /** Fraction 0..1 of the unified 5-hour subscription window still free (Anthropic OAuth). */
+  unified5hRemaining: number | null;
+  /** Fraction 0..1 of the unified 7-day subscription window still free (Anthropic OAuth). */
+  unified7dRemaining: number | null;
+  /** Which unified window Anthropic marks as binding, from -representative-claim. */
+  unifiedBinding: "5h" | "7d" | null;
+  /** Unified subscription status: "allowed" | "allowed_warning" | "rejected". */
+  unifiedStatus: string | null;
   /** Which header family this came from, for the report line. */
   source: "anthropic" | "openai" | "openrouter";
   capturedAtMs: number;
@@ -37,6 +43,14 @@ function intOf(headers: Record<string, string>, key: string): number | null {
   return Number.isFinite(n) ? n : null;
 }
 
+/** A fraction 0..1 (Anthropic reports utilization as a decimal fraction USED). */
+function fracOf(headers: Record<string, string>, key: string): number | null {
+  const raw = headers[key] ?? headers[key.toLowerCase()];
+  if (raw === undefined) return null;
+  const n = Number.parseFloat(String(raw));
+  return Number.isFinite(n) ? Math.max(0, Math.min(1, n)) : null;
+}
+
 function strOf(headers: Record<string, string>, key: string): string | null {
   const raw = headers[key] ?? headers[key.toLowerCase()];
   return raw === undefined || raw === "" ? null : String(raw);
@@ -69,20 +83,30 @@ export function parseRateLimit(
   if (family === "anthropic") {
     const reqs = intOf(h, "anthropic-ratelimit-requests-remaining");
     const toks = intOf(h, "anthropic-ratelimit-tokens-remaining");
-    // The OAuth Pro/Max unified subscription window, reported as a percentage.
-    const unifiedRaw = strOf(h, "anthropic-ratelimit-unified-status")
-      ? intOf(h, "anthropic-ratelimit-unified-remaining")
-      : intOf(h, "anthropic-ratelimit-unified-remaining");
-    if (reqs !== null || toks !== null || unifiedRaw !== null) {
+    // The OAuth Pro/Max unified subscription windows. Anthropic reports
+    // UTILIZATION — the fraction USED, 0..1 — for a 5-hour and a 7-day window
+    // (there is no "-remaining" header), plus which window is binding
+    // (-representative-claim) and an overall status. Remaining = 1 − utilization.
+    const util5h = fracOf(h, "anthropic-ratelimit-unified-5h-utilization");
+    const util7d = fracOf(h, "anthropic-ratelimit-unified-7d-utilization");
+    const claim = strOf(h, "anthropic-ratelimit-unified-representative-claim");
+    const unifiedStatus = strOf(h, "anthropic-ratelimit-unified-status");
+    const hasUnified = util5h !== null || util7d !== null || unifiedStatus !== null;
+    if (reqs !== null || toks !== null || hasUnified) {
       snap = {
         provider,
         requestsRemaining: reqs,
         tokensRemaining: toks,
         resets:
           strOf(h, "anthropic-ratelimit-unified-reset") ??
+          strOf(h, "anthropic-ratelimit-unified-5h-reset") ??
+          strOf(h, "anthropic-ratelimit-unified-7d-reset") ??
           strOf(h, "anthropic-ratelimit-tokens-reset") ??
           strOf(h, "anthropic-ratelimit-requests-reset"),
-        unifiedRemaining: unifiedRaw === null ? null : Math.max(0, Math.min(1, unifiedRaw / 100)),
+        unified5hRemaining: util5h === null ? null : 1 - util5h,
+        unified7dRemaining: util7d === null ? null : 1 - util7d,
+        unifiedBinding: claim === "5h" || claim === "7d" ? claim : null,
+        unifiedStatus,
         source: "anthropic",
         capturedAtMs: nowMs,
       };
@@ -96,7 +120,10 @@ export function parseRateLimit(
         requestsRemaining: reqs,
         tokensRemaining: toks,
         resets: strOf(h, "x-ratelimit-reset-tokens") ?? strOf(h, "x-ratelimit-reset-requests"),
-        unifiedRemaining: null,
+        unified5hRemaining: null,
+        unified7dRemaining: null,
+        unifiedBinding: null,
+        unifiedStatus: null,
         source: "openai",
         capturedAtMs: nowMs,
       };
@@ -110,7 +137,10 @@ export function parseRateLimit(
         requestsRemaining: remaining,
         tokensRemaining: null,
         resets: strOf(h, "x-ratelimit-reset"),
-        unifiedRemaining: null,
+        unified5hRemaining: null,
+        unified7dRemaining: null,
+        unifiedBinding: null,
+        unifiedStatus: null,
         source: "openrouter",
         capturedAtMs: nowMs,
       };
@@ -120,14 +150,45 @@ export function parseRateLimit(
   return snap;
 }
 
+/**
+ * Anthropic's unified reset is epoch SECONDS; render it as a readable local
+ * time. Other providers' values (ISO strings, "6s" durations, openrouter's
+ * epoch millis) are left untouched, so this only reinterprets the anthropic
+ * numeric case.
+ */
+function formatReset(snap: RateLimitSnapshot): 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 d.toLocaleString();
+  }
+  return raw;
+}
+
 /** 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;
   const parts: string[] = [];
-  if (snap.unifiedRemaining !== null) parts.push(`${Math.round(snap.unifiedRemaining * 100)}% of subscription window left`);
+  // Surface the subscription status only when it is not the ordinary "allowed",
+  // so a healthy window does not add noise but a warning/rejection is visible.
+  if (snap.unifiedStatus && snap.unifiedStatus !== "allowed") {
+    parts.push(`subscription ${snap.unifiedStatus.replace(/_/g, " ")}`);
+  }
+  if (snap.unified5hRemaining !== null) {
+    parts.push(
+      `${Math.round(snap.unified5hRemaining * 100)}% of 5h window left${snap.unifiedBinding === "5h" ? " (binding)" : ""}`,
+    );
+  }
+  if (snap.unified7dRemaining !== null) {
+    parts.push(
+      `${Math.round(snap.unified7dRemaining * 100)}% of 7d window left${snap.unifiedBinding === "7d" ? " (binding)" : ""}`,
+    );
+  }
   if (snap.requestsRemaining !== null) parts.push(`${snap.requestsRemaining} requests left`);
   if (snap.tokensRemaining !== null) parts.push(`${snap.tokensRemaining} tokens left`);
   if (parts.length === 0) return null;
-  const when = snap.resets ? `, resets ${snap.resets}` : "";
+  const reset = formatReset(snap);
+  const when = reset ? `, resets ${reset}` : "";
   return `${snap.provider}: ${parts.join(", ")}${when} (from response headers)`;
 }