pi-parasail-provider 1.0.34 → 1.0.37

package/.github/workflows/update-models.yml

@@ -0,0 +1,60 @@
+name: Update models
+
+on:
+  schedule:
+    - cron: "7 0 * * *" # 07:07 Asia/Ho_Chi_Minh
+  workflow_dispatch:
+
+# Publishing uses npm Trusted Publishing (OIDC) bound to this workflow file, so
+# no npm token is stored. A version pushed while publishing was unavailable is
+# published by the next run that finds it missing from npm.
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: update-models
+  cancel-in-progress: false
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24
+
+      - name: Fetch the model catalog
+        env:
+          PARASAIL_API_KEY: ${{ secrets.PARASAIL_API_KEY }}
+        run: node scripts/update-models.js
+
+      - name: Commit, bump and push
+        run: |
+          if git diff --quiet; then
+            echo "No model changes."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git commit -m "feat: update parasail models from API"
+          npm version patch --no-git-tag-version
+          version=$(node -p "require('./package.json').version")
+          git commit -am "chore(release): v$version"
+          git push origin HEAD:main
+
+      - name: Publish to npm if this version is missing
+        run: |
+          name=$(node -p "require('./package.json').name")
+          version=$(node -p "require('./package.json').version")
+          if npm view "$name@$version" version >/dev/null 2>&1; then
+            echo "$name@$version is already on npm."
+            exit 0
+          fi
+          # Trusted publishing needs npm 11.5.1 or newer.
+          npm install --global npm@latest
+          npm publish --access public --provenance

package/AGENTS.md

@@ -19,6 +19,7 @@ When a model needs overrides, new properties, or corrections, edit the appropria
 | `patch.json` | Per-model overrides keyed by model ID. Add reasoning flags, compat settings, pricing corrections, thinking level maps, etc. Applied on top of `models.json` at runtime and for README generation. |
 | `custom-models.json` | Models that don't exist in the provider API (hidden models, router endpoints, cross-provider aliases). Merged after patch. Format: array of full model objects (same schema as `models.json` entries). |
 | `index.ts` | Provider extension code. |
+| `sync-policy.ts` | Quiet startup sync policy (TTL, key fingerprint, cross-process lock). Provider-agnostic and shared verbatim across pi-*-provider repos — keep it free of provider specifics. |
 | `scripts/update-models.js` | The sync script itself (edit only if changing how models are fetched/transformed). |
 
 ## Data Flow

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.0.37
+
+- Pin Pi SDK development dependencies to 1.2.0 while retaining wildcard host peers; verify real manifest loading, lifecycle and native/bundled Pi hosts offline.
+
+## 1.0.35
+
+- Quiet startup sync: background revalidation (`/v1/models` plus the public pricing endpoint) runs only with an API key, only when the disk cache is older than 1 hour (`PI_PROVIDER_SYNC_TTL_MS`, `0` = always), missing, or fetched with a different key, and only in one pi process at a time (lock file next to the cache). Failed refreshes back off for 5 minutes; sessions that skip adopt a cache refreshed by another process.
+- Without an API key the extension no longer calls the public pricing endpoint either: no key, no request.
+- The model cache is only written when the authenticated model list succeeds; a failed refresh no longer overwrites the cache with the bundled models.
+- Never store the API key: key changes are detected via a salted sha256 fingerprint in `cache/parasail-models.sync.json`. The cache file format is unchanged.
+- Write the model cache atomically and swallow API key resolution failures in `session_start`.
+- Add vitest coverage for the sync policy and the session_start integration.
+
 ## 1.0.27
 
 - Validate provider registration and session lifecycle against Pi 1.0.0; update the pinned development SDK.

package/README.md

@@ -20,6 +20,7 @@ _DeepSeek, Qwen, GLM, Kimi, Llama, Gemma, Mistral — serverless with live prici
 - **Vision Support** — Qwen3-VL, Gemma 4, Qwen2.5-VL accept image + text input
 - **Unified API** — OpenAI-compatible completions endpoint
 - **Long Context** — DeepSeek V4 (1M), Llama 4 Maverick (1M), MiniMax M2.5 (1M)
