@cleocode/core 2026.6.13 → 2026.6.15

package/dist/llm/catalog-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-resolver.d.ts","sourceRoot":"","sources":["../../src/llm/catalog-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,2BAA2B,CAAC;AAMnC;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;CAC1C;AAED,kFAAkF;AAClF,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,YAAY,GAAG,cAAc,CAAC;AAE9E,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,YAAY,CAAC;IAC3B;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAKD;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAG7E;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,cAAc,GAAG,IAAI,CAcvD;AA6ED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,mBAAmB,CACvC,kBAAkB,EAAE,MAAM,EAC1B,IAAI,CAAC,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAqCtC;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD"}

package/dist/llm/catalog-resolver.js

@@ -0,0 +1,207 @@
+/**
+ * Table-first catalog read chokepoint — `resolveCatalogEntry()` (E8 · T11737).
+ *
+ * ## The single read chokepoint
+ *
+ * The provider+model catalog now has THREE physical surfaces, in strict priority:
+ *
+ *   1. **`models_catalog` DB table** (cleo-global · T11733) — the SSoT. Seeded
+ *      from the shipped offline `curated-catalog.json` (T11734).
+ *   2. **disk JSON cache** (`llm-catalog/` · T9314 · `catalog-cache.ts`) — the
+ *      offline/degraded fallback MIRROR (the most-recent models.dev snapshot).
+ *   3. **shipped seed** (`curated-catalog.json`) — the last-resort floor that
+ *      always ships in the package, so a fresh/offline install always resolves.
+ *
+ * Every catalog reader (the resolver default — T11944; future capability lookups)
+ * funnels through {@link resolveCatalogEntry} so the table and the cache can NEVER
+ * silently diverge: one chokepoint, table-or-fallback, in that order.
+ *
+ * ## Offline-first (degrade) — NO network at read time
+ *
+ * This module NEVER fetches. The network refresh op (`cleo llm refresh-catalog`)
+ * is a SEPARATE leaf. `resolveCatalogEntry()` reads the DB table first; when the
+ * table is empty/unseeded it falls back to the disk-cache snapshot, then to the
+ * shipped seed. A fresh install with no DB rows and no disk cache still resolves
+ * from the bundled `curated-catalog.json`.
+ *
+ * @module llm/catalog-resolver
+ * @task T11737
+ * @epic T11694 (E8-CATALOG-CURATION)
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getLogger } from '../logger.js';
+import { openDualScopeDb, openDualScopeDbAtPath, } from '../store/dual-scope-db.js';
+import { modelsCatalog } from '../store/schema/cleo-global/models-catalog.js';
+import { findLatestCacheFile, getCatalogDir, readCacheFile } from './catalog-cache.js';
+const logger = getLogger('llm-catalog-resolver');
+/** In-memory shipped-seed cache for the process lifetime. */
+let _seed;
+/**
+ * Open the global catalog handle at an EXPLICIT path (test seam).
+ *
+ * Production callers MUST use {@link openDualScopeDb}`('global')`. This path-aware
+ * variant exists so tests open a temp-dir `cleo.db` — never `.cleo/*.db`.
+ *
+ * @param dbPath - Absolute path to the temp `cleo.db`.
+ * @task T11737
+ */
+export async function openCatalogAtPath(dbPath) {
+    const handle = await openDualScopeDbAtPath('global', dbPath);
+    return handle.db;
+}
+/**
+ * Load the shipped seed (`curated-catalog.json`) from disk — no network.
+ *
+ * Read once and cached for the process lifetime. Returns `null` only if the
+ * bundled file is missing/unparseable (never expected — it ships in the package).
+ *
+ * @internal
+ */
+export function loadShippedSeed() {
+    if (_seed !== undefined)
+        return _seed;
+    try {
+        const thisDir = dirname(fileURLToPath(import.meta.url));
+        const jsonPath = join(thisDir, 'curated-catalog.json');
+        _seed = JSON.parse(readFileSync(jsonPath, 'utf-8'));
+    }
+    catch (err) {
+        logger.warn({ err: err instanceof Error ? err.message : String(err) }, 'catalog-resolver: shipped seed unreadable');
+        _seed = null;
+    }
+    return _seed;
+}
+/** Resolve the global Drizzle handle — injected, else canonical open. */
+async function resolveDb(deps) {
+    if (deps?.db !== undefined)
+        return deps.db;
+    const handle = await openDualScopeDb('global');
+    return handle.db;
+}
+/**
+ * Read the latest-released entry for a provider from the `models_catalog` table.
+ *
+ * Returns the single newest row (ordered by `release_date` DESC, `id` DESC as a
+ * stable tie-break) for the provider, or `null` when the provider has no rows
+ * (table empty/unseeded for that provider). LIMIT 1 — never scans the whole table.
+ *
+ * @internal
+ */
+async function readLatestFromTable(db, providerId) {
+    const { desc, eq } = await import('drizzle-orm');
+    const rows = await db
+        .select({
+        id: modelsCatalog.id,
+        providerId: modelsCatalog.providerId,
+        releaseDate: modelsCatalog.releaseDate,
+        contextLimit: modelsCatalog.contextLimit,
+    })
+        .from(modelsCatalog)
+        .where(eq(modelsCatalog.providerId, providerId))
+        .orderBy(desc(modelsCatalog.releaseDate), desc(modelsCatalog.id))
+        .limit(1);
+    const row = rows[0];
+    if (!row)
+        return null;
+    return {
+        id: row.id,
+        providerId: row.providerId,
+        releaseDate: row.releaseDate,
+        contextLimit: row.contextLimit ?? null,
+        source: 'table',
+    };
+}
+/**
+ * Resolve the latest-released catalog entry for a provider from a catalog snapshot
+ * (disk-cache file or shipped seed), sorted by `release_date` DESC.
+ *
+ * The two fallback surfaces carry different shapes — the disk cache is the raw
+ * models.dev `{ [provider]: { models: { [id]: { release_date, limit } } } }`, the
+ * shipped seed is the curated `{ models: { [provider]: { [id]: entry } } }`. This
+ * helper accepts the already-extracted per-provider model map.
+ *
+ * @internal
+ */
+function latestFromModelMap(models, providerId, source) {
+    let bestId = null;
+    let bestDate = '';
+    let bestCtx = null;
+    for (const [id, entry] of Object.entries(models)) {
+        const rd = entry.release_date;
+        if (!rd)
+            continue;
+        if (rd > bestDate || (rd === bestDate && bestId !== null && id > bestId)) {
+            bestDate = rd;
+            bestId = id;
+            bestCtx = entry.limit?.context ?? null;
+        }
+    }
+    if (bestId === null)
+        return null;
+    return { id: bestId, providerId, releaseDate: bestDate, contextLimit: bestCtx, source };
+}
+/**
+ * Resolve the latest-released catalog entry for a provider — the SINGLE table-first
+ * read chokepoint (T11737).
+ *
+ * Resolution order (offline-first, no network):
+ *   1. `models_catalog` DB table (SSoT) — newest `release_date` row for the provider.
+ *   2. disk JSON cache (`llm-catalog/`) — newest entry when the table has no rows.
+ *   3. shipped `curated-catalog.json` seed — last-resort floor (always present).
+ *
+ * Returns `null` only when NONE of the three surfaces carry a dated entry for the
+ * provider — callers then degrade to their own static literal floor (the resolver
+ * default keeps `IMPLICIT_FALLBACK_MODEL` for exactly this case — T11944).
+ *
+ * @param providerCatalogKey - The models.dev provider key (e.g. `anthropic`).
+ * @param deps - Optional injected DB handle / cache dir (tests).
+ * @returns The newest-released entry for the provider, or `null` when unresolved.
+ *
+ * @task T11737
+ */
+export async function resolveCatalogEntry(providerCatalogKey, deps) {
+    const providerId = providerCatalogKey.toLowerCase();
+    // 1. Table-first (SSoT).
+    try {
+        const db = await resolveDb(deps);
+        const fromTable = await readLatestFromTable(db, providerId);
+        if (fromTable)
+            return fromTable;
+    }
+    catch (err) {
+        // A table read failure must NOT break resolution — degrade to the mirrors.
+        logger.warn({ err: err instanceof Error ? err.message : String(err), providerId }, 'catalog-resolver: models_catalog read failed; falling back to disk cache');
+    }
+    // 2. Disk-cache mirror.
+    const cacheDir = deps?.cacheDir ?? getCatalogDir();
+    const latest = findLatestCacheFile(cacheDir);
+    if (latest) {
+        const cache = readCacheFile(latest);
+        const provider = cache?.[providerId];
+        if (provider?.models) {
+            const fromCache = latestFromModelMap(provider.models, providerId, 'disk-cache');
+            if (fromCache)
+                return fromCache;
+        }
+    }
+    // 3. Shipped-seed floor (always present in the package).
+    const seed = loadShippedSeed();
+    const seedModels = seed?.models?.[providerId];
+    if (seedModels) {
+        const fromSeed = latestFromModelMap(seedModels, providerId, 'shipped-seed');
+        if (fromSeed)
+            return fromSeed;
+    }
+    return null;
+}
+/**
+ * Reset the in-memory shipped-seed cache.
+ *
+ * @internal — for use in unit tests only.
+ */
+export function _resetCatalogResolverCache() {
+    _seed = undefined;
+}
+//# sourceMappingURL=catalog-resolver.js.map

