quotacap 0.0.34 → 0.0.35

package/dist/catalog/grok.js

@@ -0,0 +1,36 @@
+import { trackedExecFile } from "../runtime/spawn.js";
+// `grok models` prints a login preamble, a "Default model:" line, then an
+// "Available models:" list of `* id (default)` / `- id` bullets (design §6.2).
+export function parseGrokModels(stdout) {
+    const models = [];
+    for (const line of stdout.split(/\r?\n/)) {
+        const m = line.match(/^\s*[* -]\s+(\S+)/);
+        if (!m)
+            continue;
+        const id = m[1];
+        const entry = { id, displayName: id };
+        if (/\(default\)/i.test(line))
+            entry.default = true;
+        models.push(entry);
+    }
+    if (models.length === 0)
+        throw new Error("grok: no models found in `grok models` output");
+    return models;
+}
+const EXEC_TIMEOUT_MS = 8000;
+export const grokCatalogFetcher = {
+    id: "grok",
+    async fetch() {
+        // Per-fetch catalog-owned signal: never the usage poll's shared controller.
+        const { stdout } = await trackedExecFile("grok", "grok", ["models"], {
+            timeout: EXEC_TIMEOUT_MS,
+            signal: new AbortController().signal,
+        });
+        try {
+            return { grok: parseGrokModels(stdout) };
+        }
+        catch (e) {
+            throw new Error(`grok: failed to parse \`grok models\` output: ${e?.message ?? e}`);
+        }
+    },
+};

package/dist/catalog/index.d.ts

@@ -0,0 +1,17 @@
+import { type CatalogFetcher, type CatalogView } from "./types.js";
+export declare const CATALOG_CLIENT_TIMEOUT_MS = 30000;
+export { MUSE_OVERALL_MS } from "./muse.js";
+export declare const CATALOG_FAIL_COOLDOWN_MS = 60000;
+export type { CatalogFetcher, CatalogView, ListedModel } from "./types.js";
+export declare function catalogProviders(enabledProviders: string[]): string[];
+export declare const catalogFetchers: Record<string, CatalogFetcher>;
+export interface EnsureCatalogsOpts {
+    db: any;
+    wait: boolean;
+    refresh?: boolean;
+    providers: string[];
+    ttlHours: number;
+    now?: () => Date;
+    fetchers?: Record<string, CatalogFetcher>;
+}
+export declare function ensureCatalogs(opts: EnsureCatalogsOpts): Promise<Map<string, CatalogView>>;

package/dist/catalog/index.js

