quotacap 0.0.34 → 0.0.35

package/dist/format/rows.js

@@ -61,7 +61,9 @@ export function railCells(ps, now) {
     return cells;
 }
 // Shared STATE vocabulary (locked badge mapping): any exclusion reads
-// Not reporting; at-risk status beats urgency; urgency maps to pace words.
+// Not reporting; at-risk status beats urgency, then watch, then unknown;
+// on-track rows ahead of cumulative elapsed time revive Ahead of pace;
+// urgency maps to the remaining pace words.
 export function stateWord(ps) {
     if (ps.exclusionReason !== null)
         return "Not reporting";
@@ -70,8 +72,12 @@ export function stateWord(ps) {
         return "Not reporting";
     if (adv.status === "at risk")
         return "Cap risk";
+    if (adv.status === "watch")
+        return "Watch";
     if (adv.status === "unknown")
         return "Measuring";
+    if (adv.aheadOfElapsed === true)
+        return "Ahead of pace";
     switch (adv.urgency) {
         case "burn now":
         case "use soon":
@@ -124,6 +130,12 @@ export function forecastText(ps, now) {
     else if (adv.paceSource === "unknown" || adv.burnRate === null) {
         text = `Measuring pace; ${Math.round(adv.remaining)}% remains with ${adv.daysLeft.toFixed(1)}d until reset`;
     }
+    else if (adv.status === "watch") {
+        text =
+            adv.daysToExhaust !== null && Number.isFinite(adv.daysToExhaust)
+                ? `Exhausts in ${adv.daysToExhaust.toFixed(1)}d — watch`
+                : "Near the cap — watch";
+    }
     else if (adv.wastePct !== null && adv.wastePct > 0) {
         text = `${Math.round(adv.wastePct)}% waste in ${adv.daysLeft.toFixed(1)}d`;
     }
@@ -141,8 +153,8 @@ export function forecastText(ps, now) {
     }
     return text;
 }
-// Compact legend: none = On track; ! = Cap risk; ~ = Behind/Ahead pace or
-// estimated reset; ? = unknown pace or any excluded row.
+// Compact legend: none = On track; ! = Cap risk; ~ = Watch or Behind/Ahead
+// pace or estimated reset; ? = unknown pace or any excluded row.
 export function compactSuffix(ps) {
     if (ps.exclusionReason !== null)
         return "?";
@@ -151,6 +163,8 @@ export function compactSuffix(ps) {
         return "?";
     if (adv.status === "at risk")
         return "!";
+    if (adv.status === "watch")
+        return "~";
     if (adv.urgency !== "on track" || ps.quota?.resetsAtEstimated)
         return "~";
     return "";
@@ -243,7 +257,13 @@ export function paceText(ps) {
         return "—";
     // avgPace is absent on advisories from a daemon older than the split.
     const avg = adv.avgPace ?? null;
-    const recent = adv.paceSource === "recent" ? adv.burnRate : null;
+    // The 24h figure is the measured recentRate, never the blended forecast
+    // input; an older daemon omits the field and burnRate was the raw rate then.
+    const recent = adv.recentRate !== undefined
+        ? adv.recentRate
+        : adv.paceSource === "recent"
+            ? adv.burnRate
+            : null;
     if (avg !== null && recent !== null && avg.toFixed(1) !== recent.toFixed(1)) {
         return `${avg.toFixed(1)} avg · ${recent.toFixed(1)} 24h`;
     }

package/dist/format/terminal.js

@@ -28,6 +28,7 @@ const STATE_COLORS = {
     "On track": "\x1b[32m",
     "Behind pace": "\x1b[33m",
     "Ahead of pace": "\x1b[93m",
+    "Watch": "\x1b[38;5;214m",
     "Cap risk": "\x1b[31m",
     "Measuring": "\x1b[90m",
     "Not reporting": "\x1b[90m",
@@ -76,6 +77,14 @@ export function renderWide(snapshot, opts) {
     const rows = sorted.map((p) => ({ p, row: buildRow(p, opts.now) }));
     const paceWidth = Math.max("PACE (%/DAY)".length, ...rows.map(({ row }) => row.pace.length));
     const paint = (s, code) => (color ? `${code}${s}${RESET}` : s);
+    const resetsIndent = " ".repeat(width + GAP.length + 6 + GAP.length + 8 + GAP.length + paceWidth + GAP.length + 20 + GAP.length);
+    const leftoverLine = (p) => {
+        const close = p.lastCloses?.[0];
+        if (!close)
+            return null;
+        const tail = `last week ${close.leftoverPct}% leftover${close.resetsAtEstimated ? " (est.)" : ""}`;
+        return `${resetsIndent}${paint(tail, DIM)}`;
+    };
     const header = [
         "PROVIDER".padEnd(width),
         "USED".padStart(6),
@@ -96,7 +105,7 @@ export function renderWide(snapshot, opts) {
         const countdown = (opts.ascii ? asciiText(row.countdown) : row.countdown).padEnd(9);
         const state = row.state.padEnd(15);
         const forecast = opts.ascii ? asciiText(row.forecast) : row.forecast;
-        return [
+        const main = [
             color ? colorProviderField(name, recommended, row.state) : name,
             used,
             elapsed,
@@ -106,6 +115,8 @@ export function renderWide(snapshot, opts) {
             paint(state, STATE_COLORS[row.state]),
             forecast,
         ].join(GAP);
+        const leftover = leftoverLine(p);
+        return leftover ? `${main}\n${leftover}` : main;
     });
     return [paint(header, DIM), ...lines].join("\n");
 }
@@ -129,6 +140,12 @@ export function renderNarrow(snapshot, opts) {
         const paceBits = row.pace === "—" ? pace : `${pace} %/day`;
         const state = color ? `${STATE_COLORS[row.state]}${row.state}${RESET}` : row.state;
         lines.push(`${color ? colorProviderField(name, recommended, row.state) : name} ${used} used ${g.sep} ${elapsed} elapsed ${g.sep} ${paceBits}`, `${rail} resets ${countdown} ${g.sep} ${state} ${g.sep} ${forecast}`);
+        const close = p.lastCloses?.[0];
+        if (close) {
+            const indent = " ".repeat(row.railCells.length + " resets ".length);
+            const tail = `last week ${close.leftoverPct}% leftover${close.resetsAtEstimated ? " (est.)" : ""}`;
+            lines.push(`${indent}${color ? `${DIM}${tail}${RESET}` : tail}`);
+        }
     }
     return lines.join("\n");
 }

package/dist/http/server.d.ts

@@ -30,6 +30,8 @@ export interface RuntimeContext {
         exec?: string;
     }) => void;
     configPath?: string;
+    catalogTtlHours?: number;
+    catalogFetchers?: Record<string, any>;
 }
 export declare function testCtx(db: any, overrides?: Partial<RuntimeContext>): RuntimeContext;
 export declare function buildApp(ctx: RuntimeContext): FastifyInstance;

package/dist/http/server.js

@@ -16,6 +16,8 @@ import { classifyFailure } from "../diagnostics/failure.js";
 import { validateDisplayName } from "../advisory/validation.js";
 import { providerIdentity } from "../advisory/provider-names.js";
 import { setProviderNameOverride } from "../config.js";
+import { ensureCatalogs, catalogProviders, CATALOG_FAIL_COOLDOWN_MS } from "../catalog/index.js";
+import { getAllLatest } from "../store/quotas.js";
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "[::1]", "::1"]);
 export function hostnameFromHostHeader(hostHeader) {
     if (typeof hostHeader !== "string" || !hostHeader.trim())
@@ -208,6 +210,104 @@ export function buildApp(ctx) {
             };
         }
     });
+    // --- Model catalog ---
+    const catalogTtl = ctx.catalogTtlHours ?? 6;
+    function projectModels(catalogs, quotaMap) {
+        const out = [];
+        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;
+            out.push({
+                id,
+                displayName: identity.displayName,
+                harness: identity.harness,
+                vendor: identity.vendor,
+                leftoverPct,
+                resetsAt: quota?.resetsAt ?? null,
+                catalog,
+            });
+        }
+        return out;
+    }
+    app.get("/api/models", async (req, reply) => {
+        const providerParam = req.query?.provider;
+        const allProviders = catalogProviders(ctx.enabledProviders);
+        const providers = providerParam
+            ? [String(providerParam)]
+            : allProviders;
+        // Unknown provider: 400 before the (expensive) waiting ensure.
+        if (providerParam) {
+            const known = new Set(allProviders);
+            if (!known.has(providerParam)) {
+                return reply.status(400).send({ error: `unknown provider: ${providerParam}` });
+            }
+        }
+        const catalogs = await ensureCatalogs({
+            db: ctx.db,
+            wait: true,
+            providers,
+            ttlHours: catalogTtl,
+            now: ctx.now,
+            fetchers: ctx.catalogFetchers,
+        });
+        const quotas = getAllLatest(ctx.db);
+        const quotaMap = new Map(quotas.map((q) => [q.provider, q]));
+        return projectModels(catalogs, quotaMap);
+    });
+    let lastModelsRefreshAt = 0;
+    app.post("/api/models/refresh", async (req, reply) => {
+        const headerToken = req.headers["x-quotacap-token"];
+        if (!isValidToken(headerToken, ctx.token)) {
+            return reply.status(401).send({ error: "unauthorized: missing or invalid X-QuotaCap-Token header" });
+        }
+        const providerParam = req.query?.provider ?? req.body?.provider;
+        const allProviders = catalogProviders(ctx.enabledProviders);
+        if (providerParam) {
+            const known = new Set(allProviders);
+            if (!known.has(providerParam)) {
+                return reply.status(400).send({ error: `unknown provider: ${providerParam}` });
+            }
+        }
+        const providers = providerParam ? [String(providerParam)] : allProviders;
+        const nowMs = (ctx.now?.() ?? new Date()).getTime();
+        if (lastModelsRefreshAt > 0 && nowMs - lastModelsRefreshAt < CATALOG_FAIL_COOLDOWN_MS) {
+            const catalogs = await ensureCatalogs({
+                db: ctx.db,
+                wait: false,
+                providers,
+                ttlHours: catalogTtl,
+                now: ctx.now,
+                fetchers: ctx.catalogFetchers,
+            });
+            const quotas = getAllLatest(ctx.db);
+            const quotaMap = new Map(quotas.map((q) => [q.provider, q]));
+            const models = projectModels(catalogs, quotaMap);
+            return {
+                cooldown: true,
+                models,
+                results: models,
+            };
+        }
+        const catalogs = await ensureCatalogs({
+            db: ctx.db,
+            wait: true,
+            refresh: true,
+            providers,
+            ttlHours: catalogTtl,
+            now: ctx.now,
+            fetchers: ctx.catalogFetchers,
+        });
+        const quotas = getAllLatest(ctx.db);
+        const quotaMap = new Map(quotas.map((q) => [q.provider, q]));
+        const models = projectModels(catalogs, quotaMap);
+        lastModelsRefreshAt = nowMs;
+        return {
+            cooldown: false,
+            models,
+            results: models,
+        };
+    });
     app.patch("/api/providers/:id", async (req, reply) => {
         const headerToken = req.headers["x-quotacap-token"];
         if (!isValidToken(headerToken, ctx.token)) {

package/dist/mcp/server.d.ts

@@ -23,6 +23,19 @@ export declare const tools: ({
         };
         required?: undefined;
     };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            provider: {
+                type: string;
+            };
+            task?: undefined;
+        };
+        required?: undefined;
+    };
 } | {
     name: string;
     description: string;

package/dist/mcp/server.js

@@ -3,13 +3,15 @@ import { projectQuotasResponse, projectRecommendationResponse, } from "../adviso
 import { validateForecastProvider, validateTask } from "../advisory/validate.js";
 import { getDbPath, readConfig } from "../config.js";
 import { forecastText, stateWord } from "../format/rows.js";
-import { renderMarkdownTable, renderRecommendationSummary } from "../format/markdown.js";
-import { createServiceClientForBase } from "../runtime/client.js";
+import { renderMarkdownTable, renderRecommendationSummary, renderModelsMarkdownTable } from "../format/markdown.js";
+import { createServiceClientForBase, ServiceUnavailable } from "../runtime/client.js";
+import { CATALOG_CLIENT_TIMEOUT_MS } from "../catalog/index.js";
 import { VERSION } from "../version.js";
 import { ClientError, OFFLINE_LABEL, resolveSnapshot, } from "../cli/snapshot-source.js";
 export const tools = [
     { name: "get_quotas", description: "All quotas with resets and health", inputSchema: { type: "object", properties: {}, required: [] } },
     { name: "get_recommendation", description: "Which provider to use next (same advice for every task)", inputSchema: { type: "object", properties: { task: { type: "string", enum: ["any", "heavy", "light"] } } } },
+    { name: "get_models", description: "Currently listed models per quota bucket (inventory, not a task ranking)", inputSchema: { type: "object", properties: { provider: { type: "string" } } } },
     { name: "forecast", description: "Burn (24h + window avg) vs ideal + waste for a provider", inputSchema: { type: "object", properties: { provider: { type: "string" } }, required: ["provider"] } },
 ];
 // QUOTACAP_URL is used as configured: scheme, authority, effective port and
@@ -72,6 +74,28 @@ export async function handleTool(name, args) {
             ],
         };
     }
