estela 0.2.3 → 0.3.0

package/README.md

@@ -273,6 +273,61 @@ anything you use on claude.ai or another machine counts too but isn't on this
 one. Copilot is left out because it doesn't record reliable tokens. Everything
 is calculated on your machine.
 
+## Is your Claude plan the right one?
+
+```sh
+estela plan set max5            # pro | max5 | max20; add --since YYYY-MM-DD if you had it before today
+estela plan                     # last 28 days; --days N, --json, --no-color
+```
+
+Answers "is the Claude plan I pay for too big or too small?" with your own data:
+the 5-hour and weekly percentages Claude Code sends to the status line (stored
+since 0.2.4, only in the terminal), and nothing else. Example (made-up data):
+
+```
+estela plan · Max 5x (since 2026-10-01) · 26 days with data
+
+5-hour windows       41 windows · median peak 22% · p90 38% · max 61%
+Caps (≥95%)          0
+Week                 median peak 34% · max 47% · 0 weeks ≥ 90%
+Blocks (429)         0 5-hour · 0 weekly, from Claude Code's transcripts
+
+If you were on…
+  Pro ($20)          equivalent p90 190% · would have blocked you in 29 of 41 windows
+  Max 20x ($200)     no caps, same as now
+
+Recommendation       Your current plan fits your usage.
+```
+
+- **It never invents or estimates a plan's limit.** Other plans are compared only
+  on the 5-hour window, using the per-session multiplier Anthropic publishes
+  (Max 5x = 5 × Pro, Max 20x = 20 × Pro;
+  [source](https://support.claude.com/en/articles/11049741-what-is-the-max-plan)):
+  an equivalent peak is your peak × your multiplier ÷ the other plan's. Anthropic
+  doesn't publish the weekly limit between plans, so that comparison isn't made.
+  It never says how much you have left.
+- A window with a peak of 95% or more is a cap. The time stopped after a cap
+  (from the first sample at 99% to the reset) is an upper bound: we don't know if
+  you kept working.
+- "Blocks (429)" are the rate-limit responses Claude Code wrote in its
+  transcripts. They're official and go back before 0.2.4, but carry no
+  percentage, so they're shown apart and don't enter the calculation.
+- With fewer than 7 days of data there's no recommendation; from 7 to 13 it's
+  provisional. After a plan change only data since then counts.
+- Prices are Anthropic's website prices on the date in the output; check them.
+  Anthropic may change limits: run it again every month.
+
+`--json` returns the same figures with a stable structure (`version: 1`): `plan`,
+`period` (`from`, `to`, `days`, `daysWithData`, `samples`), `dataState`
+(`none` | `insufficient` | `provisional` | `ok`), `fiveHour` (`windows`,
+`medianPeak`, `p90Peak`, `maxPeak`, `caps`, `stoppedMinutesUpperBound`), `week`
+(`weeks`, `medianPeak`, `maxPeak`, `weeksAtOrAbove90`), `blocks429`,
+`alternatives[]` (`plan`, `direction`, `monthlyUsd`, `monthlyDiffUsd`,
+`p90Equivalent`, `maxEquivalent`, `blockedWindows`, `capsAvoided`),
+`recommendation` (`kind`: `tight` | `enough` | `almost` | `fits`, `plan`,
+`provisional`, `text`, or `null`), `weeklyBetweenPlans: "not_published"`,
+`sources` and `plans`. New fields may be added; none change meaning.
+
 ## A line under every Claude Code session
 
 ```sh
@@ -306,6 +361,16 @@ won't overwrite it: `--force` replaces it, `--append` shows yours after
 Estela's. `estela statusline uninstall` removes it (and puts yours back if
 you used `--append`).
 
+The status line only runs in Claude Code in the terminal: the VS Code
+extension doesn't show it.
+
+Since 0.2.4, the status line stores your 5-hour and weekly percentages locally
+(`~/.estela/rate-limits.jsonl`) so `estela plan` can analyse them. Nothing leaves
+your machine. Only what Claude Code sends is kept — each percentage, its reset
+time and the Claude Code version — at most every 5 minutes unless a figure moves,
+and for 120 days. Transcripts don't carry these percentages, so the history
+starts the day you install 0.2.4.
+
 ## Hours no import will infer
 
 Meetings, travel, research, and development without an agent that didn't leave

package/dist/cli.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.breakdownOfTurn = void 0;
+const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const node_readline_1 = require("node:readline");
 // `node:sqlite` avisa de que es experimental en cada arranque. Es ruido para
@@ -63,6 +64,12 @@ const invoice_pdf_js_1 = require("./export/invoice-pdf.js");
 const share_js_1 = require("./export/share.js");
 const server_js_1 = require("./server.js");
 const updateCheck_js_1 = require("./updateCheck.js");
+const plan_js_1 = require("./metrics/plan.js");
+const plan_blocks_js_1 = require("./plan-blocks.js");
+const plan_prices_js_1 = require("./plan-prices.js");
+const plan_report_js_1 = require("./plan-report.js");
+const rate_history_js_1 = require("./rate-history.js");
+const statusline_cache_js_1 = require("./statusline-cache.js");
 const publish_js_1 = require("./publish.js");
 const sync_js_1 = require("./sync.js");
 const team_js_1 = require("./sync/team.js");
@@ -169,6 +176,15 @@ estela — registro de horas para desarrollo asistido por IA
         Copilot queda fuera: no guarda tokens fiables. Antes de calcular
         lee los transcripts desde el lunes (--no-refresh lo evita).
         A diferencia de ai-cost, que reparte dinero, esto reparte tokens.
+
+  estela plan [--days <n>] [--json] [--no-color]
+  estela plan set pro|max5|max20 [--since AAAA-MM-DD]
+        ¿El plan de Claude que pagas te sobra o te falta? Analiza los
+        porcentajes de 5 h y semana que Claude Code manda a la status line
+        (solo en la terminal) y los compara con los otros planes usando el
+        multiplicador por sesión que publica Anthropic. El límite semanal
+        entre planes no se compara: no se publica. Primero declara tu plan
+        con "plan set". Por defecto, los últimos 28 días.
   estela statusline install [--force | --append]
         Una línea bajo cada sesión de Claude Code: proyecto, horas medidas
         hoy, la parte de tu consumo de la semana que es de este proyecto y,
@@ -369,6 +385,15 @@ estela — time tracking for AI-assisted development
         left out: it doesn't record reliable tokens. Before calculating it reads transcripts since Monday
         (--no-refresh skips that). Unlike ai-cost, which splits money, this
         splits tokens.
+
+  estela plan [--days <n>] [--json] [--no-color]
+  estela plan set pro|max5|max20 [--since YYYY-MM-DD]
+        Is your Claude plan too big or too small? It analyses the 5-hour
+        and weekly percentages Claude Code sends to the status line (only
+        in the terminal) and compares them with the other plans using the
+        per-session multiplier Anthropic publishes. The weekly limit isn't
+        compared across plans: it isn't published. Declare your plan first
+        with "plan set". Defaults to the last 28 days.
   estela statusline install [--force | --append]
         A line under every Claude Code session: project, hours measured
         today, this project's share of your usage this week and, if Claude
@@ -1544,6 +1569,90 @@ async function cmdUnpublish(args, dbPath) {
         db.close();
     }
 }
+/**
+ * `estela plan`: ¿el plan de Claude que pagas es el que te conviene?
+ *
+ * Solo con lo que manda Claude Code a la status line (rate-limits.jsonl) y el
+ * multiplicador por sesión que publica Anthropic. Ver metrics/plan.ts.
+ */
+function cmdPlan(args, dbPath) {
+    const db = (0, schema_js_1.openDatabase)(dbPath);
+    try {
+        const declared = store.getClaudePlan(db);
+        const json = args.flags["json"] === true;
+        if (!declared || !(0, plan_prices_js_1.planById)(declared.plan)) {
+            if (json)
+                console.log(JSON.stringify({ version: 1, plan: null }, null, 2));
+            else
+                console.log((0, plan_report_js_1.renderNoPlan)());
+            return;
+        }
+        const days = str(args, "days") === undefined ? 28 : Number(str(args, "days"));
+        if (!Number.isInteger(days) || days < 1 || days > rate_history_js_1.KEEP_DAYS) {
+            throw new UserError((0, index_js_1.tr) `--days tiene que ser un número entero de 1 a ${rate_history_js_1.KEEP_DAYS}.`);
+        }
+        const now = new Date();
+        const file = (0, rate_history_js_1.historyPath)(dbPath);
+        try {
+            (0, rate_history_js_1.pruneSamples)(file, now);
+        }
+        catch { /* sin rotar se analiza igual */ }
+        const all = (0, rate_history_js_1.readSamples)(file);
+        const analysis = (0, plan_js_1.analyzePlan)({ samples: all, plan: declared.plan, since: declared.since, now, days });
+        // Los 429 que Claude Code dejó en sus transcripts, en el mismo período.
+        let blocks = null;
+        try {
+            const found = (0, plan_blocks_js_1.scanBlocks)((0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "projects"), (0, plan_blocks_js_1.blocksCachePath)(dbPath), now)
+                .filter((b) => b.at >= analysis.from.getTime() && b.at <= now.getTime());
+            blocks = { fiveHour: found.filter((b) => b.type === "five_hour").length,
+                sevenDay: found.filter((b) => b.type === "seven_day").length };
+        }
+        catch { /* sin transcripts legibles, la línea no sale */ }
+        if (json) {
+            console.log(JSON.stringify((0, plan_report_js_1.planToJson)(analysis, { blocks, now }), null, 2));
+            return;
+        }
+        const color = args.flags["no-color"] !== true && !process.env["NO_COLOR"] && process.stdout.isTTY === true;
+        if (analysis.dataState === "none") {
+            // Sin ninguna muestra nunca, y la status line vio entradas sin rate_limits: API key.
+            const apiKey = all.length === 0 && (0, statusline_cache_js_1.loadCache)(dbPath).noLimitsAt !== undefined;
+            console.log((0, plan_report_js_1.renderNoData)(analysis, apiKey, color));
+            return;
+        }
+        console.log((0, plan_report_js_1.renderPlanReport)(analysis, { color, now, blocks }));
+    }
+    finally {
+        db.close();
+    }
+}
+/** `estela plan set pro|max5|max20 [--since AAAA-MM-DD]`. */
+function cmdPlanSet(args, dbPath) {
+    const id = args._[2] ?? "";
+    const plan = (0, plan_prices_js_1.planById)(id);
+    if (!plan)
+        throw new UserError((0, index_js_1.tr) `Plan desconocido: "${id}". Usa pro, max5 o max20.`);
+    const sinceText = str(args, "since");
+    let since = new Date();
+    if (sinceText !== undefined) {
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(sinceText) || Number.isNaN(new Date(`${sinceText}T00:00:00`).getTime())) {
+            throw new UserError((0, index_js_1.tr) `--since tiene que ser una fecha AAAA-MM-DD.`);
+        }
+        since = new Date(`${sinceText}T00:00:00`);
+    }
+    const db = (0, schema_js_1.openDatabase)(dbPath);
+    try {
+        store.setClaudePlan(db, plan.id, since);
+        const d = since;
+        const fecha = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+        console.log((0, index_js_1.tr) `Plan declarado: ${plan.name}, desde ${fecha}. El análisis solo usa lo guardado desde esa fecha.`);
+        if (sinceText === undefined) {
+            console.log((0, index_js_1.tr) `Si ya lo tenías antes, indica desde cuándo: estela plan set ${plan.id} --since AAAA-MM-DD`);
+        }
+    }
+    finally {
+        db.close();
+    }
+}
 /**
  * `estela sync enable --project <id>` — opt-in explícito, proyecto por
  * proyecto. Sin esta fila, ese proyecto no sale de esta máquina nunca, sea
@@ -2134,6 +2243,7 @@ function cmdStatuslineInstall(args) {
     }
     if (plan.status === "already") {
         console.log((0, index_js_1.tr) `La status line de Estela ya está instalada en ${path}.`);
+        console.log((0, index_js_1.tr) `Solo en Claude Code en la terminal: la extensión de VS Code no enseña la status line.`);
         return;
     }
     if (plan.status === "conflict") {
@@ -2158,6 +2268,9 @@ function cmdStatuslineInstall(args) {
             ? (0, index_js_1.tr) `Status line de Estela instalada en lugar de: ${plan.previous ?? ""}`
             : (0, index_js_1.tr) `Status line de Estela instalada en ${path}.`);
     console.log((0, index_js_1.tr) `Se verá en la próxima sesión de Claude Code (o al reiniciar la actual).`);
+    // Comprobado: la extensión de VS Code no ejecuta la status line. Sin este
+    // aviso, quien trabaja ahí cree que está instalada y no la ve nunca.
+    console.log((0, index_js_1.tr) `Solo en Claude Code en la terminal: la extensión de VS Code no enseña la status line.`);
     if (!(0, statusline_install_js_1.estelaOnPath)()) {
         console.log((0, index_js_1.tr) `\nAviso: "estela" no está en tu PATH, así que Claude Code no podrá ejecutarla.`);
         console.log((0, index_js_1.tr) `Instálala de forma global: npm install -g estela`);
@@ -2462,7 +2575,10 @@ async function main() {
     (0, client_js_1.setClientVersion)(VERSION);
     const dbPath = str(args, "db") ?? schema_js_1.DEFAULT_DB_PATH;
     // `estela unpublish <panel>` lleva el panel suelto, sin flag: no es un subcomando.
-    const command = args._[0] === "unpublish" ? "unpublish" : args._.join(" ");
+    const command = args._[0] === "unpublish" ? "unpublish"
+        // `estela plan set max5`: el plan va suelto, como el panel de unpublish.
+        : args._[0] === "plan" && args._[1] === "set" ? "plan set"
+            : args._.join(" ");
     // Se llama aquí, no al final: un comando que falla a medias (por ejemplo
     // "estela import" sin repositorios) debe avisar igual de que hay una
     // versión nueva, no solo los que terminan bien.
@@ -2549,6 +2665,12 @@ async function main() {
         case "unpublish":
             await cmdUnpublish(args, dbPath);
             break;
+        case "plan":
+            cmdPlan(args, dbPath);
+            break;
+        case "plan set":
+            cmdPlanSet(args, dbPath);
+            break;
         case "export":
             await cmdExport(args, dbPath);
             break;

package/dist/db/schema.js

@@ -269,6 +269,16 @@ CREATE TABLE IF NOT EXISTS personal_sync_state (
   entity_type   TEXT PRIMARY KEY,
   synced_up_to  TEXT NOT NULL DEFAULT ''
 );
+
+-- El plan de Claude que declara quien usa Estela (estela plan set): el JSON
+-- de la status line no lo dice. Una fila por cambio, para conservar el
+-- historial; el vigente es el de 'since' más reciente.
+CREATE TABLE IF NOT EXISTS claude_plans (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  plan        TEXT NOT NULL,
+  since       TEXT NOT NULL,
+  declared_at TEXT NOT NULL
+);
 `;
 /**
  * Migraciones.

package/dist/db/store.d.ts

@@ -304,4 +304,13 @@ export declare function entryDetailForTeam(db: DatabaseSync, projectId: string):
 }[];
 export declare function getAiConsent(db: DatabaseSync, projectId: string): AiConsentRecord | null;
 export declare function setAiConsent(db: DatabaseSync, projectId: string, requested: boolean, decision: AiConsentDecision): void;
+export interface DeclaredPlan {
+    readonly plan: string;
+    readonly since: Date;
+}
+/** El plan vigente: el de `since` más reciente. null si nunca se declaró. */
+export declare function getClaudePlan(db: DatabaseSync): DeclaredPlan | null;
+/** Añade un cambio de plan; los anteriores se conservan. */
+export declare function setClaudePlan(db: DatabaseSync, plan: string, since: Date, at?: Date): void;
+export declare function listClaudePlans(db: DatabaseSync): DeclaredPlan[];
 //# sourceMappingURL=store.d.ts.map

package/dist/db/store.js

@@ -61,6 +61,9 @@ exports.entryAiByDay = entryAiByDay;
 exports.entryDetailForTeam = entryDetailForTeam;
 exports.getAiConsent = getAiConsent;
 exports.setAiConsent = setAiConsent;
+exports.getClaudePlan = getClaudePlan;
+exports.setClaudePlan = setClaudePlan;
+exports.listClaudePlans = listClaudePlans;
 const node_crypto_1 = require("node:crypto");
 const shared_1 = require("@estela/shared");
 const cost_js_1 = require("../pricing/cost.js");
@@ -982,4 +985,19 @@ function setAiConsent(db, projectId, requested, decision) {
       requested = excluded.requested, decision = excluded.decision, decided_at = excluded.decided_at
   `).run(projectId, requested ? 1 : 0, decision, decision === "pending" ? null : iso(new Date()));
 }
+/** El plan vigente: el de `since` más reciente. null si nunca se declaró. */
+function getClaudePlan(db) {
+    const row = db.prepare("SELECT plan, since FROM claude_plans ORDER BY since DESC, id DESC LIMIT 1")
+        .get();
+    return row ? { plan: row.plan, since: new Date(row.since) } : null;
+}
+/** Añade un cambio de plan; los anteriores se conservan. */
+function setClaudePlan(db, plan, since, at = new Date()) {
+    db.prepare("INSERT INTO claude_plans (plan, since, declared_at) VALUES (?, ?, ?)")
+        .run(plan, iso(since), iso(at));
+}
+function listClaudePlans(db) {
+    return db.prepare("SELECT plan, since FROM claude_plans ORDER BY since, id").all()
+        .map((r) => ({ plan: r.plan, since: new Date(r.since) }));
+}
 //# sourceMappingURL=store.js.map

package/dist/i18n/en.js

@@ -577,5 +577,52 @@ exports.EN = {
     "No hay ningún panel publicado de \"{0}\". Míralos con: estela unpublish": "There's no published dashboard for \"{0}\". See them with: estela unpublish",
     // ── ESTELA_OFFLINE ──
     "ESTELA_OFFLINE=1: Estela no se conecta a la red. Quita la variable para usar tu cuenta.": "ESTELA_OFFLINE=1: Estela doesn't connect to the network. Unset it to use your account.",
+    // ── statusline install: VS Code ──
+    "Solo en Claude Code en la terminal: la extensión de VS Code no enseña la status line.": "Only in Claude Code in the terminal: the VS Code extension doesn't show the status line.",
+    // ── estela plan ──
+    "--days tiene que ser un número entero de 1 a {0}.": "--days has to be a whole number from 1 to {0}.",
+    "Plan desconocido: \"{0}\". Usa pro, max5 o max20.": "Unknown plan: \"{0}\". Use pro, max5 or max20.",
+    "--since tiene que ser una fecha AAAA-MM-DD.": "--since has to be a YYYY-MM-DD date.",
+    "Plan declarado: {0}, desde {1}. El análisis solo usa lo guardado desde esa fecha.": "Plan declared: {0}, since {1}. The analysis only uses what was stored from that date.",
+    "Si ya lo tenías antes, indica desde cuándo: estela plan set {0} --since AAAA-MM-DD": "If you had it before, say since when: estela plan set {0} --since YYYY-MM-DD",
+    "Ventanas de 5 h": "5-hour windows",
+    "ninguna completa todavía": "none yet",
+    "{0} ventanas · pico mediano {1} % · p90 {2} % · máximo {3} %": "{0} windows · median peak {1}% · p90 {2}% · max {3}%",
+    "Topes (≥95 %)": "Caps (≥95%)",
+    "Parado tras topes": "Stopped after caps",
+    "hasta {0} (estimado: no sabemos si seguías trabajando)": "up to {0} (estimated: we don't know if you kept working)",
+    "Semana": "Week",
+    "sin datos de la semana": "no weekly data",
+    "pico mediano {0} % · máximo {1} % · {2} semanas ≥ 90 %": "median peak {0}% · max {1}% · {2} weeks ≥ 90%",
+    "Bloqueos (429)": "Blocks (429)",
+    "{0} de 5 h · {1} semanales, según los transcripts de Claude Code": "{0} 5-hour · {1} weekly, from Claude Code's transcripts",
+    "Si estuvieras en…": "If you were on…",
+    "Datos de {0} días. La recomendación necesita al menos 14.": "{0} days of data. The recommendation needs at least 14.",
+    "Recomendación (provisional, {0} días)": "Recommendation (provisional, {0} days)",
+    "Recomendación": "Recommendation",
+    "Límite semanal entre planes: Anthropic no publica la relación. No lo estimamos.": "Weekly limit between plans: Anthropic doesn't publish the ratio. We don't estimate it.",
+    "Basado en el multiplicador por sesión publicado por Anthropic:": "Based on the per-session multiplier published by Anthropic:",
+    "Anthropic puede cambiar los límites; repite el análisis cada mes.": "Anthropic may change the limits; run this again every month.",
+    "Precios según la web de Anthropic a {0}; compruébalo: {1}": "Prices from Anthropic's website as of {0}; check them: {1}",
+    "Esa fecha tiene más de {0} días: los precios pueden estar desactualizados.": "That date is more than {0} days old: prices may be out of date.",
+    "(desde {0})": "(since {0})",
+    "{0} días con datos": "{0} days with data",
+    "sin topes, igual que ahora": "no caps, same as now",
+    "p90 equivalente {0} % · habrías evitado {1} de {2} topes (con el uso que llegó a registrarse)": "equivalent p90 {0}% · you'd have avoided {1} of {2} caps (with the usage that got recorded)",
+    "p90 equivalente {0} % · no te habría bloqueado en ninguna de las {1} ventanas": "equivalent p90 {0}% · wouldn't have blocked you in any of the {1} windows",
+    "p90 equivalente {0} % · te habría bloqueado en {1} de {2} ventanas": "equivalent p90 {0}% · would have blocked you in {1} of {2} windows",
+    "Vas justo con tu plan. Con {0} habrías evitado {1} de {2} topes.": "Your plan is tight for you. With {0} you'd have avoided {1} of {2} caps.",
+    "Vas justo con tu plan.": "Your plan is tight for you.",
+    "Con los datos de estas {0} semanas, el plan {1} te habría bastado en todas las ventanas de 5 h.": "Based on these {0} weeks of data, the {1} plan would have been enough in every 5-hour window.",
+    "El plan {0} te habría bastado casi siempre: te habría bloqueado {1} veces en estas semanas.": "The {0} plan would have been enough almost always: it would have blocked you {1} times in these weeks.",
+    "Tu plan actual encaja con tu uso.": "Your current plan fits your usage.",
+    "{0} menos al mes, según la web de Anthropic a {1}; compruébalo.": "{0} less per month, per Anthropic's website as of {1}; check it.",
+    "{0} más al mes, según la web de Anthropic a {1}; compruébalo.": "{0} more per month, per Anthropic's website as of {1}; check it.",
+    "estela plan compara tu uso real de Claude con los otros planes. Primero dime cuál pagas:": "estela plan compares your real Claude usage with the other plans. First tell it which one you pay for:",
+    "Si ya lo tenías antes de hoy, añade desde cuándo: --since AAAA-MM-DD": "If you had it before today, add since when: --since YYYY-MM-DD",
+    "Este análisis solo funciona con planes Pro o Max.": "This analysis only works with Pro or Max plans.",
+    "Aún no hay datos. Instala la status line (estela statusline install) y vuelve en unos días.": "No data yet. Install the status line (estela statusline install) and come back in a few days.",
+    "Solo se recogen en Claude Code en la terminal: la extensión de VS Code no ejecuta la status line.": "They're only collected in Claude Code in the terminal: the VS Code extension doesn't run the status line.",
+    "{0} $": "${0}",
 };
 //# sourceMappingURL=en.js.map

package/dist/metrics/plan.d.ts

@@ -0,0 +1,110 @@
+import { type ClaudePlan, type ClaudePlanId } from "../plan-prices.js";
+import type { RateSample } from "../rate-history.js";
+/**
+ * "¿El plan de Claude que pago es el que me conviene?"
+ *
+ * Funciones puras sobre el historial de la status line (rate-limits.jsonl):
+ * entran muestras, salen cifras, y cada cifra tiene su test.
+ *
+ * La regla de siempre, más estricta aquí que en ningún sitio: Estela no
+ * inventa ni estima el límite de ningún plan. Usa solo
+ *
+ *  - los porcentajes que manda Claude Code, tal cual, y
+ *  - el multiplicador por sesión de 5 h que publica Anthropic (plan-prices.ts).
+ *
+ * Por eso la comparación entre planes es solo de la ventana de 5 h: del
+ * límite semanal Anthropic no publica la relación entre planes, y no se
+ * calcula. Y nada de "te quedan X" ni de cuándo te vas a quedar sin cuota.
+ */
+/** Pico desde el que una ventana cuenta como tope. */
+export declare const CAP_AT = 95;
+export declare const MIN_DAYS = 7;
+export declare const FULL_DAYS = 14;
+export interface FiveHourWindow {
+    /** `resets_at` de la ventana (epoch en s). */
+    readonly reset: number;
+    readonly peak: number;
+    readonly samples: number;
+    readonly capped: boolean;
+    /** Desde la primera muestra ≥ 99 % hasta el reinicio (o hasta ahora). Cota superior, estimada. */
+    readonly stoppedMs: number;
+}
+export interface WeekWindow {
+    readonly reset: number;
+    readonly peak: number;
+}
+export interface Alternative {
+    readonly plan: ClaudePlan;
+    readonly direction: "lower" | "higher";
+    readonly p90Equivalent: number;
+    readonly maxEquivalent: number;
+    /** Ventanas cuyo pico equivalente pasa de 100: te habrían bloqueado. */
+    readonly blockedWindows: number;
+    /** Subiendo de plan: topes de ahora cuyo pico equivalente se queda por debajo del tope. */
+    readonly capsAvoided: number;
+}
+export type Recommendation = {
+    readonly kind: "tight";
+    readonly higher: ClaudePlan | null;
+    readonly capsAvoided: number | null;
+} | {
+    readonly kind: "enough";
+    readonly plan: ClaudePlan;
+    readonly weeks: number;
+} | {
+    readonly kind: "almost";
+    readonly plan: ClaudePlan;
+    readonly blocked: number;
+} | {
+    readonly kind: "fits";
+};
+export type DataState = "none" | "insufficient" | "provisional" | "ok";
+export interface PlanAnalysis {
+    readonly plan: ClaudePlan;
+    readonly since: Date;
+    readonly from: Date;
+    readonly to: Date;
+    readonly days: number;
+    readonly daysWithData: number;
+    readonly samples: number;
+    readonly dataState: DataState;
+    readonly fiveHour: {
+        readonly windows: readonly FiveHourWindow[];
+        readonly medianPeak: number | null;
+        readonly p90Peak: number | null;
+        readonly maxPeak: number | null;
+        readonly caps: number;
+        readonly stoppedMs: number;
+    };
+    readonly week: {
+        readonly weeks: readonly WeekWindow[];
+        readonly medianPeak: number | null;
+        readonly maxPeak: number | null;
+        readonly weeksAtOrAbove90: number;
+    };
+    readonly alternatives: readonly Alternative[];
+    /** null con menos de 7 días de datos. */
+    readonly recommendation: Recommendation | null;
+}
+export interface PlanAnalysisInput {
+    readonly samples: readonly RateSample[];
+    readonly plan: ClaudePlanId;
+    readonly since: Date;
+    readonly now: Date;
+    /** Período, en días hacia atrás desde `now`. */
+    readonly days: number;
+    /** Para contar los días con datos en tu zona horaria. Por defecto, la de esta máquina. */
+    readonly localDay?: (ms: number) => string;
+}
+export declare function analyzePlan(input: PlanAnalysisInput): PlanAnalysis;
+/**
+ * Una ventana por `resets_at`, redondeado al minuto: dos sesiones pueden
+ * mandar el mismo reinicio con segundos distintos. Una muestra sin reinicio
+ * no se puede asignar a ninguna ventana y no cuenta.
+ */
+export declare function fiveHourWindows(samples: readonly RateSample[], now: Date): FiveHourWindow[];
+export declare function weekWindows(samples: readonly RateSample[]): WeekWindow[];
+export declare function median(values: readonly number[]): number | null;
+/** Percentil 90 por rango más cercano: siempre es un valor observado. */
+export declare function p90(values: readonly number[]): number | null;
+//# sourceMappingURL=plan.d.ts.map

package/dist/metrics/plan.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FULL_DAYS = exports.MIN_DAYS = exports.CAP_AT = void 0;
+exports.analyzePlan = analyzePlan;
+exports.fiveHourWindows = fiveHourWindows;
+exports.weekWindows = weekWindows;
+exports.median = median;
+exports.p90 = p90;
+const plan_prices_js_1 = require("../plan-prices.js");
+/**
+ * "¿El plan de Claude que pago es el que me conviene?"
+ *
+ * Funciones puras sobre el historial de la status line (rate-limits.jsonl):
+ * entran muestras, salen cifras, y cada cifra tiene su test.
+ *
+ * La regla de siempre, más estricta aquí que en ningún sitio: Estela no
+ * inventa ni estima el límite de ningún plan. Usa solo
+ *
+ *  - los porcentajes que manda Claude Code, tal cual, y
+ *  - el multiplicador por sesión de 5 h que publica Anthropic (plan-prices.ts).
+ *
+ * Por eso la comparación entre planes es solo de la ventana de 5 h: del
+ * límite semanal Anthropic no publica la relación entre planes, y no se
+ * calcula. Y nada de "te quedan X" ni de cuándo te vas a quedar sin cuota.
+ */
+/** Pico desde el que una ventana cuenta como tope. */
+exports.CAP_AT = 95;
+/** Desde aquí se cuenta el tiempo parado tras un tope. */
+const STOPPED_FROM = 99;
+/** Una semana con este pico o más es "ir justo". */
+const TIGHT_WEEK_AT = 90;
+const TIGHT_CAPS_PER_WEEK = 2;
+/** Un plan inferior "basta" si no habría bloqueado nunca y su p90 equivalente no pasa de aquí. */
+const ENOUGH_P90 = 80;
+const ALMOST_MAX_BLOCKS = 3;
+exports.MIN_DAYS = 7;
+exports.FULL_DAYS = 14;
+function analyzePlan(input) {
+    const plan = (0, plan_prices_js_1.planById)(input.plan);
+    if (!plan)
+        throw new Error(`plan desconocido: ${input.plan}`);
+    const to = input.now;
+    const from = new Date(Math.max(input.since.getTime(), to.getTime() - input.days * 86_400_000));
+    const localDay = input.localDay ?? defaultLocalDay;
+    const samples = dedupe(input.samples)
+        .filter((s) => s.ts >= from.getTime() && s.ts <= to.getTime())
+        .sort((a, b) => a.ts - b.ts);
+    const daysWithData = new Set(samples.map((s) => localDay(s.ts))).size;
+    const windows = fiveHourWindows(samples, to);
+    const peaks = windows.map((w) => w.peak);
+    const weeks = weekWindows(samples);
+    const weekPeaks = weeks.map((w) => w.peak);
+    const caps = windows.filter((w) => w.capped).length;
+    const alternatives = plan_prices_js_1.CLAUDE_PLANS.filter((p) => p.id !== plan.id).map((target) => {
+        const factor = plan.sessionMultiplier / target.sessionMultiplier;
+        const eq = windows.map((w) => w.peak * factor);
+        return {
+            plan: target,
+            direction: target.sessionMultiplier < plan.sessionMultiplier ? "lower" : "higher",
+            p90Equivalent: p90(eq) ?? 0,
+            maxEquivalent: eq.length ? Math.max(...eq) : 0,
+            blockedWindows: eq.filter((e) => e > 100).length,
+            capsAvoided: factor < 1 ? windows.filter((w) => w.capped && w.peak * factor < exports.CAP_AT).length : 0,
+        };
+    });
+    const dataState = samples.length === 0 ? "none"
+        : daysWithData < exports.MIN_DAYS ? "insufficient"
+            : daysWithData < exports.FULL_DAYS ? "provisional" : "ok";
+    const analysis = {
+        plan, since: input.since, from, to, days: input.days, daysWithData, samples: samples.length, dataState,
+        fiveHour: {
+            windows, medianPeak: median(peaks), p90Peak: p90(peaks), maxPeak: peaks.length ? Math.max(...peaks) : null,
+            caps, stoppedMs: windows.reduce((s, w) => s + w.stoppedMs, 0),
+        },
+        week: {
+            weeks, medianPeak: median(weekPeaks), maxPeak: weekPeaks.length ? Math.max(...weekPeaks) : null,
+            weeksAtOrAbove90: weekPeaks.filter((p) => p >= TIGHT_WEEK_AT).length,
+        },
+        alternatives,
+    };
+    return {
+        ...analysis,
+        recommendation: dataState === "provisional" || dataState === "ok" ? recommend(analysis) : null,
+    };
+}
+/** Las cuatro reglas, en orden. Conservadoras: ante la duda, el plan actual. */
+function recommend(a) {
+    const weeksOfData = a.daysWithData / 7;
+    const capsPerWeek = weeksOfData > 0 ? a.fiveHour.caps / weeksOfData : 0;
+    if (capsPerWeek >= TIGHT_CAPS_PER_WEEK || a.week.weeksAtOrAbove90 > 0) {
+        const higher = a.alternatives
+            .filter((x) => x.direction === "higher")
+            .sort((x, y) => x.plan.sessionMultiplier - y.plan.sessionMultiplier)[0];
+        return { kind: "tight", higher: higher?.plan ?? null, capsAvoided: higher ? higher.capsAvoided : null };
+    }
+    const lower = a.alternatives
+        .filter((x) => x.direction === "lower")
+        .sort((x, y) => x.plan.monthlyUsd - y.plan.monthlyUsd);
+    const enough = lower.find((x) => x.blockedWindows === 0 && x.p90Equivalent <= ENOUGH_P90);
+    if (enough)
+        return { kind: "enough", plan: enough.plan, weeks: Math.max(1, Math.round(weeksOfData)) };
+    const almost = lower.find((x) => x.blockedWindows >= 1 && x.blockedWindows <= ALMOST_MAX_BLOCKS);
+    if (almost)
+        return { kind: "almost", plan: almost.plan, blocked: almost.blockedWindows };
+    return { kind: "fits" };
+}
+// ---------------------------------------------------------------------------
+/**
+ * Una ventana por `resets_at`, redondeado al minuto: dos sesiones pueden
+ * mandar el mismo reinicio con segundos distintos. Una muestra sin reinicio
+ * no se puede asignar a ninguna ventana y no cuenta.
+ */
+function fiveHourWindows(samples, now) {
+    const groups = new Map();
+    for (const s of samples) {
+        if (s.w5 === undefined || s.w5_reset === undefined)
+            continue;
+        const key = Math.round(s.w5_reset / 60);
+        const g = groups.get(key);
+        if (g)
+            g.push(s);
+        else
+            groups.set(key, [s]);
+    }
+    return [...groups.entries()].sort((a, b) => a[0] - b[0]).map(([key, g]) => {
+        const peak = Math.max(...g.map((s) => s.w5));
+        const capped = peak >= exports.CAP_AT;
+        const first99 = g.filter((s) => s.w5 >= STOPPED_FROM).map((s) => s.ts).sort((a, b) => a - b)[0];
+        const end = Math.min(key * 60_000, now.getTime());
+        return {
+            reset: key * 60, peak, samples: g.length, capped,
+            stoppedMs: capped && first99 !== undefined ? Math.max(0, end - first99) : 0,
+        };
+    });
+}
+function weekWindows(samples) {
+    const peaks = new Map();
+    for (const s of samples) {
+        if (s.w7 === undefined || s.w7_reset === undefined)
+            continue;
+        const key = Math.round(s.w7_reset / 60);
+        peaks.set(key, Math.max(peaks.get(key) ?? -Infinity, s.w7));
+    }
+    return [...peaks.entries()].sort((a, b) => a[0] - b[0]).map(([key, peak]) => ({ reset: key * 60, peak }));
+}
+/** Dos sesiones a la vez pueden escribir la misma muestra. */
+function dedupe(samples) {
+    const seen = new Set();
+    return samples.filter((s) => {
+        const k = `${s.ts}|${s.w5}|${s.w5_reset}|${s.w7}|${s.w7_reset}`;
+        if (seen.has(k))
+            return false;
+        seen.add(k);
+        return true;
+    });
+}
+function median(values) {
+    if (values.length === 0)
+        return null;
+    const v = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(v.length / 2);
+    return v.length % 2 ? v[mid] : (v[mid - 1] + v[mid]) / 2;
+}
+/** Percentil 90 por rango más cercano: siempre es un valor observado. */
+function p90(values) {
+    if (values.length === 0)
+        return null;
+    const v = [...values].sort((a, b) => a - b);
+    return v[Math.ceil(0.9 * v.length) - 1];
+}
+function defaultLocalDay(ms) {
+    const d = new Date(ms);
+    return `${d.getFullYear()}-${d.getMonth() + 1}-${d.getDate()}`;
+}
+//# sourceMappingURL=plan.js.map