@@ -0,0 +1,152 @@
+import { getCatalog, upsertCatalog, markCatalogFailure } from "../store/catalogs.js";
+import { classifyFailure } from "../diagnostics/failure.js";
+import { agyCatalogFetcher } from "./agy.js";
+import { claudeCatalogFetcher } from "./claude.js";
+import { codexCatalogFetcher } from "./codex.js";
+import { grokCatalogFetcher } from "./grok.js";
+import { kimiCatalogFetcher } from "./kimi.js";
+import { museCatalogFetcher } from "./muse.js";
+export const CATALOG_CLIENT_TIMEOUT_MS = 30_000;
+export { MUSE_OVERALL_MS } from "./muse.js";
+export const CATALOG_FAIL_COOLDOWN_MS = 60_000;
+// Returns enabled providers excluding manual, expanding agy to include synthetic agy:3p bucket.
+export function catalogProviders(enabledProviders) {
+    const list = enabledProviders.filter((p) => p !== "manual");
+    if (enabledProviders.includes("agy") && !list.includes("agy:3p")) {
+        list.push("agy:3p");
+    }
+    return list;
+}
+// Fetcher map keyed by harness binary id. `agy:3p` resolves to the `agy`
+// fetcher (one spawn writes both rows).
+export const catalogFetchers = {
+    agy: agyCatalogFetcher,
+    claude: claudeCatalogFetcher,
+    codex: codexCatalogFetcher,
+    grok: grokCatalogFetcher,
+    kimi: kimiCatalogFetcher,
+    muse: museCatalogFetcher,
+};
+// In-process state: coalescing in-flight fetches and failure cooldown.
+// Both reset on process restart (no SQLite column).
+const inFlight = new Map();
+const lastFailAt = new Map();
+// Provider ids that share a fetcher. `agy:3p` → `agy`. Others map to
+// themselves. Unknown ids get no fetcher.
+function fetcherKeyFor(provider) {
+    if (provider === "agy:3p")
+        return "agy";
+    return provider;
+}
+// Both agy buckets that a single `agy` fetch produces.
+const AGY_BUCKETS = ["agy", "agy:3p"];
+function bucketsForFetcher(fetcherKey) {
+    if (fetcherKey === "agy")
+        return AGY_BUCKETS;
+    return [fetcherKey];
+}
+function needsFetch(view, ttlHours, refresh, fetcherKey, nowMs) {
+    // Missing / never fetched.
+    if (view.status === "unfetched")
+        return true;
+    // Stale or error: retry if forced, cooldown elapsed, or no cooldown armed
+    // (process restart). Cooldown is process-memory only. Check before TTL:
+    // an error row with null fetchedAt must still respect cooldown.
+    if (view.status === "stale" || view.status === "error") {
+        if (refresh)
+            return true;
+        const failTs = lastFailAt.get(fetcherKey);
+        if (failTs == null)
+            return true;
+        return nowMs - failTs >= CATALOG_FAIL_COOLDOWN_MS;
+    }
+    // TTL expired.
+    if (view.fetchedAt != null) {
+        const age = nowMs - Date.parse(view.fetchedAt);
+        if (age > ttlHours * 3600_000)
+            return true;
+    }
+    else {
+        return true; // no fetchedAt is treated as expired
+    }
+    // Forced refresh.
+    if (refresh)
+        return true;
+    return false;
+}
+export async function ensureCatalogs(opts) {
+    const { db, wait, refresh = false, providers, ttlHours, now = () => new Date() } = opts;
+    const fetchers = opts.fetchers ?? catalogFetchers;
+    const result = new Map();
+    if (!wait) {
+        for (const p of providers) {
+            result.set(p, getCatalog(db, p));
+        }
+        return result;
+    }
+    // Deduplicate providers to the fetcher key level.
+    const seenKeys = new Set();
+    const toFetch = new Map();
+    const providerToKey = new Map();
+    for (const p of providers) {
+        const key = fetcherKeyFor(p);
+        providerToKey.set(p, key);
+        if (p === "manual" || seenKeys.has(key))
+            continue;
+        seenKeys.add(key);
+        const fetcher = fetchers[key];
+        if (!fetcher)
+            continue;
+        // Read the primary bucket to decide whether a fetch is needed.
+        const view = getCatalog(db, key);
+        const nowMs = now().getTime();
+        if (needsFetch(view, ttlHours, refresh, key, nowMs)) {
+            toFetch.set(key, fetcher);
+        }
+    }
+    // Launch fetches in parallel, coalescing with any already in-flight.
+    const pending = [];
+    for (const [key, fetcher] of toFetch) {
+        let p = inFlight.get(key);
+        if (!p) {
+            p = fetcher.fetch();
+            inFlight.set(key, p);
+            // Clean up in-flight on settle (success or failure).
+            p.then(() => inFlight.delete(key), () => inFlight.delete(key));
+        }
+        pending.push({ key, promise: p });
+    }
+    // Wait for all fetches.
+    const settled = await Promise.allSettled(pending.map((e) => e.promise));
+    for (let i = 0; i < pending.length; i++) {
+        const { key } = pending[i];
+        const outcome = settled[i];
+        const buckets = bucketsForFetcher(key);
+        const nowIso = now().toISOString();
+        if (outcome.status === "fulfilled") {
+            const lists = outcome.value;
+            for (const bucket of buckets) {
+                const listed = lists[bucket] ?? [];
+                upsertCatalog(db, bucket, listed, nowIso);
+            }
+        }
+        else {
+            const err = outcome.reason;
+            lastFailAt.set(key, now().getTime());
+            const diag = classifyFailure(key, err);
+            for (const bucket of buckets) {
+                markCatalogFailure(db, bucket, {
+                    diagnosticCode: diag.diagnosticCode,
+                    summary: diag.summary,
+                    action: diag.action,
+                    errorDetail: diag.errorDetail,
+                });
+            }
+        }
+    }
+    // Read final state for all requested providers.
+    for (const p of providers) {
+        result.set(p, getCatalog(db, p));
+    }
+    return result;
+}