package/dist/llm/catalog-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-resolver.js","sourceRoot":"","sources":["../../src/llm/catalog-resolver.ts"],"names":[],"mappings":"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"}

package/dist/llm/catalog-seeder.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Catalog seeder — populates `models_catalog` from the shipped offline seed (T11734).
+ *
+ * ## What it does
+ *
+ * {@link seedModelsCatalog} reads the bundled `curated-catalog.json`, validates it
+ * against the contract zod schema ({@link curatedCatalogSchema}), flattens every
+ * provider→model entry into a `models_catalog` row, and UPSERTS each via
+ * {@link openDualScopeDb}`('global')`. Seeding is the offline bootstrap of the
+ * catalog SSoT — NO network is touched (the network refresh op is a separate leaf).
+ *
+ * ## Idempotent (AC2) + version-skip (AC4)
+ *
+ * The seed carries a semver `version`. The seeder records the seeded version in the
+ * global key-value `__catalog_meta` row and SKIPS a re-seed when the persisted
+ * version equals the shipped version (logged, not re-written). On a NEWER shipped
+ * version it re-seeds (upsert on the `(provider_id, models_dev_id)` natural key, so
+ * a re-seed never duplicates rows — running twice yields the same row count).
+ *
+ * @module llm/catalog-seeder
+ * @task T11734
+ * @epic T11694 (E8-CATALOG-CURATION)
+ */
+import { type CuratedCatalog } from '@cleocode/contracts';
+import { type CleoGlobalDb } from '../store/dual-scope-db.js';
+import { type NewModelsCatalogRow } from '../store/schema/cleo-global/models-catalog.js';
+/** Result of a {@link seedModelsCatalog} run. */
+export interface SeedCatalogResult {
+    /** Whether rows were written this run (`false` on a version-skip). */
+    readonly seeded: boolean;
+    /** The seed version applied (or already persisted on a skip). */
+    readonly version: string;
+    /** Number of rows upserted (0 on a skip). */
+    readonly rowCount: number;
+    /** Why the run behaved as it did. */
+    readonly reason: 'seeded' | 'version-skip' | 'reseeded-newer';
+}
+/** Injectable seam for {@link seedModelsCatalog} (tests pass a temp-DB handle + fixture). */
+export interface SeedCatalogDeps {
+    /**
+     * An already-open global Drizzle handle. When omitted the seeder opens via
+     * {@link openDualScopeDb}`('global')`. Tests pass a temp-DB handle (opened via
+     * {@link openSeederAtPath}) to stay off `.cleo/*.db`.
+     */
+    readonly db?: CleoGlobalDb;
+    /**
+     * A catalog object to seed from, bypassing the bundled `curated-catalog.json`
+     * (tests pass a fixture). When omitted the shipped seed is read + validated.
+     */
+    readonly catalog?: CuratedCatalog;
+}
+/**
+ * Open the global seeder handle at an EXPLICIT path (test seam).
+ *
+ * @param dbPath - Absolute path to the temp `cleo.db`.
+ * @task T11734
+ */
+export declare function openSeederAtPath(dbPath: string): Promise<CleoGlobalDb>;
+/**
+ * Read + validate the shipped seed (`curated-catalog.json`) — no network.
+ *
+ * Throws a descriptive error when the bundled file is missing or fails schema
+ * validation, so a malformed seed fails the build/seed loudly rather than silently
+ * persisting garbage.
+ *
+ * @task T11734
+ */
+export declare function loadAndValidateSeed(): CuratedCatalog;
+/**
+ * Flatten a {@link CuratedCatalog} into `models_catalog` INSERT rows.
+ *
+ * Each provider→model entry becomes one row; nested `modalities` / `cost` are
+ * JSON-serialized into their TEXT columns. `id` and `models_dev_id` both take the
+ * entry id (the latter anchors the `(provider_id, models_dev_id)` upsert key).
+ *
+ * @task T11734
+ */
+export declare function flattenCatalogToRows(catalog: CuratedCatalog): NewModelsCatalogRow[];
+/**
+ * Seed `models_catalog` from the shipped offline seed — idempotent, offline-first.
+ *
+ * Behaviour:
+ *   - First run (no persisted version): upsert every row, persist the version. (AC1)
+ *   - Re-run with the SAME version: SKIP (logged, not re-written). (AC4)
+ *   - Re-run with a NEWER shipped version: re-seed (upsert, no duplicates). (AC3)
+ *
+ * The upsert is on the `(provider_id, models_dev_id)` natural key, so running twice
+ * yields the same row count and never duplicates (AC2). NO network is touched.
+ *
+ * @param deps - Optional injected DB handle / fixture catalog (tests).
+ * @returns A {@link SeedCatalogResult} describing what happened.
+ *
+ * @task T11734
+ */
+export declare function seedModelsCatalog(deps?: SeedCatalogDeps): Promise<SeedCatalogResult>;
+//# sourceMappingURL=catalog-seeder.d.ts.map

