catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/services/capture.ts

@@ -37,11 +37,6 @@ const HAIKU = "claude-code:claude-haiku-4-5-20251001#default";
 /** spec 1.3 §4.6: `auto` has no family; only the live kit and the capture run it */
 const AUTO = "cursor:auto#default";
 const BUNNY = "opencode:opencode/space-bunny-free#default";
-/** spec 1.3 §5.6: grok 1.0.44's default model (research §3.4) at its cheapest effort */
-const GROK = "grok:grok-4.6#low";
-/** spec 1.3 §6.6: the cheapest Gemini effort; capture runs isolated, on GEMINI_API_KEY */
-const FLASH_LOW = "antigravity:gemini-3.8-flash#low";
-
 /** Spec §11.7–8: one cheap run per backend, plus a read-only role trying to write where enforcement is advisory. */
 const CAPTURE_CASES: CaptureCase[] = [
   { backend: "codex", name: "ok", rung: "codex:gpt-6-luna#low", access: "read-only", brief: SAY_HELLO },
@@ -53,22 +48,6 @@ const CAPTURE_CASES: CaptureCase[] = [
   { backend: "cursor", name: "ok", rung: AUTO, access: "workspace-write", brief: WORK },
   { backend: "cursor", name: "resume", rung: AUTO, access: "read-only", brief: SAY_HELLO, resume: RECALL },
   { backend: "cursor", name: "read-only-write", rung: AUTO, access: "read-only", brief: TRY_WRITE },
-  // spec 1.3 §5.6: the same three on grok; its read-only is the kernel profile, or the read tools on a Mac
-  // with a symlinked docker socket
-  { backend: "grok", name: "ok", rung: GROK, access: "workspace-write", brief: WORK },
-  { backend: "grok", name: "resume", rung: GROK, access: "read-only", brief: SAY_HELLO, resume: RECALL },
-  { backend: "grok", name: "read-only-write", rung: GROK, access: "read-only", brief: TRY_WRITE },
-  // spec 1.3 §6.6: the same three on agy; read-only runs under catherd's deny rules (research §8 agy 2, 5, 6)
-  { backend: "antigravity", name: "ok", rung: FLASH_LOW, access: "workspace-write", brief: WORK },
-  {
-    backend: "antigravity",
-    name: "resume",
-    rung: FLASH_LOW,
-    access: "read-only",
-    brief: SAY_HELLO,
-    resume: RECALL,
-  },
-  { backend: "antigravity", name: "read-only-write", rung: FLASH_LOW, access: "read-only", brief: TRY_WRITE },
 ];
 export const CAPTURE_BACKENDS = [...new Set(CAPTURE_CASES.map((c) => c.backend))];
 
@@ -122,7 +101,7 @@ async function runOnce(
   const p = Bun.spawn([plan.cmd, ...plan.args], {
     cwd: plan.cwd,
     env: workerEnv(process.env, plan.env, plan.cwd),
-    // spec 1.3 §3.3: the brief goes on stdin only to a CLI whose plan reads it there (grok reads a file)
+    // spec 1.3 §3.3: the brief goes on stdin only to a CLI whose plan reads it there (one reads a file)
     stdin: plan.stdinPath ? Bun.file(plan.stdinPath) : "ignore",
     stdout: "pipe",
     stderr: "pipe",

package/src/services/catalog-service.ts

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import type { DiscoveredModel } from "../adapters/backend.ts";
 import { discovered, listingRepo, readDiscovery, writeDiscovery } from "../adapters/discovery.ts";
@@ -7,55 +7,32 @@ import "../adapters/all.ts";
 import {
   buildCatalog,
   type Catalog,
-  CanonicalRung,
   capableFor,
-  DIMS,
   type Family,
   type ModelsFile,
   ModelsFileSchema,
-  type Override,
-  OverrideSchema,
+  type Pair,
   rungInfo,
-  type ScoresFile,
-  ScoresFileSchema,
-  scoresOf,
 } from "../domain/catalog.ts";
-import { costOf, DEFAULT_BILLING, type BillingMode } from "../domain/cost.ts";
-import { CatherdError, errorMessage } from "../domain/errors.ts";
+import { type BillingMode, type Cost, costOf, DEFAULT_BILLING } from "../domain/cost.ts";
+import { errorMessage } from "../domain/errors.ts";
 import { ADAPTER_IDS, tryParseRung } from "../domain/ids.ts";
-import type { Kind } from "../domain/lane.ts";
-import { routeAt } from "../domain/route.ts";
 import { ROLES, type Role } from "../domain/roles.ts";
-import { median } from "../domain/util.ts";
 import { assetPath } from "../infra/assets.ts";
-import { withFileLock } from "../infra/filelock.ts";
 import { log } from "../infra/log.ts";
-import { configDir } from "../infra/paths.ts";
-import { readDerived } from "../infra/sources/cache.ts";
-import { ensurePrivateDir, readVersioned, writeJsonAtomic } from "../infra/store.ts";
+import { withFileLock } from "../infra/filelock.ts";
+import { indexPath } from "../infra/paths.ts";
+import { type IndexFile, IndexFileSchema } from "../domain/slopalytics.ts";
+import { fetchProxy, readIndexFile, writeIndexFile } from "../infra/slopalytics.ts";
+import { PRIVATE_DIR, readVersioned } from "../infra/store.ts";
 import type { CatalogFilter } from "./ports.ts";
-import { listRuns, readAgentRuns, readRecords, readRoutes } from "./run-store.ts";
-import { valuesUsed } from "./provenance.ts";
 import { type EvidenceTable, evidenceLine, evidenceOf, runEvidence } from "./run-evidence.ts";
-import { withStandIns } from "./standins.ts";
 
 const DAY_MS = 24 * 3_600_000;
-/** Spec §5.2: `secs_per_task` counts once a rung has this many of the user's own runs. */
-const MIN_SAMPLES = 5;
 
 let models: ModelsFile | null = null;
-let scores: ScoresFile | null = null;
 export const shippedModels = (): ModelsFile =>
   (models ??= readVersioned(assetPath("catalog/models.json"), ModelsFileSchema, 1));
-export const shippedScores = (): ScoresFile =>
-  (scores ??= readVersioned(assetPath("catalog/scores.json"), ScoresFileSchema, 1));
-
-export const overridePath = (): string => join(configDir(), "catalog.override.json");
-
-export function readOverride(): Override {
-  const file = overridePath();
-  return existsSync(file) ? readVersioned(file, OverrideSchema, 1) : OverrideSchema.parse({});
-}
 
 /**
  * Every backend's last listing (spec §3.5 `<data>/discovery/<backend>.json`); for a backend listed per
@@ -70,75 +47,36 @@ function listedModels(repo?: string): Catalog["listed"] {
   return out;
 }
 
+const RUN_INDEX = "slopalytics.json";
+
 /**
- * Spec §5.2: the median seconds of the user's own successful runs per canonical rung and lane kind
- * (`|*` over every kind), kept only with at least MIN_SAMPLES runs. A run counts under the kind of its
- * lane's route in force when it started; a run with none counts only under `|*`. Native `claude:`
- * subagent runs (agents.jsonl, from record_agent_run) count too; one that names no lane counts only
- * under `|*`.
+ * The shipped families on the Slopalytics index (the run's own pin when `runDir` holds one, else the machine's),
+ * with every listing (in `repo` for a per-repo backend).
  */
-export function measuredSecs(base: Catalog): Catalog["secs"] {
-  const groups = new Map<string, number[]>();
-  const add = (k: string, secs: number) => groups.set(k, [...(groups.get(k) ?? []), secs]);
-  const count = (
-    routes: ReturnType<typeof readRoutes>,
-    rung: string,
-    secs: number,
-    lane: string | null,
-    startedAt: string,
-  ) => {
-    let canonical: string;
-    try {
-      canonical = rungInfo(base, rung).canonical;
-    } catch {
-      return;
-    }
-    // the kind the lane was routed as when this run started, not its newest route
-    const kind: Kind | null = lane ? (routeAt(routes, lane, startedAt)?.kind ?? null) : null;
-    add(`${canonical}|*`, secs);
-    if (kind) add(`${canonical}|${kind}`, secs);
-  };
-  for (const run of listRuns().runs) {
-    const routes = readRoutes(run);
-    for (const r of readRecords(run).records)
-      if (r.status === "ok") count(routes, r.rung, r.secs, r.lane, r.startedAt);
-    for (const a of readAgentRuns(run)) {
-      if (a.status !== "ok" || a.secs === null) continue;
-      // a row is written when the subagent ends; it started `secs` earlier
-      const lane = typeof a.lane === "string" ? a.lane : null;
-      const end = Date.parse(a.at);
-      // a duration past the Date range (record_agent_run takes any) keeps the end, not a RangeError
-      const start = new Date(end - a.secs * 1000);
-      const startedAt = Number.isNaN(start.getTime()) ? a.at : start.toISOString();
-      count(routes, a.rung, a.secs, lane, startedAt);
-    }
-  }
-  const secs: Catalog["secs"] = {};
-  for (const [k, xs] of groups) if (xs.length >= MIN_SAMPLES) secs[k] = median(xs) as number;
-  return secs;
+export function loadCatalog(o: { repo?: string; runDir?: string } = {}): Catalog {
+  const pin = o.runDir === undefined ? null : join(o.runDir, RUN_INDEX);
+  // a missing pin falls back to the machine's index; one that exists but cannot be read is an error, not a fallback
+  const pinned = pin !== null && existsSync(pin) ? readVersioned(pin, IndexFileSchema, 1) : null;
+  return buildCatalog({
+    models: shippedModels(),
+    index: pinned ?? readIndexFile(indexPath()),
+    listed: listedModels(o.repo),
+  });
 }
 
 /**
- * The shipped catalog with every listing (in `repo` for a backend listed per repository), the user's
- * override (or `override` in its place: what a change to it would make) and, unless `timings: false`, own
- * timings.
+ * What a run starts on: the index refreshed if it is due, read once, with the catalog built on exactly that
+ * read, so the start check and the pin written after it cannot disagree.
  */
-export function loadCatalog(o: { timings?: boolean; repo?: string; override?: Override } = {}): Catalog {
-  // spec 1.2 §3.2: whatever the last sync derived; without one (first run, offline), the shipped values alone
-  const synced = readDerived();
-  // spec 1.2 §6.1: every value a rung lacks on a dimension the bars use comes from its nearest stand-in
-  const base = withStandIns(
-    buildCatalog({
-      models: shippedModels(),
-      scores: shippedScores(),
-      synced: synced?.scores,
-      facts: synced?.facts,
-      features: synced?.features,
-      override: o.override ?? readOverride(),
-      listed: listedModels(o.repo),
-    }),
-  );
-  return o.timings === false ? base : { ...base, secs: measuredSecs(base) };
+export async function startIndex(repo: string): Promise<{ catalog: Catalog; index: IndexFile | null }> {
+  await refreshIndex({ auto: true });
+  const index = readIndexFile(indexPath());
+  return { catalog: buildCatalog({ models: shippedModels(), index, listed: listedModels(repo) }), index };
+}
+
+/** Pins `index` into the run: later routes of the run read it, whatever the machine's index becomes. */
+export function writeRunIndex(runDir: string, index: IndexFile | null): void {
+  if (index) writeIndexFile(join(runDir, RUN_INDEX), index);
 }
 
 export interface Refreshed {
@@ -228,142 +166,19 @@ export async function freshenDiscovery(rungs: string[], now = Date.now(), repo?:
   });
 }
 
-/** A rung given as `backend:model#effort` or as a canonical `model#effort`, in canonical form. */
-function canonicalOf(c: Catalog, rung: string): string {
-  let canonical = rung;
-  try {
-    if (rung.includes(":")) canonical = rungInfo(c, rung).canonical;
-  } catch {
-    // a rung the catalog cannot resolve stays as given; the canonical check below refuses it
-  }
-  // a backend's own model id without its backend: the family that backend runs it for names it
-  const hash = canonical.lastIndexOf("#");
-  const model = canonical.slice(0, hash);
-  if (hash > 0 && !c.families.some((f) => f.id === model)) {
-    const family = c.families.find((f) => Object.values(f.on).some((m) => m?.id === model));
-    if (family) canonical = `${family.id}${canonical.slice(hash)}`;
-  }
-  if (!CanonicalRung.safeParse(canonical).success)
-    throw new CatherdError("E_INPUT_INVALID", `"${rung}" is not a rung`, {
-      fix: "name it as backend:model#effort or model#effort, e.g. codex:gpt-6-sol#high",
-    });
-  return canonical;
-}
-
-/** Spec §5.2 "treat like": the user maps an unscored rung onto a scored one in catalog.override.json. */
-export async function saveTreatLike(rung: string, like: string): Promise<{ rung: string; like: string }> {
-  const c = loadCatalog({ timings: false });
-  const from = canonicalOf(c, rung);
-  const to = canonicalOf(c, like);
-  if (!c.scores[to])
-    throw new CatherdError("E_CONFIG_INVALID", `${like} has no scores of its own to lend`, {
-      fix: "treat it like a scored rung; catalog_query lists them",
-    });
-  if (from === to)
-    throw new CatherdError("E_CONFIG_INVALID", `${rung} cannot be treated like itself`, {
-      fix: "name a different, scored rung",
-    });
-  // a rung a sync scored on some dimensions may still borrow the others; one with every value `to` lends may not
-  const own = c.scores[from] ?? {};
-  if (DIMS.filter((d) => c.scores[to]?.[d]).every((d) => own[d]))
-    throw new CatherdError(
-      "E_CONFIG_INVALID",
-      `${from} has scores of its own; a treat-like would not change it`,
-      {
-        fix: "treat-like maps only unscored rungs; catalog_query shows each rung's scores",
-      },
-    );
-  ensurePrivateDir(dirname(overridePath()));
-  await withFileLock(overridePath(), () => {
-    const cur = readOverride();
-    const next = { ...cur, schema: 1, treatLike: { ...cur.treatLike, [from]: to } };
-    const checked = OverrideSchema.safeParse(next);
-    if (!checked.success)
-      throw new CatherdError(
-        "E_CONFIG_INVALID",
-        `the treat-like ${from} → ${to} would not be a valid override`,
-        {
-          fix: checked.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "),
-        },
-      );
-    writeJsonAtomic(overridePath(), next);
-  });
-  return { rung: from, like: to };
-}
-
-/** A rung given as `backend:model#effort` or `model#effort`, as the canonical rung the override keys it by. */
-export const canonicalRung = (rung: string): string => canonicalOf(loadCatalog({ timings: false }), rung);
-
-/**
- * Spec 1.2 §6.4 `treat-like --clear|--reset`: removes the user's treat-likes for `rungs` (canonical), or every
- * one with `"all"`, from catalog.override.json; the shipped ones are not the user's to remove. Returns the
- * mappings removed. Leaves the override's other fields as they are.
- */
-export async function removeTreatLikes(rungs: string[] | "all"): Promise<[string, string][]> {
-  if (!existsSync(overridePath())) return [];
-  let removed: [string, string][] = [];
-  await withFileLock(overridePath(), () => {
-    const cur = readOverride();
-    const gone = Object.entries(cur.treatLike).filter(([r]) => rungs === "all" || rungs.includes(r));
-    removed = gone;
-    if (gone.length === 0) return;
-    const treatLike = Object.fromEntries(
-      Object.entries(cur.treatLike).filter(([r]) => !gone.some(([g]) => g === r)),
-    );
-    writeJsonAtomic(overridePath(), { ...cur, schema: 1, treatLike });
-  });
-  return removed;
-}
-
 /** The backend a billing or harness key bills or isolates: `opencode-go` is a provider of the opencode backend. */
 export const backendOfKey = (key: string) => (key === "opencode-go" ? "opencode" : key);
 
-function rungRows(
-  c: Catalog,
-  backend: string,
-  model: string,
-  efforts: string[],
-  billing: Partial<Record<string, BillingMode>>,
-  evidence: EvidenceTable,
-) {
-  return (efforts.length ? efforts : ["default"]).map((effort) => {
-    const rung = `${backend}:${model}#${effort}`;
-    const info = rungInfo(c, rung);
-    const s = scoresOf(c, info.canonical);
-    const scored: Record<
-      string,
-      {
-        value: number;
-        benchmark: string;
-        confidence: string;
-        source: string;
-        date: string;
-        /** spec 1.2 §5.3: the rung a borrowed or inferred value belongs to */
-        from?: string;
-      }
-    > = {};
-    for (const v of valuesUsed(c, info.canonical))
-      scored[v.dim] = {
-        value: v.value,
-        benchmark: v.benchmark,
-        // a value lent by a treat-like or a stand-in is catherd's guess for this rung, whatever its own confidence
-        confidence: v.inferred ? "inferred" : v.confidence,
-        source: v.source,
-        date: v.date,
-        ...(v.from ? { from: v.from } : {}),
-      };
-    const like = c.treatLike[info.canonical] ?? null;
-    return {
-      rung,
-      enabled: s !== null,
-      ...(s === null ? { why: "unscored: map it with catherd catalog treat-like <rung> <scored rung>" } : {}),
-      scores: scored,
-      treatLike: s?.via ? like : null,
-      cost: costOf(info.family, effort, billing[info.key] ?? DEFAULT_BILLING[info.key]),
-      /** spec 1.2 §8: catherd's own runs on it, over every kind; never used for routing */
-      evidence: evidenceLine(evidenceOf(evidence, info.canonical)),
-    };
-  });
+/** One indexed pair as `catalog_query` and `catalog list` show it. */
+export interface IndexedPair {
+  rung: string;
+  intelligence: number;
+  price: Pair["price"];
+  speed: number | null;
+  context: number | null;
+  cost: Cost;
+  /** spec 1.2 §8: catherd's own runs on it, over every kind; never used for routing */
+  evidence: string | null;
 }
 
 export interface CatalogModel {
@@ -373,70 +188,156 @@ export interface CatalogModel {
   model: string;
   billing: string;
   efforts: string[];
-  context: number | null;
   capabilities: Family["capabilities"] | null;
   roles: Role[];
   listed: boolean | null;
   notes: Record<string, string>;
-  /** spec 1.2 §4.1: the family's API price, dollars per million tokens, and its speed facts */
-  price: Family["price"] | null;
-  speed: Record<string, number>;
-  rungs: ReturnType<typeof rungRows>;
+  rungs: IndexedPair[];
+}
+
+function pairsOf(
+  c: Catalog,
+  backend: string,
+  model: string,
+  billing: Partial<Record<string, BillingMode>>,
+  evidence: EvidenceTable,
+): IndexedPair[] {
+  const probe = rungInfo(c, `${backend}:${model}#default`);
+  const efforts = [...new Set([...probe.efforts, "default"])];
+  return efforts
+    .flatMap((effort) => {
+      const rung = `${backend}:${model}#${effort}`;
+      const info = rungInfo(c, rung);
+      const pair = info.pair;
+      if (!pair) return [];
+      return [
+        {
+          rung,
+          intelligence: pair.intelligence,
+          price: pair.price,
+          speed: pair.speed,
+          context: info.context,
+          cost: costOf(info.family, pair, effort, billing[info.key] ?? DEFAULT_BILLING[info.key]),
+          evidence: evidenceLine(evidenceOf(evidence, info.canonical)),
+        },
+      ];
+    })
+    .sort((a, b) => a.intelligence - b.intelligence);
 }
 
 /**
- * Spec §4.8 `catalog_query`: shipped families on each backend, plus listed models catherd cannot score;
- * a backend listed per repository as it is listed in `f.repo` (a git toplevel), as `route` reads it.
+ * Spec §4.8 `catalog_query`: the indexed pairs of the shipped families on each backend, and of the listed models
+ * catherd has no family for; a model with no indexed pair is not listed. A backend listed per repository as it
+ * is listed in `f.repo` (a git toplevel), as `route` reads it.
  */
 export function catalogQuery(
   f: CatalogFilter,
   billing: Partial<Record<string, BillingMode>> = {},
 ): { total: number; models: CatalogModel[] } {
-  const c = loadCatalog({ timings: false, repo: f.repo });
+  const c = loadCatalog({ repo: f.repo });
   const evidence = runEvidence(c);
   const rows: CatalogModel[] = [];
   const known = new Set<string>();
-  const entry = (backend: string, model: string, fam: Family | null): CatalogModel => {
+  const entry = (backend: string, model: string, fam: Family | null) => {
+    const rungs = pairsOf(c, backend, model, billing, evidence);
+    if (rungs.length === 0) return;
     const probe = rungInfo(c, `${backend}:${model}#default`);
-    return {
+    rows.push({
       id: fam?.id ?? model,
       name: fam?.name ?? null,
       backend,
       model,
       billing: probe.key,
-      efforts: probe.efforts,
-      context: probe.context,
+      efforts: rungs.map((r) => r.rung.slice(r.rung.lastIndexOf("#") + 1)),
       capabilities: fam?.capabilities ?? null,
       roles: ROLES.filter((r) => capableFor(c, probe, r)),
       listed: probe.listed,
       notes: fam?.notes ?? {},
-      price: fam?.price ?? null,
-      speed: fam?.speed ?? {},
-      rungs: rungRows(c, backend, model, probe.efforts, billing, evidence),
-    };
+      rungs,
+    });
   };
   for (const fam of c.families)
     for (const [key, on] of Object.entries(fam.on)) {
       const backends = key === "claude-code" ? ["claude", "claude-code"] : [backendOfKey(key)];
-      for (const b of backends) rows.push(entry(b, on.id, fam));
+      for (const b of backends) entry(b, on.id, fam);
       known.add(`${backendOfKey(key)}:${on.id}`);
     }
   for (const [backend, l] of Object.entries(c.listed))
-    for (const m of l.models) if (!known.has(`${backend}:${m.id}`)) rows.push(entry(backend, m.id, null));
+    for (const m of l.models) if (!known.has(`${backend}:${m.id}`)) entry(backend, m.id, null);
   const needle = f.text?.toLowerCase();
   const kept = rows
     .filter(
       (m) =>
         (!f.role || m.roles.includes(f.role)) &&
         (!f.backend || m.backend === f.backend || m.billing === f.backend) &&
-        (!needle || `${m.id} ${m.model} ${m.name ?? ""}`.toLowerCase().includes(needle)) &&
-        (!f.scoredOnly || m.rungs.some((r) => r.enabled)),
+        (!needle || `${m.id} ${m.model} ${m.name ?? ""}`.toLowerCase().includes(needle)),
     )
-    .sort(
-      (a, b) =>
-        Number(b.rungs.some((r) => r.enabled)) - Number(a.rungs.some((r) => r.enabled)) ||
-        a.id.localeCompare(b.id) ||
-        a.backend.localeCompare(b.backend),
-    );
+    .sort((a, b) => a.id.localeCompare(b.id) || a.backend.localeCompare(b.backend));
   return { total: kept.length, models: kept.slice(0, f.limit) };
 }
+
+export interface IndexStatus {
+  fetchedAt: string | null;
+  checkedAt: string | null;
+  pairs: number;
+  error: string | null;
+}
+
+/** How long a fetched index is trusted before the next automatic refresh. */
+export const INDEX_TTL_MS = 3_600_000;
+
+export function indexStatus(): IndexStatus {
+  const f = readIndexFile(indexPath());
+  return {
+    fetchedAt: f?.fetchedAt ?? null,
+    checkedAt: f?.checkedAt ?? null,
+    pairs: f?.models.length ?? 0,
+    error: f?.error?.message ?? null,
+  };
+}
+
+/**
+ * Keeps `<data>/slopalytics.json` fresh: fetched when its last check is over an hour old (or `force`), the last
+ * good answer kept when the proxy fails and the error recorded beside it. Never throws. An `auto` refresh
+ * (MCP boot, `init`, run start) fetches nothing under `CATHERD_NO_SYNC=1`.
+ */
+export async function refreshIndex(
+  o: { force?: boolean; auto?: boolean; fetch?: typeof fetch; now?: number } = {},
+): Promise<IndexStatus> {
+  if (o.auto && process.env.CATHERD_NO_SYNC === "1") return indexStatus();
+  const now = o.now ?? Date.now();
+  // read, fetch and write run under one lock: a refresh that fails reads the file as the one before it left it
+  try {
+    mkdirSync(dirname(indexPath()), { recursive: true, mode: PRIVATE_DIR });
+    await withFileLock(indexPath(), () => refreshLocked(o, now), { timeoutMs: 30_000 });
+  } catch (e) {
+    log("debug", "catalog", { index: errorMessage(e) });
+  }
+  return indexStatus();
+}
+
+async function refreshLocked(o: { force?: boolean; fetch?: typeof fetch }, now: number): Promise<void> {
+  const prev = readIndexFile(indexPath());
+  if (!o.force && prev && now - Date.parse(prev.checkedAt) < INDEX_TTL_MS) return;
+  const at = new Date(now).toISOString();
+  try {
+    const got = await fetchProxy({ fetch: o.fetch });
+    writeIndexFile(indexPath(), {
+      schema: 1,
+      checkedAt: at,
+      fetchedAt: got.fetchedAt,
+      error: null,
+      models: got.models,
+    });
+  } catch (e) {
+    const message = errorMessage(e);
+    log("debug", "catalog", { index: message });
+    writeIndexFile(indexPath(), {
+      schema: 1,
+      checkedAt: at,
+      fetchedAt: prev?.fetchedAt ?? null,
+      error: { at, message },
+      models: prev?.models ?? [],
+    });
+  }
+}

package/src/services/credentials.ts

@@ -1,23 +1,22 @@
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { CatherdError, isCatherdError } from "../domain/errors.ts";
-import { log } from "../infra/log.ts";
+import { withFileLockSync } from "../infra/filelock.ts";
 import { configDir } from "../infra/paths.ts";
 import { readVersioned, writeJsonAtomic } from "../infra/store.ts";
 
-// Spec §10.4 and 1.2 §9: `<config>/credentials.json`, mode 600, holds catherd's own keys: Jev's
-// (`typesafeApiKey`) and Artificial Analysis's (`artificialAnalysisApiKey`). The schema is a loose object,
-// so a key one catherd does not know survives another's rewrite.
+// Spec §10.4: `<config>/credentials.json`, mode 600, holds catherd's own key, Jev's (`typesafeApiKey`). The
+// schema is a loose object, so a key one catherd does not know (a 1.5 file's `artificialAnalysisApiKey`)
+// survives another's rewrite.
 
 export const credentialsPath = (): string => join(configDir(), "credentials.json");
 
 const CredentialsSchema = z.looseObject({
   schema: z.literal(1).default(1),
   typesafeApiKey: z.string().optional(),
-  artificialAnalysisApiKey: z.string().optional(),
 });
-export type CredentialField = "typesafeApiKey" | "artificialAnalysisApiKey";
+export type CredentialField = "typesafeApiKey";
 
 /** How to repair a credentials file catherd cannot read: `init` alone refuses to overwrite it. */
 const credentialsFix = (): string =>
@@ -45,25 +44,15 @@ export function savedCredential(field: CredentialField): {
 
 /**
  * Keeps every other credential, and the file at mode 600 (spec §10.4). A missing file starts empty; an
- * unreadable or newer-schema one is refused (it throws) rather than overwritten.
+ * unreadable or newer-schema one is refused (it throws) rather than overwritten. The read and the write hold
+ * the file's lock (1.2 minor), so two concurrent `init`s never lose a key.
  */
 export function saveCredential(field: CredentialField, key: string): void {
-  const cur: z.infer<typeof CredentialsSchema> = existsSync(credentialsPath())
-    ? readCredentials()
-    : { schema: 1 };
-  writeJsonAtomic(credentialsPath(), { ...cur, schema: 1, [field]: key.trim() }, { mode: 0o600 });
+  mkdirSync(configDir(), { recursive: true });
+  withFileLockSync(credentialsPath(), () => {
+    const cur: z.infer<typeof CredentialsSchema> = existsSync(credentialsPath())
+      ? readCredentials()
+      : { schema: 1 };
+    writeJsonAtomic(credentialsPath(), { ...cur, schema: 1, [field]: key.trim() }, { mode: 0o600 });
+  });
 }
-
-/**
- * Spec 1.2 §9: `ARTIFICIAL_ANALYSIS_API_KEY`, else the saved key; null when neither has one. The key is
- * optional, so a credentials file that cannot be read means no key here; it is logged.
- */
-export function aaKey(env: Record<string, string | undefined> = process.env): string | null {
-  const fromEnv = env.ARTIFICIAL_ANALYSIS_API_KEY?.trim();
-  if (fromEnv) return fromEnv;
-  const { key, problem } = savedCredential("artificialAnalysisApiKey");
-  if (problem) log("warn", "sources", { error: `no Artificial Analysis key: ${problem.message}` });
-  return key;
-}
-
-export const saveAaKey = (key: string): void => saveCredential("artificialAnalysisApiKey", key);