cursor-route 0.1.10 → 0.1.13

package/src/or-free.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  assertOpenRouterModel,
+  isOrFreeModel,
+  openRouterModel,
+  OPENROUTER_FALLBACK_MODEL,
+  orFreeBoost,
+  pickOrFreeModel,
+  rankOrFreeModels,
+  type OrModel,
+} from "./or-free.ts";
+import { openRouterAdapter } from "./adapters/openrouter.ts";
+
+const CATALOG: OrModel[] = [
+  { id: "acme/generic:free", name: "Generic Free", context_length: 8_000 },
+  { id: "qwen/qwen-coder:free", name: "Qwen Coder", context_length: 128_000 },
+  { id: "acme/whisper:free", name: "Whisper" },
+  {
+    id: "anthropic/claude-sonnet",
+    name: "Sonnet",
+    pricing: { prompt: 3, completion: 15 },
+  },
+  {
+    id: "acme/zero-price",
+    name: "Zero Price Text",
+    context_length: 4_000,
+    pricing: { prompt: "0", completion: "0" },
+  },
+  {
+    id: "acme/image-only",
+    name: "Image Only",
+    architecture: { modality: "image->image" },
+    pricing: { prompt: 0, completion: 0 },
+  },
+];
+
+describe("openrouter free catalog", () => {
+  test("tags :free or zero price as free; skips paid, whisper, image-only", () => {
+    expect(isOrFreeModel({ id: "qwen/qwen-coder:free" })).toBe(true);
+    expect(
+      isOrFreeModel({
+        id: "acme/zero-price",
+        pricing: { prompt: 0, completion: 0 },
+      }),
+    ).toBe(true);
+    expect(
+      isOrFreeModel({
+        id: "anthropic/claude-sonnet",
+        pricing: { prompt: 3, completion: 15 },
+      }),
+    ).toBe(false);
+    expect(isOrFreeModel({ id: "acme/whisper:free" })).toBe(false);
+    expect(
+      isOrFreeModel({
+        id: "acme/image-only",
+        architecture: { modality: "image->image" },
+        pricing: { prompt: 0, completion: 0 },
+      }),
+    ).toBe(false);
+  });
+
+  test("boost: coder/qwen outranks generic free; no hardcoded winner id", () => {
+    expect(orFreeBoost("qwen/qwen-coder:free")).toBe(20);
+    expect(orFreeBoost("acme/generic:free")).toBe(10);
+    expect(orFreeBoost("meta-llama/llama-3.3-70b-instruct:free")).toBe(20);
+  });
+
+  test("rank prefers a :free coder with larger context over a generic :free", () => {
+    const ranked = rankOrFreeModels(CATALOG);
+    expect(ranked[0]?.id).toBe("qwen/qwen-coder:free");
+    expect(ranked.map((r) => r.id)).not.toContain("acme/whisper:free");
+    expect(ranked.map((r) => r.id)).not.toContain("anthropic/claude-sonnet");
+    expect(ranked.map((r) => r.id)).not.toContain("acme/image-only");
+  });
+
+  test("same boost: larger context_length wins, then id ascending", () => {
+    const ranked = rankOrFreeModels([
+      { id: "qwen/small-coder:free", context_length: 8_000 },
+      { id: "qwen/big-coder:free", context_length: 128_000 },
+    ]);
+    expect(ranked[0]?.id).toBe("qwen/big-coder:free");
+    expect(ranked[1]?.id).toBe("qwen/small-coder:free");
+  });
+
+  test("pickOrFreeModel uses the ranked catalog winner", () => {
+    expect(pickOrFreeModel({ catalog: CATALOG })).toBe("qwen/qwen-coder:free");
+  });
+
+  test("offline / empty catalog falls back to the OpenRouter router", () => {
+    expect(pickOrFreeModel({ catalog: [] })).toBe(OPENROUTER_FALLBACK_MODEL);
+    expect(OPENROUTER_FALLBACK_MODEL).toBe("openrouter/free");
+  });
+
+  test("assertOpenRouterModel accepts provider/model and :free", () => {
+    expect(assertOpenRouterModel("qwen/qwen-coder:free")).toBe("qwen/qwen-coder:free");
+    expect(assertOpenRouterModel("openrouter/free")).toBe("openrouter/free");
+    expect(() => assertOpenRouterModel("not-a-model")).toThrow(/provider\/model/);
+  });
+});
+
+describe("openRouterModel live pick", () => {
+  const isolate = (fn: () => void) => {
+    const dir = join(tmpdir(), `cr-or-${process.pid}-${Math.random().toString(16).slice(2)}`);
+    mkdirSync(dir, { recursive: true });
+    const prev = {
+      model: process.env.CURSOR_ROUTE_OPENROUTER_MODEL,
+      offline: process.env.CURSOR_ROUTE_OR_OFFLINE,
+      json: process.env.CURSOR_ROUTE_OR_CATALOG_JSON,
+      cache: process.env.CURSOR_ROUTE_OR_CACHE_PATH,
+      refresh: process.env.CURSOR_ROUTE_OR_REFRESH,
+    };
+    delete process.env.CURSOR_ROUTE_OPENROUTER_MODEL;
+    process.env.CURSOR_ROUTE_OR_CACHE_PATH = join(dir, "cache.json");
+    process.env.CURSOR_ROUTE_OR_REFRESH = "1";
+    try {
+      fn();
+    } finally {
+      for (const [k, v] of Object.entries(prev)) {
+        const envKey = {
+          model: "CURSOR_ROUTE_OPENROUTER_MODEL",
+          offline: "CURSOR_ROUTE_OR_OFFLINE",
+          json: "CURSOR_ROUTE_OR_CATALOG_JSON",
+          cache: "CURSOR_ROUTE_OR_CACHE_PATH",
+          refresh: "CURSOR_ROUTE_OR_REFRESH",
+        }[k]!;
+        if (v === undefined) delete process.env[envKey];
+        else process.env[envKey] = v;
+      }
+      rmSync(dir, { recursive: true, force: true });
+    }
+  };
+
+  test("free/empty + offline → openrouter/free fallback", () => {
+    isolate(() => {
+      process.env.CURSOR_ROUTE_OR_OFFLINE = "1";
+      expect(openRouterModel()).toBe("openrouter/free");
+      expect(openRouterModel("free")).toBe("openrouter/free");
+    });
+  });
+
+  test("free + injected catalog → ranked coder", () => {
+    isolate(() => {
+      process.env.CURSOR_ROUTE_OR_CATALOG_JSON = JSON.stringify({ data: CATALOG });
+      expect(openRouterModel("free")).toBe("qwen/qwen-coder:free");
+    });
+  });
+
+  test("CURSOR_ROUTE_OPENROUTER_MODEL pin wins over catalog", () => {
+    isolate(() => {
+      process.env.CURSOR_ROUTE_OPENROUTER_MODEL = "acme/pinned:free";
+      process.env.CURSOR_ROUTE_OR_CATALOG_JSON = JSON.stringify({ data: CATALOG });
+      expect(openRouterModel()).toBe("acme/pinned:free");
+      expect(openRouterModel("free")).toBe("acme/pinned:free");
+    });
+  });
+
+  test("explicit provider/model pin is used as-is", () => {
+    isolate(() => {
+      process.env.CURSOR_ROUTE_OR_CATALOG_JSON = JSON.stringify({ data: CATALOG });
+      expect(openRouterModel("meta-llama/llama-3.3-70b-instruct:free")).toBe(
+        "meta-llama/llama-3.3-70b-instruct:free",
+      );
+    });
+  });
+
+  test("offline fallback is not written to cache", () => {
+    isolate(() => {
+      delete process.env.CURSOR_ROUTE_OR_REFRESH;
+      process.env.CURSOR_ROUTE_OR_OFFLINE = "1";
+      const cache = process.env.CURSOR_ROUTE_OR_CACHE_PATH!;
+      expect(openRouterModel()).toBe("openrouter/free");
+      expect(existsSync(cache)).toBe(false);
+    });
+  });
+});
+
+describe("openrouter health stays offline", () => {
+  test("health with key + offline does not throw; mentions live pick, not a locked third-party default", () => {
+    const dir = join(tmpdir(), `cr-or-health-${process.pid}`);
+    mkdirSync(dir, { recursive: true });
+    const prev = {
+      key: process.env.OPENROUTER_API_KEY,
+      model: process.env.CURSOR_ROUTE_OPENROUTER_MODEL,
+      offline: process.env.CURSOR_ROUTE_OR_OFFLINE,
+      json: process.env.CURSOR_ROUTE_OR_CATALOG_JSON,
+      cache: process.env.CURSOR_ROUTE_OR_CACHE_PATH,
+      refresh: process.env.CURSOR_ROUTE_OR_REFRESH,
+    };
+    process.env.OPENROUTER_API_KEY = "sk-or-v1-local-test-value-000000000000";
+    delete process.env.CURSOR_ROUTE_OPENROUTER_MODEL;
+    process.env.CURSOR_ROUTE_OR_OFFLINE = "1";
+    delete process.env.CURSOR_ROUTE_OR_CATALOG_JSON;
+    process.env.CURSOR_ROUTE_OR_CACHE_PATH = join(dir, "missing-cache.json");
+    delete process.env.CURSOR_ROUTE_OR_REFRESH;
+    try {
+      const h = openRouterAdapter.health();
+      expect(h.ok).toBe(true);
+      expect(h.detail.toLowerCase()).toMatch(/live pick/);
+      expect(h.detail).toMatch(/fallback/);
+      expect(h.detail).not.toMatch(/now openrouter\/free/);
+      expect(h.detail).not.toMatch(/qwen\//);
+      expect(h.detail).not.toMatch(/defaults to openrouter\/free/);
+    } finally {
+      if (prev.key === undefined) delete process.env.OPENROUTER_API_KEY;
+      else process.env.OPENROUTER_API_KEY = prev.key;
+      if (prev.model === undefined) delete process.env.CURSOR_ROUTE_OPENROUTER_MODEL;
+      else process.env.CURSOR_ROUTE_OPENROUTER_MODEL = prev.model;
+      if (prev.offline === undefined) delete process.env.CURSOR_ROUTE_OR_OFFLINE;
+      else process.env.CURSOR_ROUTE_OR_OFFLINE = prev.offline;
+      if (prev.json === undefined) delete process.env.CURSOR_ROUTE_OR_CATALOG_JSON;
+      else process.env.CURSOR_ROUTE_OR_CATALOG_JSON = prev.json;
+      if (prev.cache === undefined) delete process.env.CURSOR_ROUTE_OR_CACHE_PATH;
+      else process.env.CURSOR_ROUTE_OR_CACHE_PATH = prev.cache;
+      if (prev.refresh === undefined) delete process.env.CURSOR_ROUTE_OR_REFRESH;
+      else process.env.CURSOR_ROUTE_OR_REFRESH = prev.refresh;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/or-free.ts

@@ -0,0 +1,243 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Live OpenRouter free-model pick — same shape as zen-free.ts.
+ * Probe GET {OPENROUTER_BASE_URL}/models, keep $0 text models, rank, cache
+ * ~15 min. Do not hardcode a third-party model id as the happy-path default.
+ * `openrouter/free` is the OpenRouter **router** fallback only.
+ */
+
+export const OPENROUTER_MODELS_URL_DEFAULT = "https://openrouter.ai/api/v1/models";
+
+/** Fetch-fail / empty-rank fallback — OpenRouter live router, not a locked model. */
+export const OPENROUTER_FALLBACK_MODEL = "openrouter/free";
+
+export interface OrModel {
+  id?: string;
+  name?: string;
+  context_length?: number;
+  pricing?: { prompt?: number | string; completion?: number | string };
+  architecture?: { modality?: string };
+}
+
+export interface OrFreePick {
+  id: string;
+  name: string;
+  context_length: number;
+  boost: number;
+  picked_at: string;
+  candidates: number;
+  source: "ranked-free" | "fallback";
+}
+
+const EXCLUDE_RE =
+  /lyria|whisper|tts|embed|embedding|image|vision-only|audio|diffusion|flux|stable-diffusion|moderation/i;
+const BOOST_RE =
+  /coder|instruct|chat|nemotron|qwen|llama|gemma|gpt-oss|kimi|glm|deepseek/i;
+
+function orModelsUrl(): string {
+  const base = (process.env.OPENROUTER_BASE_URL || "https://openrouter.ai/api/v1")
+    .trim()
+    .replace(/\/+$/, "");
+  return `${base}/models`;
+}
+
+function cacheMinutes(): number {
+  const n = Number(process.env.CURSOR_ROUTE_OR_CACHE_MINUTES);
+  return Number.isFinite(n) && n > 0 ? n : 15;
+}
+
+function cachePath(): string {
+  return process.env.CURSOR_ROUTE_OR_CACHE_PATH?.trim() ||
+    join(tmpdir(), "cursor-route-or-best-free.json");
+}
+
+export function assertOpenRouterModel(id: string): string {
+  if (!/^[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._\-:]+)+$/i.test(id)) {
+    throw new Error(
+      `Invalid OpenRouter model ${id}; expected provider/model (e.g. qwen/qwen3-coder:free) or free`,
+    );
+  }
+  return id;
+}
+
+function num(v: unknown): number {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string" && v.trim()) {
+    const n = Number(v);
+    if (Number.isFinite(n)) return n;
+  }
+  return NaN;
+}
+
+export function isOrFreeModel(m: OrModel): boolean {
+  const id = (m.id || "").trim();
+  if (!id) return false;
+  if (EXCLUDE_RE.test(id) || EXCLUDE_RE.test(m.name || "")) return false;
+  const modality = m.architecture?.modality;
+  if (typeof modality === "string" && modality.trim() && !/text/i.test(modality)) {
+    return false;
+  }
+  const prompt = num(m.pricing?.prompt);
+  const completion = num(m.pricing?.completion);
+  const pricedFree = prompt === 0 && completion === 0;
+  const tagged = id.endsWith(":free");
+  return tagged || pricedFree;
+}
+
+/** Higher boost wins. Coding/chat families beat generic free. No hardcoded id. */
+export function orFreeBoost(id: string): number {
+  return BOOST_RE.test(id) ? 20 : 10;
+}
+
+export function rankOrFreeModels(models: OrModel[]): Array<{
+  id: string;
+  name: string;
+  context_length: number;
+  boost: number;
+}> {
+  const out: Array<{ id: string; name: string; context_length: number; boost: number }> = [];
+  for (const m of models) {
+    if (!isOrFreeModel(m)) continue;
+    const raw = (m.id || "").trim();
+    let id: string;
+    try {
+      id = assertOpenRouterModel(raw);
+    } catch {
+      continue;
+    }
+    const ctx = Number.isFinite(Number(m.context_length)) ? Number(m.context_length) : 0;
+    out.push({
+      id,
+      name: (m.name || raw).trim(),
+      context_length: ctx,
+      boost: orFreeBoost(id),
+    });
+  }
+  out.sort((a, b) => {
+    if (b.boost !== a.boost) return b.boost - a.boost;
+    if (b.context_length !== a.context_length) return b.context_length - a.context_length;
+    return a.id.localeCompare(b.id);
+  });
+  return out;
+}
+
+function readCache(): OrFreePick | null {
+  const p = cachePath();
+  if (!existsSync(p)) return null;
+  try {
+    const j = JSON.parse(readFileSync(p, "utf8")) as OrFreePick;
+    if (!j?.id) return null;
+    const ageMs = Date.now() - Date.parse(j.picked_at);
+    if (!Number.isFinite(ageMs) || ageMs < 0) return null;
+    if (ageMs > cacheMinutes() * 60_000) return null;
+    assertOpenRouterModel(j.id);
+    return j;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(pick: OrFreePick): void {
+  try {
+    writeFileSync(cachePath(), JSON.stringify(pick), { mode: 0o600 });
+  } catch {
+    /* cache is optional */
+  }
+}
+
+function httpGetSync(url: string, timeoutMs = 4000): string | null {
+  const sec = Math.max(1, Math.ceil(timeoutMs / 1000));
+  // Public GET /models — no Authorization header (key would land in `ps` argv).
+  const curl = spawnSync(
+    "curl",
+    ["-fsS", "--max-time", String(sec), "-H", "Accept: application/json", url],
+    {
+      encoding: "utf8",
+      timeout: timeoutMs + 500,
+      env: { ...process.env },
+    },
+  );
+  if (curl.status === 0 && curl.stdout?.trim()) return curl.stdout;
+  return null;
+}
+
+function parseCatalog(raw: string): OrModel[] {
+  const j = JSON.parse(raw) as { data?: OrModel[] } | OrModel[];
+  if (Array.isArray(j)) return j;
+  if (Array.isArray(j.data)) return j.data;
+  return [];
+}
+
+export function loadOrCatalog(): OrModel[] {
+  const inline = process.env.CURSOR_ROUTE_OR_CATALOG_JSON?.trim();
+  if (inline) return parseCatalog(inline);
+  if (process.env.CURSOR_ROUTE_OR_OFFLINE === "1") return [];
+  const body = httpGetSync(orModelsUrl());
+  if (!body) return [];
+  try {
+    return parseCatalog(body);
+  } catch {
+    return [];
+  }
+}
+
+/** Last live pick if the cache is still fresh — health-safe (no network). */
+export function cachedOrFreePick(): string | null {
+  try {
+    return readCache()?.id ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Best live OpenRouter free text model, or OPENROUTER_FALLBACK_MODEL if the
+ * catalog is empty/offline. `CURSOR_ROUTE_OR_REFRESH=1` skips cache.
+ * Tests: `CURSOR_ROUTE_OR_OFFLINE=1` or `CURSOR_ROUTE_OR_CATALOG_JSON`.
+ */
+export function pickOrFreeModel(opts?: { catalog?: OrModel[]; refresh?: boolean }): string {
+  const refresh =
+    opts?.refresh ||
+    process.env.CURSOR_ROUTE_OR_REFRESH === "1";
+  if (!refresh && opts?.catalog === undefined) {
+    const cached = readCache();
+    if (cached) return cached.id;
+  }
+  const models = opts?.catalog ?? loadOrCatalog();
+  const ranked = rankOrFreeModels(models);
+  const winner = ranked[0];
+  if (!winner) {
+    // Do not cache fallback — a 15-min stale fallback would masquerade as a
+    // live pick in health (`now openrouter/free`). Retry the catalog next call.
+    return OPENROUTER_FALLBACK_MODEL;
+  }
+  const pick: OrFreePick = {
+    id: winner.id,
+    name: winner.name,
+    context_length: winner.context_length,
+    boost: winner.boost,
+    picked_at: new Date().toISOString(),
+    candidates: ranked.length,
+    source: "ranked-free",
+  };
+  if (opts?.catalog === undefined) writeCache(pick);
+  return pick.id;
+}
+
+/**
+ * Resolve OpenRouter `--model` / env to a concrete `provider/model` id.
+ * Empty or `free` → CURSOR_ROUTE_OPENROUTER_MODEL pin, else live catalog pick.
+ */
+export function openRouterModel(raw?: string | null): string {
+  const v = (raw ?? "").trim();
+  if (!v || v.toLowerCase() === "free") {
+    const env = (process.env.CURSOR_ROUTE_OPENROUTER_MODEL ?? "").trim();
+    if (env && env.toLowerCase() !== "free") return assertOpenRouterModel(env);
+    return pickOrFreeModel();
+  }
+  return assertOpenRouterModel(v);
+}

package/src/zen-free.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  asOpenCodeZenId,
+  isZenFreeModel,
+  openCodeModel,
+  OPENCODE_DEFAULT_MODEL,
+  pickZenFreeModel,
+  rankZenFreeModels,
+  zenFreeBoost,
+  type ZenModel,
+} from "./zen-free.ts";
+
+const CATALOG: ZenModel[] = [
+  { id: "big-pickle", name: "Big Pickle" },
+  { id: "hy3-free", name: "HY3 Free" },
+  { id: "claude-opus-4-6", name: "Claude Opus 4.6" },
+  { id: "muse-spark-1.2-contributor-free", name: "Muse Spark Contributor" },
+  { id: "laguna-s-2.1-free", name: "Laguna" },
+  { id: "x-preview-f-free", name: "Ox Alpha Free" },
+  { id: "whisper-free", name: "Whisper" },
+];
+
+describe("zen free catalog", () => {
+  test("tags -free / big-pickle as free; skips paid and audio", () => {
+    expect(isZenFreeModel({ id: "x-preview-f-free" })).toBe(true);
+    expect(isZenFreeModel({ id: "big-pickle" })).toBe(true);
+    expect(isZenFreeModel({ id: "openrouter/qwen/qwen3-coder:free" })).toBe(true);
+    expect(isZenFreeModel({ id: "claude-opus-4-6" })).toBe(false);
+    expect(isZenFreeModel({ id: "whisper-free" })).toBe(false);
+    expect(
+      isZenFreeModel({
+        id: "some-zero-price",
+        pricing: { prompt: 0, completion: 0 },
+      }),
+    ).toBe(true);
+  });
+
+  test("Ox Alpha outranks coding free, which outranks big-pickle and contributor", () => {
+    expect(zenFreeBoost("opencode/x-preview-f-free")).toBe(40);
+    expect(zenFreeBoost("opencode/laguna-s-2.1-free")).toBe(20);
+    expect(zenFreeBoost("opencode/hy3-free")).toBe(20);
+    expect(zenFreeBoost("opencode/big-pickle")).toBe(5);
+    expect(zenFreeBoost("opencode/muse-spark-1.2-contributor-free")).toBe(1);
+  });
+
+  test("rank: Ox Alpha first while listed; paid/whisper dropped", () => {
+    const ranked = rankZenFreeModels(CATALOG);
+    expect(ranked[0]?.id).toBe("opencode/x-preview-f-free");
+    expect(ranked.map((r) => r.id)).not.toContain("opencode/claude-opus-4-6");
+    expect(ranked.map((r) => r.id)).not.toContain("opencode/whisper-free");
+    expect(ranked.at(-1)?.id).toBe("opencode/muse-spark-1.2-contributor-free");
+  });
+
+  test("rank without Ox: coding free beats big-pickle", () => {
+    const ranked = rankZenFreeModels([
+      { id: "big-pickle" },
+      { id: "laguna-s-2.1-free" },
+      { id: "muse-spark-1.2-contributor-free" },
+    ]);
+    expect(ranked[0]?.id).toBe("opencode/laguna-s-2.1-free");
+    expect(ranked[1]?.id).toBe("opencode/big-pickle");
+  });
+
+  test("asOpenCodeZenId prefixes bare Zen ids", () => {
+    expect(asOpenCodeZenId("x-preview-f-free")).toBe("opencode/x-preview-f-free");
+    expect(asOpenCodeZenId("opencode/big-pickle")).toBe("opencode/big-pickle");
+  });
+
+  test("pickZenFreeModel uses the ranked catalog winner", () => {
+    expect(pickZenFreeModel({ catalog: CATALOG })).toBe("opencode/x-preview-f-free");
+  });
+
+  test("offline / empty catalog falls back to Ox Alpha", () => {
+    expect(pickZenFreeModel({ catalog: [] })).toBe(OPENCODE_DEFAULT_MODEL);
+    expect(OPENCODE_DEFAULT_MODEL).toBe("opencode/x-preview-f-free");
+  });
+});
+
+describe("openCodeModel live pick", () => {
+  const isolate = (fn: () => void) => {
+    const dir = join(tmpdir(), `cr-zen-${process.pid}-${Math.random().toString(16).slice(2)}`);
+    mkdirSync(dir, { recursive: true });
+    const prev = {
+      model: process.env.CURSOR_ROUTE_OPENCODE_MODEL,
+      offline: process.env.CURSOR_ROUTE_ZEN_OFFLINE,
+      json: process.env.CURSOR_ROUTE_ZEN_CATALOG_JSON,
+      cache: process.env.CURSOR_ROUTE_ZEN_CACHE_PATH,
+      refresh: process.env.CURSOR_ROUTE_ZEN_REFRESH,
+    };
+    delete process.env.CURSOR_ROUTE_OPENCODE_MODEL;
+    process.env.CURSOR_ROUTE_ZEN_CACHE_PATH = join(dir, "cache.json");
+    process.env.CURSOR_ROUTE_ZEN_REFRESH = "1";
+    try {
+      fn();
+    } finally {
+      for (const [k, v] of Object.entries(prev)) {
+        const envKey = {
+          model: "CURSOR_ROUTE_OPENCODE_MODEL",
+          offline: "CURSOR_ROUTE_ZEN_OFFLINE",
+          json: "CURSOR_ROUTE_ZEN_CATALOG_JSON",
+          cache: "CURSOR_ROUTE_ZEN_CACHE_PATH",
+          refresh: "CURSOR_ROUTE_ZEN_REFRESH",
+        }[k]!;
+        if (v === undefined) delete process.env[envKey];
+        else process.env[envKey] = v;
+      }
+      rmSync(dir, { recursive: true, force: true });
+    }
+  };
+
+  test("free/empty + offline → Ox Alpha fallback", () => {
+    isolate(() => {
+      process.env.CURSOR_ROUTE_ZEN_OFFLINE = "1";
+      expect(openCodeModel()).toBe("opencode/x-preview-f-free");
+      expect(openCodeModel("free")).toBe("opencode/x-preview-f-free");
+    });
+  });
+
+  test("free + injected catalog → Ox Alpha", () => {
+    isolate(() => {
+      process.env.CURSOR_ROUTE_ZEN_CATALOG_JSON = JSON.stringify({ data: CATALOG });
+      expect(openCodeModel("free")).toBe("opencode/x-preview-f-free");
+    });
+  });
+
+  test("CURSOR_ROUTE_OPENCODE_MODEL pin wins over catalog", () => {
+    isolate(() => {
+      process.env.CURSOR_ROUTE_OPENCODE_MODEL = "opencode/hy3-free";
+      process.env.CURSOR_ROUTE_ZEN_CATALOG_JSON = JSON.stringify({ data: CATALOG });
+      expect(openCodeModel()).toBe("opencode/hy3-free");
+      expect(openCodeModel("free")).toBe("opencode/hy3-free");
+    });
+  });
+});