quotacap 0.0.39 → 0.0.40

package/README.md

@@ -24,7 +24,7 @@ QuotaCap helps you get more from the AI coding subscriptions you already pay for
 | Kimi Code | `pty` — `kimi` then `/usage`, parse `Weekly/5h limit: Y% used` | Live |
 | Grok | `pty` — `grok` then `/usage`, parse `Weekly limit (plan)` + `Credits: $X` | Live |
 | Muse Code | `pty` — `muse --trust-workspace` then `/usage`, parse `Subscription · Muse Code <plan>` + `Weekly/Current N% used`; on `Currently unavailable`, up to three headless `muse exec` warm turns and re-reads inside the poll | Live |
-| OpenCode Go | `api` — `GET https://opencode.ai/zen/go/v1/usage` with the OpenCode auth key; opt-in via `quotacap providers enable opencode-go` (consent recorded, disable revokes it) | Live (opt-in) |
+| OpenCode Go | `api` — `GET https://opencode.ai/zen/go/v1/usage` with the OpenCode auth key; reports 5h, weekly and monthly windows; opt-in via `quotacap providers enable opencode-go` (consent recorded, disable revokes it) | Live (opt-in) |
 
 Exec adapters run via `execFile` with an argv list. PTY adapters run via `node-pty` (`src/adapters/pty.ts`). They are TUI-fragile: a vendor text change breaks the parser and the row degrades fail-closed until the regex is fixed. Poll latency is 2–10 s per PTY provider (settle plus completion); `muse` can reach about 75 s when it has to warm an unavailable subscription. It dominates `POST /api/refresh` and the first poll, not the steady-state 15 m timer.
 

package/dist/adapters/agy.js