package/dist/catalog/kimi.d.ts

@@ -0,0 +1,3 @@
+import type { CatalogFetcher, ListedModel } from "./types.js";
+export declare function parseKimiProviderList(jsonText: string): ListedModel[];
+export declare const kimiCatalogFetcher: CatalogFetcher;

package/dist/catalog/kimi.js

@@ -0,0 +1,51 @@
+import { trackedExecFile } from "../runtime/spawn.js";
+// `kimi provider list --json` (design §6.3): top-level `models` map keyed by
+// "<provider>/<key>"; every entry is on the live picker. id is the entry's
+// `model` when present, else the key's trailing segment. `default` only when a
+// top-level defaultModel names the key (the 2026-09-16 spike JSON had none).
+export function parseKimiProviderList(jsonText) {
+    const data = JSON.parse(jsonText);
+    const models = data?.models;
+    if (!models || typeof models !== "object" || Array.isArray(models)) {
+        throw new Error("kimi: provider list JSON has no models object");
+    }
+    const defaultModel = typeof data.defaultModel === "string" ? data.defaultModel : null;
+    const out = [];
+    for (const [key, v] of Object.entries(models)) {
+        if (!v || typeof v !== "object")
+            continue;
+        const id = typeof v.model === "string" && v.model ? v.model : (key.split("/").pop() ?? key);
+        const entry = {
+            id,
+            displayName: typeof v.displayName === "string" && v.displayName ? v.displayName : id,
+        };
+        if (Array.isArray(v.supportEfforts)) {
+            const efforts = v.supportEfforts.filter((e) => typeof e === "string");
+            if (efforts.length > 0)
+                entry.efforts = efforts;
+        }
+        if (defaultModel !== null && key === defaultModel)
+            entry.default = true;
+        out.push(entry);
+    }
+    if (out.length === 0)
+        throw new Error("kimi: provider list JSON contained no models");
+    return out;
+}
+const EXEC_TIMEOUT_MS = 8000;
+export const kimiCatalogFetcher = {
+    id: "kimi",
+    async fetch() {
+        // Per-fetch catalog-owned signal: never the usage poll's shared controller.
+        const { stdout } = await trackedExecFile("kimi", "kimi", ["provider", "list", "--json"], {
+            timeout: EXEC_TIMEOUT_MS,
+            signal: new AbortController().signal,
+        });
+        try {
+            return { kimi: parseKimiProviderList(stdout) };
+        }
+        catch (e) {
+            throw new Error(`kimi: failed to parse \`kimi provider list --json\` output: ${e?.message ?? e}`);
+        }
+    },
+};

package/dist/catalog/muse.d.ts

@@ -0,0 +1,4 @@
+import type { CatalogFetcher, ListedModel } from "./types.js";
+export declare function parseMuseModelPicker(transcript: string): ListedModel[];
+export declare const MUSE_OVERALL_MS = 28000;
+export declare const museCatalogFetcher: CatalogFetcher;

