quotacap 0.0.43 → 0.0.45

package/dist/adapters/index.d.ts

@@ -6,16 +6,26 @@ export interface PollAllOptions {
     /** Max concurrent adapter polls. Default 3: seven heavy CLI/TUI spawns at
      * once starve each other into timeouts. */
     maxConcurrency?: number;
-    /** Attempts per adapter including the first. Default 2 (one retry).
+    /** Attempts per adapter including the first. Default 3.
      * 1 disables retry. */
     maxAttempts?: number;
-    /** Delay between attempts. Default 1000. */
-    retryDelayMs?: number;
+    /** Backoff base between attempts: the delay after failed attempt n is
+     * min(cap, base * 2^(n-1)) with equal jitter. Default 2000. */
+    baseRetryDelayMs?: number;
+    /** Backoff ceiling. Default 8000. */
+    maxRetryDelayMs?: number;
     /** When aborted, in-flight attempts run out but no retry is started. */
     signal?: AbortSignal;
 }
+/**
+ * Exponential backoff with equal jitter: half the exponential delay plus a
+ * uniform random half, so concurrent adapters do not retry in lockstep.
+ * failedAttempt is 1-based (1 = the first attempt just failed).
+ */
+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

@@ -30,6 +30,17 @@ export const ADAPTER_TIMEOUTS = {
     muse: 90000,
     "opencode-go": 8000,
 };
+/**
+ * Exponential backoff with equal jitter: half the exponential delay plus a
+ * uniform random half, so concurrent adapters do not retry in lockstep.
+ * failedAttempt is 1-based (1 = the first attempt just failed).
+ */
+export function computeRetryDelayMs(failedAttempt, baseMs = 2000, capMs = 8000, rng = Math.random) {
+    const base = Math.max(0, baseMs);
+    const cap = Math.max(0, capMs);
+    const exp = Math.min(cap, base * 2 ** Math.max(0, failedAttempt - 1));
+    return Math.floor(exp / 2 + rng() * (exp / 2));
+}
 /** Order-preserving concurrency-limited map. */
 export async function mapWithConcurrency(items, limit, fn) {
     const results = new Array(items.length);
@@ -45,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
@@ -98,8 +114,9 @@ async function pollOnceWithGate(id, adapter, timeout) {
 const delay = (ms) => new Promise((r) => setTimeout(r, ms));
 export async function pollAll(enabled, opts) {
     const maxConcurrency = opts?.maxConcurrency ?? 3;
-    const maxAttempts = Math.max(1, opts?.maxAttempts ?? 2);
-    const retryDelayMs = Math.max(0, opts?.retryDelayMs ?? 1000);
+    const maxAttempts = Math.max(1, opts?.maxAttempts ?? 3);
+    const baseRetryDelayMs = opts?.baseRetryDelayMs ?? 2000;
+    const maxRetryDelayMs = opts?.maxRetryDelayMs ?? 8000;
     const runOne = async (id) => {
         const a = adapters[id];
         if (!a)
@@ -123,7 +140,7 @@ export async function pollAll(enabled, opts) {
             const retry = outcome.timedOut || isRetryableChildFailure(outcome.reason);
             if (!retry)
                 break;
-            await delay(retryDelayMs);
+            await delay(computeRetryDelayMs(attempt, baseRetryDelayMs, maxRetryDelayMs));
         }
         return { provider: id, status: "rejected", reason: lastReason };
     };

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.43";
+export const VERSION = "0.0.45";

package/package.json

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