@@ -29,8 +29,8 @@ function parseGroup(g, provider, rawJsonString, now) {
     return {
         provider,
         plan: "unknown",
-        usedPct,
-        sessionPct,
+        weeklyPct: usedPct,
+        fiveHourPct: sessionPct,
         resetsAt,
         periodStart,
         source: "cli",

package/dist/adapters/claude.js

@@ -13,7 +13,7 @@ export function parseClaudeUsage(result, now = new Date()) {
     const resets = new Date(resetsAt).getTime();
     const periodStart = (parsedReset ? new Date(resets - 7 * 86400000) : new Date(now.getTime() - 7 * 86400000)).toISOString();
     return {
-        provider: "claude", plan: "max", usedPct, sessionPct,
+        provider: "claude", plan: "max", weeklyPct: usedPct, fiveHourPct: sessionPct,
         resetsAt, periodStart, source: "cli", fetchedAt: now.toISOString(), raw: result,
     };
 }

package/dist/adapters/codex.js

@@ -123,8 +123,8 @@ export function parseCodexTui(text, now = new Date()) {
     return {
         provider: "codex",
         plan,
-        usedPct,
-        sessionPct,
+        weeklyPct: usedPct,
+        fiveHourPct: sessionPct,
         resetsAt: weeklyIso,
         periodStart,
         source: "tui",

package/dist/adapters/grok.js

@@ -133,7 +133,7 @@ export function parseGrokTui(text, now = new Date()) {
     return {
         provider: "grok",
         plan,
-        usedPct,
+        weeklyPct: usedPct,
         resetsAt,
         periodStart,
         source: "tui",

package/dist/adapters/kimi.js

@@ -51,8 +51,8 @@ export function parseKimiTui(text, now = new Date()) {
     return {
         provider: "kimi",
         plan,
-        usedPct,
-        sessionPct,
+        weeklyPct: usedPct,
+        fiveHourPct: sessionPct,
         resetsAt: weeklyIso,
         periodStart,
         source: "tui",

package/dist/adapters/manual.js

@@ -15,8 +15,8 @@ export function parseManualUsage(provider, text, now = new Date()) {
     return {
         provider,
         plan: "unknown",
-        usedPct,
-        sessionPct,
+        weeklyPct: usedPct,
+        fiveHourPct: sessionPct,
         resetsAt,
         periodStart,
         source: "manual",

package/dist/adapters/muse.js

@@ -115,8 +115,8 @@ export function parseMuseTui(text, now = new Date()) {
     return {
         provider: "muse",
         plan,
-        usedPct,
-        sessionPct,
+        weeklyPct: usedPct,
+        fiveHourPct: sessionPct,
         resetsAt,
         periodStart,
         source: "tui",

package/dist/adapters/opencode-go.js

@@ -46,6 +46,32 @@ function readBearerToken(env = process.env) {
     }
     return entry.key;
 }
+// `rate-limited` is the binding state, not a failure: it is exactly the
+// reading issue 109 needed. Anything unreadable fails closed.
+function parseMonthly(usage) {
+    const monthly = usage.monthly;
+    if (typeof monthly !== "object" || monthly === null)
+        return {};
+    const m = monthly;
+    if (m.status !== "ok" && m.status !== "rate-limited") {
+        throw new Error("opencode-go: unknown monthly status");
+    }
+    const percent = m.percent;
+    if (typeof percent !== "number" || !Number.isFinite(percent) || percent < 0) {
+        throw new Error("opencode-go: bad monthly pct");
+    }
+    const resetsMs = Date.parse(String(m.resetsAt ?? ""));
+    if (!Number.isFinite(resetsMs)) {
+        throw new Error("opencode-go: bad monthly reset");
+    }
+    const exhausted = m.status === "rate-limited" || percent > 100;
+    return {
+        monthlyKind: "included",
+        monthlyStatus: exhausted ? "exhausted" : "ok",
+        monthlyPct: exhausted ? 100 : percent,
+        monthlyResetsAt: new Date(resetsMs).toISOString(),
+    };
+}
 export function parseOpencodeGoUsage(body, now = new Date()) {
     const usage = body?.usage;
     if (typeof usage !== "object" || usage === null) {
@@ -77,15 +103,17 @@ export function parseOpencodeGoUsage(body, now = new Date()) {
     if (typeof sessionPct !== "number" || !Number.isFinite(sessionPct) || sessionPct < 0 || sessionPct > 100) {
         throw new Error("opencode-go: bad rolling pct");
     }
+    const monthly = parseMonthly(usage);
     return {
         provider: "opencode-go",
         plan: "unknown",
-        usedPct,
-        sessionPct,
+        weeklyPct: usedPct,
+        fiveHourPct: sessionPct,
         resetsAt: new Date(resetsMs).toISOString(),
         periodStart: new Date(resetsMs - 7 * 86400000).toISOString(),
         source: "api",
         fetchedAt: now.toISOString(),
+        ...monthly,
     };
 }
 export const opencodeGoAdapter = {

package/dist/adapters/types.d.ts

@@ -1,8 +1,16 @@
 export interface Quota {
     provider: string;
     plan: string;
-    usedPct: number;
-    sessionPct?: number;
+    /** The paced window. 0..100. Named `usedPct` before this release. */
+    weeklyPct: number;
+    /** 5-hour rolling window. 0..100. Display only — never ranks. Was `sessionPct`. */
+    fiveHourPct?: number;
+    /** Included monthly envelope. 0..100. Absent means the provider has no monthly window. */
+    monthlyPct?: number;
+    monthlyResetsAt?: string;
+    monthlyStatus?: "ok" | "exhausted";
+    /** "included" only this slice. A spend cap or PAYG ceiling will carry its own value. */
+    monthlyKind?: "included";
     resetsAt: string;
     periodStart: string;
     source: "cli" | "api" | "scrape" | "manual" | "tui";
@@ -10,6 +18,13 @@ export interface Quota {
     creditsUsd?: number;
     resetsAtEstimated?: boolean;
 }
+/** Store and wire shape: `Quota` plus the one-release aliases. */
+export interface QuotaWire extends Quota {
+    /** @deprecated alias for weeklyPct. Removed the release after next. */
+    usedPct: number;
+    /** @deprecated alias for fiveHourPct. Removed the release after next. */
+    sessionPct?: number;
+}
 export interface ParsedQuota extends Quota {
     raw?: string;
 }

package/dist/advisory/engine.d.ts

@@ -1,9 +1,9 @@
 import type { Quota } from "../adapters/types.js";
-import type { Advisory, RecommendationBasis } from "./types.js";
+import type { Advisory, RecommendationBasis, BindingWindow } from "./types.js";
 /**
  * Pace from a single reading.
  *
- * `usedPct` is a running total since the window opened, and `periodStart` is
+ * `weeklyPct` is a running total since the window opened, and `periodStart` is
  * a required field every adapter sets, so a pace is always computable from
  * one poll. Returns null when `periodStart` is missing or unparseable, or
  * when less than MIN_PACE_SPAN_DAYS has elapsed (annualizing a smaller
@@ -22,6 +22,7 @@ export declare function recommend(quotas: Quota[], _task: string, paceByProvider
     wastePct: number;
     idealRate: number;
     recommendationBasis: RecommendationBasis;
+    bindingWindow: BindingWindow;
     alternatives: Quota[];
     advisories: Advisory[];
 } | {
@@ -30,6 +31,7 @@ export declare function recommend(quotas: Quota[], _task: string, paceByProvider
     wastePct: null;
     idealRate: number;
     recommendationBasis: RecommendationBasis;
+    bindingWindow: BindingWindow;
     alternatives: Quota[];
     advisories: Advisory[];
 };

package/dist/advisory/engine.js

@@ -3,7 +3,7 @@ const DAY_MS = 86400000;
 /**
  * Pace from a single reading.
  *
- * `usedPct` is a running total since the window opened, and `periodStart` is
+ * `weeklyPct` is a running total since the window opened, and `periodStart` is
  * a required field every adapter sets, so a pace is always computable from
  * one poll. Returns null when `periodStart` is missing or unparseable, or
  * when less than MIN_PACE_SPAN_DAYS has elapsed (annualizing a smaller
@@ -18,7 +18,7 @@ export function averagePace(q, now = new Date()) {
     const elapsedDays = (now.getTime() - start) / DAY_MS;
     if (elapsedDays < MIN_PACE_SPAN_DAYS)
         return null;
-    const pace = q.usedPct / elapsedDays;
+    const pace = q.weeklyPct / elapsedDays;
     if (!Number.isFinite(pace))
         return null;
     return Math.max(0, pace);
@@ -60,13 +60,29 @@ function elapsedPctOf(q, now) {
 export function computeAdvisory(q, recent, baseline, now = new Date()) {
     const resets = new Date(q.resetsAt);
     const daysLeft = Math.max(0.1, (resets.getTime() - now.getTime()) / DAY_MS);
-    const remaining = 100 - q.usedPct;
+    const remaining = 100 - q.weeklyPct;
     const idealRate = remaining / daysLeft;
     const avgPace = averagePace(q, now);
     // Nothing left to burn: force the capped verdict even when the recent
     // window is flat (burn 0 at 100% used must not read "on track").
     const exhausted = remaining <= 0;
     const burnRate = blendForecast(recent, baseline);
+    // Above every return: the unknown-pace path below is exactly what pool 2
+    // ranks, so a binding computed later would leave it on weekly numbers.
+    const weeklyHeadroom = remaining / daysLeft;
+    let bindingWindow = "weekly";
+    let bindingRemaining = remaining;
+    let bindingDaysLeft = daysLeft;
+    if (q.monthlyKind === "included" && typeof q.monthlyPct === "number" && q.monthlyResetsAt) {
+        const monthlyRemaining = q.monthlyStatus === "exhausted" ? 0 : Math.max(0, 100 - q.monthlyPct);
+        const monthlyDaysLeft = Math.max(0.1, (new Date(q.monthlyResetsAt).getTime() - now.getTime()) / DAY_MS);
+        const monthlyHeadroom = monthlyRemaining / monthlyDaysLeft;
+        if (monthlyHeadroom < weeklyHeadroom || monthlyRemaining === 0) {
+            bindingWindow = "monthly";
+            bindingRemaining = monthlyRemaining;
+            bindingDaysLeft = monthlyDaysLeft;
+        }
+    }
     // paceSource describes recent availability; the blend's composition is
     // carried by recentRate and baselineRate.
     const paceSource = recent !== null ? "recent" : burnRate !== null ? "window-average" : "unknown";
@@ -88,6 +104,9 @@ export function computeAdvisory(q, recent, baseline, now = new Date()) {
             status: exhausted ? "at risk" : "unknown",
             wastePct: exhausted ? 0 : null,
             urgency: exhausted ? "slow down" : "on track",
+            bindingWindow,
+            bindingRemaining,
+            bindingDaysLeft,
         };
     }
     if (exhausted) {
@@ -107,14 +126,17 @@ export function computeAdvisory(q, recent, baseline, now = new Date()) {
             status: "at risk",
             wastePct: 0,
             urgency: "slow down",
+            bindingWindow,
+            bindingRemaining,
+            bindingDaysLeft,
         };
     }
     // Red needs a deadband margin and a cumulatively-ahead position on a
     // verified clock; a missing or estimated clock caps at Watch.
     const elapsed = elapsedPctOf(q, now);
     const estimated = q.resetsAtEstimated === true;
-    const gate = elapsed !== null && !estimated && q.usedPct >= elapsed * (1 - GATE_TOL);
-    const aheadOfElapsed = elapsed !== null && !estimated && q.usedPct > elapsed * (1 + GATE_TOL);
+    const gate = elapsed !== null && !estimated && q.weeklyPct >= elapsed * (1 - GATE_TOL);
+    const aheadOfElapsed = elapsed !== null && !estimated && q.weeklyPct > elapsed * (1 + GATE_TOL);
     const wastePct = Math.max(0, remaining - burnRate * daysLeft);
     const daysToExhaust = burnRate > 0 ? remaining / burnRate : Infinity;
     const over = daysToExhaust < daysLeft * (1 - RISK_MARGIN);
@@ -137,7 +159,18 @@ export function computeAdvisory(q, recent, baseline, now = new Date()) {
         urgency = "save";
     if (estimated && urgency === "burn now")
         urgency = "use soon";
-    return { provider: q.provider, daysLeft, remaining, idealRate, burnRate, recentRate: recent, baselineRate: baseline, aheadOfElapsed, avgPace, burnMeasured, paceSource, daysToExhaust, status, wastePct, urgency };
+    return { provider: q.provider, daysLeft, remaining, idealRate, burnRate, recentRate: recent, baselineRate: baseline, aheadOfElapsed, avgPace, burnMeasured, paceSource, daysToExhaust, status, wastePct, urgency, bindingWindow, bindingRemaining, bindingDaysLeft };
+}
+/**
+ * Known-waste sort key. `wastePct` is a flow (budget forecast to go unspent
+ * by the weekly deadline); `bindingRemaining` is a stock. The binding window's
+ * headroom per day, priced over the weekly days-left the pool sorts on, caps
+ * the claim at what the account can actually absorb. Weekly-bound providers
+ * are untouched: the ratio is 1 and `wastePct <= remaining` always.
+ */
+function rankWaste(a) {
+    const affordable = a.bindingRemaining * (a.daysLeft / a.bindingDaysLeft);
+    return Math.min(a.wastePct, affordable);
 }
 export function recommend(quotas, _task, paceByProvider = new Map(), now = new Date()) {
     if (!quotas.length) {
@@ -147,6 +180,7 @@ export function recommend(quotas, _task, paceByProvider = new Map(), now = new D
             wastePct: 0,
             idealRate: 0,
             recommendationBasis: "none",
+            bindingWindow: "weekly",
             alternatives: [],
             advisories: [],
         };
@@ -162,32 +196,38 @@ export function recommend(quotas, _task, paceByProvider = new Map(), now = new D
     // are a fallback pool, read from the flags on the quotas already received.
     const estimatedProviders = new Set(quotas.filter(q => q.resetsAtEstimated === true).map(q => q.provider));
     // 1. Prefer measured providers with positive avoidable waste (actionable "Use more" candidates).
-    const positiveWaste = advisories.filter((a) => a.paceSource !== "unknown" && a.wastePct !== null && a.wastePct > 0);
+    const positiveWaste = advisories.filter((a) => a.paceSource !== "unknown" && a.wastePct !== null && a.wastePct > 0 && a.bindingRemaining > 0);
     if (positiveWaste.length > 0) {
         const verified = positiveWaste.filter(a => !estimatedProviders.has(a.provider));
         const pool = verified.length ? verified : positiveWaste.filter(a => estimatedProviders.has(a.provider));
-        const burnNow = pool.filter(a => a.urgency === "burn now");
-        const use = (burnNow.length ? burnNow : pool).sort((a, b) => b.wastePct - a.wastePct)[0];
+        const burnNow = pool.filter(a => a.urgency === "burn now" && a.bindingWindow === "weekly");
+        const use = (burnNow.length ? burnNow : pool).sort((a, b) => rankWaste(b) - rankWaste(a))[0];
         return {
             use: use.provider,
-            reason: `${Math.round(use.wastePct)}% waste in ${use.daysLeft.toFixed(1)}d`,
-            wastePct: use.wastePct,
+            reason: use.bindingWindow === "monthly"
+                ? `${Math.round(use.bindingRemaining)}% of month left in ${use.bindingDaysLeft.toFixed(1)}d`
+                : `${Math.round(use.wastePct)}% waste in ${use.daysLeft.toFixed(1)}d`,
+            wastePct: rankWaste(use),
             idealRate: use.idealRate,
             recommendationBasis: "known-waste",
+            bindingWindow: use.bindingWindow,
             alternatives: quotas,
             advisories,
         };
     }
     // 2. Low-confidence fallback: rank unknown providers by remaining headroom (remaining / daysLeft).
-    const unknownProviders = advisories.filter(a => a.paceSource === "unknown" && a.remaining > 0);
+    const unknownProviders = advisories.filter(a => a.paceSource === "unknown" && a.bindingRemaining > 0);
     if (unknownProviders.length > 0) {
-        const use = unknownProviders.sort((a, b) => (b.remaining / b.daysLeft) - (a.remaining / a.daysLeft))[0];
+        const use = unknownProviders.sort((a, b) => (b.bindingRemaining / b.bindingDaysLeft) - (a.bindingRemaining / a.bindingDaysLeft))[0];
         return {
             use: use.provider,
-            reason: `Measuring pace; ${Math.round(use.remaining)}% remains with ${use.daysLeft.toFixed(1)}d until reset`,
+            reason: use.bindingWindow === "monthly"
+                ? `Measuring pace; ${Math.round(use.bindingRemaining)}% of month left with ${use.bindingDaysLeft.toFixed(1)}d until reset`
+                : `Measuring pace; ${Math.round(use.remaining)}% remains with ${use.daysLeft.toFixed(1)}d until reset`,
             wastePct: null,
             idealRate: use.idealRate,
             recommendationBasis: "unknown-headroom",
+            bindingWindow: use.bindingWindow,
             alternatives: quotas,
             advisories,
         };
@@ -199,6 +239,7 @@ export function recommend(quotas, _task, paceByProvider = new Map(), now = new D
         wastePct: 0,
         idealRate: 0,
         recommendationBasis: "none",
+        bindingWindow: "weekly",
         alternatives: quotas,
         advisories,
     };

package/dist/advisory/snapshot.js

@@ -20,6 +20,13 @@ function normalizeAdvisory(adv) {
         avgPace: adv.avgPace !== null && Number.isFinite(adv.avgPace) ? adv.avgPace : null,
         daysToExhaust: adv.daysToExhaust !== null && Number.isFinite(adv.daysToExhaust) ? adv.daysToExhaust : null,
         wastePct: adv.wastePct !== null && Number.isFinite(adv.wastePct) ? adv.wastePct : null,
+        bindingWindow: adv.bindingWindow === "monthly" ? "monthly" : "weekly",
+        bindingRemaining: Number.isFinite(adv.bindingRemaining)
+            ? adv.bindingRemaining
+            : Number.isFinite(adv.remaining) ? adv.remaining : 0,
+        bindingDaysLeft: Number.isFinite(adv.bindingDaysLeft)
+            ? adv.bindingDaysLeft
+            : Number.isFinite(adv.daysLeft) ? adv.daysLeft : 0,
     };
 }
 export function buildSnapshot(db, opts) {
@@ -67,9 +74,9 @@ export function buildSnapshot(db, opts) {
         if (quota !== null) {
             const resetsMs = new Date(quota.resetsAt).getTime();
             const fetchedMs = new Date(quota.fetchedAt).getTime();
-            if (!Number.isFinite(quota.usedPct) ||
-                quota.usedPct < 0 ||
-                quota.usedPct > 100 ||
+            if (!Number.isFinite(quota.weeklyPct) ||
+                quota.weeklyPct < 0 ||
+                quota.weeklyPct > 100 ||
                 Number.isNaN(resetsMs) ||
                 Number.isNaN(fetchedMs)) {
                 isInvalid = true;
@@ -168,6 +175,7 @@ export function buildSnapshot(db, opts) {
             wastePct: null,
             idealRate: 0,
             recommendationBasis: "none",
+            bindingWindow: "weekly",
             models: [],
             catalogStatus: "unfetched",
             catalogFetchedAt: null,

package/dist/advisory/types.d.ts

@@ -1,4 +1,4 @@
-import type { Quota } from "../adapters/types.js";
+import type { QuotaWire } from "../adapters/types.js";
 import type { AttemptRecord } from "../store/attempts.js";
 import type { CatalogStatus, CatalogView, ListedModel } from "../catalog/types.js";
 /**
@@ -15,6 +15,7 @@ export type Urgency = "burn now" | "use soon" | "slow down" | "save" | "on track
 export type BurnStatus = "at risk" | "watch" | "on track" | "unknown";
 export type PaceSource = "recent" | "window-average" | "unknown";
 export type RecommendationBasis = "known-waste" | "unknown-headroom" | "none";
+export type BindingWindow = "weekly" | "monthly";
 export type ExclusionReason = "not-reporting" | "stale" | "reset-passed" | "invalid" | "provider-failed" | null;
 export type { AttemptRecord };
 export interface Advisory {
@@ -39,6 +40,12 @@ export interface Advisory {
     status: BurnStatus;
     wastePct: number | null;
     urgency: Urgency;
+    /** Which included window is scarcer per day left. "weekly" when there is no included monthly. */
+    bindingWindow: BindingWindow;
+    /** Remaining percent of the binding window. Equals `remaining` when weekly binds. */
+    bindingRemaining: number;
+    /** Days until the binding window resets. Equals `daysLeft` when weekly binds. */
+    bindingDaysLeft: number;
 }
 export interface Recommendation {
     use: string;
@@ -46,10 +53,11 @@ export interface Recommendation {
     wastePct: number | null;
     idealRate: number;
     recommendationBasis: RecommendationBasis;
+    bindingWindow: BindingWindow;
     models: ListedModel[];
     catalogStatus: CatalogStatus;
     catalogFetchedAt: string | null;
-    alternatives: Array<Quota & {
+    alternatives: Array<QuotaWire & {
         catalog: CatalogView;
     }>;
     advisories: Advisory[];
@@ -74,7 +82,7 @@ export interface ProviderSnapshot {
     harness: string | null;
     description: string | null;
     enabled: boolean;
-    quota: Quota | null;
+    quota: QuotaWire | null;
     lastAttempt: AttemptRecord | null;
     lastSuccessAt: string | null;
     reporting: boolean;

package/dist/cli/models.js

@@ -11,7 +11,7 @@ function projectModels(catalogs, quotaMap, providerNames) {
     for (const [id, catalog] of catalogs) {
         const identity = providerIdentity(id, providerNames);
         const quota = quotaMap.get(id);
-        const leftoverPct = quota?.usedPct != null ? Math.round((100 - quota.usedPct) * 10) / 10 : null;
+        const leftoverPct = quota?.weeklyPct != null ? Math.round((100 - quota.weeklyPct) * 10) / 10 : null;
         out.push({
             id,
             displayName: identity.displayName,

package/dist/diagnostics/failure.js

@@ -232,6 +232,15 @@ function matchPrecedence(evidence, errorName, errorCode, text) {
     if (/\bbad rolling pct\b/i.test(text)) {
         return { code: "parse_error", phrase: "bad rolling pct" };
     }
+    if (/\bbad monthly pct\b/i.test(text)) {
+        return { code: "parse_error", phrase: "bad monthly pct" };
+    }
+    if (/\bbad monthly reset\b/i.test(text)) {
+        return { code: "parse_error", phrase: "bad monthly reset" };
+    }
+    if (/\bunknown monthly status\b/i.test(text)) {
+        return { code: "parse_error", phrase: "unknown monthly status" };
+    }
     if (/\busage status not ok\b/i.test(text)) {
         return { code: "parse_error", phrase: "usage status not ok" };
     }

package/dist/format/rows.d.ts

@@ -1,5 +1,5 @@
 import type { ProviderSnapshot } from "../advisory/types.js";
-export type StateWord = "On track" | "Behind pace" | "Ahead of pace" | "Cap risk" | "Watch" | "Measuring" | "Not reporting";
+export type StateWord = "On track" | "Behind pace" | "Ahead of pace" | "Cap risk" | "Watch" | "Measuring" | "Not reporting" | "Monthly exhausted";
 export type RailCell = "used" | "tick" | "unused";
 export type SortKey = "recommended" | "reset-asc" | "reset-desc" | "used-desc" | "used-asc";
 export type CompactSuffix = "" | "!" | "~" | "?";
@@ -16,7 +16,12 @@ export interface Row {
 }
 export declare const RAIL_CELLS = 20;
 export declare const SORT_KEYS: SortKey[];
+export declare function weeklyPctOf(q: {
+    weeklyPct?: number;
+    usedPct?: number;
+} | null | undefined): number | undefined;
 export declare function fmtDuration(ms: number): string;
+export declare function weekdayOf(iso: string | undefined): string;
 export declare function countdownText(ps: ProviderSnapshot, now: Date): string;
 export declare function elapsedPct(ps: ProviderSnapshot, now: Date): number | null;
 export declare function usedPctOf(ps: ProviderSnapshot): number | null;

package/dist/format/rows.js

@@ -9,6 +9,11 @@ function msOf(iso) {
     const ms = new Date(iso).getTime();
     return Number.isNaN(ms) ? null : ms;
 }
+// The CLI talks HTTP to a daemon that may predate the rename, which sent only
+// `usedPct`. Read both for one release; drop the fallback with the aliases.
+export function weeklyPctOf(q) {
+    return q?.weeklyPct ?? q?.usedPct;
+}
 // Compact duration: 7d / 12h / 45m. Countdown convention floors; sub-minute
 // spans read 1m so a live window never prints 0m.
 export function fmtDuration(ms) {
@@ -18,6 +23,12 @@ export function fmtDuration(ms) {
         return `${Math.floor(ms / HOUR_MS)}h`;
     return `${Math.max(1, Math.floor(ms / MIN_MS))}m`;
 }
+// Short weekday of an ISO instant in the locked English copy, e.g. "Tue".
+// Pinned to en-US: the sentence it feeds ("unused until Tue") is English, so
+// a non-English machine must not print a localized weekday inside it.
+export function weekdayOf(iso) {
+    return new Date(iso ?? "").toLocaleDateString("en-US", { weekday: "short" });
+}
 export function countdownText(ps, now) {
     const resetsMs = msOf(ps.quota?.resetsAt);
     let text;
@@ -40,14 +51,14 @@ export function elapsedPct(ps, now) {
     return Math.round(Math.min(100, Math.max(0, pct)));
 }
 export function usedPctOf(ps) {
-    const u = ps.quota?.usedPct;
+    const u = weeklyPctOf(ps.quota);
     return typeof u === "number" && Number.isFinite(u) ? Math.round(u) : null;
 }
 export function railCells(ps, now) {
     const cells = new Array(RAIL_CELLS).fill("unused");
     if (ps.exclusionReason !== null)
         return cells;
-    const u = ps.quota?.usedPct;
+    const u = weeklyPctOf(ps.quota);
     const used = typeof u === "number" && Number.isFinite(u)
         ? Math.min(RAIL_CELLS, Math.max(0, Math.round((u / 100) * RAIL_CELLS)))
         : 0;
@@ -70,6 +81,10 @@ export function stateWord(ps) {
     const adv = ps.advisory;
     if (!adv)
         return "Not reporting";
+    // A blocked month outranks every weekly verdict: weekly leftover cannot be
+    // spent until the month resets.
+    if (adv.bindingWindow === "monthly" && adv.bindingRemaining === 0)
+        return "Monthly exhausted";
     if (adv.status === "at risk")
         return "Cap risk";
     if (adv.status === "watch")
@@ -124,7 +139,13 @@ export function forecastText(ps, now) {
     if (!adv)
         return "no readings yet";
     let text;
-    if (adv.remaining <= 0) {
+    if (adv.bindingWindow === "monthly" && adv.bindingRemaining <= 0) {
+        text = `unused until ${weekdayOf(ps.quota?.monthlyResetsAt)}`;
+    }
+    else if (adv.bindingWindow === "monthly") {
+        text = `${Math.round(adv.bindingRemaining)}% of month left`;
+    }
+    else if (adv.remaining <= 0) {
         text = "Exhausted";
     }
     else if (adv.paceSource === "unknown" || adv.burnRate === null) {
@@ -179,7 +200,7 @@ function wasteOf(p) {
     return typeof w === "number" && Number.isFinite(w) ? w : null;
 }
 function finiteUsed(p) {
-    const u = p.quota?.usedPct;
+    const u = weeklyPctOf(p.quota);
     return typeof u === "number" && Number.isFinite(u) ? u : null;
 }
 export function sortProviders(providers, key, use) {
@@ -192,6 +213,8 @@ export function sortProviders(providers, key, use) {
                     return 0;
                 if (p.exclusionReason !== null)
                     return 2;
+                if (p.advisory?.bindingWindow === "monthly" && p.advisory.bindingRemaining === 0)
+                    return 2;
                 return 1;
             };
             indexed.sort((a, b) => {

package/dist/format/terminal.js

@@ -1,4 +1,4 @@
-import { buildRow, compactSuffix, sortProviders, } from "./rows.js";
+import { buildRow, compactSuffix, sortProviders, weeklyPctOf, } from "./rows.js";
 const GAP = "  ";
 const MIN_PROV_WIDTH = 12;
 const MAX_PROV_WIDTH = 22;
@@ -32,6 +32,7 @@ const STATE_COLORS = {
     "Cap risk": "\x1b[31m",
     "Measuring": "\x1b[90m",
     "Not reporting": "\x1b[90m",
+    "Monthly exhausted": "\x1b[31m",
 };
 // provWidth covers the 2-char prefix plus name, measured before ANSI.
 export function provWidthFor(ids) {
@@ -92,7 +93,7 @@ export function renderWide(snapshot, opts) {
         "PACE (%/DAY)".padEnd(paceWidth),
         "USED VS TIME".padEnd(20),
         "RESETS".padEnd(9),
-        "STATE".padEnd(15),
+        "STATE".padEnd(19),
         "FORECAST",
     ].join(GAP);
     const lines = rows.map(({ p, row }) => {
@@ -103,7 +104,7 @@ export function renderWide(snapshot, opts) {
         const pace = (opts.ascii ? asciiText(row.pace) : row.pace).padEnd(paceWidth);
         const rail = renderRail(row.railCells, g, row.state, color);
         const countdown = (opts.ascii ? asciiText(row.countdown) : row.countdown).padEnd(9);
-        const state = row.state.padEnd(15);
+        const state = row.state.padEnd(19);
         const forecast = opts.ascii ? asciiText(row.forecast) : row.forecast;
         const main = [
             color ? colorProviderField(name, recommended, row.state) : name,
@@ -158,7 +159,7 @@ export function renderCompact(snapshot, _now) {
     const entries = sorted
         .filter((p) => p.quota !== null)
         .map((p) => {
-        const u = p.quota?.usedPct;
+        const u = weeklyPctOf(p.quota);
         const used = typeof u === "number" && Number.isFinite(u) ? String(Math.round(u)) : "?";
         return `[${p.id}:${used}%${compactSuffix(p)}]`;
     });

package/dist/http/server.js

@@ -220,7 +220,7 @@ export function buildApp(ctx) {
         for (const [id, catalog] of catalogs) {
             const identity = providerIdentity(id, ctx.providerNames);
             const quota = quotaMap.get(id);
-            const leftoverPct = quota?.usedPct != null ? Math.round((100 - quota.usedPct) * 10) / 10 : null;
+            const leftoverPct = quota?.weeklyPct != null ? Math.round((100 - quota.weeklyPct) * 10) / 10 : null;
             out.push({
                 id,
                 displayName: identity.displayName,
@@ -452,8 +452,8 @@ export function buildApp(ctx) {
             upsertQuota(ctx.db, {
                 provider: parsed.provider,
                 plan: parsed.plan,
-                usedPct: parsed.usedPct,
-                sessionPct: parsed.sessionPct,
+                weeklyPct: parsed.weeklyPct,
+                fiveHourPct: parsed.fiveHourPct,
                 resetsAt: parsed.resetsAt,
                 periodStart: parsed.periodStart,
                 source: "manual",

package/dist/runtime/poll.js

@@ -138,7 +138,7 @@ export function createCoordinator(opts) {
                     success: true,
                     failureCategory: null,
                 });
-                const usedPct = row.value?.usedPct;
+                const usedPct = row.value?.weeklyPct;
                 const pctSuffix = typeof usedPct === "number" && Number.isFinite(usedPct)
                     ? ` (${usedPct}% used)`
                     : "";