pi-parasail-provider 1.0.33 → 1.0.35

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,14 @@
 # Changelog
 
+## 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,13 +84,13 @@ 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 |
-| Glm 53 Flash Vercel | 1M | ❌ | Text | 16K | — | — | — |
 | Googlegemma 3 4b It | 131K | ❌ | Text | 16K | $0.05 | — | — |
 | 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 |
 | Kimi K2.6 | 262K | ✅ | Text + Image | 16K | $0.75 | $3.50 | $0.16 |
 | Kimi K3 | 1M | ✅ | Text + Image | 16K | $2.60 | $13.00 | $0.26 |
+| Kimi K3 Fast | 1M | ✅ | Text + Image | 16K | $3.00 | $15.00 | $0.30 |
 | Llama 3.3 70B | 131K | ❌ | Text | 16K | $0.22 | $0.50 | $0.11 |
 | Llama 32 3b Instruct | 131K | ❌ | Text | 16K | $0.05 | $0.33 | — |
 | Llama 4 Maverick 17B-128E | 524K | ❌ | Text + Image | 16K | $0.35 | $1.00 | $0.17 |
@@ -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/deprecated-models.json

@@ -64,5 +64,27 @@
       "supportsStore": false
     },
     "deprecatedAt": "2026-10-08T00:00:21.187Z"
+  },
+  "parasail-glm-53-flash-vercel": {
+    "id": "parasail-glm-53-flash-vercel",
+    "name": "Glm 53 Flash Vercel",
+    "reasoning": false,
+    "input": [
+      "text"
+    ],
+    "cost": {
+      "input": 0,
+      "output": 0,
+      "cacheRead": 0,
+      "cacheWrite": 0
+    },
+    "contextWindow": 1048576,
+    "maxTokens": 16384,
+    "compat": {
+      "maxTokensField": "max_completion_tokens",
+      "supportsDeveloperRole": false,
+      "supportsStore": false
+    },
+    "deprecatedAt": "2026-10-09T00:00:22.639Z"
   }
 }

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

@@ -371,27 +371,6 @@
       "supportsStore": false
     }
   },
-  {
-    "id": "parasail-glm-53-flash-vercel",
-    "name": "Glm 53 Flash Vercel",
-    "reasoning": false,
-    "input": [
-      "text"
-    ],
-    "cost": {
-      "input": 0,
-      "output": 0,
-      "cacheRead": 0,
-      "cacheWrite": 0
-    },
-    "contextWindow": 1048576,
-    "maxTokens": 16384,
-    "compat": {
-      "maxTokensField": "max_completion_tokens",
-      "supportsDeveloperRole": false,
-      "supportsStore": false
-    }
-  },
   {
     "id": "parasail-kimi-k3",
     "name": "Kimi K3",
@@ -455,6 +434,27 @@
       "supportsStore": false
     }
   },
