pi-coralbricks-provider 1.0.30 → 1.0.32

package/README.md

@@ -27,7 +27,9 @@ Run `bun run test:pi` for offline manifest, catalog, lifecycle and streaming che
 - **OpenAI-compatible API** — standard `/v1/chat/completions`, streaming, and tool calling
 - **Per-family thinking levels** — zai-style `thinking` control for GLM (including a *real* off switch), `reasoning_effort` for DeepSeek V4.1 Flash
 - **Accurate cost tracking** — input, cache-write and output rates mirror Coral's [published pricing](https://www.coralbricks.ai/pricing), and cached reads are **$0 on every model**
-- **Self-healing model sync** — stale-while-revalidate from the authenticated `/v1/models` (or the unauthenticated [public catalog](https://www.coralbricks.ai/api/public/models) before auth), hot-swapped at session start
+- **Self-healing model sync** — stale-while-revalidate from the authenticated `/v1/models`, hot-swapped at session start and after `/login`. Without a key it makes no network request and serves the cached or embedded catalog
+- **Quiet startup sync** — startup never waits on the network, and the catalog is refreshed at most hourly, by one pi process at a time, so `/new`, `pi -p` and fan-out child agents share one cache (see [Model Sync](#model-sync))
+- **Safe to install twice** — when a standalone install and a copy bundled in another Pi package (such as [pi-fabric](https://github.com/fabric-runtime/pi-fabric)) load together, only the newest copy registers the provider (see [Installed more than once](#installed-more-than-once))
 - **synbad-validated** — [synbad](https://github.com/synthetic-lab/synbad) tool-calling and reasoning-parsing evals pass 13/13 in every run on GLM 5.3 in both unary and streaming modes
 
 ## Installation
@@ -49,7 +51,7 @@ pi install npm:pi-coralbricks-provider
 Then set your API key and run pi:
 
 ```bash
-# Recommended: add to auth.json
+# Recommended: run /login coralbricks inside pi (saves it to auth.json)
 # See Authentication section below
 
 # Or set as environment variable
@@ -69,7 +71,7 @@ pi
 
 2. Set your Coral API key:
    ```bash
-   # Recommended: add to auth.json
+   # Recommended: run /login coralbricks inside pi (saves it to auth.json)
    # See Authentication section below
 
    # Or set as environment variable
@@ -81,6 +83,12 @@ pi
    pi -e /path/to/pi-coralbricks-provider
    ```
 
+### Installed more than once
+
+Another Pi package can bundle this extension; [pi-fabric](https://github.com/fabric-runtime/pi-fabric) does. You can still install it yourself, for example to get a newer version first. When two or more copies load into one Pi session, the newest version registers `coralbricks`, syncs models and serves `/coralbricks-settings`. The other copies register nothing and make no requests, so `/model` lists each model once and `/v1/models` is fetched once. Copies of the same version keep the one that loaded first.
+
+The copies find each other through a process-global registry (`Symbol.for("pi-coralbricks-provider.registry.v1")`), scoped to the Pi extension runtime through the event bus Pi shares among that runtime's extensions. The newest copy wins whichever order Pi loads them in. If it loads second, it takes over before the session starts, and Pi serves its registration because a provider registered later under the same id replaces the earlier one. Ownership never moves back, and it ends with the session, so `/reload`, `/new`, `/resume` and `/fork` start from a clean slate. Versions before 1.0.32 do not take part and always register.
+
 ## Available Models
 
 | Model | Context | Vision | Reasoning | Input $/M | Cache Read $/M | Cache Write $/M | Output $/M |
@@ -172,12 +180,12 @@ saving. If editing the file manually, run `/reload` to apply it.
 
 The Coral API key can be configured in multiple ways (resolved in this order):
 
-1. **`auth.json`** (recommended) — Add to `~/.pi/agent/auth.json`:
+1. **Runtime override** — Use the `--api-key` CLI flag
+2. **`auth.json`** (recommended) — Run `/login coralbricks` inside pi and paste your key; pi saves it to `~/.pi/agent/auth.json` and refreshes the model list from the authenticated `/v1/models`. Or add it by hand:
    ```json
    { "coralbricks": { "type": "api_key", "key": "cb_your-key" } }
    ```
-   The `key` field supports literal values, env var names, and shell commands (prefix with `!`).
-2. **Runtime override** — Use the `--api-key` CLI flag
+   The `key` field supports literal values, env var names, and shell commands (prefix with `!`). `/logout` (pick CoralBricks) removes the stored key; `CORALBRICKS_API_KEY` is left alone.
 3. **Environment variable** — Set `CORALBRICKS_API_KEY`
 
 With [localterm](https://www.npmjs.com/package/localterm), store it once and it's exposed everywhere:
@@ -186,6 +194,13 @@ With [localterm](https://www.npmjs.com/package/localterm), store it once and it'
 localterm secret set coralbricks_api_key
 ```
 
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CORALBRICKS_API_KEY` | No | Your Coral API key (fallback if not in `auth.json` or `--api-key`) |
+| `PI_PROVIDER_SYNC_TTL_MS` | No | Model sync freshness window in ms (default `3600000`; `0` = revalidate every session start) |
+
 > Coral Inference is currently in a design-partner program — mint keys at [coralbricks.ai/api-keys](https://www.coralbricks.ai/api-keys). Newly-minted keys may take ~30 seconds to be honored, and `403 access_denied` means the account isn't on the allowlist yet.
 
 ## Thinking Levels
@@ -242,6 +257,18 @@ CORALBRICKS_API_KEY=cb_... node ../synbad/dist/source/index.js eval \
   --model glm-5.3-fp4 --count 1 --reasoning-effort high
 ```
 
+## Model Sync
+
+At startup the extension serves the last catalog it cached (`~/.pi/agent/cache/coralbricks-models.json`), or the catalog embedded in the package. Once Pi resolves a key (`/login coralbricks`, `auth.json`, `--api-key` or `CORALBRICKS_API_KEY`), it refreshes from the authenticated `/v1/models` at session start and after `/login`, caches the result and swaps it in. With no key it makes no network request at all.
+
+Startup never waits on the network: the session-start refresh runs in the background, and only when:
+
+- a Coral API key is configured (no key, no request),
+- the cache is older than 1 hour, missing or unreadable, was fetched with a different API key, or was written by a version before this sync policy, and
+- no other pi process is already refreshing it (a `coralbricks-models.lock` file next to the cache).
+
+So `/new`, `/reload`, `pi -p` and fan-out child agents share one cache instead of each calling the API; a session that skips the fetch still picks up a cache another process refreshed, and every cache write is atomic. `/login coralbricks` and a changed key always refresh, whatever the cache's age. A failed refresh is retried after 5 minutes at the earliest. `PI_PROVIDER_SYNC_TTL_MS` changes the window (`0` revalidates on every session start). Only a hash fingerprint of the key is stored (`coralbricks-models.sync.json`), never the key itself. When several copies of the extension load (see [Installed more than once](#installed-more-than-once)), only the owning copy touches the lock or the network.
+
 ## Updating Models
 
 Run the update script to fetch the latest models from Coral's API:

package/auth.ts

@@ -0,0 +1,30 @@
+import { envApiKeyAuth, type ApiKeyAuth } from "@earendil-works/pi-ai";
+
+export const CORALBRICKS_ENV_VAR = "CORALBRICKS_API_KEY";
+export const CORALBRICKS_KEYS_URL = "https://www.coralbricks.ai/api-keys";
+
+/**
+ * API-key auth for `/login coralbricks`, the pattern Pi's built-in OpenRouter and
+ * Vercel AI Gateway providers use (pi-ai `envApiKeyAuth`): a stored auth.json
+ * `coralbricks` api_key wins, then CORALBRICKS_API_KEY. Login stores
+ * `{ "type": "api_key", "key": ... }` under `coralbricks`, the entry this
+ * extension has always read, and `/logout` removes it.
+ */
+export function coralApiKeyAuth(): ApiKeyAuth {
+  const base = envApiKeyAuth("CoralBricks API key", [CORALBRICKS_ENV_VAR]);
+  return {
+    ...base,
+    login: async (interaction) => {
+      interaction.signal.throwIfAborted();
+      interaction.notify({
+        type: "info",
+        message: "Create a Coral Inference API key at https://www.coralbricks.ai (API keys page). New keys can take ~30 seconds to be honored.",
+        links: [{ url: CORALBRICKS_KEYS_URL, label: "coralbricks.ai/api-keys" }],
+      });
+      const key = (await interaction.prompt({ type: "secret", message: "Enter CoralBricks API key", placeholder: "cb_..." })).trim();
+      interaction.signal.throwIfAborted();
+      if (!key) throw new Error("No CoralBricks API key entered");
+      return { type: "api_key", key };
+    },
+  };
+}

package/guard.ts

@@ -0,0 +1,155 @@
+/**
+ * One provider per Pi runtime, however many copies of this package load.
+ *
+ * A standalone install (`pi install npm:pi-coralbricks-provider`) and a copy
+ * bundled inside another Pi package (pi-fabric) load from separate module
+ * roots, so module state is not shared between them. Without coordination both
+ * would register `coralbricks`, both would sync models at session start, and
+ * both would add `/coralbricks-settings`.
+ *
+ * Copies coordinate through a process-global registry under
+ * `Symbol.for("pi-coralbricks-provider.registry.v1")`. It is scoped per Pi
+ * extension runtime: copies discover a shared scope token over the extension
+ * event bus Pi gives every extension of one runtime (`pi.events`). Pi drops a
+ * runtime's bus subscriptions when it invalidates that runtime (`/reload`,
+ * `/new`, `/resume`, `/fork`), so the next generation starts from an empty
+ * scope and never inherits a stale owner. Separate runtimes in one process
+ * (another SDK session, an isolated loader) get separate scopes.
+ *
+ * Within a scope the highest version owns the provider; equal versions keep the
+ * copy that loaded first. Ownership is decided while extensions load, before
+ * Pi binds a session:
+ *
+ * - The first copy owns the scope and registers the provider.
+ * - A later copy that is not newer yields: it registers nothing and never
+ *   syncs models.
+ * - A later, newer copy takes over: the incumbent resigns (its hooks go inert)
+ *   and the newer copy registers the provider. Pi applies registrations in
+ *   load order and a native provider with an existing id replaces the previous
+ *   one, so the newer registration is the one Pi serves.
+ *
+ * Ownership only ever moves to a strictly newer version, and only at load
+ * time, so it cannot flap, and only the owner fetches `/v1/models`. The first
+ * copy registers `/coralbricks-settings` once and serves it through whichever
+ * copy owns the scope. Ownership ends with the session (`session_shutdown`).
+ * Copies older than this protocol do not take part and keep registering.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const REGISTRY_KEY = Symbol.for("pi-coralbricks-provider.registry.v1");
+const SCOPE_CHANNEL = "pi-coralbricks-provider:scope.v1";
+
+/** What one loaded copy offers the registry. Stable across versions (protocol v1). */
+export interface CoralCopy {
+  readonly version: string;
+  /** A newer copy took over this runtime: stop syncing and serving. */
+  resign(): void;
+  /** `/coralbricks-settings`, as this copy implements it. */
+  settings(args: string, ctx: unknown): Promise<void>;
+}
+
+interface Scope {
+  owner?: CoralCopy;
+}
+
+type Registry = WeakMap<object, Scope>;
+
+export interface RuntimeClaim {
+  /** True while this copy owns the provider in its runtime. */
+  owns(): boolean;
+  /** True for the first copy in the runtime, which registers the shared command. */
+  readonly first: boolean;
+  /** The copy that owns the runtime now, if any. */
+  owner(): CoralCopy | undefined;
+  /** End this copy's ownership (session shutdown). */
+  release(): void;
+}
+
+function registry(): Registry {
+  const global = globalThis as typeof globalThis & { [REGISTRY_KEY]?: Registry };
+  global[REGISTRY_KEY] ??= new WeakMap();
+  return global[REGISTRY_KEY];
+}
+
+function parseVersion(version: string): { core: number[]; pre: string | undefined } | undefined {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(version.trim());
+  if (!match) return undefined;
+  return { core: [Number(match[1]), Number(match[2]), Number(match[3])], pre: match[4] };
+}
+
+function comparePrerelease(a: string, b: string): number {
+  const left = a.split(".");
+  const right = b.split(".");
+  for (let i = 0; i < Math.max(left.length, right.length); i++) {
+    if (left[i] === undefined) return -1;
+    if (right[i] === undefined) return 1;
+    const numericLeft = /^\d+$/.test(left[i]);
+    const numericRight = /^\d+$/.test(right[i]);
+    if (numericLeft && numericRight) {
+      const diff = Number(left[i]) - Number(right[i]);
+      if (diff !== 0) return Math.sign(diff);
+    } else if (numericLeft !== numericRight) {
+      return numericLeft ? -1 : 1;
+    } else if (left[i] !== right[i]) {
+      return left[i] < right[i] ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+/** Semver precedence; a malformed version sorts below every valid one. */
+export function compareVersions(a: string, b: string): number {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  if (!left || !right) return left ? 1 : right ? -1 : 0;
+  for (let i = 0; i < 3; i++) {
+    const diff = left.core[i] - right.core[i];
+    if (diff !== 0) return Math.sign(diff);
+  }
+  if (left.pre === undefined || right.pre === undefined) {
+    return left.pre === right.pre ? 0 : left.pre === undefined ? 1 : -1;
+  }
+  return comparePrerelease(left.pre, right.pre);
+}
+
+/** The scope token every copy in this extension runtime shares. */
+function joinScope(pi: ExtensionAPI): { token: object; first: boolean } {
+  // A host without an extension event bus gives every copy its own scope.
+  if (typeof pi.events?.emit !== "function" || typeof pi.events.on !== "function") return { token: {}, first: true };
+  let token: object | undefined;
+  // Copies already loaded in this runtime answer synchronously on the bus.
+  pi.events.emit(SCOPE_CHANNEL, (found: unknown) => {
+    if (!token && typeof found === "object" && found !== null) token = found;
+  });
+  const first = token === undefined;
+  const scope = token ?? {};
+  pi.events.on(SCOPE_CHANNEL, (reply: unknown) => {
+    if (typeof reply === "function") reply(scope);
+  });
+  return { token: scope, first };
+}
+
+/** Decide, while this copy loads, whether it owns the `coralbricks` provider in its runtime. */
+export function claimRuntime(pi: ExtensionAPI, copy: CoralCopy): RuntimeClaim {
+  const { token, first } = joinScope(pi);
+  const scopes = registry();
+  let scope = scopes.get(token);
+  if (!scope) {
+    scope = {};
+    scopes.set(token, scope);
+  }
+  const incumbent = scope.owner;
+  if (!incumbent || compareVersions(copy.version, incumbent.version) > 0) {
+    scope.owner = copy;
+    incumbent?.resign();
+  }
+  const current = scope;
+  return {
+    first,
+    owns: () => current.owner === copy,
+    owner: () => current.owner,
+    release: () => {
+      if (current.owner === copy) current.owner = undefined;
+    },
+  };
+}

package/index.ts

@@ -7,17 +7,25 @@
  *
  * Model resolution strategy: Stale-While-Revalidate
  *   1. Serve stale immediately: disk cache → embedded models.json (zero-latency)
- *   2. Revalidate in background: authenticated /v1/models (authoritative enabled
- *      set + per-million USD pricing) with the unauthenticated public catalog
- *      (https://www.coralbricks.ai/api/public/models) as fallback
- *      → merge with embedded → cache → hot-swap
+ *   2. Revalidate in background once a key resolves: authenticated /v1/models
+ *      (authoritative enabled set + per-million USD pricing)
+ *      → merge with embedded → cache → hot-swap. Without a key nothing is
+ *      fetched; the stale catalog serves until /login or a key appears.
+ *      Quiet startup sync (sync-policy.ts): only when the disk cache is older
+ *      than the TTL (1h, PI_PROVIDER_SYNC_TTL_MS), missing, or fetched with a
+ *      different key, or Pi forces it (after /login), and only one pi process
+ *      at a time (lock file next to the cache).
  *   3. patch.json + custom-models.json applied on top of whichever source won
  *
+ * When several copies of this package load into one Pi runtime (a standalone
+ * install plus a copy bundled in another package), only the newest registers
+ * the provider and syncs models (guard.ts).
+ *
  * Merge order: [live|cache|embedded] → apply patch.json → merge custom-models.json
  *
  * Usage:
- *   # Option 1: Store in auth.json (recommended)
- *   # Add to ~/.pi/agent/auth.json:
+ *   # Option 1: /login coralbricks inside pi (stores the key in auth.json), or
+ *   # add to ~/.pi/agent/auth.json yourself:
  *   #   "coralbricks": { "type": "api_key", "key": "cb_your-key" }
  *
  *   # Option 2: Set as environment variable
@@ -31,14 +39,19 @@
  */
 
 import { getAgentDir, type ExtensionAPI, type ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { lazyStream, type Api, type Credential, type Model, type RefreshModelsContext } from "@earendil-works/pi-ai";
 import type { AssistantMessageEventStream, SimpleStreamOptions } from "@earendil-works/pi-ai/compat";
 import { clampThinkingLevel, streamOpenAICompletions, streamOpenAIResponses } from "@earendil-works/pi-ai/compat";
-import { loadConfig, registerSettingsCommand } from "./settings";
+import { createSettingsCommand, loadConfig, SETTINGS_COMMAND } from "./settings";
+import { claimRuntime, type CoralCopy } from "./guard";
 import { park, planPark, withParkFallback, type ParkPlan } from "./park";
+import { coralApiKeyAuth, CORALBRICKS_ENV_VAR } from "./auth";
+import { acquireModelSync, cacheChangedSinceLoad, markCacheLoaded, writeFileAtomic } from "./sync-policy";
 import modelsData from "./models.json" with { type: "json" };
 import customModelsData from "./custom-models.json" with { type: "json" };
 import patchData from "./patch.json" with { type: "json" };
 import deprecatedData from "./deprecated-models.json" with { type: "json" };
+import packageData from "./package.json" with { type: "json" };
 import fs from "fs";
 import path from "path";
 
@@ -182,9 +195,10 @@ function buildModels(base: JsonModel[], custom: JsonModel[], patch: PatchData):
 // Stale-While-Revalidate Model Sync
 
 const PROVIDER_ID = "coralbricks";
+const PROVIDER_NAME = "CoralBricks";
 const BASE_URL = "https://inference.coralbricks.ai/v1";
 const MODELS_URL = `${BASE_URL}/models`;
-const PUBLIC_CATALOG_URL = "https://www.coralbricks.ai/api/public/models";
+const PACKAGE_VERSION: string = packageData.version;
 const CACHE_DIR = path.join(getAgentDir(), "cache");
 const CACHE_PATH = path.join(CACHE_DIR, `${PROVIDER_ID}-models.json`);
 const LIVE_FETCH_TIMEOUT_MS = 8000;
@@ -271,35 +285,6 @@ function transformApiModel(apiModel: any): JsonModel | null {
   return model;
 }
 
-/**
- * Transform a row from the public model catalog
- * (https://www.coralbricks.ai/api/public/models) — the no-auth mirror of the
- * gateway control plane. Fields: slug, name, contextWindow ("1M"),
- * inputPerM / outputPerM, and since 2026-10-08 cacheWritePerM (the cache write on
- * top of input). Coral's own prices are authoritative here; the parity/field vendor
- * comparison fields are ignored. A row without cacheWritePerM leaves cacheWrite 0 so
- * mergeWithEmbedded keeps the embedded rate.
- */
-function transformCatalogModel(entry: any): JsonModel | null {
-  if (!entry?.slug) return null;
-  const model: JsonModel = {
-    id: entry.slug,
-    name: typeof entry.name === "string" && entry.name ? entry.name : displayName(entry.slug),
-    reasoning: false,
-    input: ["text"],
-    cost: {
-      input: toNumber(entry.inputPerM),
-      output: toNumber(entry.outputPerM),
-      cacheRead: 0,
-      cacheWrite: writtenTokenCost(toNumber(entry.inputPerM), entry.cacheWritePerM),
-    },
-    contextWindow: parseContextWindow(entry.contextWindow),
-    maxTokens: DEFAULT_MAX_TOKENS[entry.slug] ?? FALLBACK_MAX_TOKENS,
-  };
-  model.compat = baseCompat();
-  return model;
-}
-
 async function fetchV1Models(apiKey: string, signal?: AbortSignal): Promise<JsonModel[] | null> {
   try {
     const response = await fetch(MODELS_URL, {
@@ -316,32 +301,14 @@ async function fetchV1Models(apiKey: string, signal?: AbortSignal): Promise<Json
   }
 }
 
-async function fetchPublicCatalog(signal?: AbortSignal): Promise<JsonModel[] | null> {
-  try {
-    const response = await fetch(PUBLIC_CATALOG_URL, {
-      signal: signal ? AbortSignal.any([AbortSignal.timeout(LIVE_FETCH_TIMEOUT_MS), signal]) : AbortSignal.timeout(LIVE_FETCH_TIMEOUT_MS),
-    });
-    if (!response.ok) return null;
-    const data = await response.json();
-    const entries = Array.isArray(data) ? data : (data.models || []);
-    if (!Array.isArray(entries) || entries.length === 0) return null;
-    return entries.map(transformCatalogModel).filter((m): m is JsonModel => m !== null);
-  } catch {
-    return null;
-  }
-}
-
 /**
- * Live model fetch. The authenticated /v1/models is authoritative (it is the
- * exact per-key enabled set); the public catalog is the unauthenticated
- * fallback so model discovery works before a key is configured.
+ * Live model fetch from the authenticated /v1/models, the exact per-key enabled
+ * set. Without a key there is no request: the disk cache, then the embedded
+ * models.json, serve until a key resolves (/login, auth.json, the environment).
  */
 async function fetchLiveModels(apiKey: string | undefined, signal?: AbortSignal): Promise<JsonModel[] | null> {
-  if (apiKey) {
-    const fromApi = await fetchV1Models(apiKey, signal);
-    if (fromApi && fromApi.length > 0) return fromApi;
-  }
-  return fetchPublicCatalog(signal);
+  if (!apiKey) return null;
+  return fetchV1Models(apiKey, signal);
 }
 
 function loadCachedModels(): JsonModel[] | null {
@@ -356,7 +323,8 @@ function loadCachedModels(): JsonModel[] | null {
 function cacheModels(models: JsonModel[]): void {
   try {
     fs.mkdirSync(CACHE_DIR, { recursive: true });
-    fs.writeFileSync(CACHE_PATH, JSON.stringify(models, null, 2) + "\n");
+    // Atomic (tmp + rename): other pi processes may be reading the cache right now.
+    writeFileAtomic(CACHE_PATH, JSON.stringify(models, null, 2) + "\n");
   } catch {
     // Cache write failure is non-fatal
   }
@@ -373,8 +341,8 @@ function mergeWithEmbedded(liveModels: JsonModel[], embeddedModels: JsonModel[])
       // Self-heal: live API pricing is authoritative field-by-field. Prefer the
       // live cost when the API reports it (non-zero); fall back to embedded when
       // the API is silent (0). Coral reports cached_input_per_m as 0 because
-      // cached reads are free, which matches the curated cacheRead: 0. The
-      // public catalog has no cache-write rate, so its 0 keeps the embedded one.
+      // cached reads are free, which matches the curated cacheRead: 0. A row
+      // without a cache-write rate reports 0, which keeps the embedded one.
       // Curation (reasoning/input/compat/name/thinkingLevelMap/maxTokens) still wins via ...embedded.
       result.push({
         ...liveModel,
@@ -430,6 +398,7 @@ function withDeprecated(models: JsonModel[]): JsonModel[] {
 }
 
 function loadStaleModels(embeddedModels: JsonModel[]): JsonModel[] {
+  markCacheLoaded(CACHE_PATH); // stat before read: lets a skipped sync spot newer caches
   const cached = loadCachedModels();
   if (!cached || cached.length === 0) return embeddedModels;
 
@@ -443,12 +412,26 @@ function loadStaleModels(embeddedModels: JsonModel[]): JsonModel[] {
   return cached;
 }
 
-async function revalidateModels(apiKey: string | undefined, embeddedModels: JsonModel[], signal?: AbortSignal): Promise<JsonModel[] | null> {
-  const liveModels = await fetchLiveModels(apiKey, signal);
-  if (!liveModels || liveModels.length === 0) return null;
-  const merged = mergeWithEmbedded(liveModels, embeddedModels);
-  cacheModels(merged);
-  return merged;
+/**
+ * Background revalidation, gated by the quiet startup sync policy
+ * (sync-policy.ts): no key → no fetch; fresh cache (TTL) → no fetch; another
+ * process already fetching → no fetch. When skipped, a cache that another
+ * process refreshed since we loaded it is adopted from disk instead.
+ * `force` bypasses the TTL (Pi sets it after /login); it is still single-flight.
+ */
+async function revalidateModels(apiKey: string | undefined, embeddedModels: JsonModel[], signal?: AbortSignal, force = false): Promise<JsonModel[] | null> {
+  const lease = acquireModelSync({ cachePath: CACHE_PATH, apiKey, force });
+  if (!lease) return cacheChangedSinceLoad(CACHE_PATH) ? loadStaleModels(embeddedModels) : null;
+  let merged: JsonModel[] | null = null;
+  try {
+    const liveModels = await fetchLiveModels(apiKey, signal);
+    if (!liveModels || liveModels.length === 0) return null;
+    merged = mergeWithEmbedded(liveModels, embeddedModels);
+    cacheModels(merged);
+    return merged;
+  } finally {
+    lease.release(merged ? "fetched" : signal?.aborted ? "aborted" : "failed");
+  }
 }
 
 /** pi-ai's clampOpenAIPromptCacheKey, inlined: Coral accepts the same field. */
@@ -467,8 +450,8 @@ export function streamCoral(
   const apiKey = options?.apiKey || cachedApiKey || "";
   if (!apiKey) {
     throw new Error(
-      `No API key for CoralBricks. Add it to ~/.pi/agent/auth.json ` +
-      `("coralbricks"), set CORALBRICKS_API_KEY, or use --api-key.`,
+      `No API key for CoralBricks. Run /login coralbricks, add it to ` +
+      `~/.pi/agent/auth.json ("coralbricks"), set CORALBRICKS_API_KEY, or use --api-key.`,
     );
   }
 
@@ -536,12 +519,28 @@ export function streamCoral(
 // API Key Resolution (via ModelRegistry)
 
 let cachedApiKey: string | undefined;
-let revalidateAbort: AbortController | null = null;
 
 async function resolveApiKey(modelRegistry: ModelRegistry): Promise<void> {
   cachedApiKey = (await modelRegistry.getApiKeyForProvider(PROVIDER_ID)) ?? undefined;
 }
 
+/**
+ * The chat models Pi composes from a `pi.registerProvider(name, config)` catalog:
+ * each row bound to this provider's id, endpoint and selected API. The native
+ * registration below serves exactly these, so ids, pricing, thinking maps and
+ * compat flags reach Pi unchanged.
+ */
+function toProviderModels(models: JsonModel[], api: Api): Model<Api>[] {
+  return models.map((model) => ({ ...model, api, provider: PROVIDER_ID, baseUrl: BASE_URL, headers: undefined }) as unknown as Model<Api>);
+}
+
+/** The key a refresh should fetch with: Pi's own resolution when a session exposed it. */
+async function refreshApiKey(modelRegistry: ModelRegistry | undefined, credential: Credential | undefined): Promise<string | undefined> {
+  if (modelRegistry) return (await modelRegistry.getApiKeyForProvider(PROVIDER_ID)) ?? undefined;
+  if (credential?.type === "api_key" && credential.key) return credential.key;
+  return process.env[CORALBRICKS_ENV_VAR] || undefined;
+}
+
 // Extension Entry Point
 
 export default function (pi: ExtensionAPI) {
@@ -549,32 +548,102 @@ export default function (pi: ExtensionAPI) {
   const customModels = customModelsData as JsonModel[];
   const patches = patchData as PatchData;
 
+  let revalidateAbort: AbortController | null = null;
+  let settingsCommand: ReturnType<typeof createSettingsCommand> | undefined;
+  const copy: CoralCopy = {
+    version: PACKAGE_VERSION,
+    // A newer copy took this runtime over while extensions loaded; Pi serves its
+    // registration instead of ours, and our hooks below go inert.
+    resign: () => revalidateAbort?.abort(),
+    settings: async (args, ctx) => settingsCommand?.handler(args, ctx as any),
+  };
+  const claim = claimRuntime(pi, copy);
+  // A newer copy, or an equal one that loaded first, already serves this runtime.
+  if (!claim.owns()) return;
+
   let config = loadConfig();
   let currentModels = buildModels(loadStaleModels(embeddedModels), customModels, patches);
   const selectedApi = () => config.api === "responses" ? "openai-responses" : "openai-completions";
+  let providerModels = toProviderModels(currentModels, selectedApi());
+
+  // The key the catalog was last revalidated with (null: not yet this process).
+  // Pi refreshes catalogs on startup, on /model and after /login; only a changed
+  // key (a fresh /login, --api-key) or a forced refresh re-fetches /v1/models,
+  // so session-start revalidation stays the one routine fetch.
+  let revalidatedKey: string | undefined | null = null;
+  let keySync: Promise<void> = Promise.resolve();
+  // The in-flight session-start revalidation; it never rejects.
+  let sessionSync: Promise<void> = Promise.resolve();
+  let modelRegistry: ModelRegistry | undefined;
+
+  async function refreshModels(context: RefreshModelsContext): Promise<void> {
+    if (!context.allowNetwork || !claim.owns()) return;
+    await keySync;
+    const apiKey = await refreshApiKey(modelRegistry, context.credential);
+    if (context.signal.aborted || (!context.force && apiKey === revalidatedKey)) return;
+    revalidatedKey = apiKey;
+    cachedApiKey = apiKey;
+    revalidateAbort?.abort(); // a newer credential supersedes an in-flight session revalidation
+    await sessionSync; // ...and must release its sync lock first, or this refresh would skip as "locked"
+    if (context.signal.aborted) return;
+    // Through the quiet-sync lease: a forced refresh (after /login) or a new key
+    // skips the TTL; otherwise a fresh disk cache from another process serves.
+    const freshBase = claim.owns() ? await revalidateModels(apiKey, embeddedModels, context.signal, context.force) : null;
+    if (!freshBase || context.signal.aborted) return;
+    const next = buildModels(freshBase, customModels, patches);
+    await context.publish({
+      update: () => {
+        currentModels = next;
+        providerModels = toProviderModels(next, selectedApi());
+      },
+    });
+  }
+
   function registerProvider() {
-    pi.registerProvider(PROVIDER_ID, {
+    if (!claim.owns()) return;
+    providerModels = toProviderModels(currentModels, selectedApi());
+    // An already-selected model may still carry the previous API. Snapshot
+    // the current selection per request, without mutating that model/history.
+    const stream = (model: Model<any>, context: any, options?: any) =>
+      lazyStream(model, async () => streamCoral({ ...model, api: selectedApi() }, context, options, { park: config.park }));
+    // Native provider (pi-ai `Provider`): the same catalog and stream as the
+    // config form, plus API-key auth with a `/login coralbricks` flow.
+    pi.registerProvider({
+      id: PROVIDER_ID,
+      name: PROVIDER_NAME,
       baseUrl: BASE_URL,
-      apiKey: "$CORALBRICKS_API_KEY",
-      api: selectedApi(),
-      models: currentModels,
-      // An already-selected model may still carry the previous API. Snapshot
-      // the current selection per request, without mutating that model/history.
-      streamSimple: (model, context, options) => streamCoral({ ...model, api: selectedApi() }, context, options, { park: config.park }),
+      auth: { apiKey: coralApiKeyAuth() },
+      getModels: () => providerModels,
+      refreshModels,
+      stream,
+      streamSimple: stream,
     });
   }
   registerProvider();
-  registerSettingsCommand(pi, () => config, (next) => {
+  settingsCommand = createSettingsCommand(() => config, (next) => {
     config = next;
     registerProvider();
   });
+  // One command per runtime, served by whichever copy owns it when invoked.
+  if (claim.first) {
+    pi.registerCommand(SETTINGS_COMMAND, {
+      description: settingsCommand.description,
+      handler: (args, ctx) => (claim.owner() ?? copy).settings(args, ctx),
+    });
+  }
 
   pi.on("session_start", async (_event, ctx) => {
+    if (!claim.owns()) return;
+    modelRegistry = ctx.modelRegistry;
     revalidateAbort?.abort();
     revalidateAbort = new AbortController();
     const signal = revalidateAbort.signal;
-    void resolveApiKey(ctx.modelRegistry)
-      .then(() => revalidateModels(cachedApiKey, embeddedModels, signal))
+    const resolved = resolveApiKey(ctx.modelRegistry);
+    keySync = resolved.then(() => { revalidatedKey = cachedApiKey; }, () => {});
+    // Fire-and-forget: startup never waits on the network. Only the owning copy
+    // reaches the sync lease (and so the lock file and /v1/models).
+    sessionSync = resolved
+      .then(() => (claim.owns() && !signal.aborted ? revalidateModels(cachedApiKey, embeddedModels, signal) : null))
       .then((freshBase) => {
         if (freshBase && !signal.aborted) {
           currentModels = buildModels(freshBase, customModels, patches);
@@ -586,7 +655,8 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("session_shutdown", () => {
     revalidateAbort?.abort();
+    claim.release();
   });
 }
 
-export { applyPatch, buildModels, mergeWithEmbedded, transformApiModel, transformCatalogModel, activeDeprecatedModels, withDeprecated, parseContextWindow, PROVIDER_ID, BASE_URL };
+export { applyPatch, buildModels, mergeWithEmbedded, transformApiModel, activeDeprecatedModels, withDeprecated, parseContextWindow, PROVIDER_ID, BASE_URL };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-coralbricks-provider",
-  "version": "1.0.30",
+  "version": "1.0.32",
   "description": "CoralBricks provider extension for pi - Access GLM 5.3 and DeepSeek V4.1 Flash (FP4 variants included) through the Coral Inference API",
   "author": "monotykamary",
   "homepage": "https://github.com/monotykamary/pi-coralbricks-provider#readme",
@@ -38,7 +38,10 @@
   "files": [
     "index.ts",
     "settings.ts",
+    "auth.ts",
     "park.ts",
+    "guard.ts",
+    "sync-policy.ts",
     "models.json",
     "deprecated-models.json",
     "custom-models.json",

package/settings.ts

@@ -50,12 +50,16 @@ export function saveApi(api: CoralApi): void {
 
 const PARK_DESCRIPTION = "Responses only. Stores each response on Coral (store:true) and sends only new items with previous_response_id. Falls back to a full replay when the chain does not match.";
 
-export function registerSettingsCommand(
-  pi: ExtensionAPI,
+type SettingsCommand = Parameters<ExtensionAPI["registerCommand"]>[1];
+
+export const SETTINGS_COMMAND = "coralbricks-settings";
+
+/** `/coralbricks-settings` for one loaded copy; index.ts registers it once per runtime. */
+export function createSettingsCommand(
   getConfig: () => CoralConfig,
   apply: (config: CoralConfig) => void,
-): void {
-  pi.registerCommand("coralbricks-settings", {
+): SettingsCommand {
+  return {
     description: "Configure CoralBricks API (Chat Completions or opt-in Responses) and Responses parking",
     async handler(_args, ctx) {
       if (!ctx.hasUI) {
@@ -127,5 +131,13 @@ export function registerSettingsCommand(
         };
       });
     },
-  });
+  };
+}
+
+export function registerSettingsCommand(
+  pi: ExtensionAPI,
+  getConfig: () => CoralConfig,
+  apply: (config: CoralConfig) => void,
+): void {
+  pi.registerCommand(SETTINGS_COMMAND, createSettingsCommand(getConfig, apply));
 }

package/sync-policy.ts

@@ -0,0 +1,309 @@
+/**
+ * Quiet startup sync — shared policy for background model-catalog revalidation.
+ *
+ * Every pi process (interactive start, /new, /reload, `pi -p`, and every child
+ * agent a fan-out tool spawns) fires `session_start`. Revalidating the live
+ * `/models` catalog on each of those spams the provider API, so this module
+ * decides — without any network I/O and without ever throwing — whether *this*
+ * process should fetch at all:
+ *
+ *   1. No credentials → no fetch (serve disk cache → embedded models.json).
+ *   2. Freshness window → skip while the disk cache is younger than the TTL.
+ *      TTL source: the cache file's mtime. The cache is only (re)written after a
+ *      successful live fetch, so mtime is "last fetched at" — and caches written
+ *      by older extension versions carry it too, with no format change.
+ *      Default 1 hour; override with PI_PROVIDER_SYNC_TTL_MS (0 = always).
+ *   3. Forced refresh ignores the TTL: cache missing/corrupt, API key changed
+ *      since the cache was fetched (compared via a salted sha256 fingerprint —
+ *      never the key itself), or the caller passes `force` (e.g. after /login).
+ *   4. Failure backoff → after a failed fetch with the same key, non-forced
+ *      attempts wait min(5 min, TTL) so a bad key or outage is not retried by
+ *      every process that starts.
+ *   5. Cross-process single-flight → an atomic lock file (`open(…, "wx")`) next
+ *      to the cache; whoever creates it fetches, everyone else skips and keeps
+ *      serving the cache. Locks older than the stale timeout (crashed holder)
+ *      are reclaimed. Any filesystem error fails open to "skip the fetch".
+ *
+ * Files (for a cache at `<agentDir>/cache/<provider>-models.json`):
+ *   <provider>-models.json        the cache itself — unchanged plain JSON array
+ *   <provider>-models.sync.json   sidecar: { version, keyFingerprint, fetchedAt, failedAt?, failedKeyFingerprint? }
+ *   <provider>-models.lock        present only while one process is fetching
+ *
+ * Older extension versions ignore the sidecar/lock and read the cache as
+ * before; a cache without a sidecar (written by an older version) is treated
+ * as "fetched with an unknown key" and revalidated once (still single-flight).
+ *
+ * This file is provider-agnostic: it is copied verbatim into every
+ * pi-*-provider repo. Keep it free of pi imports and provider specifics.
+ *
+ * Typical use inside a provider's revalidateModels():
+ *
+ *   const lease = acquireModelSync({ cachePath: CACHE_PATH, apiKey, force });
+ *   if (!lease) return cacheChangedSinceLoad(CACHE_PATH) ? loadStaleModels(embedded) : null;
+ *   let merged = null;
+ *   try { …fetch, merge, cacheModels(merged)…; return merged; }
+ *   finally { lease.release(merged ? "fetched" : signal?.aborted ? "aborted" : "failed"); }
+ */
+
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+
+/** Env override for the freshness window, shared by all pi-*-provider extensions. */
+export const SYNC_TTL_ENV = "PI_PROVIDER_SYNC_TTL_MS";
+export const DEFAULT_SYNC_TTL_MS = 60 * 60 * 1000;
+/** A lock older than this is assumed abandoned (crashed holder). Must exceed the fetch timeout. */
+export const DEFAULT_LOCK_STALE_MS = 60 * 1000;
+/** Pause after a failed fetch (same key) before non-forced retries; capped at the TTL. */
+export const FAILURE_BACKOFF_MS = 5 * 60 * 1000;
+
+/** Why this process was granted the fetch. */
+export type SyncReason = "missing" | "key-changed" | "forced" | "stale";
+/** Why this process must not fetch (serve cache/embedded instead). */
+export type SkipReason = "no-key" | "fresh" | "backoff" | "locked" | "unwritable";
+/** How a granted fetch ended; "aborted" (session replaced/shut down) records no failure. */
+export type SyncOutcome = "fetched" | "failed" | "aborted";
+
+export type SyncPlan = { fetch: true; reason: SyncReason } | { fetch: false; reason: SkipReason };
+
+export interface ModelSyncOptions {
+  /** Absolute path of the provider's disk cache, e.g. `<agentDir>/cache/<provider>-models.json`. */
+  cachePath: string;
+  /** Resolved credential. Falsy → never fetch. */
+  apiKey: string | undefined | null;
+  /** Revalidate regardless of TTL/backoff (e.g. right after /login). Still single-flight. */
+  force?: boolean;
+  /** Freshness window; defaults to $PI_PROVIDER_SYNC_TTL_MS, else 1 hour. */
+  ttlMs?: number;
+  lockStaleMs?: number;
+  /** Cache validity check; defaults to "non-empty JSON array" (the models cache format). */
+  isValidCache?: (data: unknown) => boolean;
+  /** Clock override for tests. */
+  now?: number;
+  /** Optional diagnostics hook: called with the reason whenever the fetch is skipped. */
+  onSkip?: (reason: SkipReason) => void;
+}
+
+export interface ModelSyncLease {
+  readonly reason: SyncReason;
+  /** Always call exactly once (use try/finally). Records the outcome and drops the lock. */
+  release(outcome: SyncOutcome): void;
+}
+
+interface SyncMeta {
+  version: 1;
+  keyFingerprint?: string;
+  fetchedAt?: number;
+  failedAt?: number;
+  failedKeyFingerprint?: string;
+}
+
+// ─── Small helpers ────────────────────────────────────────────────────────────
+
+/** Salted, truncated sha256 of the key: detects key changes, cannot be reversed into the key. */
+export function keyFingerprint(apiKey: string): string {
+  return crypto.createHash("sha256").update(`pi-provider-sync\0${apiKey}`).digest("hex").slice(0, 16);
+}
+
+export function resolveSyncTtlMs(ttlMs?: number): number {
+  if (typeof ttlMs === "number" && Number.isFinite(ttlMs) && ttlMs >= 0) return ttlMs;
+  const raw = process.env[SYNC_TTL_ENV];
+  const fromEnv = raw === undefined || raw.trim() === "" ? NaN : Number(raw);
+  return Number.isFinite(fromEnv) && fromEnv >= 0 ? fromEnv : DEFAULT_SYNC_TTL_MS;
+}
+
+/** `foo-models.json` → `foo-models` (sidecar/lock base name). */
+function sidecarBase(cachePath: string): string {
+  return cachePath.replace(/\.json$/i, "");
+}
+export const syncMetaPath = (cachePath: string): string => `${sidecarBase(cachePath)}.sync.json`;
+export const syncLockPath = (cachePath: string): string => `${sidecarBase(cachePath)}.lock`;
+
+function mtimeMs(file: string): number | null {
+  try {
+    return fs.statSync(file).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function readJson(file: string): unknown {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function readMeta(cachePath: string): SyncMeta | null {
+  const data = readJson(syncMetaPath(cachePath));
+  return data && typeof data === "object" && !Array.isArray(data) ? (data as SyncMeta) : null;
+}
+
+/**
+ * Write via temp file + rename so concurrent readers in other processes never
+ * observe a half-written file (a torn cache would otherwise read as "corrupt"
+ * and force a refetch). Throws on failure — callers decide whether that is fatal.
+ */
+export function writeFileAtomic(file: string, contents: string): void {
+  const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+  try {
+    fs.writeFileSync(tmp, contents);
+    fs.renameSync(tmp, file);
+  } catch (error) {
+    try { fs.unlinkSync(tmp); } catch { /* already gone */ }
+    throw error;
+  }
+}
+
+function writeMeta(cachePath: string, meta: SyncMeta): void {
+  try {
+    writeFileAtomic(syncMetaPath(cachePath), JSON.stringify(meta) + "\n");
+  } catch {
+    // Non-fatal: worst case the next process revalidates once more.
+  }
+}
+
+// ─── In-process view of the shared cache ──────────────────────────────────────
+
+// mtime of the cache as this process last loaded/wrote it, per cache path.
+const loadedCacheMtimes = new Map<string, number>();
+
+/** Call right before reading the disk cache at startup (stat-before-read keeps races harmless). */
+export function markCacheLoaded(cachePath: string): void {
+  loadedCacheMtimes.set(cachePath, mtimeMs(cachePath) ?? 0);
+}
+
+/**
+ * True when another process rewrote the shared cache since this process last
+ * loaded it, so a long-lived session can adopt the newer catalog from disk
+ * instead of fetching it again.
+ */
+export function cacheChangedSinceLoad(cachePath: string): boolean {
+  const current = mtimeMs(cachePath);
+  return current !== null && current !== loadedCacheMtimes.get(cachePath);
+}
+
+// ─── Policy ───────────────────────────────────────────────────────────────────
+
+const isNonEmptyArray = (data: unknown): boolean => Array.isArray(data) && data.length > 0;
+
+/** Decide whether a fetch is warranted (no lock taken, no I/O beyond local stat/read). */
+export function planModelSync(options: ModelSyncOptions): SyncPlan {
+  const { cachePath, apiKey, force = false } = options;
+  if (!apiKey) return { fetch: false, reason: "no-key" };
+
+  const now = options.now ?? Date.now();
+  const ttlMs = resolveSyncTtlMs(options.ttlMs);
+  const fingerprint = keyFingerprint(apiKey);
+  const meta = readMeta(cachePath);
+  const cacheMtime = mtimeMs(cachePath);
+  const valid = cacheMtime !== null && (options.isValidCache ?? isNonEmptyArray)(readJson(cachePath));
+
+  let reason: SyncReason;
+  if (!valid) reason = "missing";
+  // A cache without a sidecar (older extension version) counts as an unknown key.
+  else if (meta?.keyFingerprint !== fingerprint) reason = "key-changed";
+  else if (force) reason = "forced";
+  else if (now - cacheMtime < ttlMs) return { fetch: false, reason: "fresh" };
+  else reason = "stale";
+
+  if (!force && meta?.failedKeyFingerprint === fingerprint && typeof meta.failedAt === "number"
+      && now - meta.failedAt < Math.min(FAILURE_BACKOFF_MS, ttlMs)) {
+    return { fetch: false, reason: "backoff" };
+  }
+  return { fetch: true, reason };
+}
+
+/** Atomically create the lock file; reclaim it once if its holder looks dead. */
+function tryLock(lockPath: string, token: string, lockStaleMs: number, now: number): "locked" | "held" | "unwritable" {
+  try {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  } catch {
+    return "unwritable";
+  }
+  for (let attempt = 0; attempt < 2; attempt++) {
+    let fd: number;
+    try {
+      fd = fs.openSync(lockPath, "wx");
+    } catch (error) {
+      // EEXIST: someone holds the lock. Anything else (EACCES, ENOTDIR, EROFS…):
+      // the cache dir is unusable — fail open to "skip the fetch".
+      if ((error as NodeJS.ErrnoException)?.code !== "EEXIST") return "unwritable";
+      if (attempt > 0) return "held";
+      const lockMtime = mtimeMs(lockPath);
+      if (lockMtime === null) continue; // released between open and stat: retry once
+      if (now - lockMtime <= lockStaleMs) return "held"; // a live process is fetching
+      // Stale: the holder crashed or hung. Reclaim and retry once. (Two processes
+      // reclaiming the same stale lock at the same instant may both fetch — a rare,
+      // harmless duplicate.)
+      try { fs.unlinkSync(lockPath); } catch { /* someone else reclaimed it first */ }
+      continue;
+    }
+    // We own the lock. Record a token so release() only deletes our own lock.
+    let wrote = false;
+    try {
+      fs.writeSync(fd, JSON.stringify({ pid: process.pid, token, at: now }));
+      wrote = true;
+    } catch {
+      // e.g. ENOSPC — handled below
+    } finally {
+      try { fs.closeSync(fd); } catch { /* ignore */ }
+    }
+    if (wrote) return "locked";
+    try { fs.unlinkSync(lockPath); } catch { /* ignore */ }
+    return "unwritable";
+  }
+  return "held";
+}
+
+/**
+ * Decide and, when this process should fetch, take the cross-process lock.
+ * Returns null when the caller must skip the network (serve cache/embedded).
+ * Never throws.
+ */
+export function acquireModelSync(options: ModelSyncOptions): ModelSyncLease | null {
+  try {
+    const plan = planModelSync(options);
+    if (!plan.fetch) return skip(options, plan.reason);
+
+    const { cachePath } = options;
+    const now = options.now ?? Date.now();
+    const lockPath = syncLockPath(cachePath);
+    const token = crypto.randomBytes(8).toString("hex");
+    const lock = tryLock(lockPath, token, options.lockStaleMs ?? DEFAULT_LOCK_STALE_MS, now);
+    if (lock !== "locked") return skip(options, lock === "held" ? "locked" : "unwritable");
+
+    const fingerprint = keyFingerprint(options.apiKey as string);
+    let released = false;
+    return {
+      reason: plan.reason,
+      release(outcome: SyncOutcome): void {
+        if (released) return;
+        released = true;
+        try {
+          const at = Date.now();
+          if (outcome === "fetched") {
+            writeMeta(cachePath, { version: 1, keyFingerprint: fingerprint, fetchedAt: at });
+            markCacheLoaded(cachePath); // our own write is not "another process's" update
+          } else if (outcome === "failed") {
+            const previous = readMeta(cachePath);
+            writeMeta(cachePath, { ...previous, version: 1, failedAt: at, failedKeyFingerprint: fingerprint });
+          }
+          // Only remove the lock if it is still ours (it may have been reclaimed as stale).
+          const held = readJson(lockPath) as { token?: string } | undefined;
+          if (held?.token === token) fs.unlinkSync(lockPath);
+        } catch {
+          // Never throw from cleanup; a leftover lock expires after lockStaleMs.
+        }
+      },
+    };
+  } catch {
+    return skip(options, "unwritable");
+  }
+}
+
+function skip(options: ModelSyncOptions, reason: SkipReason): null {
+  try { options.onSkip?.(reason); } catch { /* diagnostics must never break startup */ }
+  return null;
+}