docks-kit 0.18.0 → 0.19.0

package/cli/src/engine-native/kitDb.ts

@@ -0,0 +1,250 @@
+/**
+ * Per-machine kit store at ~/.docks-kit/kit.db. This module is the only code
+ * that opens the database: it applies the schema migrations, imports the
+ * legacy ~/.docks-kit/state.json once, and serves the network lookup cache.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+
+import { GENERATED_PACKAGE_VERSION } from "../generated/sotPayload";
+import { p } from "./exec";
+
+/**
+ * Append-only. Never edit or reorder a shipped entry. A release that changes the
+ * schema appends one SQL string. State tables (harness_selection, omp_session)
+ * get data-preserving migrations; cache_entry may be dropped and recreated
+ * because every row can be refetched.
+ */
+const MIGRATIONS: ReadonlyArray<string> = [
+  `CREATE TABLE harness_selection (
+  harness TEXT PRIMARY KEY CHECK (harness IN ('claude','codex','agents','omp'))
+) STRICT, WITHOUT ROWID;
+CREATE TABLE omp_session (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  selector TEXT NOT NULL CHECK (trim(selector) <> ''),
+  thinking TEXT CHECK (thinking IS NULL OR trim(thinking) <> ''),
+  advisor_thinking TEXT CHECK (advisor_thinking IS NULL OR trim(advisor_thinking) <> '')
+) STRICT;
+CREATE TABLE cache_entry (
+  key TEXT PRIMARY KEY,
+  fingerprint TEXT NOT NULL,
+  fetched_at INTEGER NOT NULL,
+  payload TEXT NOT NULL
+) STRICT, WITHOUT ROWID;`,
+];
+
+export const KIT_DB_SCHEMA_VERSION: number = MIGRATIONS.length;
+
+export class KitDbTooNewError extends Error {}
+
+export function kitDbFile(home: string): string {
+  return p(home, ".docks-kit", "kit.db");
+}
+
+function userVersion(db: DatabaseSync): number {
+  const version = db.prepare("PRAGMA user_version").get()?.["user_version"];
+  return typeof version === "number" ? version : 0;
+}
+
+/** Run fn inside BEGIN IMMEDIATE; roll back and rethrow on any error. */
+export function inTransaction<T>(db: DatabaseSync, fn: () => T): T {
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    const result = fn();
+    db.exec("COMMIT");
+    return result;
+  } catch (error) {
+    try {
+      db.exec("ROLLBACK");
+    } catch {
+      // SQLite already rolled back (for example on SQLITE_FULL); keep the original error.
+    }
+    throw error;
+  }
+}
+
+function tooNew(version: number): KitDbTooNewError {
+  return new KitDbTooNewError(
+    `~/.docks-kit/kit.db uses schema ${version}; this docks-kit knows schema ${KIT_DB_SCHEMA_VERSION}. Upgrade docks-kit (docks-kit update).`,
+  );
+}
+
+/** Returns true when this call applied migrations. */
+function migrate(db: DatabaseSync): boolean {
+  const current = userVersion(db);
+  if (current > KIT_DB_SCHEMA_VERSION) throw tooNew(current);
+  if (current === KIT_DB_SCHEMA_VERSION) return false;
+  return inTransaction(db, () => {
+    // Another process, possibly a newer kit, can migrate between the first
+    // read and the lock; never lower its version.
+    const locked = userVersion(db);
+    if (locked > KIT_DB_SCHEMA_VERSION) throw tooNew(locked);
+    if (locked === KIT_DB_SCHEMA_VERSION) return false;
+    for (const sql of MIGRATIONS.slice(locked)) db.exec(sql);
+    db.exec(`PRAGMA user_version = ${KIT_DB_SCHEMA_VERSION}`);
+    return true;
+  });
+}
+
+interface LegacyState {
+  readonly harnesses: ReadonlyArray<string>;
+  readonly session?: { selector: string; thinking: string | null; advisorThinking: string | null };
+}
+
+export function isNonBlankString(value: unknown): value is string {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+/** A blank or non-string value is stored as NULL. */
+export function nonBlankOrNull(value: unknown): string | null {
+  return isNonBlankString(value) ? value : null;
+}
+
+// Same validation the JSON store applied: root object, version 1, non-blank
+// selector and levels. Unknown or duplicate harness names are dropped by the
+// table's CHECK and PRIMARY KEY through INSERT OR IGNORE.
+function parseLegacyState(file: string): LegacyState | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8")) as unknown;
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
+  if (!("version" in parsed) || parsed.version !== 1) return undefined;
+
+  const rawHarnesses = "harnesses" in parsed ? parsed.harnesses : undefined;
+  const harnesses = Array.isArray(rawHarnesses)
+    ? rawHarnesses.filter((value): value is string => typeof value === "string")
+    : [];
+  const entry = "ompSession" in parsed ? parsed.ompSession : undefined;
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return { harnesses };
+  const selector = nonBlankOrNull("selector" in entry ? entry.selector : undefined);
+  if (selector === null) return { harnesses };
+  return {
+    harnesses,
+    session: {
+      selector,
+      thinking: nonBlankOrNull("thinking" in entry ? entry.thinking : undefined),
+      advisorThinking: nonBlankOrNull(
+        "advisorThinking" in entry ? entry.advisorThinking : undefined,
+      ),
+    },
+  };
+}
+
+function importLegacyState(db: DatabaseSync, legacy: string): void {
+  inTransaction(db, () => {
+    const rows = db
+      .prepare(
+        "SELECT (SELECT count(*) FROM harness_selection) + (SELECT count(*) FROM omp_session) AS n",
+      )
+      .get()?.["n"];
+    if (rows !== 0) return;
+    const state = parseLegacyState(legacy);
+    if (state === undefined) return;
+    const insertHarness = db.prepare(
+      "INSERT OR IGNORE INTO harness_selection (harness) VALUES (?)",
+    );
+    for (const harness of state.harnesses) insertHarness.run(harness);
+    if (state.session !== undefined) {
+      db.prepare(
+        "INSERT INTO omp_session (id, selector, thinking, advisor_thinking) VALUES (1, ?, ?, ?)",
+      ).run(state.session.selector, state.session.thinking, state.session.advisorThinking);
+    }
+  });
+  // An invalid file is renamed too, so no later run parses it again.
+  try {
+    renameSync(legacy, `${legacy}.migrated`);
+  } catch (error) {
+    // A parallel process renamed it first.
+    const code = typeof error === "object" && error !== null && "code" in error ? error.code : "";
+    if (code !== "ENOENT") throw error;
+  }
+}
+
+/**
+ * Open kit.db, migrate it, import the legacy state file once, and run fn.
+ * A read with neither kit.db nor state.json present creates nothing and
+ * returns undefined.
+ */
+export function withKitDb<T>(
+  home: string,
+  access: "read" | "write",
+  fn: (db: DatabaseSync) => T,
+): T | undefined {
+  const file = kitDbFile(home);
+  const legacy = p(home, ".docks-kit", "state.json");
+  if (access === "read" && !existsSync(file) && !existsSync(legacy)) return undefined;
+
+  const directory = p(home, ".docks-kit");
+  // `mode` applies only when mkdir creates the path, so an existing permissive
+  // ~/.docks-kit would keep its mode.
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  chmodSync(directory, 0o700);
+
+  const db = new DatabaseSync(file);
+  try {
+    // SQLite gives the -wal and -shm files the mode of the main file.
+    if (process.platform !== "win32") chmodSync(file, 0o600);
+    // busy_timeout first: the switch to WAL needs a lock.
+    db.exec(
+      "PRAGMA busy_timeout = 5000; PRAGMA journal_mode = WAL; PRAGMA synchronous = NORMAL; PRAGMA foreign_keys = ON;",
+    );
+    const migrated = migrate(db);
+    const importing = existsSync(legacy);
+    if (importing) importLegacyState(db, legacy);
+    const result = fn(db);
+    // Fold the WAL into kit.db so a copy of kit.db alone holds every row.
+    // Reads can migrate or import too, so they checkpoint after writing.
+    if (access === "write" || migrated || importing) {
+      db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    }
+    return result;
+  } finally {
+    db.close();
+  }
+}
+
+// A new kit release refetches every cached row.
+const CACHE_FINGERPRINT = GENERATED_PACKAGE_VERSION;
+
+/** Return a fresh cached payload; every failure is a miss. */
+export function readCache(
+  home: string,
+  key: string,
+  maxAgeMs: number,
+  now: number,
+): string | undefined {
+  try {
+    return withKitDb(home, "read", (db) => {
+      const row = db
+        .prepare("SELECT fingerprint, fetched_at, payload FROM cache_entry WHERE key = ?")
+        .get(key);
+      const fetchedAt = row?.["fetched_at"];
+      const payload = row?.["payload"];
+      if (row?.["fingerprint"] !== CACHE_FINGERPRINT) return undefined;
+      if (typeof fetchedAt !== "number" || typeof payload !== "string") return undefined;
+      return now - fetchedAt <= maxAgeMs ? payload : undefined;
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+/** Store a successful lookup; a failed write does nothing. */
+export function writeCache(home: string, key: string, payload: string, now: number): void {
+  try {
+    withKitDb(home, "write", (db) =>
+      inTransaction(db, () => {
+        db.prepare("DELETE FROM cache_entry WHERE fingerprint <> ?").run(CACHE_FINGERPRINT);
+        db.prepare(
+          `INSERT INTO cache_entry (key, fingerprint, fetched_at, payload) VALUES (?, ?, ?, ?)
+ON CONFLICT(key) DO UPDATE SET fingerprint = excluded.fingerprint, fetched_at = excluded.fetched_at, payload = excluded.payload`,
+        ).run(key, CACHE_FINGERPRINT, now, payload);
+      }),
+    );
+  } catch {
+    // The cache is an optimization; the next run fetches again.
+  }
+}

package/cli/src/engine-native/liveModels.ts

@@ -0,0 +1,263 @@
+import { readFileSync } from "node:fs";
+
+import { capture, p, which } from "./exec";
+import { LEGACY_SELECTION, readHarnessSelection } from "./harnesses";
+import { isObject, parseJson } from "./jq";
+import { isNonBlankString, readCache, writeCache } from "./kitDb";
+import { modelCatalog } from "./models";
+import type { CatalogSource, CatalogTool, FetchLike, ResolvedCatalog } from "./sharedTypes";
+
+export interface LiveCatalogInputs {
+  readonly home: string;
+  readonly refresh: boolean;
+  readonly fetch: FetchLike;
+  readonly which: (name: string) => string;
+  readonly capture: (cmd: string, args: ReadonlyArray<string>) => Promise<string>;
+  readonly now: () => number;
+}
+
+export const defaultLiveInputs = (home: string, refresh = false): LiveCatalogInputs => ({
+  home,
+  refresh,
+  fetch: globalThis.fetch,
+  which,
+  capture,
+  now: Date.now,
+});
+
+type LiveModel = ResolvedCatalog["models"][number];
+type LiveLookup = {
+  readonly source: Exclude<CatalogSource, "curated">;
+  readonly fetchedAt?: string;
+  readonly models: ReadonlyArray<LiveModel>;
+};
+type Lookup = LiveLookup | { readonly fallbackReason: string };
+
+export function curatedCatalog(tool: CatalogTool): ResolvedCatalog {
+  if (tool === "omp") return { tool, source: "curated", verified: "?", models: [] };
+  return { tool, source: "curated", ...modelCatalog(tool) };
+}
+
+function mergeCurated(curated: ResolvedCatalog, live: ReadonlyArray<LiveModel>): Array<LiveModel> {
+  const models: Array<LiveModel> = [];
+  const notes = new Map<string, string>();
+  for (const entry of curated.models) {
+    if (entry.kind === "alias") models.push(entry);
+    if (entry.note !== undefined) notes.set(entry.id, entry.note);
+  }
+  for (const entry of live) {
+    const note = notes.get(entry.id) ?? entry.note;
+    models.push(
+      note === undefined ? { id: entry.id, kind: "id" } : { id: entry.id, kind: "id", note },
+    );
+  }
+  return models;
+}
+
+export async function resolveCatalog(
+  tool: CatalogTool,
+  inputs: LiveCatalogInputs,
+): Promise<ResolvedCatalog> {
+  const curated = curatedCatalog(tool);
+  if (!(readHarnessSelection(inputs.home) ?? LEGACY_SELECTION).includes(tool)) {
+    return { ...curated, fallbackReason: `${tool} harness not enabled (docks-kit harnesses)` };
+  }
+
+  const lookup =
+    tool === "claude"
+      ? await claudeCatalog(inputs)
+      : tool === "codex"
+        ? codexCatalog(inputs.home)
+        : await ompCatalog(inputs);
+  if ("fallbackReason" in lookup) return { ...curated, fallbackReason: lookup.fallbackReason };
+  return {
+    ...curated,
+    source: lookup.source,
+    ...(lookup.fetchedAt === undefined ? {} : { fetchedAt: lookup.fetchedAt }),
+    models: tool === "omp" ? lookup.models : mergeCurated(curated, lookup.models),
+  };
+}
+
+const ANTHROPIC_CACHE_KEY = "models:anthropic";
+const ANTHROPIC_CACHE_TTL = 6 * 3600_000;
+const NO_CLAUDE_LOGIN = "no Claude Code login found in ~/.claude/.credentials.json";
+
+function cachedClaudeCatalog(payload: string): LiveLookup | undefined {
+  const cached = parseJson(payload);
+  if (cached === undefined || !isObject(cached)) return undefined;
+  const fetchedAt = cached["fetchedAt"];
+  const ids = cached["ids"];
+  if (typeof fetchedAt !== "string" || !Array.isArray(ids)) {
+    return undefined;
+  }
+  if (!ids.every(isNonBlankString)) return undefined;
+  const displayNames = cached["displayNames"];
+  // Names align with ids; older cache rows contain ids only.
+  const names =
+    Array.isArray(displayNames) &&
+    displayNames.length === ids.length &&
+    displayNames.every((name) => name === null || isNonBlankString(name))
+      ? displayNames
+      : undefined;
+  return {
+    source: "anthropic-api",
+    fetchedAt,
+    models: ids.map((id, index) => {
+      const name = names?.[index];
+      return typeof name === "string" ? { id, kind: "id", note: name } : { id, kind: "id" };
+    }),
+  };
+}
+
+async function claudeCatalog(inputs: LiveCatalogInputs): Promise<Lookup> {
+  if (!inputs.refresh) {
+    const cached = readCache(inputs.home, ANTHROPIC_CACHE_KEY, ANTHROPIC_CACHE_TTL, inputs.now());
+    if (cached !== undefined) {
+      const catalog = cachedClaudeCatalog(cached);
+      if (catalog !== undefined) return catalog;
+    }
+  }
+
+  let credentialsText: string;
+  try {
+    credentialsText = readFileSync(p(inputs.home, ".claude", ".credentials.json"), "utf8");
+  } catch {
+    return { fallbackReason: NO_CLAUDE_LOGIN };
+  }
+  const credentials = parseJson(credentialsText);
+  const oauth =
+    credentials !== undefined && isObject(credentials) ? credentials["claudeAiOauth"] : undefined;
+  if (oauth === undefined || !isObject(oauth)) return { fallbackReason: NO_CLAUDE_LOGIN };
+  const token = oauth["accessToken"];
+  const expiresAt = oauth["expiresAt"];
+  if (!isNonBlankString(token) || typeof expiresAt !== "number" || !Number.isFinite(expiresAt)) {
+    return { fallbackReason: NO_CLAUDE_LOGIN };
+  }
+  if (expiresAt <= inputs.now()) {
+    return { fallbackReason: "Claude Code login expired; start claude once to refresh it" };
+  }
+
+  const models: Array<LiveModel> = [];
+  let afterId: string | undefined;
+  try {
+    for (;;) {
+      const url = `https://api.anthropic.com/v1/models?limit=1000${afterId === undefined ? "" : `&after_id=${encodeURIComponent(afterId)}`}`;
+      const response = await inputs.fetch(url, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "anthropic-version": "2023-06-01",
+          "anthropic-beta": "oauth-2025-04-20",
+        },
+        signal: AbortSignal.timeout(5000),
+      });
+      if (response.status !== 200) {
+        return { fallbackReason: `Anthropic API returned HTTP ${response.status}` };
+      }
+      const page: unknown = await response.json();
+      if (typeof page !== "object" || page === null || Array.isArray(page)) {
+        throw new Error("invalid response");
+      }
+      if (
+        !("data" in page) ||
+        !Array.isArray(page.data) ||
+        !("has_more" in page) ||
+        typeof page.has_more !== "boolean"
+      ) {
+        throw new Error("invalid response");
+      }
+      for (const row of page.data) {
+        if (typeof row !== "object" || row === null || Array.isArray(row) || !("id" in row))
+          continue;
+        const id = row.id;
+        if (!isNonBlankString(id)) continue;
+        const name = "display_name" in row ? row.display_name : undefined;
+        models.push(isNonBlankString(name) ? { id, kind: "id", note: name } : { id, kind: "id" });
+      }
+      if (!page.has_more) break;
+      const lastId = "last_id" in page ? page.last_id : undefined;
+      if (!isNonBlankString(lastId) || lastId === afterId) throw new Error("invalid response");
+      afterId = lastId;
+    }
+  } catch (error) {
+    return {
+      fallbackReason: `Anthropic API unreachable: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+
+  // An empty list would drop every curated id; never cache it.
+  if (models.length === 0) return { fallbackReason: "Anthropic API returned no models" };
+  const fetched = inputs.now();
+  const fetchedAt = new Date(fetched).toISOString();
+  writeCache(
+    inputs.home,
+    ANTHROPIC_CACHE_KEY,
+    JSON.stringify({
+      fetchedAt,
+      ids: models.map((model) => model.id),
+      displayNames: models.map((model) => model.note ?? null),
+    }),
+    fetched,
+  );
+  return { source: "anthropic-api", fetchedAt, models };
+}
+
+const NO_CODEX_CACHE = "no Codex model cache (~/.codex/models_cache.json); run codex once";
+const UNREADABLE_CODEX_CACHE = "Codex model cache is unreadable";
+
+function codexCatalog(home: string): Lookup {
+  let text: string;
+  try {
+    text = readFileSync(p(home, ".codex", "models_cache.json"), "utf8");
+  } catch (error) {
+    const missing =
+      typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+    return { fallbackReason: missing ? NO_CODEX_CACHE : UNREADABLE_CODEX_CACHE };
+  }
+  const cache = parseJson(text);
+  if (cache === undefined || !isObject(cache) || !Array.isArray(cache["models"])) {
+    return { fallbackReason: UNREADABLE_CODEX_CACHE };
+  }
+  const models: Array<LiveModel> = [];
+  for (const row of cache["models"]) {
+    if (!isObject(row) || row["visibility"] !== "list") continue;
+    const id = row["slug"];
+    if (!isNonBlankString(id)) continue;
+    const name = row["display_name"];
+    models.push(isNonBlankString(name) ? { id, kind: "id", note: name } : { id, kind: "id" });
+  }
+  if (models.length === 0) return { fallbackReason: "Codex model cache lists no models" };
+  const fetchedAt = cache["fetched_at"];
+  return {
+    source: "codex-cache",
+    ...(typeof fetchedAt === "string" ? { fetchedAt } : {}),
+    models,
+  };
+}
+
+const NO_OMP_CATALOG = "'omp models --json' returned no usable catalog";
+
+async function ompCatalog(inputs: LiveCatalogInputs): Promise<Lookup> {
+  const omp = inputs.which("omp");
+  if (omp === "") return { fallbackReason: "omp not found on PATH" };
+  let raw: string;
+  try {
+    raw = await inputs.capture(omp, ["models", "--json"]);
+  } catch {
+    return { fallbackReason: NO_OMP_CATALOG };
+  }
+  const catalog = parseJson(raw);
+  if (catalog === undefined || !isObject(catalog) || !Array.isArray(catalog["models"])) {
+    return { fallbackReason: NO_OMP_CATALOG };
+  }
+  const models: Array<LiveModel> = [];
+  for (const row of catalog["models"]) {
+    if (!isObject(row) || row["kind"] !== "chat") continue;
+    const id = row["selector"];
+    if (!isNonBlankString(id)) continue;
+    const name = row["name"];
+    models.push(isNonBlankString(name) ? { id, kind: "id", note: name } : { id, kind: "id" });
+  }
+  if (models.length === 0) return { fallbackReason: NO_OMP_CATALOG };
+  return { source: "omp-cli", fetchedAt: new Date(inputs.now()).toISOString(), models };
+}

package/cli/src/engine-native/models.ts

@@ -1,23 +1,25 @@
 /**
- * Model-catalog helpers: manifest listing plus Claude/Codex model validation.
- * Message strings are covered by the golden suites.
+ * Model-catalog helpers: SoT parsing, listing, and Claude/Codex model validation.
+ * Curated message strings are covered by the golden suites.
  */
 import type { Ctx } from "./index";
 import { isObject, parseJson } from "./jq";
 import { payloadDisplayPath, payloadText } from "../payload";
-import type { JsonObject } from "./sharedTypes";
+import type { CatalogSource, JsonObject, ResolvedCatalog } from "./sharedTypes";
 
-export interface ModelEntry {
-  readonly id: string;
-  readonly kind: "alias" | "id";
-  readonly note?: string;
-}
+export type ModelEntry = ResolvedCatalog["models"][number];
 
 export interface ModelCatalog {
   readonly verified: string;
   readonly models: ReadonlyArray<ModelEntry>;
 }
 
+const LIVE_SOURCE_LABELS: Record<Exclude<CatalogSource, "curated">, string> = {
+  "anthropic-api": "Anthropic API via Claude Code login",
+  "codex-cache": "~/.codex/models_cache.json",
+  "omp-cli": "omp models --json",
+};
+
 function toolEntry(tool: string): JsonObject | undefined {
   const doc = parseJson(payloadText("SoT/models.json"));
   if (doc === undefined || !isObject(doc)) return undefined;
@@ -49,43 +51,47 @@ export function modelCatalog(tool: string): ModelCatalog {
   return { verified: typeof verified === "string" ? verified : "?", models };
 }
 
-export function printModels(ctx: Ctx, tool: string): void {
+export function printModels(ctx: Ctx, catalog: ResolvedCatalog): void {
   const { echo, warn } = ctx.services.logger;
-  const entry = toolEntry(tool);
-  if (entry === undefined) {
+  const { tool, models, source, verified, fetchedAt } = catalog;
+  if (source === "curated" && models.length === 0) {
     warn(`Model catalog unavailable (${payloadDisplayPath("SoT/models.json")})`);
     return;
   }
-  const verified = typeof entry["verified"] === "string" ? entry["verified"] : "?";
-  const lines = [`Available ${tool} models (kit-verified ${verified} — SoT/models.json):`];
-  for (const m of modelEntries(entry)) {
-    const note = typeof m["note"] === "string" ? `  — ${m["note"]}` : "";
-    lines.push(`  ${String(m["id"] ?? "")}${note}`);
+  const header =
+    source === "curated"
+      ? `Available ${tool} models (kit-verified ${verified} — SoT/models.json):`
+      : `Available ${tool} models (live — ${LIVE_SOURCE_LABELS[source]}, fetched ${fetchedAt ?? "?"}; aliases and notes from SoT/models.json):`;
+  echo(header);
+  for (const model of models) {
+    echo(`  ${model.id}${model.note === undefined ? "" : `  — ${model.note}`}`);
   }
   if (tool === "claude")
-    lines.push("  (full claude-* model IDs outside the catalog are accepted with a warning)");
-  if (tool === "codex")
-    lines.push("  (well-formed IDs outside the catalog are accepted with a warning)");
-  for (const line of lines) echo(line);
+    echo("  (full claude-* model IDs outside the catalog are accepted with a warning)");
+  if (tool === "codex") echo("  (well-formed IDs outside the catalog are accepted with a warning)");
 }
 
-export function validateClaudeModel(ctx: Ctx, m: string): boolean {
+export function validateClaudeModel(ctx: Ctx, m: string, catalog: ResolvedCatalog): boolean {
   if (m === "") return false;
-  if (modelCatalog("claude").models.some((entry) => entry.id === m)) return true;
+  if (catalog.models.some((entry) => entry.id === m)) return true;
   if (m.startsWith("claude-")) {
     ctx.services.logger.warn(
-      `Claude model '${m}' is not in the kit-verified catalog (SoT/models.json) — applying anyway`,
+      catalog.source === "curated"
+        ? `Claude model '${m}' is not in the kit-verified catalog (SoT/models.json) — applying anyway`
+        : `Claude model '${m}' is not in the live Anthropic model list — applying anyway`,
     );
     return true;
   }
   return false;
 }
 
-export function validateCodexModel(ctx: Ctx, m: string): boolean {
+export function validateCodexModel(ctx: Ctx, m: string, catalog: ResolvedCatalog): boolean {
   if (!/^[A-Za-z0-9._-]+$/.test(m)) return false;
-  if (!modelCatalog("codex").models.some((entry) => entry.id === m)) {
+  if (!catalog.models.some((entry) => entry.id === m)) {
     ctx.services.logger.warn(
-      `Codex model '${m}' is not in the kit-verified catalog (SoT/models.json) — applying anyway (check ~/.codex/config.toml if Codex rejects it)`,
+      catalog.source === "curated"
+        ? `Codex model '${m}' is not in the kit-verified catalog (SoT/models.json) — applying anyway (check ~/.codex/config.toml if Codex rejects it)`
+        : `Codex model '${m}' is not in the live Codex model list — applying anyway (check ~/.codex/config.toml if Codex rejects it)`,
     );
   }
   return true;

package/cli/src/engine-native/modes.ts

@@ -11,12 +11,13 @@ import { syncCodexModel } from "./codexToml";
 import type { Ctx } from "./index";
 import { isObject, parseJson, type Json } from "./jq";
 import { printModels, validateClaudeModel, validateCodexModel } from "./models";
+import { defaultLiveInputs, resolveCatalog } from "./liveModels";
 import { bunBootstrap } from "./bun";
-import { installedVersion, present, report } from "./toolchain";
+import { installedVersion, outdatedReport, present, report } from "./toolchain";
 
-export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
+export async function modeModel(ctx: Ctx, args: ReadonlyArray<string>): Promise<number> {
   const { echo, err, warn } = ctx.services.logger;
-  let tool = "";
+  let tool: "claude" | "codex" | "" = "";
   let value = "";
   for (const arg of args) {
     if (arg === "--dry-run") ctx.dryRun = true;
@@ -32,7 +33,7 @@ export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
     err("Usage: model <claude|codex> [value] [--dry-run]");
     return 2;
   }
-
+  const catalog = await resolveCatalog(tool, defaultLiveInputs(ctx.home));
   if (value === "") {
     if (tool === "claude") {
       const deployed = p(ctx.home, ".claude", "settings.json");
@@ -61,20 +62,20 @@ export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
       echo(`deployed: ${tomlModelText(result.data)}`);
       echo(`SoT:      ${tomlModelText(payloadText("SoT/.codex/config.toml"))}`);
     }
-    printModels(ctx, tool);
+    printModels(ctx, catalog);
     return 0;
   }
 
   if (tool === "claude") {
-    if (!validateClaudeModel(ctx, value)) {
-      printModels(ctx, "claude");
+    if (!validateClaudeModel(ctx, value, catalog)) {
+      printModels(ctx, catalog);
       err(`Invalid Claude model '${value}'`);
       return 2;
     }
     syncClaudeModel(ctx, value);
   } else {
-    if (!validateCodexModel(ctx, value)) {
-      printModels(ctx, "codex");
+    if (!validateCodexModel(ctx, value, catalog)) {
+      printModels(ctx, catalog);
       err(`Invalid Codex model '${value}'`);
       return 2;
     }
@@ -133,8 +134,12 @@ export async function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): Prom
     await report(ctx);
     return 0;
   }
+  if (op === "outdated") {
+    await outdatedReport(ctx, { refresh: args.includes("--refresh") });
+    return 0;
+  }
   if (op !== "ensure") {
-    err("Usage: toolchain [check|ensure <tool>]");
+    err("Usage: toolchain [check|ensure <tool>|outdated [--refresh]]");
     return 2;
   }
   if (tool === "") {