package/dist/llm/catalog-seeder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-seeder.d.ts","sourceRoot":"","sources":["../../src/llm/catalog-seeder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,OAAO,EAAE,KAAK,cAAc,EAAwB,MAAM,qBAAqB,CAAC;AAGhF,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,+CAA+C,CAAC;AAIvD,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,cAAc,GAAG,gBAAgB,CAAC;CAC/D;AAED,6FAA6F;AAC7F,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,YAAY,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAG5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAKpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,mBAAmB,EAAE,CA0BnF;AAiDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAgD1F"}

package/dist/llm/catalog-seeder.js

@@ -0,0 +1,189 @@
+/**
+ * Catalog seeder — populates `models_catalog` from the shipped offline seed (T11734).
+ *
+ * ## What it does
+ *
+ * {@link seedModelsCatalog} reads the bundled `curated-catalog.json`, validates it
+ * against the contract zod schema ({@link curatedCatalogSchema}), flattens every
+ * provider→model entry into a `models_catalog` row, and UPSERTS each via
+ * {@link openDualScopeDb}`('global')`. Seeding is the offline bootstrap of the
+ * catalog SSoT — NO network is touched (the network refresh op is a separate leaf).
+ *
+ * ## Idempotent (AC2) + version-skip (AC4)
+ *
+ * The seed carries a semver `version`. The seeder records the seeded version in the
+ * global key-value `__catalog_meta` row and SKIPS a re-seed when the persisted
+ * version equals the shipped version (logged, not re-written). On a NEWER shipped
+ * version it re-seeds (upsert on the `(provider_id, models_dev_id)` natural key, so
+ * a re-seed never duplicates rows — running twice yields the same row count).
+ *
+ * @module llm/catalog-seeder
+ * @task T11734
+ * @epic T11694 (E8-CATALOG-CURATION)
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { curatedCatalogSchema } from '@cleocode/contracts';
+import { sql } from 'drizzle-orm';
+import { getLogger } from '../logger.js';
+import { openDualScopeDb, openDualScopeDbAtPath, } from '../store/dual-scope-db.js';
+import { modelsCatalog, } from '../store/schema/cleo-global/models-catalog.js';
+const logger = getLogger('llm-catalog-seeder');
+/**
+ * Open the global seeder handle at an EXPLICIT path (test seam).
+ *
+ * @param dbPath - Absolute path to the temp `cleo.db`.
+ * @task T11734
+ */
+export async function openSeederAtPath(dbPath) {
+    const handle = await openDualScopeDbAtPath('global', dbPath);
+    return handle.db;
+}
+/**
+ * Read + validate the shipped seed (`curated-catalog.json`) — no network.
+ *
+ * Throws a descriptive error when the bundled file is missing or fails schema
+ * validation, so a malformed seed fails the build/seed loudly rather than silently
+ * persisting garbage.
+ *
+ * @task T11734
+ */
+export function loadAndValidateSeed() {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const jsonPath = join(thisDir, 'curated-catalog.json');
+    const raw = JSON.parse(readFileSync(jsonPath, 'utf-8'));
+    return curatedCatalogSchema.parse(raw);
+}
+/**
+ * Flatten a {@link CuratedCatalog} into `models_catalog` INSERT rows.
+ *
+ * Each provider→model entry becomes one row; nested `modalities` / `cost` are
+ * JSON-serialized into their TEXT columns. `id` and `models_dev_id` both take the
+ * entry id (the latter anchors the `(provider_id, models_dev_id)` upsert key).
+ *
+ * @task T11734
+ */
+export function flattenCatalogToRows(catalog) {
+    const rows = [];
+    for (const [providerId, models] of Object.entries(catalog.models)) {
+        for (const [modelId, entry] of Object.entries(models)) {
+            rows.push({
+                id: modelId,
+                providerId,
+                name: entry.name,
+                family: entry.family,
+                attachment: entry.attachment,
+                reasoning: entry.reasoning,
+                temperature: entry.temperature,
+                interleaved: entry.interleaved,
+                toolCall: entry.tool_call,
+                modalities: JSON.stringify(entry.modalities),
+                cost: JSON.stringify(entry.cost),
+                contextLimit: entry.limit.context,
+                outputLimit: entry.limit.output,
+                status: entry.status,
+                releaseDate: entry.release_date,
+                modelsDevId: entry.id,
+                source: 'seed',
+            });
+        }
+    }
+    return rows;
+}
+/** Resolve the global Drizzle handle — injected, else canonical open. */
+async function resolveDb(deps) {
+    if (deps?.db !== undefined)
+        return deps.db;
+    const handle = await openDualScopeDb('global');
+    return handle.db;
+}
+/** The KV key under which the seeded catalog version is persisted. */
+const CATALOG_VERSION_KEY = 'catalog.seed.version';
+/**
+ * Read the persisted seeded-catalog version from the lightweight `__catalog_meta`
+ * KV table (created on demand), or `null` when never seeded.
+ *
+ * @internal
+ */
+async function readPersistedVersion(db) {
+    db.run(sql `CREATE TABLE IF NOT EXISTS __catalog_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)`);
+    const rows = (await db.all(sql `SELECT value FROM __catalog_meta WHERE key = ${CATALOG_VERSION_KEY} LIMIT 1`));
+    return rows[0]?.value ?? null;
+}
+/** Persist the seeded-catalog version into `__catalog_meta`. @internal */
+async function writePersistedVersion(db, version) {
+    db.run(sql `INSERT INTO __catalog_meta (key, value) VALUES (${CATALOG_VERSION_KEY}, ${version})
+        ON CONFLICT(key) DO UPDATE SET value = excluded.value`);
+}
+/** Compare two semver strings — `a > b`? Padded numeric per-segment compare. @internal */
+function semverGreater(a, b) {
+    const pa = a.split('.').map((n) => Number.parseInt(n, 10));
+    const pb = b.split('.').map((n) => Number.parseInt(n, 10));
+    for (let i = 0; i < 3; i++) {
+        const da = pa[i] ?? 0;
+        const db = pb[i] ?? 0;
+        if (da > db)
+            return true;
+        if (da < db)
+            return false;
+    }
+    return false;
+}
+/**
+ * Seed `models_catalog` from the shipped offline seed — idempotent, offline-first.
+ *
+ * Behaviour:
+ *   - First run (no persisted version): upsert every row, persist the version. (AC1)
+ *   - Re-run with the SAME version: SKIP (logged, not re-written). (AC4)
+ *   - Re-run with a NEWER shipped version: re-seed (upsert, no duplicates). (AC3)
+ *
+ * The upsert is on the `(provider_id, models_dev_id)` natural key, so running twice
+ * yields the same row count and never duplicates (AC2). NO network is touched.
+ *
+ * @param deps - Optional injected DB handle / fixture catalog (tests).
+ * @returns A {@link SeedCatalogResult} describing what happened.
+ *
+ * @task T11734
+ */
+export async function seedModelsCatalog(deps) {
+    const catalog = deps?.catalog ?? loadAndValidateSeed();
+    const db = await resolveDb(deps);
+    const persisted = await readPersistedVersion(db);
+    if (persisted !== null && !semverGreater(catalog.version, persisted)) {
+        logger.debug({ persisted, shipped: catalog.version }, 'catalog-seeder: persisted version >= shipped; skipping re-seed');
+        return { seeded: false, version: persisted, rowCount: 0, reason: 'version-skip' };
+    }
+    const rows = flattenCatalogToRows(catalog);
+    for (const row of rows) {
+        await db
+            .insert(modelsCatalog)
+            .values(row)
+            .onConflictDoUpdate({
+            target: [modelsCatalog.providerId, modelsCatalog.modelsDevId],
+            set: {
+                id: row.id,
+                name: row.name,
+                family: row.family,
+                attachment: row.attachment,
+                reasoning: row.reasoning,
+                temperature: row.temperature,
+                interleaved: row.interleaved,
+                toolCall: row.toolCall,
+                modalities: row.modalities,
+                cost: row.cost,
+                contextLimit: row.contextLimit,
+                outputLimit: row.outputLimit,
+                status: row.status,
+                releaseDate: row.releaseDate,
+                source: row.source,
+                seededAt: sql `(datetime('now'))`,
+            },
+        });
+    }
+    await writePersistedVersion(db, catalog.version);
+    const reason = persisted === null ? 'seeded' : 'reseeded-newer';
+    logger.debug({ version: catalog.version, rowCount: rows.length, reason }, 'catalog-seeder: models_catalog seeded');
+    return { seeded: true, version: catalog.version, rowCount: rows.length, reason };
+}
+//# sourceMappingURL=catalog-seeder.js.map