+  {
+    "id": "parasail-kimi-k3-fast",
+    "name": "Kimi K3 Fast",
+    "reasoning": false,
+    "input": [
+      "text"
+    ],
+    "cost": {
+      "input": 3,
+      "output": 15,
+      "cacheRead": 0.3,
+      "cacheWrite": 0
+    },
+    "contextWindow": 1000000,
+    "maxTokens": 16384,
+    "compat": {
+      "maxTokensField": "max_completion_tokens",
+      "supportsDeveloperRole": false,
+      "supportsStore": false
+    }
+  },
   {
     "id": "parasail-llama-4-maverick-instruct-fp8",
     "name": "Llama 4 Maverick 17B-128E",

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "pi-parasail-provider",
-  "version": "1.0.33",
+  "version": "1.0.35",
   "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 && node scripts/test-pi-compat.mjs",
+    "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"
@@ -40,7 +41,8 @@
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "1.1.0",
     "typescript": "6.0.3",
-    "@types/node": "^25.9.1"
+    "@types/node": "^25.9.1",
+    "vitest": "4.1.7"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"

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

package/tests/quiet-startup-sync.test.ts

@@ -0,0 +1,304 @@
+/**
+ * Quiet startup sync, end to end through the extension's real session_start
+ * handler: the live /models catalog is fetched only with a key, only when the
+ * disk cache is stale (or the key changed), only by one process at a time, and
+ * never on the session_start critical path.
+ *
+ * Porting: only the "Provider specifics" block below differs between
+ * pi-*-provider repos.
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { keyFingerprint, syncLockPath, syncMetaPath } from "../sync-policy";
+import embeddedModels from "../models.json" with { type: "json" };
+
+// ─── Provider specifics ───────────────────────────────────────────────────────
+const PROVIDER_ID = "parasail";
+// transformApiModel only keeps parasail- prefixed ids.
+const LIVE_ONLY_ID = "parasail-live-only-test-model";
+/** A minimal successful /models response containing LIVE_ONLY_ID. */
+const liveModelsResponse = () => Response.json({ data: [{ id: LIVE_ONLY_ID }] });
+// Parasail also enriches the catalog from a public pricing endpoint. It sits
+// behind the same lease, so `fetch` below counts /v1/models calls and
+// `pricingFetch` counts pricing calls.
+const PRICING_URL = "https://www.saas.parasail.io/api/v1/prices/serverlessEndpoints";
+const pricingResponse = () => Response.json([
+  { externalAlias: LIVE_ONLY_ID, contextLength: 65536, inputCost: 1.25, outputCost: 2.5, cachedCost: 0.5, tags: [] },
+]);
+let pricingFetch: ReturnType<typeof vi.fn>;
+// ──────────────────────────────────────────────────────────────────────────────
+
+const HOUR = 60 * 60 * 1000;
+const KEY = "sk-quiet-sync-test";
+
+let home: string;
+let cachePath: string;
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.unstubAllGlobals();
+  vi.resetModules();
+  if (home) fs.rmSync(home, { recursive: true, force: true });
+});
+
+function setupHome(): void {
+  home = fs.mkdtempSync(path.join(os.tmpdir(), `pi-${PROVIDER_ID}-sync-`));
+  cachePath = path.join(home, "cache", `${PROVIDER_ID}-models.json`);
+  vi.stubEnv("PI_CODING_AGENT_DIR", home);
+  vi.stubEnv("PI_PROVIDER_SYNC_TTL_MS", "");
+}
+
+function writeCache(ageMs: number, models: unknown[] = embeddedModels, fingerprintKey: string | null = KEY): void {
+  fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+  fs.writeFileSync(cachePath, JSON.stringify(models));
+  const t = new Date(Date.now() - ageMs);
+  fs.utimesSync(cachePath, t, t);
+  if (fingerprintKey !== null) {
+    fs.writeFileSync(syncMetaPath(cachePath), JSON.stringify({ version: 1, keyFingerprint: keyFingerprint(fingerprintKey) }));
+  }
+}
+
+function stubFetch(impl: () => Promise<Response> = async () => liveModelsResponse()) {
+  const fetch = vi.fn(impl);
+  pricingFetch = vi.fn(async () => pricingResponse());
+  vi.stubGlobal("fetch", (input: unknown) => String(input) === PRICING_URL ? pricingFetch() : fetch());
+  return fetch;
+}
+
+/** Load the extension fresh (module-level cache paths read PI_CODING_AGENT_DIR). */
+async function loadExtension() {
+  vi.resetModules();
+  const mod = await import("../index");
+  const handlers = new Map<string, (...args: any[]) => any>();
+  const registrations: Array<{ models: Array<{ id: string }> }> = [];
+  mod.default({
+    on: (event: string, handler: (...args: any[]) => any) => handlers.set(event, handler),
+    registerProvider: (_id: string, config: any) => registrations.push(config),
+    registerCommand: () => {},
+  } as any);
+  const getApiKeyForProvider = vi.fn(async (): Promise<string | undefined> => KEY);
+  const startSession = () => handlers.get("session_start")!({ type: "session_start" }, { modelRegistry: { getApiKeyForProvider } });
+  return { handlers, registrations, getApiKeyForProvider, startSession };
+}
+
+/** Let the fire-and-forget revalidation chain run to completion. */
+const settle = () => new Promise((resolve) => setTimeout(resolve, 50));
+const hasLiveModel = (config: { models: Array<{ id: string }> } | undefined) => !!config?.models.some((m) => m.id === LIVE_ONLY_ID);
+
+describe("quiet startup sync", () => {
+  it("skips the live fetch while the disk cache is fresher than the TTL", async () => {
+    setupHome();
+    writeCache(10 * 60 * 1000);
+    const fetch = stubFetch();
+    const ext = await loadExtension();
+    await ext.startSession();
+    await settle();
+    expect(ext.getApiKeyForProvider).toHaveBeenCalled();
+    expect(fetch).not.toHaveBeenCalled();
+    expect(ext.registrations).toHaveLength(1);
+  });
+
+  it("revalidates a stale cache once, hot-swaps the catalog and rewrites the cache", async () => {
+    setupHome();
+    writeCache(2 * HOUR);
+    const fetch = stubFetch();
+    const ext = await loadExtension();
+    await ext.startSession();
+    await vi.waitFor(() => expect(hasLiveModel(ext.registrations.at(-1))).toBe(true));
+    expect(fetch).toHaveBeenCalledOnce();
+    const cached = JSON.parse(fs.readFileSync(cachePath, "utf8"));
+    // Cache stays a plain JSON array so older extension versions still read it.
+    expect(Array.isArray(cached)).toBe(true);
+    expect(cached.some((m: { id: string }) => m.id === LIVE_ONLY_ID)).toBe(true);
+    // Pricing enrichment rides on the same sync.
+    expect(pricingFetch).toHaveBeenCalledOnce();
+    expect(cached.find((m: { id: string }) => m.id === LIVE_ONLY_ID).cost.input).toBe(1.25);
+    expect(Date.now() - fs.statSync(cachePath).mtimeMs).toBeLessThan(60_000);
+    expect(fs.existsSync(syncLockPath(cachePath))).toBe(false);
+    const meta = fs.readFileSync(syncMetaPath(cachePath), "utf8");
+    expect(meta).not.toContain(KEY);
+    expect(JSON.parse(meta).keyFingerprint).toBe(keyFingerprint(KEY));
+
+    // A second session in the same process (/new) is now inside the TTL.
+    await ext.startSession();
+    await settle();
+    expect(fetch).toHaveBeenCalledOnce();
+  });
+
+  it("never touches the network without an API key", async () => {
+    setupHome();
+    const fetch = stubFetch();
+    const ext = await loadExtension();
+    ext.getApiKeyForProvider.mockResolvedValue(undefined);
+    await ext.startSession();
+    await settle();
+    expect(fetch).not.toHaveBeenCalled();
+    expect(pricingFetch).not.toHaveBeenCalled(); // public endpoint, but still gated on the key
+    expect(fs.existsSync(cachePath)).toBe(false);
+    expect(fs.existsSync(syncLockPath(cachePath))).toBe(false);
+    expect(ext.registrations).toHaveLength(1);
+  });
+
+  it("skips when another process holds the revalidation lock", async () => {
+    setupHome();
+    writeCache(2 * HOUR);
+    fs.writeFileSync(syncLockPath(cachePath), JSON.stringify({ pid: 999999, token: "other-process" }));
+    const fetch = stubFetch();
+    const ext = await loadExtension();
+    await ext.startSession();
+    await settle();
+    expect(fetch).not.toHaveBeenCalled();
+    expect(pricingFetch).not.toHaveBeenCalled();
+    expect(JSON.parse(fs.readFileSync(syncLockPath(cachePath), "utf8")).token).toBe("other-process");
+  });
+
+  it("reclaims a stale lock left by a crashed process", async () => {
+    setupHome();
+    writeCache(2 * HOUR);
+    const lockPath = syncLockPath(cachePath);
+    fs.writeFileSync(lockPath, JSON.stringify({ pid: 999999, token: "crashed" }));
+    const old = new Date(Date.now() - 10 * 60 * 1000);
+    fs.utimesSync(lockPath, old, old);
+    const fetch = stubFetch();
+    const ext = await loadExtension();
+    await ext.startSession();
+    await vi.waitFor(() => expect(hasLiveModel(ext.registrations.at(-1))).toBe(true));
+    expect(fetch).toHaveBeenCalledOnce();
+    expect(fs.existsSync(lockPath)).toBe(false);
+  });
+
+  it("forces a revalidation when the API key changed, even inside the TTL", async () => {
+    setupHome();
+    writeCache(60 * 1000, embeddedModels, "previous-key");
+    const fetch = stubFetch();
+    const ext = await loadExtension();
+    await ext.startSession();
+    await vi.waitFor(() => expect(hasLiveModel(ext.registrations.at(-1))).toBe(true));
+    expect(fetch).toHaveBeenCalledOnce();
+  });
+
+  it("revalidates once when the cache predates the sync sidecar (older extension version)", async () => {
+    setupHome();
+    writeCache(60 * 1000, embeddedModels, null);
+    const fetch = stubFetch();
+    const ext = await loadExtension();
+    expect(ext.registrations[0].models.length).toBeGreaterThan(0); // old cache is still served
+    await ext.startSession();
+    await vi.waitFor(() => expect(hasLiveModel(ext.registrations.at(-1))).toBe(true));
+    expect(fetch).toHaveBeenCalledOnce();
+  });
+
+  it("does not throw or fetch when the cache dir is unwritable", async () => {
+    setupHome();
+    fs.writeFileSync(path.join(home, "cache"), "a file where the cache dir should be");
+    const fetch = stubFetch();
+    const ext = await loadExtension();
+    await expect(ext.startSession()).resolves.toBeUndefined();
+    await settle();
+    expect(fetch).not.toHaveBeenCalled();
+    expect(ext.registrations).toHaveLength(1);
+  });
+
+  it("does not await the network in session_start", async () => {
+    setupHome();
+    writeCache(2 * HOUR);
+    let release!: () => void;
+    const fetch = stubFetch(() => new Promise<Response>((resolve) => { release = () => resolve(liveModelsResponse()); }));
+    const ext = await loadExtension();
+    const outcome = await Promise.race([
+      Promise.resolve(ext.startSession()).then(() => "returned"),
+      new Promise((resolve) => setTimeout(() => resolve("blocked"), 1000)),
+    ]);
+    expect(outcome).toBe("returned");
+    await vi.waitFor(() => expect(fetch).toHaveBeenCalledOnce());
+    release();
+    await vi.waitFor(() => expect(hasLiveModel(ext.registrations.at(-1))).toBe(true));
+  });
+
+  it("swallows API key resolution failures (no unhandled rejection)", async () => {
+    setupHome();
+    const fetch = stubFetch();
+    const ext = await loadExtension();
+    const unhandled = vi.fn();
+    process.on("unhandledRejection", unhandled);
+    try {
+      ext.getApiKeyForProvider.mockRejectedValue(new Error("keychain locked"));
+      await ext.startSession();
+      await settle();
+      expect(unhandled).not.toHaveBeenCalled();
+      expect(fetch).not.toHaveBeenCalled();
+    } finally {
+      process.off("unhandledRejection", unhandled);
+    }
+  });
+
+  it("backs off after a failed fetch instead of retrying in every new process", async () => {
+    setupHome();
+    writeCache(2 * HOUR);
+    const fetch = stubFetch(async () => new Response("unauthorized", { status: 401 }));
+    let ext = await loadExtension();
+    await ext.startSession();
+    await vi.waitFor(() => expect(fetch).toHaveBeenCalledOnce());
+    await settle();
+    ext = await loadExtension(); // next pi process
+    await ext.startSession();
+    await settle();
+    expect(fetch).toHaveBeenCalledOnce();
+  });
+
+  it("adopts a cache refreshed by another process without fetching", async () => {
+    setupHome();
+    writeCache(30 * 60 * 1000);
+    const fetch = stubFetch();
+    const ext = await loadExtension();
+    // Another pi process revalidated after this one started.
+    const refreshed = [...embeddedModels, { ...embeddedModels[0], id: LIVE_ONLY_ID }];
+    fs.writeFileSync(cachePath, JSON.stringify(refreshed));
+    await ext.startSession();
+    await vi.waitFor(() => expect(hasLiveModel(ext.registrations.at(-1))).toBe(true));
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it("PI_PROVIDER_SYNC_TTL_MS=0 revalidates on every session start", async () => {
+    setupHome();
+    vi.stubEnv("PI_PROVIDER_SYNC_TTL_MS", "0");
+    writeCache(0);
+    const fetch = stubFetch();
+    const ext = await loadExtension();
+    await ext.startSession();
+    await vi.waitFor(() => expect(fetch).toHaveBeenCalledOnce());
+  });
+
+  it("does not write the cache when the model list fails, even if pricing succeeds", async () => {
+    setupHome();
+    writeCache(2 * HOUR);
+    const before = fs.readFileSync(cachePath, "utf8");
+    const mtime = fs.statSync(cachePath).mtimeMs;
+    const fetch = stubFetch(async () => new Response("unavailable", { status: 503 }));
+    const ext = await loadExtension();
+    await ext.startSession();
+    await vi.waitFor(() => expect(fetch).toHaveBeenCalledOnce());
+    await settle();
+    expect(pricingFetch).toHaveBeenCalledOnce();
+    expect(fs.readFileSync(cachePath, "utf8")).toBe(before);
+    expect(fs.statSync(cachePath).mtimeMs).toBe(mtime);
+    expect(ext.registrations).toHaveLength(1);
+    expect(JSON.parse(fs.readFileSync(syncMetaPath(cachePath), "utf8")).failedKeyFingerprint).toBe(keyFingerprint(KEY));
+  });
+
+  it("still caches the live model list when the pricing endpoint fails", async () => {
+    setupHome();
+    writeCache(2 * HOUR);
+    const fetch = stubFetch();
+    pricingFetch.mockImplementation(async () => new Response("down", { status: 500 }));
+    const ext = await loadExtension();
+    await ext.startSession();
+    await vi.waitFor(() => expect(hasLiveModel(ext.registrations.at(-1))).toBe(true));
+    expect(fetch).toHaveBeenCalledOnce();
+    const cached = JSON.parse(fs.readFileSync(cachePath, "utf8"));
+    expect(cached.some((m: { id: string }) => m.id === LIVE_ONLY_ID)).toBe(true);
+  });
+});

package/tests/sync-policy.test.ts

@@ -0,0 +1,259 @@
+/**
+ * Unit tests for sync-policy.ts — the provider-agnostic quiet startup sync
+ * policy (TTL, key fingerprint, failure backoff, cross-process lock).
+ *
+ * Provider-agnostic: copied verbatim into every pi-*-provider repo alongside
+ * sync-policy.ts.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  DEFAULT_SYNC_TTL_MS,
+  SYNC_TTL_ENV,
+  acquireModelSync,
+  cacheChangedSinceLoad,
+  keyFingerprint,
+  markCacheLoaded,
+  planModelSync,
+  resolveSyncTtlMs,
+  syncLockPath,
+  syncMetaPath,
+  writeFileAtomic,
+} from "../sync-policy";
+
+const HOUR = 60 * 60 * 1000;
+const KEY = "sk-test-secret-key";
+
+let dir: string;
+let cachePath: string;
+
+beforeEach(() => {
+  vi.stubEnv(SYNC_TTL_ENV, "");
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-sync-policy-"));
+  cachePath = path.join(dir, "cache", "example-models.json");
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function writeCache(ageMs: number, models: unknown = [{ id: "m" }]): void {
+  fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+  fs.writeFileSync(cachePath, JSON.stringify(models));
+  const t = new Date(Date.now() - ageMs);
+  fs.utimesSync(cachePath, t, t);
+}
+
+function writeMeta(meta: Record<string, unknown>): void {
+  fs.writeFileSync(syncMetaPath(cachePath), JSON.stringify({ version: 1, ...meta }));
+}
+
+function writeLock(ageMs: number, token = "someone-else"): void {
+  fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+  fs.writeFileSync(syncLockPath(cachePath), JSON.stringify({ pid: 999999, token }));
+  const t = new Date(Date.now() - ageMs);
+  fs.utimesSync(syncLockPath(cachePath), t, t);
+}
+
+describe("keyFingerprint", () => {
+  it("is a stable 16-hex digest that never contains the key", () => {
+    const fp = keyFingerprint(KEY);
+    expect(fp).toMatch(/^[0-9a-f]{16}$/);
+    expect(keyFingerprint(KEY)).toBe(fp);
+    expect(keyFingerprint(`${KEY}x`)).not.toBe(fp);
+    expect(fp).not.toContain(KEY);
+  });
+});
+
+describe("resolveSyncTtlMs", () => {
+  it("defaults to 1 hour", () => {
+    expect(resolveSyncTtlMs()).toBe(DEFAULT_SYNC_TTL_MS);
+    expect(DEFAULT_SYNC_TTL_MS).toBe(HOUR);
+  });
+
+  it(`honors ${SYNC_TTL_ENV} (0 = always revalidate) and ignores garbage`, () => {
+    vi.stubEnv(SYNC_TTL_ENV, "0");
+    expect(resolveSyncTtlMs()).toBe(0);
+    vi.stubEnv(SYNC_TTL_ENV, "120000");
+    expect(resolveSyncTtlMs()).toBe(120000);
+    vi.stubEnv(SYNC_TTL_ENV, "-5");
+    expect(resolveSyncTtlMs()).toBe(DEFAULT_SYNC_TTL_MS);
+    vi.stubEnv(SYNC_TTL_ENV, "soon");
+    expect(resolveSyncTtlMs()).toBe(DEFAULT_SYNC_TTL_MS);
+  });
+
+  it("prefers an explicit ttlMs over the env", () => {
+    vi.stubEnv(SYNC_TTL_ENV, "0");
+    expect(resolveSyncTtlMs(5000)).toBe(5000);
+  });
+});
+
+describe("planModelSync", () => {
+  it("never fetches without a key", () => {
+    expect(planModelSync({ cachePath, apiKey: undefined })).toEqual({ fetch: false, reason: "no-key" });
+    expect(planModelSync({ cachePath, apiKey: "" })).toEqual({ fetch: false, reason: "no-key" });
+  });
+
+  it("fetches when the cache is missing or corrupt", () => {
+    expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: true, reason: "missing" });
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    fs.writeFileSync(cachePath, "{not json");
+    expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: true, reason: "missing" });
+    writeCache(0, []);
+    expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: true, reason: "missing" });
+  });
+
+  it("skips inside the TTL and fetches once it expires", () => {
+    writeCache(10 * 60 * 1000);
+    writeMeta({ keyFingerprint: keyFingerprint(KEY) });
+    expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: false, reason: "fresh" });
+    writeCache(2 * HOUR);
+    expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: true, reason: "stale" });
+    vi.stubEnv(SYNC_TTL_ENV, "0");
+    writeCache(0);
+    expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: true, reason: "stale" });
+  });
+
+  it("forces a fetch when the key changed or the cache predates the sidecar", () => {
+    writeCache(0);
+    expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: true, reason: "key-changed" });
+    writeMeta({ keyFingerprint: keyFingerprint("old-key") });
+    expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: true, reason: "key-changed" });
+  });
+
+  it("forces a fetch on demand (e.g. after /login) regardless of TTL", () => {
+    writeCache(0);
+    writeMeta({ keyFingerprint: keyFingerprint(KEY) });
+    expect(planModelSync({ cachePath, apiKey: KEY, force: true })).toEqual({ fetch: true, reason: "forced" });
+  });
+
+  it("backs off after a recent failure with the same key, unless forced", () => {
+    writeCache(2 * HOUR);
+    writeMeta({ keyFingerprint: keyFingerprint(KEY), failedAt: Date.now() - 1000, failedKeyFingerprint: keyFingerprint(KEY) });
+    expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: false, reason: "backoff" });
+    expect(planModelSync({ cachePath, apiKey: KEY, force: true }).fetch).toBe(true);
+    // A different key is not held back by another key's failure.
+    expect(planModelSync({ cachePath, apiKey: "new-key" })).toEqual({ fetch: true, reason: "key-changed" });
+    // Backoff expires.
+    writeMeta({ keyFingerprint: keyFingerprint(KEY), failedAt: Date.now() - HOUR, failedKeyFingerprint: keyFingerprint(KEY) });
+    expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: true, reason: "stale" });
+  });
+});
+
+describe("acquireModelSync", () => {
+  it("is single-flight: a second caller skips while the lock is held", () => {
+    const skipped: string[] = [];
+    const first = acquireModelSync({ cachePath, apiKey: KEY });
+    expect(first?.reason).toBe("missing");
+    expect(fs.existsSync(syncLockPath(cachePath))).toBe(true);
+    expect(acquireModelSync({ cachePath, apiKey: KEY, onSkip: (r) => skipped.push(r) })).toBeNull();
+    expect(skipped).toEqual(["locked"]);
+    first!.release("aborted");
+    expect(fs.existsSync(syncLockPath(cachePath))).toBe(false);
+    expect(acquireModelSync({ cachePath, apiKey: KEY })).not.toBeNull();
+  });
+
+  it("skips while another process holds a live lock", () => {
+    writeLock(1000);
+    const skipped: string[] = [];
+    expect(acquireModelSync({ cachePath, apiKey: KEY, onSkip: (r) => skipped.push(r) })).toBeNull();
+    expect(skipped).toEqual(["locked"]);
+  });
+
+  it("reclaims a stale lock left by a crashed process", () => {
+    writeLock(5 * 60 * 1000);
+    const lease = acquireModelSync({ cachePath, apiKey: KEY });
+    expect(lease).not.toBeNull();
+    lease!.release("aborted");
+    expect(fs.existsSync(syncLockPath(cachePath))).toBe(false);
+  });
+
+  it("never removes a lock it no longer owns", () => {
+    const lease = acquireModelSync({ cachePath, apiKey: KEY, lockStaleMs: 0 })!;
+    writeLock(0, "reclaimed-by-another-process");
+    lease.release("aborted");
+    expect(JSON.parse(fs.readFileSync(syncLockPath(cachePath), "utf8")).token).toBe("reclaimed-by-another-process");
+  });
+
+  it("records the key fingerprint on success (never the key) and the failure on error", () => {
+    let lease = acquireModelSync({ cachePath, apiKey: KEY })!;
+    writeCache(0);
+    lease.release("fetched");
+    const raw = fs.readFileSync(syncMetaPath(cachePath), "utf8");
+    expect(raw).not.toContain(KEY);
+    expect(JSON.parse(raw)).toMatchObject({ version: 1, keyFingerprint: keyFingerprint(KEY) });
+    expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: false, reason: "fresh" });
+
+    lease = acquireModelSync({ cachePath, apiKey: KEY, force: true })!;
+    lease.release("failed");
+    expect(JSON.parse(fs.readFileSync(syncMetaPath(cachePath), "utf8"))).toMatchObject({
+      keyFingerprint: keyFingerprint(KEY),
+      failedKeyFingerprint: keyFingerprint(KEY),
+    });
+  });
+
+  it("does not record a failure for an aborted fetch", () => {
+    acquireModelSync({ cachePath, apiKey: KEY })!.release("aborted");
+    expect(fs.existsSync(syncMetaPath(cachePath))).toBe(false);
+  });
+
+  it("fails open (null, no throw) when the cache dir is unwritable", () => {
+    // A regular file where the cache directory should be: mkdir/open fail even as root.
+    fs.writeFileSync(path.join(dir, "cache"), "not a directory");
+    const skipped: string[] = [];
+    expect(() => acquireModelSync({ cachePath, apiKey: KEY, onSkip: (r) => skipped.push(r) })).not.toThrow();
+    expect(acquireModelSync({ cachePath, apiKey: KEY })).toBeNull();
+    expect(skipped).toEqual(["unwritable"]);
+  });
+
+  // Real processes: children load sync-policy.ts via Node's built-in type stripping (Node >= 22.18).
+  it.skipIf(!(process.features as { typescript?: unknown }).typescript)("lets exactly one of many concurrent processes fetch", async () => {
+    writeCache(2 * HOUR);
+    writeMeta({ keyFingerprint: keyFingerprint(KEY) });
+    const modulePath = fileURLToPath(new URL("../sync-policy.ts", import.meta.url));
+    // Each child: try to acquire; the winner "fetches" for 300ms, writes the
+    // cache and releases. Late starters must then see a fresh cache.
+    const child = `
+      const { acquireModelSync, writeFileAtomic } = await import(${JSON.stringify(modulePath)});
+      const [cachePath, key] = process.argv.slice(-2);
+      const lease = acquireModelSync({ cachePath, apiKey: key });
+      if (lease) {
+        await new Promise((r) => setTimeout(r, 300));
+        writeFileAtomic(cachePath, JSON.stringify([{ id: "fresh" }]));
+        lease.release("fetched");
+      }
+      process.stdout.write(lease ? "fetch" : "skip");
+    `;
+    const run = () => new Promise<string>((resolve, reject) => {
+      execFile(process.execPath, ["--input-type=module", "-e", child, cachePath, KEY], (err, stdout) => err ? reject(err) : resolve(stdout));
+    });
+    const results = await Promise.all(Array.from({ length: 8 }, run));
+    expect(results.filter((r) => r === "fetch")).toHaveLength(1);
+    expect(results.filter((r) => r === "skip")).toHaveLength(7);
+    expect(fs.existsSync(syncLockPath(cachePath))).toBe(false);
+  }, 20000);
+});
+
+describe("cache helpers", () => {
+  it("writeFileAtomic replaces the file without leaving temp files", () => {
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    writeFileAtomic(cachePath, "[1]");
+    writeFileAtomic(cachePath, "[2]");
+    expect(fs.readFileSync(cachePath, "utf8")).toBe("[2]");
+    expect(fs.readdirSync(path.dirname(cachePath))).toEqual([path.basename(cachePath)]);
+  });
+
+  it("cacheChangedSinceLoad spots a cache rewritten by another process", () => {
+    writeCache(HOUR);
+    markCacheLoaded(cachePath);
+    expect(cacheChangedSinceLoad(cachePath)).toBe(false);
+    writeCache(0);
+    expect(cacheChangedSinceLoad(cachePath)).toBe(true);
+  });
+});

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["tests/**/*.test.ts"],
+    clearMocks: true,
+    restoreMocks: true,
+  },
+});