package/dist/catalog/muse.js

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import { runPty, stripAnsi } from "../adapters/pty.js";
+import { museProbeDir } from "../adapters/muse.js";
+// Muse TUI `/model` picker (design §6.6). The statusline shows the current
+// model (`muse-spark-1.3·max`) before the picker opens, so ids are collected
+// only from the slice after the first "Choose model". The statusline id marks
+// `default` when it also appears in the picker.
+export function parseMuseModelPicker(transcript) {
+    const cleaned = stripAnsi(transcript);
+    const m = /Choose\s*model/i.exec(cleaned);
+    if (!m)
+        throw new Error("muse: no model picker (Choose model) in transcript");
+    const after = cleaned.slice(m.index + m[0].length);
+    const ids = [];
+    for (const im of after.matchAll(/muse-spark-[\w.-]+/g)) {
+        if (!ids.includes(im[0]))
+            ids.push(im[0]);
+    }
+    if (ids.length === 0)
+        throw new Error("muse: no muse-spark ids after the model picker");
+    const statusline = /muse-spark-[\w.-]+/.exec(cleaned.slice(0, m.index));
+    const statusId = statusline ? statusline[0] : null;
+    return ids.map((id) => {
+        const entry = { id, displayName: id };
+        if (statusId !== null && id === statusId)
+            entry.default = true;
+        return entry;
+    });
+}
+export const MUSE_OVERALL_MS = 28_000;
+export const museCatalogFetcher = {
+    id: "muse",
+    async fetch() {
+        const cwd = museProbeDir();
+        fs.mkdirSync(cwd, { recursive: true });
+        // Catalog-owned overall abort (28s). Phase timers inside runPty are
+        // separate; this signal kills the child if everything combined exceeds
+        // the budget. Never the usage-poll shared controller.
+        const transcript = await runPty({
+            file: "muse",
+            args: ["--trust-workspace"],
+            cwd,
+            env: { MUSE_NO_AUTO_UPDATE: "1" },
+            cols: 140,
+            rows: 50,
+            readyRegex: /muse-spark|Muse Code \d/,
+            readyTimeoutMs: 8000,
+            settleDelayMs: 1000,
+            input: "/model",
+            submitInput: "\r",
+            submitAfterMs: 1500,
+            completionRegex: /Choose\s*model/i,
+            abortOn: /Do you trust this workspace|Working \(\d+s|Subscriptions aren't currently available|subscription_unavailable/,
+            timeoutMs: 14000,
+            respondToQueries: true,
+            maxBytes: 256 * 1024,
+            signal: AbortSignal.timeout(MUSE_OVERALL_MS),
+            label: "muse-catalog",
+        });
+        try {
+            return { muse: parseMuseModelPicker(transcript) };
+        }
+        catch (e) {
+            throw new Error(`muse: failed to parse /model picker: ${e?.message ?? e}`);
+        }
+    },
+};

package/dist/catalog/types.d.ts

@@ -0,0 +1,21 @@
+export type CatalogStatus = "ok" | "stale" | "error" | "unfetched";
+export interface ListedModel {
+    id: string;
+    displayName: string;
+    default?: boolean;
+    efforts?: string[];
+}
+export interface CatalogView {
+    status: CatalogStatus;
+    fetchedAt: string | null;
+    listed: ListedModel[];
+    diagnosticCode?: string | null;
+    summary?: string | null;
+    action?: string | null;
+}
+export interface CatalogFetcher {
+    /** Harness binary / usage adapter id: claude, codex, kimi, grok, agy, muse. */
+    id: string;
+    fetch(): Promise<Record<string, ListedModel[]>>;
+}
+export declare function emptyCatalog(): CatalogView;

package/dist/catalog/types.js

@@ -0,0 +1,3 @@
+export function emptyCatalog() {
+    return { status: "unfetched", fetchedAt: null, listed: [] };
+}

package/dist/cli/advise.js

@@ -7,6 +7,23 @@ import { isServiceManaged, runServiceCommand } from "../service/index.js";
 import { detectChannel, printUpdateFooter, printVersionLine, readUpdateCache, refreshUpdateCache, updateFooter, } from "../runtime/updates.js";
 import { ClientError, OFFLINE_LABEL, emptySnapshot, offlineOnlyClient, resolveSnapshot } from "./snapshot-source.js";
 import { checkSkew, execSkewWarning, olderCliWarning, takeoverManaged, unmanagedSkewWarning, } from "./takeover.js";
+function formatModelsLine(rec, now, ttlHours = 6) {
+    if (!rec.models || rec.models.length === 0)
+        return null;
+    const ids = rec.models.map((m) => m.id).join(", ");
+    let suffix = "";
+    if (rec.catalogStatus === "stale") {
+        suffix = " (stale)";
+    }
+    else if (rec.catalogFetchedAt) {
+        const ageMs = now.getTime() - new Date(rec.catalogFetchedAt).getTime();
+        const hours = Math.floor(ageMs / 3_600_000);
+        if (hours >= ttlHours) {
+            suffix = ` (listed ${hours}h ago)`;
+        }
+    }
+    return `models: ${ids}${suffix}`;
+}
 export function registerAdviseCommand(program, deps) {
     const createClient = deps.createClient ?? ((o) => createServiceClient(o));
     const openDb = deps.openDb;
@@ -127,6 +144,9 @@ export function registerAdviseCommand(program, deps) {
             console.log(JSON.stringify(rec, null, 2));
         else {
             console.log(`${rec.use}: ${rec.reason}`);
+            const modelsLine = formatModelsLine(rec, t, cfg.catalogTtlHours);
+            if (modelsLine)
+                console.log(modelsLine);
             printVersionLine(o, VERSION, health?.version);
             printUpdateFooter(o, footer);
         }

package/dist/cli/clients.d.ts

@@ -1,5 +1,6 @@
 import type { Command } from "commander";
 import type { ServiceClient } from "../runtime/client.js";
+import type { CatalogFetcher } from "../catalog/index.js";
 import type { SleepFn } from "./takeover.js";
 import type { UpdateCache } from "../runtime/updates.js";
 export interface CreateClientOptions {
@@ -10,6 +11,7 @@ export interface CreateClientOptions {
 export interface ClientCommandDeps {
     createClient?: (opts: CreateClientOptions) => ServiceClient;
     openDb?: (dbPath: string) => any;
+    migrate?: (db: any) => void;
     resolveWidth?: () => {
         columns: number | undefined;
         tty: boolean;
@@ -24,5 +26,6 @@ export interface ClientCommandDeps {
         readToken?: () => string | undefined;
     };
     checkUpdates?: () => Promise<UpdateCache | null>;
+    catalogFetchers?: Record<string, CatalogFetcher>;
 }
 export declare function registerClientCommands(program: Command, deps?: ClientCommandDeps): void;

package/dist/cli/clients.js

@@ -3,10 +3,12 @@ import { registerStatusCommand } from "./status.js";
 import { registerAdviseCommand } from "./advise.js";
 import { registerIngestCommand } from "./ingest.js";
 import { registerProvidersCommand } from "./providers.js";
+import { registerModelsCommand } from "./models.js";
 export function registerClientCommands(program, deps) {
     registerStatusCommand(program, deps ?? {});
     registerAdviseCommand(program, deps ?? {});
     registerProvidersCommand(program, deps ?? {});
+    registerModelsCommand(program, deps ?? {});
     if (isExperimentalIngestEnabled()) {
         registerIngestCommand(program, deps ?? {});
     }

package/dist/cli/models.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { ClientCommandDeps } from "./clients.js";
+export declare function registerModelsCommand(program: Command, deps?: ClientCommandDeps): void;

package/dist/cli/models.js

@@ -0,0 +1,134 @@
+import { ensureConfig, getDbPath } from "../config.js";
+import { CATALOG_CLIENT_TIMEOUT_MS, ensureCatalogs, catalogProviders } from "../catalog/index.js";
+import { openDb, migrate } from "../store/db.js";
+import { getAllLatest } from "../store/quotas.js";
+import { providerIdentity } from "../advisory/provider-names.js";
+import { readToken } from "../runtime/token.js";
+import { createServiceClient } from "../runtime/client.js";
+import { OFFLINE_LABEL } from "./snapshot-source.js";
+function projectModels(catalogs, quotaMap, providerNames) {
+    const out = [];
+    for (const [id, catalog] of catalogs) {
+        const identity = providerIdentity(id, providerNames);
+        const quota = quotaMap.get(id);
+        const leftoverPct = quota?.usedPct != null ? Math.round((100 - quota.usedPct) * 10) / 10 : null;
+        out.push({
+            id,
+            displayName: identity.displayName,
+            harness: identity.harness,
+            vendor: identity.vendor,
+            leftoverPct,
+            resetsAt: quota?.resetsAt ?? null,
+            catalog,
+        });
+    }
+    return out;
+}
+function printTable(list) {
+    if (!list || list.length === 0) {
+        console.log("No model catalog data available.");
+        return;
+    }
+    const rows = list.map((entry) => {
+        const prov = entry.displayName ?? entry.id;
+        const leftover = entry.leftoverPct != null ? `${entry.leftoverPct}%` : "—";
+        const status = entry.catalog?.status ?? "unfetched";
+        const ids = (entry.catalog?.listed ?? []).map((m) => m.id).join(", ") || "(none)";
+        return { prov, leftover, status, ids };
+    });
+    const maxProv = Math.max(8, ...rows.map((r) => r.prov.length));
+    const maxLeft = Math.max(8, ...rows.map((r) => r.leftover.length));
+    const maxStat = Math.max(6, ...rows.map((r) => r.status.length));
+    const header = [
+        "PROVIDER".padEnd(maxProv),
+        "LEFTOVER".padEnd(maxLeft),
+        "STATUS".padEnd(maxStat),
+        "MODELS",
+    ].join("  ");
+    const lines = rows.map((r) => [r.prov.padEnd(maxProv), r.leftover.padEnd(maxLeft), r.status.padEnd(maxStat), r.ids].join("  "));
+    console.log([header, ...lines].join("\n"));
+}
+export function registerModelsCommand(program, deps = {}) {
+    const createClient = deps.createClient ?? ((o) => createServiceClient(o));
+    const openDbFn = deps.openDb ?? openDb;
+    const migrateFn = deps.migrate ?? migrate;
+    const readTokenFn = deps.takeoverOpts?.readToken ?? readToken;
+    const now = deps.now ?? (() => new Date());
+    const exit = deps.exit ?? process.exit;
+    program
+        .command("models")
+        .description("list available models per quota bucket")
+        .option("--json", "machine-readable output")
+        .option("--provider <id>", "filter to a single provider")
+        .option("--refresh", "force refresh all catalogs")
+        .action(async (o) => {
+        const { config: cfg } = await ensureConfig();
+        const client = createClient({
+            port: cfg.port,
+            token: readTokenFn(),
+            timeoutMs: CATALOG_CLIENT_TIMEOUT_MS,
+        });
+        let body;
+        try {
+            const url = o.refresh
+                ? (o.provider ? `/api/models/refresh?provider=${encodeURIComponent(o.provider)}` : "/api/models/refresh")
+                : (o.provider ? `/api/models?provider=${encodeURIComponent(o.provider)}` : "/api/models");
+            const method = o.refresh ? "post" : "get";
+            if (method === "post") {
+                body = await client.post(url, {});
+            }
+            else {
+                body = await client.get(url);
+            }
+        }
+        catch (err) {
+            // HTTP 4xx errors from a reachable service propagate as errors.
+            if (err?.status && err.status >= 400 && err.status < 500) {
+                console.error(err?.message ?? String(err));
+                exit(1);
+                return;
+            }
+            // Offline fallback when daemon is unreachable:
+            // quotacap models in offline mode may spawn fetchers (wait: true in-process).
+            console.error(OFFLINE_LABEL);
+            try {
+                const dbPath = getDbPath();
+                const db = openDbFn(dbPath);
+                migrateFn(db);
+                const providerParam = o.provider;
+                const allProviders = catalogProviders(cfg.enabledProviders);
+                const known = new Set(allProviders);
+                if (providerParam && !known.has(providerParam)) {
+                    console.error(`unknown provider: ${providerParam}`);
+                    exit(1);
+                    return;
+                }
+                const providers = providerParam ? [providerParam] : allProviders;
+                const catalogs = await ensureCatalogs({
+                    db,
+                    wait: true,
+                    refresh: !!o.refresh,
+                    providers,
+                    ttlHours: cfg.catalogTtlHours,
+                    now,
+                    fetchers: deps.catalogFetchers,
+                });
+                const quotas = getAllLatest(db);
+                const quotaMap = new Map(quotas.map((q) => [q.provider, q]));
+                body = projectModels(catalogs, quotaMap, cfg.providerNames);
+            }
+            catch (offlineErr) {
+                console.error(offlineErr?.message ?? String(offlineErr));
+                exit(1);
+                return;
+            }
+        }
+        const list = Array.isArray(body) ? body : (body?.models ?? body?.results ?? []);
+        if (o.json) {
+            console.log(JSON.stringify(body, null, 2));
+        }
+        else {
+            printTable(list);
+        }
+    });
+}

package/dist/cli/snapshot-source.js

@@ -186,6 +186,7 @@ export function withProviderNames(snapshot) {
             vendor: p.vendor ?? null,
             harness: p.harness ?? null,
             description: p.description ?? null,
+            lastCloses: Array.isArray(p.lastCloses) ? p.lastCloses : [],
         })),
     };
 }

package/dist/config.d.ts

@@ -5,6 +5,7 @@ export declare const ProviderDisplayNameSchema: z.ZodEffects<z.ZodEffects<z.ZodS
 declare const ConfigSchema: z.ZodObject<{
     port: z.ZodDefault<z.ZodNumber>;
     pollMinutes: z.ZodDefault<z.ZodNumber>;
+    catalogTtlHours: z.ZodDefault<z.ZodNumber>;
     enabledProviders: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     knownProviders: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     providerNames: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
@@ -12,6 +13,7 @@ declare const ConfigSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     port: number;
     pollMinutes: number;
+    catalogTtlHours: number;
     enabledProviders: string[];
     knownProviders: string[];
     providerNames: Record<string, string>;
@@ -19,6 +21,7 @@ declare const ConfigSchema: z.ZodObject<{
 }, {
     port?: number | undefined;
     pollMinutes?: number | undefined;
+    catalogTtlHours?: number | undefined;
     enabledProviders?: string[] | undefined;
     knownProviders?: string[] | undefined;
     providerNames?: Record<string, string> | undefined;

package/dist/config.js

@@ -33,6 +33,7 @@ export const ProviderDisplayNameSchema = z
 const ConfigSchema = z.object({
     port: z.number().default(8787),
     pollMinutes: z.number().default(15),
+    catalogTtlHours: z.number().finite().positive().default(6),
     enabledProviders: z.array(z.string()).default(["claude", "codex", "kimi", "grok", "agy", "muse"]),
     knownProviders: z.array(z.string()).default(["claude", "codex", "kimi", "grok", "agy", "muse"]),
     providerNames: z.record(z.string(), ProviderDisplayNameSchema).default({}),
@@ -85,6 +86,7 @@ const VALID_PROVIDER_IDS = Object.keys(adapters).sort();
 const ServiceConfigSchema = z.object({
     port: z.number().int().min(1).max(65535),
     pollMinutes: z.number().finite().positive(),
+    catalogTtlHours: z.number().finite().positive().default(6),
     enabledProviders: z
         .array(z.string())
         .superRefine((ids, ctx) => {

package/dist/format/markdown.d.ts

@@ -1,3 +1,4 @@
 import type { StateSnapshot } from "../advisory/types.js";
 export declare function renderMarkdownTable(snapshot: StateSnapshot, now: Date): string;
 export declare function renderRecommendationSummary(snapshot: StateSnapshot): string;
+export declare function renderModelsMarkdownTable(models: any[]): string;

package/dist/format/markdown.js

@@ -22,3 +22,17 @@ export function renderRecommendationSummary(snapshot) {
     const rec = snapshot.recommendation;
     return `${rec.use}: ${rec.reason}`;
 }
+export function renderModelsMarkdownTable(models) {
+    const lines = models.map((m) => {
+        const name = m.displayName ?? m.id;
+        const leftover = m.leftoverPct != null ? `${m.leftoverPct}%` : "—";
+        const status = m.catalog?.status ?? "unfetched";
+        const ids = (m.catalog?.listed ?? []).map((x) => x.id).join(", ") || "(none)";
+        return `| ${esc(name)} | ${leftover} | ${esc(status)} | ${esc(ids)} |`;
+    });
+    return [
+        "| Provider | Leftover | Status | Models |",
+        "|---|---|---|---|",
+        ...lines,
+    ].join("\n");
+}

package/dist/format/rows.d.ts

@@ -1,5 +1,5 @@
 import type { ProviderSnapshot } from "../advisory/types.js";
-export type StateWord = "On track" | "Behind pace" | "Ahead of pace" | "Cap risk" | "Measuring" | "Not reporting";
+export type StateWord = "On track" | "Behind pace" | "Ahead of pace" | "Cap risk" | "Watch" | "Measuring" | "Not reporting";
 export type RailCell = "used" | "tick" | "unused";
 export type SortKey = "recommended" | "reset-asc" | "reset-desc" | "used-desc" | "used-asc";
 export type CompactSuffix = "" | "!" | "~" | "?";