package/dist/llm/catalog-seeder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-seeder.js","sourceRoot":"","sources":["../../src/llm/catalog-seeder.ts"],"names":[],"mappings":"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"}

package/dist/llm/cli-ops.d.ts

@@ -19,6 +19,22 @@
 import type { LlmAddParams, LlmAddResult, LlmAuxiliaryStatusParams, LlmAuxiliaryStatusResult, LlmListParams, LlmListResult, LlmProfileParams, LlmProfileResult, LlmRemoveParams, LlmRemoveResult, LlmSystemsOfUseParams, LlmSystemsOfUseResult, LlmTestParams, LlmTestResult, LlmUseParams, LlmUseResult, LlmWhoamiParams, LlmWhoamiResult } from '@cleocode/contracts';
 import { type EngineResult } from '@cleocode/contracts';
 import { resolveAuxiliaryFallbackChain } from './auxiliary-fallback.js';
+/**
+ * Redact every occurrence of a secret in free text (S-11).
+ *
+ * Used before DEBUG-logging a provider error body: Anthropic 4xx payloads can
+ * reflect request headers (including the bearer token) back in human-readable
+ * form, so the body must never reach a log stream with the live secret in it.
+ * Replaces each occurrence with the standard last-4 preview. Empty/short
+ * secrets (< 8 chars) redact nothing — they cannot meaningfully leak and a
+ * short needle would shred unrelated text.
+ *
+ * @param text   - Raw text that may contain the secret.
+ * @param secret - The live credential to scrub.
+ * @returns The text with every occurrence of the secret replaced.
+ * @task T11968
+ */
+export declare function redactSecret(text: string, secret: string | null): string;
 /**
  * `llm.add` — upsert a credential into the multi-credential pool.
  *

package/dist/llm/cli-ops.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-ops.d.ts","sourceRoot":"","sources":["../../src/llm/cli-ops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,wBAAwB,EACxB,wBAAwB,EACxB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,eAAe,EAEf,qBAAqB,EACrB,qBAAqB,EACrB,aAAa,EACb,aAAa,EACb,YAAY,EACZ,YAAY,EAEZ,eAAe,EACf,eAAe,EAGhB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,YAAY,EAIlB,MAAM,qBAAqB,CAAC;AAO7B,OAAO,EAGL,6BAA6B,EAC9B,MAAM,yBAAyB,CAAC;AAuHjC;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAwBtF;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC,CAWzF;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC,CAc/F;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CA4BtF;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,YAAY,CAAC,gBAAgB,CAAC,CAAC,CAqDzC;AAED;;;;;;;;;GASG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC,CA4FzF;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC,CAgC/F;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,YAAY,CAAC,qBAAqB,CAAC,CAAC,CAO9C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,wBAAwB,GAC/B,OAAO,CAAC,YAAY,CAAC,wBAAwB,CAAC,CAAC,CAoBjD;AAGD,OAAO,EAAE,6BAA6B,EAAE,CAAC"}
+{"version":3,"file":"cli-ops.d.ts","sourceRoot":"","sources":["../../src/llm/cli-ops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,wBAAwB,EACxB,wBAAwB,EACxB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,eAAe,EAEf,qBAAqB,EACrB,qBAAqB,EACrB,aAAa,EACb,aAAa,EACb,YAAY,EACZ,YAAY,EAEZ,eAAe,EACf,eAAe,EAGhB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,YAAY,EAIlB,MAAM,qBAAqB,CAAC;AAQ7B,OAAO,EAGL,6BAA6B,EAC9B,MAAM,yBAAyB,CAAC;AAuCjC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAGxE;AAoFD;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAwBtF;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC,CAWzF;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC,CAc/F;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CA4BtF;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,YAAY,CAAC,gBAAgB,CAAC,CAAC,CAqDzC;AAED;;;;;;;;;GASG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC,CAoGzF;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC,CAgC/F;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,YAAY,CAAC,qBAAqB,CAAC,CAAC,CAO9C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,wBAAwB,GAC/B,OAAO,CAAC,YAAY,CAAC,wBAAwB,CAAC,CAAC,CAoBjD;AAGD,OAAO,EAAE,6BAA6B,EAAE,CAAC"}

package/dist/llm/cli-ops.js

@@ -18,6 +18,7 @@
  */
 import { engineError, engineSuccess, WHOAMI_ROLE_IDS, } from '@cleocode/contracts';
 import { setConfigValue } from '../config.js';
