@desplega.ai/agent-swarm 1.98.0 → 1.98.1

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.98.0",
+    "version": "1.98.1",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.98.0",
+  "version": "1.98.1",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",
@@ -95,7 +95,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.3.10",
     "@faker-js/faker": "^10.4.0",
-    "@opencode-ai/plugin": "1.14.30",
+    "@opencode-ai/plugin": "1.17.4",
     "@types/bun": "latest"
   },
   "peerDependencies": {
@@ -118,7 +118,7 @@
     "@linear/sdk": "^77.0.0",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "@openai/codex-sdk": "^0.139.0",
-    "@opencode-ai/sdk": "^1.16.2",
+    "@opencode-ai/sdk": "^1.17.4",
     "@openfort/openfort-node": "^0.9.1",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",

package/src/be/modelsdev-cache.ts

@@ -24,6 +24,11 @@ export const MODELSDEV_CACHE_PATH = path.join("src", "be", "modelsdev-cache.json
 /**
  * Resolve the vendored models.dev cache from source checkouts and compiled
  * Docker images. The API image copies the snapshot to `/app/src/be/...`.
+ *
+ * This file is now fallback-only for pricing freshness: boot seeding uses it
+ * when the DB is empty or models.dev is unavailable, while
+ * `src/be/pricing-refresh.ts` owns live price updates. The UI model picker
+ * still imports the same snapshot for names, labels, and context windows.
  */
 export function loadModelsDevCache(): ModelsDevCache | null {
   const explicitPath = process.env.MODELSDEV_CACHE_PATH;

package/src/be/pricing-refresh.ts

@@ -0,0 +1,189 @@
+import { scrubSecrets } from "../utils/secret-scrubber";
+import {
+  createLogEntry,
+  getActivePricingRow,
+  getDb,
+  type InsertPricingRowInput,
+  insertPricingRow,
+} from "./db";
+import type { ModelsDevCache } from "./modelsdev-cache";
+import { buildModelsDevSeedRows, type PricingSeedRow } from "./seed-pricing";
+
+const MODELSDEV_API_URL = "https://models.dev/api.json";
+export const PRICING_REFRESH_INTERVAL_MS = 12 * 60 * 60 * 1000;
+
+let lastETag: string | null = null;
+let refreshLoopStarted = false;
+
+interface RefreshPricingOptions {
+  fetchImpl?: typeof fetch;
+  now?: number;
+}
+
+export interface PricingRefreshResult {
+  status: "refreshed" | "not_modified";
+  candidateRows: number;
+  inserted: number;
+  unchanged: number;
+  pruned: number;
+  etag?: string;
+}
+
+function logPricingRefresh(message: string): void {
+  console.log(scrubSecrets(`[pricing-refresh] ${message}`));
+}
+
+function logPricingRefreshError(message: string, err: unknown): void {
+  const detail = err instanceof Error ? err.message : String(err);
+  console.warn(scrubSecrets(`[pricing-refresh] ${message}: ${detail}`));
+}
+
+function insertChangedPricingRows(
+  rows: PricingSeedRow[],
+  now: number,
+): {
+  inserted: number;
+  unchanged: number;
+} {
+  let inserted = 0;
+  let unchanged = 0;
+
+  const tx = getDb().transaction((seedRows: PricingSeedRow[]) => {
+    for (const row of seedRows) {
+      const existing = getActivePricingRow(row.provider, row.model, row.tokenClass, now);
+      if (existing?.pricePerMillionUsd === row.pricePerMillionUsd) {
+        unchanged += 1;
+        continue;
+      }
+
+      const input: InsertPricingRowInput = {
+        ...row,
+        effectiveFrom: now,
+      };
+      insertPricingRow(input);
+      inserted += 1;
+    }
+  });
+
+  tx(rows);
+  return { inserted, unchanged };
+}
+
+function prunePricingHistory(keepLatest = 2): number {
+  const result = getDb()
+    .prepare(
+      `DELETE FROM pricing
+       WHERE rowid IN (
+         SELECT rowid
+         FROM (
+           SELECT
+             rowid,
+             ROW_NUMBER() OVER (
+               PARTITION BY provider, model, token_class
+               ORDER BY effective_from DESC
+             ) AS rn
+           FROM pricing
+         )
+         WHERE rn > ?
+       )`,
+    )
+    .run(keepLatest);
+  return result.changes;
+}
+
+function auditPricingRefresh(result: PricingRefreshResult): void {
+  try {
+    createLogEntry({
+      eventType: "pricing.refresh",
+      newValue: `${result.status}: inserted=${result.inserted}; unchanged=${result.unchanged}; pruned=${result.pruned}`,
+      metadata: {
+        status: result.status,
+        candidateRows: result.candidateRows,
+        inserted: result.inserted,
+        unchanged: result.unchanged,
+        pruned: result.pruned,
+        etag: result.etag,
+      },
+    });
+  } catch (err) {
+    logPricingRefreshError("audit log write failed", err);
+  }
+}
+
+function auditPricingRefreshFailure(err: unknown): void {
+  try {
+    createLogEntry({
+      eventType: "pricing.refresh.failed",
+      newValue: scrubSecrets(err instanceof Error ? err.message : String(err)),
+    });
+  } catch (auditErr) {
+    logPricingRefreshError("failure audit log write failed", auditErr);
+  }
+}
+
+export async function refreshPricingFromModelsDev(
+  opts: RefreshPricingOptions = {},
+): Promise<PricingRefreshResult> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const now = opts.now ?? Date.now();
+  const headers: Record<string, string> = lastETag ? { "If-None-Match": lastETag } : {};
+
+  const response = await fetchImpl(MODELSDEV_API_URL, { headers });
+  if (response.status === 304) {
+    const result: PricingRefreshResult = {
+      status: "not_modified",
+      candidateRows: 0,
+      inserted: 0,
+      unchanged: 0,
+      pruned: 0,
+      etag: lastETag ?? undefined,
+    };
+    auditPricingRefresh(result);
+    logPricingRefresh("models.dev returned 304; pricing rows unchanged");
+    return result;
+  }
+  if (!response.ok) {
+    throw new Error(`models.dev returned HTTP ${response.status}`);
+  }
+
+  const cache = (await response.json()) as ModelsDevCache;
+  const etag = response.headers.get("etag");
+  const rows = buildModelsDevSeedRows(cache);
+  const { inserted, unchanged } = insertChangedPricingRows(rows, now);
+  const pruned = prunePricingHistory(2);
+  lastETag = etag;
+
+  const result: PricingRefreshResult = {
+    status: "refreshed",
+    candidateRows: rows.length,
+    inserted,
+    unchanged,
+    pruned,
+    etag: lastETag ?? undefined,
+  };
+  auditPricingRefresh(result);
+  logPricingRefresh(
+    `refreshed ${rows.length} candidate row(s); inserted=${inserted}; unchanged=${unchanged}; pruned=${pruned}`,
+  );
+  return result;
+}
+
+async function runPricingRefreshSafely(): Promise<void> {
+  try {
+    await refreshPricingFromModelsDev();
+  } catch (err) {
+    logPricingRefreshError("refresh failed", err);
+    auditPricingRefreshFailure(err);
+  }
+}
+
+export function startPricingRefreshLoop(): void {
+  if (refreshLoopStarted) return;
+  refreshLoopStarted = true;
+
+  void runPricingRefreshSafely();
+  const interval = setInterval(() => {
+    void runPricingRefreshSafely();
+  }, PRICING_REFRESH_INTERVAL_MS);
+  interval.unref?.();
+}

package/src/be/seed-pricing.ts

@@ -2,7 +2,9 @@
  * Phase 2 of the cost-tracking plan — seed the `pricing` table at server boot.
  *
  * The vendored models.dev snapshot at `src/be/modelsdev-cache.json` is the
- * single source of truth for per-token rates. We project it into rows keyed by
+ * cold-start fallback for per-token rates. Runtime freshness is owned by
+ * `src/be/pricing-refresh.ts`, which fetches models.dev after boot and inserts
+ * newer effective rows when prices change. We project both sources into rows keyed by
  * `(provider, model, token_class)` so the recompute path in
  * `src/http/session-data.ts` can rebuild USD from tokens regardless of which
  * adapter wrote the row.
@@ -74,7 +76,7 @@ const ANTHROPIC_SHORTNAME_TO_MODELSDEV: Record<string, string> = {
   haiku: "claude-haiku-4-5",
 };
 
-interface PricingSeedRow {
+export interface PricingSeedRow {
   provider: PricingProvider;
   model: string;
   tokenClass: PricingTokenClass;
@@ -127,7 +129,7 @@ function projectCostBlock(
  * "what the adapter writes for `model`" and "what models.dev keys by" is
  * explicit and auditable.
  */
-function buildModelsDevSeedRows(cache: ModelsDevCache): PricingSeedRow[] {
+export function buildModelsDevSeedRows(cache: ModelsDevCache): PricingSeedRow[] {
   const rows: PricingSeedRow[] = [];
 
   // ---- Anthropic / claude family ----------------------------------------

package/src/commands/profile-sync.ts

@@ -34,6 +34,42 @@ export const IDENTITY_MD_PATH = "/workspace/IDENTITY.md";
 export const TOOLS_MD_PATH = "/workspace/TOOLS.md";
 export const HEARTBEAT_MD_PATH = "/workspace/HEARTBEAT.md";
 export const SETUP_SCRIPT_PATH = "/workspace/start-up.sh";
+
+// ──────────────────────────────────────────────────────────────────────────
+// Identity-file baseline hashes — prevents session-end sync from clobbering
+// DB-side edits made by Lead (via update-profile) during a running session.
+//
+// Flow:
+//   1. Runner writes DB content → /workspace/*.md at session start.
+//   2. Runner records SHA-256 hashes of the written content (the "baselines").
+//   3. At session end, sync compares current file hash against its baseline.
+//      - Hash matches → file untouched by the agent → skip sync (preserves
+//        any DB-side edits Lead made during the session).
+//      - Hash differs → agent modified the file → sync it back to DB.
+// ──────────────────────────────────────────────────────────────────────────
+export const IDENTITY_BASELINES_PATH = "/tmp/identity-baselines.json";
+
+export type IdentityBaselines = Record<string, string>;
+
+export function contentSha256(content: string): string {
+  return new Bun.CryptoHasher("sha256").update(content).digest("hex");
+}
+
+export async function writeIdentityBaselines(baselines: IdentityBaselines): Promise<void> {
+  await Bun.write(IDENTITY_BASELINES_PATH, JSON.stringify(baselines));
+}
+
+export async function readIdentityBaselines(
+  readFile: FileReader = readFileIfExists,
+): Promise<IdentityBaselines | null> {
+  try {
+    const raw = await readFile(IDENTITY_BASELINES_PATH);
+    if (!raw) return null;
+    return JSON.parse(raw) as IdentityBaselines;
+  } catch {
+    return null;
+  }
+}
 /**
  * Claude Code's personal-file CLAUDE.md path. This is what the Claude plugin
  * Stop hook reads and owns — the runner only uses it as a backstop for an
@@ -135,18 +171,27 @@ export function extractSetupScriptContent(raw: string): string | null {
  * the trim / max-length guards and the SOUL/IDENTITY min-length guard. Returns
  * an empty object when nothing is syncable (callers should skip the POST).
  * `undefined` inputs mean the file was absent.
+ *
+ * When `baselines` is provided, skips any field whose content hash matches the
+ * baseline (i.e. the file was not modified during the session). This prevents
+ * session-end sync from clobbering DB-side edits made by Lead.
  */
-export function buildIdentityPayload(files: {
-  soulMd?: string;
-  identityMd?: string;
-  toolsMd?: string;
-  heartbeatMd?: string;
-}): Record<string, string> {
+export function buildIdentityPayload(
+  files: {
+    soulMd?: string;
+    identityMd?: string;
+    toolsMd?: string;
+    heartbeatMd?: string;
+  },
+  baselines?: IdentityBaselines | null,
+): Record<string, string> {
   const updates: Record<string, string> = {};
 
   if (files.soulMd !== undefined) {
     const content = files.soulMd;
-    if (content.trim() && content.length <= MAX_FILE_LENGTH) {
+    if (baselines?.soulMd && contentSha256(content) === baselines.soulMd) {
+      // File unchanged during session — skip to preserve Lead's DB edits
+    } else if (content.trim() && content.length <= MAX_FILE_LENGTH) {
       if (content.length < IDENTITY_FILE_MIN_LENGTH) {
         console.error(
           `[profile-sync] Skipping SOUL.md sync: content too short (${content.length} chars, minimum ${IDENTITY_FILE_MIN_LENGTH}). This prevents accidental profile corruption.`,
@@ -159,7 +204,9 @@ export function buildIdentityPayload(files: {
 
   if (files.identityMd !== undefined) {
     const content = files.identityMd;
-    if (content.trim() && content.length <= MAX_FILE_LENGTH) {
+    if (baselines?.identityMd && contentSha256(content) === baselines.identityMd) {
+      // File unchanged during session — skip to preserve Lead's DB edits
+    } else if (content.trim() && content.length <= MAX_FILE_LENGTH) {
       if (content.length < IDENTITY_FILE_MIN_LENGTH) {
         console.error(
           `[profile-sync] Skipping IDENTITY.md sync: content too short (${content.length} chars, minimum ${IDENTITY_FILE_MIN_LENGTH}). This prevents accidental profile corruption.`,
@@ -172,14 +219,18 @@ export function buildIdentityPayload(files: {
 
   if (files.toolsMd !== undefined) {
     const content = files.toolsMd;
-    if (content.trim() && content.length <= MAX_FILE_LENGTH) {
+    if (baselines?.toolsMd && contentSha256(content) === baselines.toolsMd) {
+      // File unchanged during session — skip
+    } else if (content.trim() && content.length <= MAX_FILE_LENGTH) {
       updates.toolsMd = content;
     }
   }
 
   if (files.heartbeatMd !== undefined) {
     const content = files.heartbeatMd;
-    if (content.length <= MAX_FILE_LENGTH) {
+    if (baselines?.heartbeatMd && contentSha256(content) === baselines.heartbeatMd) {
+      // File unchanged during session — skip
+    } else if (content.length <= MAX_FILE_LENGTH) {
       updates.heartbeatMd = content;
     }
   }
@@ -205,6 +256,12 @@ async function readFileIfExists(path: string): Promise<string | undefined> {
  * Collect the profile-update POST bodies to send. Each entry is one POST.
  * `fields` selects which groups to include. The file reader is injectable so
  * the field-selection / guard logic can be unit-tested without touching the FS.
+ *
+ * When `changeSource` is `"session_sync"`, loads baseline hashes written at
+ * session start and skips identity fields whose content hasn't changed — this
+ * prevents blind-overwriting DB-side edits made by Lead during the session.
+ * On-edit syncs (`"self_edit"`) bypass baselines entirely since the agent
+ * explicitly changed the file and the new content should propagate.
  */
 export async function collectProfilePayloads(
   fields: ProfileSyncField[],
@@ -214,13 +271,18 @@ export async function collectProfilePayloads(
 ): Promise<ProfilePayload[]> {
   const payloads: ProfilePayload[] = [];
 
+  const baselines = changeSource === "session_sync" ? await readIdentityBaselines(readFile) : null;
+
   if (fields.includes("identity")) {
-    const updates = buildIdentityPayload({
-      soulMd: await readFile(SOUL_MD_PATH),
-      identityMd: await readFile(IDENTITY_MD_PATH),
-      toolsMd: await readFile(TOOLS_MD_PATH),
-      heartbeatMd: await readFile(HEARTBEAT_MD_PATH),
-    });
+    const updates = buildIdentityPayload(
+      {
+        soulMd: await readFile(SOUL_MD_PATH),
+        identityMd: await readFile(IDENTITY_MD_PATH),
+        toolsMd: await readFile(TOOLS_MD_PATH),
+        heartbeatMd: await readFile(HEARTBEAT_MD_PATH),
+      },
+      baselines,
+    );
     if (Object.keys(updates).length > 0) {
       payloads.push({ label: "identity", body: { ...updates, changeSource } });
     }
@@ -229,7 +291,11 @@ export async function collectProfilePayloads(
   if (fields.includes("claude")) {
     const raw = await readFile(claudeMdPath);
     if (raw?.trim() && raw.length <= MAX_FILE_LENGTH) {
-      payloads.push({ label: "claude", body: { claudeMd: raw, changeSource } });
+      if (baselines?.claudeMd && contentSha256(raw) === baselines.claudeMd) {
+        // CLAUDE.md unchanged during session — skip to preserve Lead's DB edits
+      } else {
+        payloads.push({ label: "claude", body: { claudeMd: raw, changeSource } });
+      }
     }
   }
 

package/src/commands/runner.ts

@@ -57,7 +57,12 @@ import { validateJsonSchema } from "../workflows/json-schema-validator.ts";
 import { interpolate } from "../workflows/template.ts";
 import { buildContextPreamble, buildResumeContextPreamble } from "./context-preamble.ts";
 import { awaitCredentials, BootMaxWaitExceededError, EX_CONFIG } from "./credential-wait.ts";
-import { resolveClaudeMdPath, syncProfileFilesToServer } from "./profile-sync.ts";
+import {
+  contentSha256,
+  resolveClaudeMdPath,
+  syncProfileFilesToServer,
+  writeIdentityBaselines,
+} from "./profile-sync.ts";
 import {
   buildCredStatusReport,
   buildLatestModelReport,
@@ -4307,6 +4312,23 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
     }
   }
 
+  // Record baseline hashes of identity files as written from DB. Session-end
+  // sync compares current file content against these baselines: unchanged files
+  // are skipped, which prevents clobbering DB-side edits made by Lead via
+  // update-profile during the running session.
+  try {
+    const baselines: Record<string, string> = {};
+    if (agentSoulMd) baselines.soulMd = contentSha256(agentSoulMd);
+    if (agentIdentityMd) baselines.identityMd = contentSha256(agentIdentityMd);
+    if (agentToolsMd) baselines.toolsMd = contentSha256(agentToolsMd);
+    if (agentHeartbeatMd) baselines.heartbeatMd = contentSha256(agentHeartbeatMd);
+    if (agentClaudeMd) baselines.claudeMd = contentSha256(agentClaudeMd);
+    await writeIdentityBaselines(baselines);
+    console.log(`[${role}] Recorded identity file baselines for session-end sync`);
+  } catch {
+    // Non-fatal — worst case, session-end sync proceeds as before (blind overwrite)
+  }
+
   // ========== Boot-time skill load (signature-gated, replaces the standalone
   // skill-fetch + FS sync blocks). The polling loop below calls the same
   // helper per task to hot-reload skills mid-flight. Skipped for

package/src/hooks/hook.ts

@@ -9,6 +9,7 @@ import {
   postRatings,
   type RetrievalRow,
 } from "../be/memory/raters/llm";
+import { contentSha256, readIdentityBaselines } from "../commands/profile-sync";
 import type { Agent } from "../types";
 import { getApiKey } from "../utils/api-key";
 import { getMcpBaseUrl } from "../utils/constants";
@@ -581,7 +582,12 @@ export async function handleHook(): Promise<void> {
   const IDENTITY_FILE_MIN_LENGTH = 500;
 
   /**
-   * Sync SOUL.md and IDENTITY.md content back to the server
+   * Sync SOUL.md and IDENTITY.md content back to the server.
+   *
+   * When `changeSource` is `"session_sync"` (the Stop-hook default), loads
+   * baseline hashes written at session start and skips any file whose content
+   * hasn't changed. This prevents the session-end sync from clobbering DB-side
+   * edits that Lead made via `update-profile` during the running session.
    */
   const syncIdentityFilesToServer = async (
     agentId: string,
@@ -589,12 +595,16 @@ export async function handleHook(): Promise<void> {
   ): Promise<void> => {
     if (!mcpConfig) return;
 
+    const baselines = changeSource === "session_sync" ? await readIdentityBaselines() : null;
+
     const updates: Record<string, string> = {};
 
     const soulFile = Bun.file(SOUL_MD_PATH);
     if (await soulFile.exists()) {
       const content = await soulFile.text();
-      if (content.trim() && content.length <= 65536) {
+      if (baselines?.soulMd && contentSha256(content) === baselines.soulMd) {
+        // Unchanged during session — skip to preserve Lead's DB edits
+      } else if (content.trim() && content.length <= 65536) {
         if (content.length < IDENTITY_FILE_MIN_LENGTH) {
           console.error(
             `[hook] Skipping SOUL.md sync: content too short (${content.length} chars, minimum ${IDENTITY_FILE_MIN_LENGTH}). This prevents accidental profile corruption.`,
@@ -608,7 +618,9 @@ export async function handleHook(): Promise<void> {
     const identityFile = Bun.file(IDENTITY_MD_PATH);
     if (await identityFile.exists()) {
       const content = await identityFile.text();
-      if (content.trim() && content.length <= 65536) {
+      if (baselines?.identityMd && contentSha256(content) === baselines.identityMd) {
+        // Unchanged during session — skip
+      } else if (content.trim() && content.length <= 65536) {
         if (content.length < IDENTITY_FILE_MIN_LENGTH) {
           console.error(
             `[hook] Skipping IDENTITY.md sync: content too short (${content.length} chars, minimum ${IDENTITY_FILE_MIN_LENGTH}). This prevents accidental profile corruption.`,
@@ -622,7 +634,9 @@ export async function handleHook(): Promise<void> {
     const toolsMdFile = Bun.file(TOOLS_MD_PATH);
     if (await toolsMdFile.exists()) {
       const content = await toolsMdFile.text();
-      if (content.trim() && content.length <= 65536) {
+      if (baselines?.toolsMd && contentSha256(content) === baselines.toolsMd) {
+        // Unchanged during session — skip
+      } else if (content.trim() && content.length <= 65536) {
         updates.toolsMd = content;
       }
     }
@@ -630,7 +644,9 @@ export async function handleHook(): Promise<void> {
     const heartbeatFile = Bun.file(HEARTBEAT_MD_PATH);
     if (await heartbeatFile.exists()) {
       const content = await heartbeatFile.text();
-      if (content.length <= 65536) {
+      if (baselines?.heartbeatMd && contentSha256(content) === baselines.heartbeatMd) {
+        // Unchanged during session — skip
+      } else if (content.length <= 65536) {
         updates.heartbeatMd = content;
       }
     }

package/src/http/index.ts

@@ -451,6 +451,8 @@ try {
 try {
   const { seedPricingFromModelsDev } = await import("../be/seed-pricing");
   seedPricingFromModelsDev();
+  const { startPricingRefreshLoop } = await import("../be/pricing-refresh");
+  startPricingRefreshLoop();
 } catch (err) {
   console.error("[startup] Failed to seed pricing rows:", err);
 }

package/src/providers/pricing-sources.md

@@ -1,16 +1,32 @@
 # Pricing sources
 
-This page lists the sources that feed the `pricing` table at server boot.
-Operators bumping a rate by hand should also update this file.
+This page lists the sources that feed the `pricing` table. Operators bumping a
+rate by hand should also update this file.
 
-## Primary: vendored models.dev snapshot
+## Primary pricing freshness: runtime models.dev refresh
 
-- **Source-of-truth path**: `src/be/modelsdev-cache.json`
+- **Runtime module**: `src/be/pricing-refresh.ts`
+- **Upstream**: `https://models.dev/api.json`, fetched with `If-None-Match`.
+- **Boot wiring**: after `seedPricingFromModelsDev()`, the API server starts one
+  non-blocking refresh and then repeats every 12 hours with `setInterval`.
+- **Update rule**: project upstream through `buildModelsDevSeedRows()` and insert
+  a new `effective_from=Date.now()` row only when the model/token class is new
+  or the active price changed. Identical prices are no-ops.
+- **Growth bound**: after each refresh, keep only the latest two rows per
+  `(provider, model, token_class)` triple.
+- **Pinned local entries**: safe by construction. The runtime refresh only adds
+  pricing rows; it does not rewrite or delete the committed snapshot.
+
+## Fallback/UI catalog: vendored models.dev snapshot
+
+- **Fallback path**: `src/be/modelsdev-cache.json`
 - **UI compatibility path**: `ui/src/lib/modelsdev-cache.json` symlinks to the
   backend snapshot so existing UI imports keep working.
 - **Loaded by**: `src/be/modelsdev-cache.ts` → `src/be/seed-pricing.ts` →
   `seedPricingFromModelsDev()`,
   called from `src/server.ts` after `initDb`.
+- **Role**: cold-start fallback seed for pricing when models.dev is unavailable,
+  plus the UI model-picker source for names, labels, and context windows.
 - **Projection rules** (see the same module for code-level detail):
   - Anthropic models → rows under `provider='claude'` AND `provider='claude-managed'`.
     Shortnames (`opus`, `sonnet`, `haiku`) ALSO get rows keyed by the current
@@ -22,12 +38,13 @@ Operators bumping a rate by hand should also update this file.
     stripped name and the full `google/...` id) so internal-ai callers find
     a hit either way.
 
-- **Refresh procedure** (the only place to update the snapshot):
+- **Snapshot refresh procedure**:
   - Run `bun run scripts/refresh-modelsdev-pricing.ts` (Phase 2 — adds the
     script). It fetches the latest snapshot from models.dev, diffs against
     the vendored copy, prints a summary, and writes the new file.
   - Commit the regenerated `src/be/modelsdev-cache.json` together with a bump
-    note in the PR description.
+    note in the PR description. This is no longer the pricing freshness path;
+    use it when the fallback/UI catalog needs new labels or context-window data.
 
 ## Manual overrides
 
@@ -50,6 +67,7 @@ no input/output pricing rows at the lookup time, the row is persisted with
 `costSource='unpriced'` (rather than 'harness'). The UI surfaces this as a
 yellow badge.
 
-To fix: either add the model to `src/be/modelsdev-cache.json` (preferred — the
-upstream snapshot probably needs refreshing) or add a manual override row via
-the existing admin route `POST /api/pricing`.
+To fix: first check whether the runtime refresh is failing. If the model must
+also appear in the UI picker or cold-start fallback, add it to
+`src/be/modelsdev-cache.json`; otherwise add a manual override row via the
+existing admin route `POST /api/pricing`.

package/src/server.ts

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import pkg from "../package.json";
 import { initDb } from "./be/db";
+import { startPricingRefreshLoop } from "./be/pricing-refresh";
 import { seedPricingFromModelsDev } from "./be/seed-pricing";
 import { registerCancelTaskTool } from "./tools/cancel-task";
 import { registerContextDiffTool } from "./tools/context-diff";
@@ -172,6 +173,7 @@ export function createServer() {
   // call on every boot. See src/be/seed-pricing.ts for the projection logic
   // and the manual-override constants for runtime-fee / ACU pricing.
   seedPricingFromModelsDev();
+  startPricingRefreshLoop();
 
   const server = new McpServer(
     {