+- **Quiet live model sync** — Models and pricing refresh from the Parasail API in the background, at most hourly and by one pi process at a time ([details](#model-sync))
 
 ## Installation
 
@@ -83,7 +84,7 @@ Get your API key at [parasail.io](https://parasail.io/).
 | Glm 53 | 1M | ❌ | Text | 16K | $1.40 | $4.40 | $0.26 |
 | Glm 53 Flash | 1M | ❌ | Text | 16K | $0.15 | $0.50 | $0.03 |
 | Glm 53 Flash Fast | 1M | ❌ | Text | 16K | $0.19 | $0.63 | $0.04 |
-| Googlegemma 3 4b It | 131K | ❌ | Text | 16K | $0.05 | — | — |
+| Googlegemma 3 4b It | 131K | ❌ | Text | 16K | $0.04 | $0.05 | $0.02 |
 | Gpt Oss 120b Fast | 131K | ✅ | Text | 16K | $0.15 | $0.60 | — |
 | GPT-OSS 120B | 131K | ✅ | Text | 16K | $0.10 | $0.75 | $0.06 |
 | GPT-OSS 20B | 131K | ✅ | Text | 16K | $0.03 | $0.15 | $0.02 |
@@ -155,6 +156,7 @@ Get your API key at [parasail.io](https://parasail.io/).
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `PARASAIL_API_KEY` | No | Your Parasail API key (fallback if not in auth.json) |
+| `PI_PROVIDER_SYNC_TTL_MS` | No | Model sync freshness window in ms (default `3600000`; `0` = revalidate every session start) |
 
 ## Configuration
 
@@ -184,6 +186,22 @@ The `patch.json` file contains overrides that are applied on top of `models.json
 - Adding compat settings that the API doesn't provide
 - Overriding pricing/context window when specs change
 
+## Model sync
+
+Startup never waits on the network. pi starts with the cached catalog (`~/.pi/agent/cache/parasail-models.json`,
+falling back to the bundled `models.json`) and revalidates against `/v1/models` and the public pricing endpoint in the
+background — only when:
+
+- a Parasail API key is configured (no key, no request — not even to the public pricing endpoint),
+- the cache is older than 1 hour, missing, or was fetched with a different API key, and
+- no other pi process is already refreshing it (a `parasail-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. The cache is only rewritten when the
+model list succeeds (pricing is a best-effort enrichment). 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 (`parasail-models.sync.json`), never the key itself.
+
 ## Updating Models
 
 Run the update script to fetch the latest models from Parasail's API:

package/index.ts

@@ -13,6 +13,10 @@
  *   2. Revalidate in background:
  *      a. Live API /v1/models → merge with embedded → enrich with pricing
  *      b. Public pricing endpoint → apply input/output/cache costs + context windows
+ *      Quiet startup sync (sync-policy.ts): only with an API key (the public
+ *      pricing endpoint is not called without one either), only when the disk
+ *      cache is older than the TTL (1h, PI_PROVIDER_SYNC_TTL_MS) or the key
+ *      changed, 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
  *
  * Merge order: [live|cache|embedded] → apply patch.json → merge custom-models.json
@@ -38,6 +42,7 @@ import patchData from "./patch.json" with { type: "json" };
 import deprecatedData from "./deprecated-models.json" with { type: "json" };
 import fs from "fs";
 import path from "path";
+import { acquireModelSync, cacheChangedSinceLoad, markCacheLoaded, writeFileAtomic } from "./sync-policy";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -288,7 +293,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
   }
@@ -361,6 +367,7 @@ function withDeprecated(models: JsonModel[]): JsonModel[] {
 }
 
 function loadStaleModels(embeddedModels: JsonModel[]): JsonModel[] {
+  markCacheLoaded(CACHE_PATH); // stat before read: lets session_start spot newer caches
   const cached = loadCachedModels();
   if (!cached || cached.length === 0) return embeddedModels;
 
@@ -374,23 +381,38 @@ function loadStaleModels(embeddedModels: JsonModel[]): JsonModel[] {
   return cached;
 }
 
-async function revalidateModels(apiKey: string | undefined, embeddedModels: JsonModel[], signal?: AbortSignal): Promise<JsonModel[] | null> {
-  // Fetch both models list and pricing in parallel
-  const [liveModels, pricing] = await Promise.all([
-    apiKey ? fetchLiveModels(apiKey, signal) : Promise.resolve(null),
-    fetchPricingData(signal),
-  ]);
-
-  // Use embedded as base if live fetch failed
-  const base = liveModels && liveModels.length > 0
-    ? mergeWithEmbedded(liveModels, embeddedModels)
-    : embeddedModels;
-
-  // Always apply live pricing if available (public endpoint, no auth needed)
-  const enriched = pricing ? applyPricing(base, pricing) : base;
-
-  cacheModels(enriched);
-  return enriched;
+/**
+ * Background revalidation, gated by the quiet startup sync policy
+ * (sync-policy.ts): no key → no fetch at all (not even the public pricing
+ * endpoint); 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; it is
+ * still single-flight.
+ *
+ * One lease covers both requests. They run in parallel, each bounded by
+ * LIVE_FETCH_TIMEOUT_MS, so the lease is held well under the lock stale time.
+ * The authenticated /v1/models list is authoritative: the cache is written
+ * (and the sync recorded as "fetched") only when it succeeds. Pricing is a
+ * best-effort enrichment on top of it.
+ */
+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 enriched: JsonModel[] | null = null;
+  try {
+    // Fetch both models list and pricing in parallel
+    const [liveModels, pricing] = await Promise.all([
+      apiKey ? fetchLiveModels(apiKey, signal) : Promise.resolve(null),
+      fetchPricingData(signal),
+    ]);
+    if (!liveModels || liveModels.length === 0) return null;
+    const base = mergeWithEmbedded(liveModels, embeddedModels);
+    enriched = pricing ? applyPricing(base, pricing) : base;
+    cacheModels(enriched);
+    return enriched;
+  } finally {
+    lease.release(enriched ? "fetched" : signal?.aborted ? "aborted" : "failed");
+  }
 }
 
 // ─── API Key Resolution (via ModelRegistry) ────────────────────────────────────
@@ -420,14 +442,17 @@ export default function (pi: ExtensionAPI) {
     models: staleModels,
   });
 
-  // Revalidate in background: fetch live models + pricing → merge → cache → hot-swap
-  // Pricing endpoint is public (no auth needed), models endpoint requires API key
+  // Revalidate in background: fetch live models + pricing → merge → cache → hot-swap.
+  // Both requests are gated on an API key (quiet startup sync). Fire-and-forget:
+  // never await network here — startup must not block on the provider API.
+  // Nothing is awaited and every rejection is swallowed.
   pi.on("session_start", async (_event, ctx) => {
     revalidateAbort?.abort();
     revalidateAbort = new AbortController();
     const signal = revalidateAbort.signal;
-    resolveApiKey(ctx.modelRegistry).then(() => {
-      revalidateModels(cachedApiKey, embeddedModels, signal).then((freshBase) => {
+    void resolveApiKey(ctx.modelRegistry)
+      .then(() => revalidateModels(cachedApiKey, embeddedModels, signal))
+      .then((freshBase) => {
         if (freshBase && !signal.aborted) {
           pi.registerProvider("parasail", {
             baseUrl: BASE_URL,
@@ -436,8 +461,8 @@ export default function (pi: ExtensionAPI) {
             models: buildModels(freshBase, customModels, patches),
           });
         }
-      });
-    });
+      })
+      .catch(() => { /* keep serving the stale catalog */ });
   });
 
   pi.on("session_shutdown", () => {

package/models.json

@@ -635,9 +635,9 @@
       "text"
     ],
     "cost": {
-      "input": 0.05,
-      "output": 0,
-      "cacheRead": 0,
+      "input": 0.04,
+      "output": 0.05,
+      "cacheRead": 0.02,
       "cacheWrite": 0
     },
     "contextWindow": 131072,

package/package.json

@@ -1,9 +1,18 @@
 {
   "name": "pi-parasail-provider",
-  "version": "1.0.34",
+  "version": "1.0.37",
   "description": "Parasail provider extension for pi - Access top open-source models (DeepSeek, Qwen, GLM, Kimi, Llama, Gemma, Mistral) through the Parasail API",
   "type": "module",
   "main": "index.ts",
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "tsc --noEmit && vitest run && node scripts/test-pi-compat.mjs",
+    "test": "vitest run",
+    "update-models": "node scripts/update-models.js",
+    "test:pi": "node scripts/test-pi-compat.mjs",
+    "typecheck": "tsc --noEmit"
+  },
   "keywords": [
     "pi",
     "extension",
@@ -30,19 +39,16 @@
     "brace-expansion": "5.0.12"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@types/node": "^25.9.1",
     "typescript": "6.0.3",
-    "@types/node": "^25.9.1"
+    "vitest": "4.1.7"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"
   },
-  "scripts": {
-    "clean": "echo 'nothing to clean'",
-    "build": "echo 'nothing to build'",
-    "check": "tsc --noEmit && node scripts/test-pi-compat.mjs",
-    "update-models": "node scripts/update-models.js",
-    "test:pi": "node scripts/test-pi-compat.mjs",
-    "typecheck": "tsc --noEmit"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/monotykamary/pi-parasail-provider.git"
   }
-}
+}

package/scripts/test-pi-compat.mjs

@@ -14,7 +14,7 @@ globalThis.fetch = async () => new Response('', { status: 503 });
 let session;
 try {
   const { createAgentSession, DefaultResourceLoader, ModelRuntime, SessionManager, SettingsManager, VERSION } = await import('@earendil-works/pi-coding-agent');
-  assert.equal(VERSION, '1.1.0', 'run compatibility checks against the pinned host');
+  assert.equal(VERSION, '1.2.0', 'run compatibility checks against the pinned host');
   const manifest = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
   const hostPackages = ['@earendil-works/pi-ai', '@earendil-works/pi-agent-core', '@earendil-works/pi-coding-agent', '@earendil-works/pi-tui', 'typebox'];
   for (const name of hostPackages) {
@@ -65,7 +65,7 @@ try {
     modelCount += models.length;
   }
   await session.extensionRunner.emit({ type: 'session_shutdown' });
-  assert.deepEqual(errors, [], 'startup and shutdown handlers must work with Pi 1.1.0 contexts');
+  assert.deepEqual(errors, [], 'startup and shutdown handlers must work with Pi 1.2.0 contexts');
   console.log(`${manifest.name}: Pi ${VERSION} loader, manifest, session startup, and ${modelCount} models OK`);
 } finally {
   session?.dispose();

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;
+}