quotacap 0.0.44 → 0.0.46

package/dist/adapters/index.d.ts

@@ -25,6 +25,7 @@ export interface PollAllOptions {
 export declare function computeRetryDelayMs(failedAttempt: number, baseMs?: number, capMs?: number, rng?: () => number): number;
 /** Order-preserving concurrency-limited map. */
 export declare function mapWithConcurrency<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+export declare const RETRYABLE_DIAGNOSTIC_CODES: ReadonlySet<string>;
 export declare function isRetryableChildFailure(reason: unknown): boolean;
 export declare function pollAll(enabled: string[], opts?: PollAllOptions): Promise<({
     provider: string;

package/dist/adapters/index.js

@@ -56,13 +56,18 @@ export async function mapWithConcurrency(items, limit, fn) {
     await Promise.all(workers);
     return results;
 }
-// A child that ran and produced a diagnosable output problem is worth one
-// more attempt; a login wall, missing binary, trust prompt, or rate limit
-// will not clear in a second, and a mid-flight child death (killAll,
-// crash) must never respawn — especially during shutdown.
-const RETRYABLE_CODES = new Set(["parse_error", "network", "service_unavailable"]);
+// A child that ran and produced a diagnosable output problem is worth more
+// attempts; a login wall, missing binary, trust prompt, or rate limit will
+// not clear on retry, and a mid-flight child death (killAll, crash) must
+// never respawn — especially during shutdown. Shared with the coordinator,
+// which consults it for both in-generation retries and recovery polls.
+export const RETRYABLE_DIAGNOSTIC_CODES = new Set([
+    "parse_error",
+    "network",
+    "service_unavailable",
+]);
 export function isRetryableChildFailure(reason) {
-    return RETRYABLE_CODES.has(classifyFailure("Provider", reason).diagnosticCode);
+    return RETRYABLE_DIAGNOSTIC_CODES.has(classifyFailure("Provider", reason).diagnosticCode);
 }
 async function pollOnceWithGate(id, adapter, timeout) {
     // One controller per attempt: a timeout aborts only that attempt's

package/dist/adapters/kimi.d.ts

@@ -35,6 +35,13 @@ export declare function refreshKimiOAuthToken(oauthHost: string, refreshToken: s
     refresh_token?: string;
     expires_in?: number;
 }>;
+/** The Kimi account has no active subscription (observed: cancelled plan
+ * answers /usages 200 with `{}`, /me `user_level_name` "Free", and the TUI
+ * shows "No usage data available"). The TUI reports the same state, so the
+ * PTY fallback is skipped: report it, do not mask it with a timeout. */
+export declare class KimiSubscriptionInactiveError extends Error {
+    constructor(detail: string);
+}
 /** A refresh rotated the tokens but the result could not be saved for the Kimi CLI. */
 export declare class KimiCredentialWriteError extends Error {
     constructor(credPath: string, cause: unknown);

package/dist/adapters/kimi.js

@@ -153,6 +153,14 @@ function parseKimiApiMonthly(u, legacyUsages) {
     }
     return {};
 }
+function isEmptyUsageBody(u) {
+    const usage = u.usage;
+    const hasUsage = !!usage && typeof usage === "object" && Object.keys(usage).length > 0;
+    const hasLimits = Array.isArray(u.limits) && u.limits.length > 0;
+    const usages = u.usages;
+    const hasUsages = !!usages && typeof usages === "object" && Object.keys(usages).length > 0;
+    return !hasUsage && !hasLimits && !hasUsages;
+}
 export function parseKimiApiUsage(usagesBody, meBody, now = new Date()) {
     if (typeof usagesBody !== "object" || usagesBody === null) {
         throw new Error("kimi: invalid api response");
@@ -212,6 +220,21 @@ export function parseKimiApiUsage(usagesBody, meBody, now = new Date()) {
             }
         }
     }
+    // 3. Plan identity (from meBody), before the field throws: an empty
+    // usage body on a free plan is a dead subscription, not a parse failure.
+    let plan = "unknown";
+    if (meBody && typeof meBody === "object") {
+        const me = meBody;
+        if (typeof me.user_level_name === "string" && me.user_level_name.trim().length > 0) {
+            plan = me.user_level_name.trim().toLowerCase();
+        }
+    }
+    if (weeklyPct === null && sessionPct === null && !resetsAt && isEmptyUsageBody(u) && plan === "free") {
+        throw new KimiSubscriptionInactiveError("plan free, empty usage response");
+    }
+    // Any other shape without data stays a parse error: an empty body on a
+    // paid or unknown plan falls through to the PTY path, whose transcript
+    // decides (usage panel vs "No usage data available").
     if (weeklyPct === null || weeklyPct < 0 || weeklyPct > 100) {
         throw new Error("kimi: weekly pct not found in api response");
     }
@@ -221,14 +244,6 @@ export function parseKimiApiUsage(usagesBody, meBody, now = new Date()) {
     if (!resetsAt || Number.isNaN(new Date(resetsAt).getTime())) {
         throw new Error("kimi: weekly reset not found in api response");
     }
-    // 3. Plan identity (from meBody)
-    let plan = "unknown";
-    if (meBody && typeof meBody === "object") {
-        const me = meBody;
-        if (typeof me.user_level_name === "string" && me.user_level_name.trim().length > 0) {
-            plan = me.user_level_name.trim().toLowerCase();
-        }
-    }
     // 4. Optional monthly quota (from limit_month_total, limits, or subscriptionBalance)
     const monthly = parseKimiApiMonthly(u, legacyUsages);
     const periodStart = new Date(new Date(resetsAt).getTime() - 7 * 86400000).toISOString();
@@ -377,6 +392,16 @@ export async function refreshKimiOAuthToken(oauthHost, refreshToken, deviceId, s
         expires_in: typeof data.expires_in === "number" ? data.expires_in : undefined,
     };
 }
+/** The Kimi account has no active subscription (observed: cancelled plan
+ * answers /usages 200 with `{}`, /me `user_level_name` "Free", and the TUI
+ * shows "No usage data available"). The TUI reports the same state, so the
+ * PTY fallback is skipped: report it, do not mask it with a timeout. */
+export class KimiSubscriptionInactiveError extends Error {
+    constructor(detail) {
+        super(`kimi: subscription inactive (${detail})`);
+        this.name = "KimiSubscriptionInactiveError";
+    }
+}
 /** A refresh rotated the tokens but the result could not be saved for the Kimi CLI. */
 export class KimiCredentialWriteError extends Error {
     constructor(credPath, cause) {
@@ -463,6 +488,11 @@ export async function pollKimiApi(ctx) {
         headers.Authorization = `Bearer ${freshToken}`;
         usagesRes = await fetch(usagesUrl, { headers, signal });
     }
+    // 402/403 on an authenticated /usages call is an entitlement state, not
+    // a transport failure: the account has no active subscription.
+    if (usagesRes.status === 402 || usagesRes.status === 403) {
+        throw new KimiSubscriptionInactiveError(`HTTP ${usagesRes.status}`);
+    }
     if (!usagesRes.ok) {
         throw new Error(`kimi: usage request failed (HTTP ${usagesRes.status})`);
     }
@@ -520,9 +550,13 @@ export const kimiAdapter = {
                 return await pollKimiApi(authCtx);
             }
             catch (e) {
-                // A lost rotated token leaves the CLI logged out: report it, do not mask it with the PTY path.
+                // A lost rotated token leaves the CLI logged out, and a dead
+                // subscription reads the same in the TUI: report either, do not
+                // mask them with the PTY path.
                 if (e instanceof KimiCredentialWriteError)
                     throw e;
+                if (e instanceof KimiSubscriptionInactiveError)
+                    throw e;
             }
         }
         return pollKimiPty();

package/dist/advisory/snapshot.js

@@ -97,7 +97,10 @@ export function buildSnapshot(db, opts) {
                 providerFailed = true;
             }
         }
-        // Precedence: invalid, reset-passed, provider-failed, stale, not-reporting
+        // Precedence: invalid, provider-failed, reset-passed, stale, not-reporting.
+        // A fresh failure outranks a passed reset: "poll again to capture the new
+        // window" is only actionable when polls succeed, and would otherwise mask
+        // the real state (e.g. an inactive subscription) behind a re-poll prompt.
         let exclusionReason = null;
         if (quota === null) {
             exclusionReason = "not-reporting";
@@ -105,12 +108,12 @@ export function buildSnapshot(db, opts) {
         else if (isInvalid) {
             exclusionReason = "invalid";
         }
-        else if (resetPassed) {
-            exclusionReason = "reset-passed";
-        }
         else if (providerFailed) {
             exclusionReason = "provider-failed";
         }
+        else if (resetPassed) {
+            exclusionReason = "reset-passed";
+        }
         else if (stale) {
             exclusionReason = "stale";
         }

package/dist/diagnostics/failure.js

@@ -86,6 +86,15 @@ const UNRECOGNIZED_OMITTED = "Unrecognized diagnostic text omitted";
 // "account is not eligible" is the Antigravity sentence; a bare "not eligible" is not.
 // The hyphen covers "Sign-in with". "signed in with" does not match.
 const ACCOUNT_CONFIRMATION = /\b(?:account is not eligible|verify your account|eligibility check failed|device code|sign(?:ing)?[ -]in with)\b/i;
+// Cancelled- or missing-subscription wording. The QuotaCap-authored phrase
+// ("subscription inactive", thrown by adapters that detect it directly) plus
+// Kimi's own sentences for the same state: the /usage panel shows "No usage
+// data available" and prompting fails with "[provider.auth_error] 403 ...
+// does not have access to Kimi Code ... Upgrade your plan". Bare "does not
+// have access" is not enough: it must name Kimi Code, so file-permission
+// errors never match. A bare "Upgrade your plan" is not enough either: it
+// can be upsell banner text on an otherwise healthy screen.
+const SUBSCRIPTION_INACTIVE = /\bsubscription inactive\b|\bno usage data available\b|\bprovider\.auth_error\b|\bdoes not have access to Kimi Code\b/i;
 function matchPrecedence(evidence, errorName, errorCode, text) {
     // Order 1: timeout — Structured AbortError or an explicit QuotaCap abort/timeout checkpoint.
     // A ready or completion timeout whose transcript is an account-confirmation
@@ -93,7 +102,13 @@ function matchPrecedence(evidence, errorName, errorCode, text) {
     // abort stays a timeout even if that screen is in the transcript.
     const signInTimeout = ACCOUNT_CONFIRMATION.test(text) &&
         (evidence?.checkpoint === "ready timeout" || evidence?.checkpoint === "completion timeout");
+    // Same fall-through for a dead subscription: a completion timeout whose
+    // stable transcript is the empty usage panel reports the subscription
+    // state, not the timeout that a missing completion pattern caused.
+    const inactiveTimeout = SUBSCRIPTION_INACTIVE.test(text) &&
+        (evidence?.checkpoint === "ready timeout" || evidence?.checkpoint === "completion timeout");
     const isAbort = !signInTimeout &&
+        !inactiveTimeout &&
         (errorName === "AbortError" ||
             errorCode === "ABORT_ERR" ||
             evidence?.checkpoint === "abort" ||
@@ -158,6 +173,12 @@ function matchPrecedence(evidence, errorName, errorCode, text) {
     }
     // Order 6: auth — login required, not logged in, logged out, unauthorized, unauthorised, forbidden,
     // run <provider> login to continue, or error indicating missing, invalid, or expired credentials, authentication, or API key
+    // A dead subscription sorts as auth (the 403 is an authorization state),
+    // first in this order so its summary wins over login wording: the user is
+    // logged in, and "login required" would mislead.
+    if (SUBSCRIPTION_INACTIVE.test(text)) {
+        return { code: "auth", phrase: "subscription inactive" };
+    }
     if (/\brun\s+[a-z0-9_:-]+\s+login\s+to\s+continue\b/i.test(text)) {
         return { code: "auth", phrase: "run <provider> login to continue" };
     }
@@ -424,7 +445,8 @@ export function diagnosticError(reason, evidence) {
             const matchedLines = lines.filter((l) => /\b(error|failed|failure|fatal|unauthorized|unauthorised|denied|forbidden|panic|exception)\b/i.test(l) ||
                 /\btrust\b/i.test(l) ||
                 /\b(stdin is not a terminal|device not configured|not a tty|inappropriate ioctl|node-pty)\b/i.test(l) ||
-                ACCOUNT_CONFIRMATION.test(l));
+                ACCOUNT_CONFIRMATION.test(l) ||
+                SUBSCRIPTION_INACTIVE.test(l));
             safeStdoutText = matchedLines.join(" ");
         }
         else {
@@ -497,6 +519,12 @@ function getSummaryAndAction(code, providerName, provider, errorDetail) {
                 action: `Open ${providerName} directly in your terminal to check whether it starts. If it works there, inspect the QuotaCap service log and report the adapter failure. Refresh in the dashboard retries through the same service.`,
             };
         case "auth":
+            if (/\bsubscription inactive\b/i.test(errorDetail)) {
+                return {
+                    summary: `${providerName} subscription inactive`,
+                    action: `Open ${providerName} to manage your subscription, or run \`quotacap providers disable ${provider}\` to stop polling it. Then select Refresh in the QuotaCap dashboard.`,
+                };
+            }
             if (/\baccount confirmation required\b/i.test(errorDetail)) {
                 return {
                     summary: `${providerName} needs you to confirm the subscription account`,

package/dist/runtime/poll.d.ts

@@ -34,6 +34,15 @@ export interface CoordinatorState {
     lastCompletedPollAt: string | null;
     lastResult: RefreshResult | null;
 }
+export interface RecoveryOptions {
+    /** First recovery delay. Default 60000. Doubles per consecutive failure. */
+    baseDelayMs?: number;
+    /** Recovery delay ceiling. Default 600000. */
+    maxDelayMs?: number;
+    /** Stop auto-recovery after this many consecutive failures per provider.
+     * Scheduled ticks keep trying; a success resets the count. Default 5. */
+    maxFailures?: number;
+}
 export interface CoordinatorOptions {
     db: any;
     enabledProviders: string[];
@@ -48,6 +57,10 @@ export interface CoordinatorOptions {
     dataDir?: string;
     /** Opt-in forensics: write a redacted evidence bundle per poll failure. */
     debugFailureBundles?: boolean;
+    /** Auto-recovery: re-poll providers whose window expired or went stale
+     * instead of waiting for the next scheduled tick. Enabled by default;
+     * pass false to disable. */
+    recovery?: false | RecoveryOptions;
 }
 export interface Coordinator {
     refresh(): Promise<RefreshResult>;

package/dist/runtime/poll.js

@@ -1,7 +1,8 @@
 // Poll coordinator: scheduled and manual refresh share one in-flight poll
 // with a completion-measured cooldown (decisions D3/D4).
-import { pollAll, ADAPTER_TIMEOUTS } from "../adapters/index.js";
-import { getAllLatest, upsertQuota } from "../store/quotas.js";
+import { pollAll, ADAPTER_TIMEOUTS, RETRYABLE_DIAGNOSTIC_CODES } from "../adapters/index.js";
+import { getAllLatest, getLatestByProvider, upsertQuota } from "../store/quotas.js";
+import { STALE_MS } from "../advisory/snapshot.js";
 import { readServiceMetadata } from "../config.js";
 import { writeFailureBundle, providerBin, getCliVersion } from "../diagnostics/bundle.js";
 import { VERSION } from "../version.js";
@@ -56,6 +57,11 @@ export function createCoordinator(opts) {
     const onSettled = opts.onSettled;
     const dataDir = opts.dataDir;
     const debugFailureBundles = opts.debugFailureBundles === true;
+    const recoveryEnabled = opts.recovery !== false;
+    const recoveryOpts = typeof opts.recovery === "object" ? opts.recovery : {};
+    const recoveryBaseMs = recoveryOpts.baseDelayMs ?? 60000;
+    const recoveryMaxMs = recoveryOpts.maxDelayMs ?? 600000;
+    const recoveryMaxFailures = recoveryOpts.maxFailures ?? 5;
     let inFlight = null;
     let lastResult = null;
     let lastCompletedPollAt = null;
@@ -64,6 +70,9 @@ export function createCoordinator(opts) {
     let started = false;
     let intervalMs = 0;
     let timer = null;
+    let recoveryTimer = null;
+    const recoveryFailures = new Map();
+    const recoveryExhausted = new Set();
     function arm() {
         if (timer)
             clearTimeout(timer);
@@ -81,9 +90,9 @@ export function createCoordinator(opts) {
             enabledProviders,
         }));
     }
-    async function runGeneration() {
+    async function runGeneration(ids = enabledProviders) {
         const attemptedAt = new Date(now()).toISOString();
-        const rows = await pollFn(enabledProviders);
+        const rows = await pollFn(ids);
         const completedAt = new Date(now()).toISOString();
         // Self-fence before any poll write (decision D1).
         if (ownershipVerify && !ownershipVerify()) {
@@ -202,12 +211,117 @@ export function createCoordinator(opts) {
                 }
             }
         }
+        // Partial (recovery) generations merge into the previous full result so
+        // a refresh response never drops providers that were not re-polled.
+        if (lastResult && ids.length < enabledProviders.length) {
+            const idsSet = new Set(ids);
+            result.fulfilled = [
+                ...lastResult.fulfilled.filter((f) => !idsSet.has(f?.provider)),
+                ...result.fulfilled,
+            ];
+            result.rejected = [
+                ...lastResult.rejected.filter((r) => !idsSet.has(r.provider)),
+                ...result.rejected,
+            ];
+            result.results = [
+                ...lastResult.results.filter((r) => !idsSet.has(r.provider)),
+                ...result.results,
+            ];
+            result.degraded = result.rejected.length > 0;
+        }
         lastResult = result;
         lastCompletedPollAt = completedAt;
         completedAtMs = new Date(completedAt).getTime();
+        // Recovery bookkeeping before re-arming: an attempt is an attempt,
+        // whether it came from the schedule, a manual refresh, or recovery.
+        for (const id of ids) {
+            if (needsRecovery(id)) {
+                recoveryFailures.set(id, (recoveryFailures.get(id) ?? 0) + 1);
+            }
+            else {
+                recoveryFailures.delete(id);
+                recoveryExhausted.delete(id);
+            }
+        }
+        evaluateRecovery();
         return result;
     }
-    function launch() {
+    /** A provider needs recovery when its row is expired but a fresh poll
+     * could plausibly fix it: reset passed or stale, and the last failure —
+     * if any — is a retryable or timeout cause, never auth or a hard wall. */
+    function needsRecovery(id) {
+        if (id === "manual")
+            return false;
+        const quota = getLatestByProvider(db, id);
+        if (!quota)
+            return false;
+        const nowMs = now();
+        const resetsMs = new Date(quota.resetsAt).getTime();
+        const fetchedMs = new Date(quota.fetchedAt).getTime();
+        const resetPassed = !Number.isNaN(resetsMs) && resetsMs <= nowMs;
+        const stale = !Number.isNaN(fetchedMs) && nowMs - fetchedMs > STALE_MS;
+        if (!resetPassed && !stale)
+            return false;
+        const attempt = getAttempt(db, id);
+        if (attempt && !attempt.success && attempt.diagnosticCode) {
+            const code = attempt.diagnosticCode;
+            if (code !== "timeout" && !RETRYABLE_DIAGNOSTIC_CODES.has(code))
+                return false;
+        }
+        return true;
+    }
+    function evaluateRecovery() {
+        if (recoveryTimer) {
+            clearTimeout(recoveryTimer);
+            recoveryTimer = null;
+        }
+        if (closing || !recoveryEnabled)
+            return;
+        const needy = enabledProviders.filter((id) => needsRecovery(id) && (recoveryFailures.get(id) ?? 0) < recoveryMaxFailures);
+        for (const id of enabledProviders) {
+            if (needsRecovery(id) && (recoveryFailures.get(id) ?? 0) >= recoveryMaxFailures) {
+                if (!recoveryExhausted.has(id)) {
+                    recoveryExhausted.add(id);
+                    console.log(`[quotacap] [${id}] recovery exhausted; waiting for the next scheduled poll`);
+                }
+            }
+        }
+        if (needy.length === 0)
+            return;
+        const worst = Math.max(...needy.map((id) => recoveryFailures.get(id) ?? 0));
+        const delay = Math.min(recoveryMaxMs, recoveryBaseMs * 2 ** worst);
+        console.log(`[quotacap] [${needy.join(", ")}] scheduling recovery poll in ${Math.round(delay / 1000)}s`);
+        recoveryTimer = setTimeout(() => {
+            recoveryTimer = null;
+            void fireRecovery(needy);
+        }, delay);
+    }
+    async function fireRecovery(ids) {
+        if (closing)
+            return;
+        // Self-fence on wake, like scheduledTick: do not spawn doomed children.
+        if (ownershipVerify && !ownershipVerify()) {
+            closing = true;
+            onOwnershipLost();
+            return;
+        }
+        const targets = ids.filter((id) => needsRecovery(id));
+        if (targets.length === 0) {
+            evaluateRecovery();
+            return;
+        }
+        try {
+            await (inFlight ?? launch(targets));
+        }
+        catch (e) {
+            const detail = classifyFailure("all", e).errorDetail;
+            console.warn("[quotacap] recovery poll failed", detail);
+        }
+        finally {
+            evaluateRecovery();
+        }
+    }
+    function launch(ids = enabledProviders) {
         // Gate first: inFlight is set before pollFn runs, so getState()
         // reports in-progress from inside the poll itself.
         let resolve;
@@ -222,7 +336,7 @@ export function createCoordinator(opts) {
                 inFlight = null;
         };
         gate.then(clear, clear);
-        runGeneration().then(resolve, reject);
+        runGeneration(ids).then(resolve, reject);
         return gate;
     }
     function refresh() {
@@ -281,6 +395,10 @@ export function createCoordinator(opts) {
             clearTimeout(timer);
             timer = null;
         }
+        if (recoveryTimer) {
+            clearTimeout(recoveryTimer);
+            recoveryTimer = null;
+        }
     }
     function getState() {
         const polling = inFlight !== null

package/dist/version.js

@@ -1,2 +1,2 @@
 // generated by scripts/build-embed.mjs — do not edit
-export const VERSION = "0.0.44";
+export const VERSION = "0.0.46";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quotacap",
-  "version": "0.0.44",
+  "version": "0.0.46",
   "description": "Local quota tracker for AI coding plans with a dashboard, CLI, MCP server, and next-plan recommendations.",
   "license": "MIT",
   "keywords": [