+import { getLogger } from '../logger.js';
 // S-13 (CWE-209): wrap any user-facing error string in the project-wide
 // `redactContent` helper so a stack trace or fetch error that incidentally
 // contains a credential substring is automatically scrubbed before it
@@ -30,6 +31,7 @@ import { addCredential, getCredentialByLabel, listCredentials, removeCredential,
 import { IMPLICIT_FALLBACK_MODEL, resolveLLMForRole } from './role-resolver.js';
 import { tokenPreview } from './sealed-credential.js';
 import { listSystemsOfUse } from './system-of-use-registry.js';
+const logger = getLogger('llm-cli-ops');
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -50,6 +52,26 @@ const ALL_ROLES = WHOAMI_ROLE_IDS;
 // ---------------------------------------------------------------------------
 // Redaction helpers
 // ---------------------------------------------------------------------------
+/**
+ * Redact every occurrence of a secret in free text (S-11).
+ *
+ * Used before DEBUG-logging a provider error body: Anthropic 4xx payloads can
+ * reflect request headers (including the bearer token) back in human-readable
+ * form, so the body must never reach a log stream with the live secret in it.
+ * Replaces each occurrence with the standard last-4 preview. Empty/short
+ * secrets (< 8 chars) redact nothing — they cannot meaningfully leak and a
+ * short needle would shred unrelated text.
+ *
+ * @param text   - Raw text that may contain the secret.
+ * @param secret - The live credential to scrub.
+ * @returns The text with every occurrence of the secret replaced.
+ * @task T11968
+ */
+export function redactSecret(text, secret) {
+    if (!secret || secret.length < 8 || !text)
+        return text;
+    return text.split(secret).join(`…${secret.slice(-4)}`);
+}
 /**
  * Return a redacted preview of a token tagged by auth scheme (S-11).
  *
@@ -75,10 +97,10 @@ function tokenPreviewOf(token, authType) {
 /**
  * Build the redacted view used by every `cleo llm` result envelope.
  *
- * `hasRefreshToken` is hard-coded to `false` in Phase 2 — see
- * `StoredCredential` in `credentials-store.ts` for the S-07 rationale.
- * The contract field stays on `LlmStoredCredentialView` so Phase 3 can
- * resurrect it once a real refresh flow ships.
+ * `hasRefreshToken` reflects whether a refresh token is actually stored —
+ * the refresh flow consuming it shipped in `credential-pool.ts`
+ * (`_refreshViaPkce` / `proactiveRefresh`), superseding the Phase-2 S-07
+ * hardcode that reported `false` unconditionally (T11958).
  */
 function viewOf(c) {
     return {
@@ -86,7 +108,7 @@ function viewOf(c) {
         label: c.label,
         authType: c.authType,
         tokenPreview: tokenPreviewOf(c.accessToken, c.authType),
-        hasRefreshToken: false,
+        hasRefreshToken: typeof c.refreshToken === 'string' && c.refreshToken.length > 0,
         expiresAt: c.expiresAt ?? null,
         priority: c.priority,
         source: c.source,
@@ -351,14 +373,19 @@ export async function llmTest(params) {
     try {
         const response = await fetch(url, { method: 'POST', headers, body });
         if (!response.ok) {
-            // S-11: NEVER echo the response body in the error envelope. Some
+            // S-11: NEVER echo the response body in the error ENVELOPE. Some
             // provider 4xx responses include reflected request headers (e.g.
             // Anthropic's error payload can carry `x-api-key` substring matches
             // back in human-readable form), and a sloppy log pipeline could
-            // surface that to an audit log. Surface only the HTTP status —
-            // operators who need the body can re-run with `CLEO_LOG_LEVEL=debug`
-            // and inspect the underlying fetch trace.
-            return engineError('E_PROVIDER_PING_FAILED', `${provider} returned HTTP ${response.status} (body suppressed for credential safety; rerun with CLEO_LOG_LEVEL=debug to inspect via raw fetch trace)`);
+            // surface that to an audit log. Surface only the HTTP status in the
+            // envelope — and emit the body to the DEBUG log with the in-scope
+            // credential redacted, so the failure is actually diagnosable
+            // (T11958/DHQ-075 repro follow-through: the previous message promised
+            // a "raw fetch trace" that did not exist).
+            const bodyText = await response.text().catch(() => '');
+            logger.debug({ provider, status: response.status, body: redactSecret(bodyText, token).slice(0, 1024) }, 'llm.test provider ping failed');
+            return engineError('E_PROVIDER_PING_FAILED', `${provider} returned HTTP ${response.status} (body suppressed for credential safety; ` +
+                `rerun with CLEO_LOG_LEVEL=debug to log the redacted response body)`);
         }
         const parsed = (await response.json());
         providerResponseId = typeof parsed.id === 'string' ? parsed.id : null;