+    if (name === "get_models") {
+        const provider = args?.provider;
+        const base = process.env.QUOTACAP_URL ?? "http://localhost:8787";
+        const client = createServiceClientForBase(base, { timeoutMs: CATALOG_CLIENT_TIMEOUT_MS });
+        const url = provider ? `/api/models?provider=${encodeURIComponent(provider)}` : "/api/models";
+        try {
+            const body = await client.get(url);
+            const list = Array.isArray(body) ? body : (body?.models ?? []);
+            return {
+                content: [
+                    { type: "text", text: renderModelsMarkdownTable(list) },
+                    { type: "text", text: JSON.stringify(body, null, 2) },
+                ],
+            };
+        }
+        catch (err) {
+            if (err instanceof ServiceUnavailable) {
+                throw new Error("model catalog unavailable (daemon unreachable)");
+            }
+            throw err;
+        }
+    }
     if (name === "forecast") {
         rejectMissingProvider(args);
         const { snapshot, source } = await resolveState();
@@ -91,6 +115,7 @@ export async function handleTool(name, args) {
             state: stateWord(ps),
             forecast: forecastText(ps, new Date()),
             lastAttempt: ps.lastAttempt,
+            lastCloses: ps.lastCloses,
         };
         return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
     }
@@ -137,8 +162,11 @@ export async function runMcpServer() {
                 try {
                     const result = await handleTool(toolName, toolArgs);
                     const content = Array.isArray(result?.content) ? result.content : [{ type: "text", text: JSON.stringify(result, null, 2) }];
+                    const res = { content };
+                    if (result?.isError)
+                        res.isError = true;
                     if (!isNotification)
-                        respond(id, { content });
+                        respond(id, res);
                 }
                 catch (e) {
                     const content = [{ type: "text", text: e?.message ?? String(e) }];

package/dist/runtime/poll.d.ts

@@ -54,5 +54,18 @@ export interface Coordinator {
     setClosing(): void;
     isClosing(): boolean;
 }
+export declare const PRE_RESET_LEAD_MS: number;
+export declare const PRE_RESET_MIN_REMAINING_MS: number;
+export declare function nextPollDelayMs(opts: {
+    nowMs: number;
+    intervalMs: number;
+    latest: Array<{
+        provider: string;
+        resetsAt?: string | null;
+        resetsAtEstimated?: boolean;
+    }>;
+    lastCompletedPollAtMs: number | null;
+    enabledProviders: string[];
+}): number;
 export declare function mapFailureCategory(reason: unknown): Exclude<FailureCategory, null>;
 export declare function createCoordinator(opts: CoordinatorOptions): Coordinator;

package/dist/runtime/poll.js

@@ -1,7 +1,7 @@
 // Poll coordinator: scheduled and manual refresh share one in-flight poll
 // with a completion-measured cooldown (decisions D3/D4).
 import { pollAll } from "../adapters/index.js";
-import { upsertQuota } from "../store/quotas.js";
+import { getAllLatest, upsertQuota } from "../store/quotas.js";
 import { recordAttempt, getAttempt, } from "../store/attempts.js";
 import { classifyFailure, } from "../diagnostics/failure.js";
 export class ServiceClosing extends Error {
@@ -13,6 +13,32 @@ export class ServiceClosing extends Error {
 function defaultPollFn(enabled) {
     return pollAll(enabled);
 }
+export const PRE_RESET_LEAD_MS = 5 * 60 * 1000;
+export const PRE_RESET_MIN_REMAINING_MS = 25 * 1000;
+export function nextPollDelayMs(opts) {
+    const { nowMs, intervalMs, latest, lastCompletedPollAtMs, enabledProviders } = opts;
+    let best = intervalMs;
+    for (const row of latest) {
+        const enabled = enabledProviders.includes(row.provider) ||
+            (row.provider.startsWith("agy:") && enabledProviders.includes("agy"));
+        if (!enabled || row.resetsAtEstimated || !row.resetsAt)
+            continue;
+        const resetsMs = new Date(row.resetsAt).getTime();
+        if (Number.isNaN(resetsMs) || resetsMs <= nowMs || resetsMs - nowMs < PRE_RESET_MIN_REMAINING_MS) {
+            continue;
+        }
+        const target = resetsMs - PRE_RESET_LEAD_MS;
+        if (lastCompletedPollAtMs !== null &&
+            lastCompletedPollAtMs >= target &&
+            lastCompletedPollAtMs < resetsMs) {
+            continue;
+        }
+        const raw = Math.max(0, target - nowMs);
+        const delay = raw === 0 ? 1000 : raw;
+        best = Math.min(best, Math.min(intervalMs, delay));
+    }
+    return best;
+}
 export function mapFailureCategory(reason) {
     return classifyFailure("Provider", reason).category;
 }
@@ -42,7 +68,13 @@ export function createCoordinator(opts) {
                 const detail = classifyFailure("all", e).errorDetail;
                 console.warn("[quotacap] scheduled poll failed", detail);
             });
-        }, intervalMs);
+        }, nextPollDelayMs({
+            nowMs: now(),
+            intervalMs,
+            latest: getAllLatest(db),
+            lastCompletedPollAtMs: lastCompletedPollAt ? completedAtMs : null,
+            enabledProviders,
+        }));
     }
     async function runGeneration() {
         const attemptedAt = new Date(now()).toISOString();

package/dist/runtime/service.js

@@ -17,6 +17,7 @@ import { detectChannel, refreshUpdateCache } from "./updates.js";
 import { VERSION } from "../version.js";
 import { claudeAdapter } from "../adapters/claude.js";
 import { classifyFailure } from "../diagnostics/failure.js";
+import { ensureCatalogs, catalogProviders } from "../catalog/index.js";
 export function resolveClaudeExecPath() {
     try {
         const resolved = execFileSync("which", ["claude"], {
@@ -198,6 +199,7 @@ export async function startService(opts) {
             coordinator,
             enabledProviders: config.enabledProviders,
             providerNames: config.providerNames,
+            catalogTtlHours: config.catalogTtlHours,
             version: VERSION,
             exec: process.execPath,
             canWrite: () => claim.verify(),
@@ -231,6 +233,13 @@ export async function startService(opts) {
         console.warn("[quotacap] initial poll failed", detail);
     });
     coordinator.start(config.pollMinutes * 60 * 1000);
+    // Background catalog warm: wait: true after listen, never blocks /health ready.
+    void ensureCatalogs({
+        db,
+        wait: true,
+        providers: catalogProviders(config.enabledProviders),
+        ttlHours: config.catalogTtlHours,
+    }).catch(() => { });
     let stopping = false;
     let stopped = false;
     async function stop() {

package/dist/store/catalogs.d.ts

@@ -0,0 +1,10 @@
+import { type CatalogView, type ListedModel } from "../catalog/types.js";
+export declare function getCatalog(db: any, provider: string): CatalogView;
+export declare function getCatalogs(db: any): Map<string, CatalogView>;
+export declare function upsertCatalog(db: any, provider: string, listed: ListedModel[], fetchedAt: string): void;
+export declare function markCatalogFailure(db: any, provider: string, diag: {
+    diagnosticCode: string;
+    summary: string;
+    action: string;
+    errorDetail: string;
+}): void;

package/dist/store/catalogs.js

@@ -0,0 +1,64 @@
+import { emptyCatalog } from "../catalog/types.js";
+function isMissingTable(e) {
+    return /no such table/i.test(e?.message ?? "");
+}
+function mapCatalog(r) {
+    return {
+        status: r.status,
+        fetchedAt: r.fetched_at ?? null,
+        listed: JSON.parse(r.models_json ?? "[]"),
+        diagnosticCode: r.diagnostic_code ?? null,
+        summary: r.summary ?? null,
+        action: r.action ?? null,
+    };
+}
+export function getCatalog(db, provider) {
+    let r;
+    try {
+        r = db.prepare(`SELECT * FROM model_catalogs WHERE provider=?`).get(provider);
+    }
+    catch (e) {
+        // Pre-catalog DB or an offline file the daemon has not migrated: read as
+        // unfetched. Never migrate or throw from a read helper.
+        if (isMissingTable(e))
+            return emptyCatalog();
+        throw e;
+    }
+    if (!r)
+        return emptyCatalog();
+    return mapCatalog(r);
+}
+export function getCatalogs(db) {
+    let rows;
+    try {
+        rows = db.prepare(`SELECT * FROM model_catalogs`).all();
+    }
+    catch (e) {
+        if (isMissingTable(e))
+            return new Map();
+        throw e;
+    }
+    return new Map(rows.map((r) => [r.provider, mapCatalog(r)]));
+}
+export function upsertCatalog(db, provider, listed, fetchedAt) {
+    db.prepare(`INSERT INTO model_catalogs(provider, status, models_json, fetched_at, diagnostic_code, summary, action, error_detail)
+    VALUES(?,?,?,?,NULL,NULL,NULL,NULL)
+    ON CONFLICT(provider) DO UPDATE SET status=excluded.status, models_json=excluded.models_json, fetched_at=excluded.fetched_at,
+    diagnostic_code=NULL, summary=NULL, action=NULL, error_detail=NULL`)
+        .run(provider, "ok", JSON.stringify(listed), fetchedAt);
+}
+export function markCatalogFailure(db, provider, diag) {
+    const row = db.prepare(`SELECT status FROM model_catalogs WHERE provider=?`).get(provider);
+    if (row) {
+        // A prior success degrades to stale and keeps models_json/fetched_at; a
+        // repeated failure on an error row stays error.
+        const status = row.status === "ok" ? "stale" : row.status;
+        db.prepare(`UPDATE model_catalogs SET status=?, diagnostic_code=?, summary=?, action=?, error_detail=? WHERE provider=?`)
+            .run(status, diag.diagnosticCode, diag.summary, diag.action, diag.errorDetail, provider);
+    }
+    else {
+        db.prepare(`INSERT INTO model_catalogs(provider, status, models_json, fetched_at, diagnostic_code, summary, action, error_detail)
+      VALUES(?, 'error', '[]', NULL, ?,?,?,?)`)
+            .run(provider, diag.diagnosticCode, diag.summary, diag.action, diag.errorDetail);
+    }
+}

package/dist/store/db.js

@@ -39,7 +39,33 @@ export function migrate(db) {
     db.exec(`CREATE TABLE IF NOT EXISTS quotas(id INTEGER PRIMARY KEY, provider TEXT, plan TEXT, used_pct REAL, resets_at TEXT, period_start TEXT, source TEXT, fetched_at TEXT, credits_usd REAL, resets_at_estimated INTEGER, session_pct REAL);
            CREATE TABLE IF NOT EXISTS snapshots(day TEXT, provider TEXT, used_pct REAL, burn_rate REAL, ideal_rate REAL, PRIMARY KEY(day, provider));
            CREATE TABLE IF NOT EXISTS adapter_attempts(provider TEXT PRIMARY KEY, attempted_at TEXT NOT NULL, completed_at TEXT, succeeded_at TEXT, success INTEGER NOT NULL, failure_category TEXT, diagnostic_code TEXT, summary TEXT, action TEXT, error_detail TEXT);
-           CREATE INDEX IF NOT EXISTS idx_quotas_provider ON quotas(provider);`);
+           CREATE INDEX IF NOT EXISTS idx_quotas_provider ON quotas(provider);
+           CREATE TABLE IF NOT EXISTS model_catalogs(
+             provider TEXT PRIMARY KEY,
+             fetched_at TEXT,
+             status TEXT NOT NULL,
+             models_json TEXT NOT NULL,
+             diagnostic_code TEXT,
+             summary TEXT,
+             action TEXT,
+             error_detail TEXT
+           );
+           CREATE TABLE IF NOT EXISTS window_closes(
+             id INTEGER PRIMARY KEY,
+             provider TEXT NOT NULL,
+             plan TEXT,
+             used_pct REAL NOT NULL,
+             leftover_pct REAL NOT NULL,
+             sampled_at TEXT NOT NULL,
+             sampled_quota_id INTEGER NOT NULL,
+             period_start TEXT,
+             resets_at TEXT,
+             resets_at_estimated INTEGER,
+             detected_at TEXT NOT NULL,
+             reason TEXT NOT NULL,
+             UNIQUE(provider, sampled_quota_id)
+           );
+           CREATE INDEX IF NOT EXISTS idx_window_closes_provider_detected ON window_closes(provider, detected_at DESC);`);
     try {
         const cols = db.prepare(`PRAGMA table_info(quotas)`).all();
         const names = new Set(cols.map((c) => c.name));

package/dist/store/quotas.d.ts

@@ -1,6 +1,28 @@
+export declare function isWeeklyCycleBreak(prev: {
+    usedPct: number;
+    t: number;
+    resetsAt: string | null;
+}, cur: {
+    usedPct: number;
+    t: number;
+    resetsAt: string | null;
+}): boolean;
 export declare function upsertQuota(db: any, q: any): void;
+export declare function getWindowCloses(db: any, provider: string, limit?: number): Array<{
+    provider: string;
+    plan: string | null;
+    usedPct: number;
+    leftoverPct: number;
+    sampledAt: string;
+    periodStart: string | null;
+    resetsAt: string | null;
+    resetsAtEstimated: boolean;
+    detectedAt: string;
+    reason: "usage-drop" | "resets-at-rolled" | "both";
+}>;
 export declare function getLatestByProvider(db: any, provider: string): any;
 export declare function getAllLatest(db: any): any;
 export declare const getQuotas: typeof getAllLatest;
 export declare function getSnapshots(db: any): any;
 export declare function getBurnRates(db: any, now?: number): Map<string, number>;
+export declare function getHistoryBaseline(db: any, limit?: number): Map<string, number>;