cursor-route 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 _(none)_
 
+## 0.1.11 — 2026-08-21
+
+- `--worker opencode --model free` now **ranks the live OpenCode Zen catalog** (`GET https://opencode.ai/zen/v1/models`, cached ~15 min) instead of hardcoding `opencode/big-pickle`. Ox Alpha (`opencode/x-preview-f-free`) wins while it is listed and free; coding `-free` models next; `big-pickle` last among non-contributor free. Fetch-fail fallback is Ox Alpha.
+- Pin with `--model provider/model` or `CURSOR_ROUTE_OPENCODE_MODEL`. Tests/CI: `CURSOR_ROUTE_ZEN_OFFLINE=1` or `CURSOR_ROUTE_ZEN_CATALOG_JSON` (health never fetches — cache or fallback only).
+- Mid stays `claude-ds`; easy stays OpenRouter chat. OpenCode is still opt-in, not a lane default.
+
 ## 0.1.10 — 2026-08-21
 
 - Opt-in `--worker opencode`: OpenCode `run` as a coding agent that defaults to Zen free model `opencode/big-pickle` (alias `--model free`). Not a lane default — mid stays `claude-ds`, easy stays OpenRouter chat.

package/README.md

@@ -29,7 +29,7 @@ If you already live in Cursor, X Premium (Grok CLI), and DeepSeek — stop payin
 | Grok CLI | X Premium | `--lane hard` implement |
 | DeepSeek via claude-ds | DeepSeek API / plan | `--lane mid` implement (**Flash** default; `--model pro` when needed) |
 | OpenRouter free models | OpenRouter API (free tier) | `--lane easy` wording/drafts — non-secret prompts only (see Security) |
-| OpenCode (opt-in) | OpenCode Zen free models | `--worker opencode` implement on free Zen (default `opencode/big-pickle`) |
+| OpenCode (opt-in) | OpenCode Zen free models | `--worker opencode` implement on live Zen free pick (Ox Alpha while listed) |
 | Codex / extra Claude | Optional | Not required for v0 |
 
 Exact dollars vary — the point is **reuse subscriptions you already have**.
@@ -227,18 +227,20 @@ key-shaped material in `start` / `send`, and the runner re-checks the prompt fil
 ## OpenCode setup (opt-in free coding worker)
 
 `--worker opencode` runs [OpenCode](https://opencode.ai) as a **coding agent** on
-OpenCode Zen free models (default `opencode/big-pickle`). This is **not** a lane
-default — mid stays `claude-ds`; easy stays OpenRouter chat (no tools). Use it
-to burn fewer Grok / DeepSeek tokens on implement work.
+live OpenCode Zen free models (`--model free` fetches the catalog and ranks,
+same idea as the OpenRouter free picker). Ox Alpha (`opencode/x-preview-f-free`)
+wins while it is listed and free. This is **not** a lane default — mid stays
+`claude-ds`; easy stays OpenRouter chat (no tools). Use it to burn fewer Grok /
+DeepSeek tokens on implement work.
 
 ```bash
 npm i -g opencode-ai          # or: brew install opencode
 opencode auth login           # connect OpenCode Zen (or another provider)
-# optional:
-export CURSOR_ROUTE_OPENCODE_MODEL=opencode/big-pickle   # default; alias --model free
+# optional pin (skips the live catalog pick):
+export CURSOR_ROUTE_OPENCODE_MODEL=opencode/hy3-free
 
 cursor-route health                              # worker:opencode should be ✓
-cursor-route start --worker opencode "…"         # Big Pickle (free)
+cursor-route start --worker opencode "…"         # live Zen free pick
 cursor-route start --worker opencode --model free "…"
 cursor-route start --worker opencode --model opencode/hy3-free "…"
 ```
@@ -247,7 +249,8 @@ The adapter launches `opencode run --dir <cwd> --model <id>` with the prompt via
 `cat` (never interpolated). Always-approve maps to `--auto` (explicit `"deny"`
 rules still apply); `--ask` omits `--auto`. It never rewrites
 `~/.config/opencode/opencode.json`, so parallel jobs don't race. Override the
-binary with `CURSOR_ROUTE_OPENCODE_BIN`.
+binary with `CURSOR_ROUTE_OPENCODE_BIN`. `--model free` caches the ranked catalog
+for ~15 minutes (`CURSOR_ROUTE_ZEN_CACHE_MINUTES`).
 
 **Non-secret prompts:** several Zen free models may log or train on prompts during
 their free period (see [OpenCode Zen](https://opencode.ai/docs/zen/) privacy notes).
@@ -280,7 +283,7 @@ No. The mid worker is DeepSeek. Claude Code is the harness, configured with `ANT
 Run `npm i -g cursor-route`, install tmux if needed, then run `cursor-route health`. The package is available at https://www.npmjs.com/package/cursor-route, and the source is at https://github.com/cemini23/cursor-route.
 
 **Is it free?**  
-The cursor-route code is open source under MIT. It does not make the worker services free. Your costs depend on Cursor, DeepSeek API usage, and the Grok access or balance available to you. The easy lane can be free on OpenRouter's free-model route (`openrouter/free`). `--worker opencode` can run OpenCode Zen free models (default `opencode/big-pickle`).
+The cursor-route code is open source under MIT. It does not make the worker services free. Your costs depend on Cursor, DeepSeek API usage, and the Grok access or balance available to you. The easy lane can be free on OpenRouter's free-model route (`openrouter/free`). `--worker opencode` can run live OpenCode Zen free models (`--model free` ranks the catalog).
 
 ## Related
 

package/SECURITY.md

@@ -15,7 +15,7 @@ Do **not** open a public issue for credential leaks or RCE-class bugs.
 
 1. **No secrets in prompts or job files.** Do not paste API keys, SSH private keys, Discord tokens, or `.env` contents into `cursor-route start` / `send` prompts.
 2. **Free OpenRouter easy-lane models may log prompts.** `--lane easy` / `--worker openrouter` is for **non-secret** wording/drafts only. The refuse gate (`start` / `send`, plus the runner's re-check) applies to every lane — never send key-shaped material to the easy lane.
-3. **OpenCode Zen free models may log or train during their free period.** `--worker opencode` defaults to `opencode/big-pickle`. Treat it like the easy lane for secrets. Prefer `opencode/x-preview-f-free` (Ox Alpha) when you need the zero-retention free option.
+3. **OpenCode Zen free models may log or train during their free period.** `--worker opencode --model free` picks from the live Zen catalog (Ox Alpha / `x-preview-f-free` currently ranks first and is zero-retention). Treat other free Zen models like the easy lane for secrets. Pin `CURSOR_ROUTE_OPENCODE_MODEL` when you need a specific id.
 4. **Always-approve is powerful.** Default headless workers skip interactive permission prompts (`--always-approve` / `--dangerously-skip-permissions` / OpenCode `--auto`). Opt out with `--ask` / `CURSOR_ROUTE_ASK=1` when you need HITL.
 5. **Install from known channels only.** Prefer `npm i -g cursor-route` or a git clone of this repo. Do not pipe unknown `curl | bash` installers as the primary path.
 6. **Workers inherit your auth.** Grok CLI, Claude Code / claude-ds, and OpenCode use *your* local login. Treat worker panes like you would treat your own shell.

package/dist/adapters/opencode.js

@@ -1,12 +1,12 @@
 import { execSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { shellQuote } from "../util.js";
-import { openCodeModel, OPENCODE_DEFAULT_MODEL } from "../config.js";
+import { openCodeModel, OPENCODE_DEFAULT_MODEL, cachedZenFreePick } from "../config.js";
 /**
- * Opt-in OpenCode worker (`opencode run`) — a coding agent that can use
- * OpenCode Zen free models (default `opencode/big-pickle`) to cut Grok /
- * DeepSeek usage. Not a lane default: mid stays claude-ds; easy stays
- * OpenRouter chat (no tools).
+ * Opt-in OpenCode worker (`opencode run`) — a coding agent on live OpenCode
+ * Zen free models (`--model free` ranks the catalog; Ox Alpha wins while
+ * listed). Not a lane default: mid stays claude-ds; easy stays OpenRouter
+ * chat (no tools).
  *
  * We never rewrite ~/.config/opencode/opencode.json (parallel jobs would
  * race). Always-approve maps to `opencode run --auto` (still honors explicit
@@ -42,18 +42,13 @@ export const opencodeAdapter = {
                 detail: "opencode not found — install: npm i -g opencode-ai (or brew install opencode). Then: opencode auth login. Mid default remains claude-ds.",
             };
         }
-        let defaultModel = OPENCODE_DEFAULT_MODEL;
-        try {
-            defaultModel = openCodeModel();
-        }
-        catch {
-            /* invalid env — health still ok; startJob will fail loud */
-        }
+        // Health stays offline: show a fresh cache hit, else the Ox Alpha fallback.
+        const pick = cachedZenFreePick() || OPENCODE_DEFAULT_MODEL;
         return {
             worker: "opencode",
             ok: true,
             binary,
-            detail: `ok (opencode run; default model ${defaultModel}; auth at first start — opencode auth login if jobs fail; mid default remains claude-ds)`,
+            detail: `ok (opencode run; --model free = live Zen pick, now ${pick}; auth at first start — opencode auth login if jobs fail; mid default remains claude-ds)`,
         };
     },
     buildLaunch({ promptFile, cwd, alwaysApprove, modelId }) {

package/dist/cli.js

@@ -31,7 +31,7 @@ Usage:
 Start options:
   --worker <grok|claude-ds|openrouter|deepseek|opencode>  Worker adapter (default: grok; deepseek/opencode = opt-in)
   --lane <easy|mid|hard>                Lane → worker (easy=openrouter, mid=claude-ds, hard=grok)
-  --model <flash|pro|free|provider/model>  claude-ds/deepseek: flash|pro. opencode: free (default opencode/big-pickle) or provider/model
+  --model <flash|pro|free|provider/model>  claude-ds/deepseek: flash|pro. opencode: free (live Zen catalog pick) or provider/model
   --dir <path>                          Working directory (default: cwd)
   --ask                                 Disable always-approve for this job
   --dry-run                             Print launch command; do not start
@@ -53,7 +53,7 @@ Env:
   OPENROUTER_API_KEY                 OpenRouter key (required for --worker openrouter / --lane easy)
   CURSOR_ROUTE_OPENROUTER_MODEL      OpenRouter model (default: openrouter/free)
   OPENROUTER_BASE_URL                OpenRouter API base (default: https://openrouter.ai/api/v1)
-  CURSOR_ROUTE_OPENCODE_MODEL        OpenCode model (default: opencode/big-pickle); --model overrides
+  CURSOR_ROUTE_OPENCODE_MODEL        OpenCode model pin (unset or free = live Zen free pick); --model overrides
 `);
     process.exit(exitCode);
 }
@@ -156,7 +156,7 @@ function asOpenCodeModel(v) {
     if (v === undefined || v === true)
         return undefined;
     if (typeof v !== "string") {
-        throw new Error(`Invalid --model; expected provider/model (e.g. opencode/big-pickle) or free`);
+        throw new Error(`Invalid --model; expected provider/model (e.g. opencode/x-preview-f-free) or free`);
     }
     return openCodeModel(v);
 }

package/dist/config.js

@@ -49,33 +49,7 @@ export function openRouterModel() {
 export function openRouterBaseUrl() {
     return process.env.OPENROUTER_BASE_URL || "https://openrouter.ai/api/v1";
 }
-/**
- * Default OpenCode model: OpenCode Zen Big Pickle (free, limited-time).
- * Override: CURSOR_ROUTE_OPENCODE_MODEL or `--model provider/model`.
- * Alias `free` resolves to this default (or the env override).
- */
-export const OPENCODE_DEFAULT_MODEL = "opencode/big-pickle";
-/** Whitelist OpenCode `provider/model` ids (no spaces / injection). */
-export function assertOpenCodeModel(id) {
-    if (!/^[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._\-:]+)+$/i.test(id)) {
-        throw new Error(`Invalid OpenCode model ${id}; expected provider/model (e.g. opencode/big-pickle) or free`);
-    }
-    return id;
-}
-/**
- * Resolve OpenCode `--model` / env to a concrete `provider/model` id.
- * Empty or `free` → CURSOR_ROUTE_OPENCODE_MODEL, else OPENCODE_DEFAULT_MODEL.
- */
-export function openCodeModel(raw) {
-    const v = (raw ?? "").trim();
-    if (!v || v.toLowerCase() === "free") {
-        const env = (process.env.CURSOR_ROUTE_OPENCODE_MODEL ?? "").trim();
-        if (!env || env.toLowerCase() === "free")
-            return OPENCODE_DEFAULT_MODEL;
-        return assertOpenCodeModel(env);
-    }
-    return assertOpenCodeModel(v);
-}
+export { OPENCODE_DEFAULT_MODEL, assertOpenCodeModel, openCodeModel, cachedZenFreePick, } from "./zen-free.js";
 function maxConcurrentJobsFromEnv() {
     const raw = process.env.CURSOR_ROUTE_MAX_JOBS;
     if (raw) {
@@ -92,7 +66,7 @@ function maxConcurrentJobsFromEnv() {
  */
 export const config = {
     product: "cursor-route",
-    version: "0.1.10",
+    version: "0.1.11",
     get jobsDir() {
         return defaultJobsDir();
     },

package/dist/zen-free.js

@@ -0,0 +1,237 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * Live OpenCode Zen free-model pick — same idea as agent-toolkit
+ * `select-openrouter-free-model.ps1`: probe the catalog, keep $0 text/coding
+ * models, rank, cache ~15 min. Hardcoded ids are fallback only.
+ *
+ * Catalog: GET https://opencode.ai/zen/v1/models (no key). Zen ids are
+ * `big-pickle` / `x-preview-f-free`; the CLI wants `opencode/<id>`.
+ */
+export const ZEN_MODELS_URL_DEFAULT = "https://opencode.ai/zen/v1/models";
+/** Offline / fetch-fail fallback — Ox Alpha (zero-retention, currently top-tier free). */
+export const OPENCODE_DEFAULT_MODEL = "opencode/x-preview-f-free";
+const EXCLUDE_RE = /lyria|whisper|tts|embed|embedding|image|vision-only|audio|diffusion|flux|stable-diffusion|moderation/i;
+const CODING_RE = /coder|instruct|chat|laguna|nemotron|glm|qwen|kimi|deepseek|mimo|hy3|gpt-oss|north|gemma/i;
+const OX_ALPHA_RE = /x-preview|ox-alpha|oxalpha/i;
+const CONTRIBUTOR_RE = /contributor-free/i;
+function zenModelsUrl() {
+    return (process.env.CURSOR_ROUTE_ZEN_MODELS_URL || ZEN_MODELS_URL_DEFAULT).trim();
+}
+function cacheMinutes() {
+    const n = Number(process.env.CURSOR_ROUTE_ZEN_CACHE_MINUTES);
+    return Number.isFinite(n) && n > 0 ? n : 15;
+}
+function cachePath() {
+    return process.env.CURSOR_ROUTE_ZEN_CACHE_PATH?.trim() ||
+        join(tmpdir(), "cursor-route-zen-best-free.json");
+}
+export function assertOpenCodeModel(id) {
+    if (!/^[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._\-:]+)+$/i.test(id)) {
+        throw new Error(`Invalid OpenCode model ${id}; expected provider/model (e.g. opencode/x-preview-f-free) or free`);
+    }
+    return id;
+}
+/** Prefix a Zen catalog id (`x-preview-f-free`) for `opencode run --model`. */
+export function asOpenCodeZenId(raw) {
+    const id = raw.trim();
+    if (!id)
+        throw new Error("empty Zen model id");
+    return id.includes("/") ? assertOpenCodeModel(id) : assertOpenCodeModel(`opencode/${id}`);
+}
+function num(v) {
+    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 isZenFreeModel(m) {
+    const id = (m.id || "").trim();
+    if (!id)
+        return false;
+    if (EXCLUDE_RE.test(id) || EXCLUDE_RE.test(m.name || ""))
+        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") ||
+        id.endsWith(":free") ||
+        /(^|\/)big-pickle$/i.test(id);
+    return tagged || pricedFree;
+}
+/** Higher boost wins. Ox Alpha first while it is in the free catalog. */
+export function zenFreeBoost(id) {
+    const s = id.toLowerCase();
+    if (OX_ALPHA_RE.test(s))
+        return 40;
+    if (CONTRIBUTOR_RE.test(s))
+        return 1;
+    if (CODING_RE.test(s))
+        return 20;
+    if (s.endsWith("-free") || s.endsWith(":free"))
+        return 10;
+    if (/(^|\/)big-pickle$/.test(s))
+        return 5;
+    return 0;
+}
+export function rankZenFreeModels(models) {
+    const out = [];
+    for (const m of models) {
+        if (!isZenFreeModel(m))
+            continue;
+        const raw = (m.id || "").trim();
+        let id;
+        try {
+            id = asOpenCodeZenId(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: zenFreeBoost(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() {
+    const p = cachePath();
+    if (!existsSync(p))
+        return null;
+    try {
+        const j = JSON.parse(readFileSync(p, "utf8"));
+        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;
+        assertOpenCodeModel(j.id);
+        return j;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(pick) {
+    try {
+        writeFileSync(cachePath(), JSON.stringify(pick), { mode: 0o600 });
+    }
+    catch {
+        /* cache is optional */
+    }
+}
+function httpGetSync(url, timeoutMs = 4000) {
+    const sec = Math.max(1, Math.ceil(timeoutMs / 1000));
+    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) {
+    const j = JSON.parse(raw);
+    if (Array.isArray(j))
+        return j;
+    if (Array.isArray(j.data))
+        return j.data;
+    return [];
+}
+export function loadZenCatalog() {
+    const inline = process.env.CURSOR_ROUTE_ZEN_CATALOG_JSON?.trim();
+    if (inline)
+        return parseCatalog(inline);
+    if (process.env.CURSOR_ROUTE_ZEN_OFFLINE === "1")
+        return [];
+    const body = httpGetSync(zenModelsUrl());
+    if (!body)
+        return [];
+    try {
+        return parseCatalog(body);
+    }
+    catch {
+        return [];
+    }
+}
+/** Last live pick if the cache is still fresh — health-safe (no network). */
+export function cachedZenFreePick() {
+    try {
+        return readCache()?.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Best live Zen free model, or OPENCODE_DEFAULT_MODEL if the catalog is empty/offline.
+ * `CURSOR_ROUTE_ZEN_REFRESH=1` skips cache. Tests: `CURSOR_ROUTE_ZEN_OFFLINE=1` or
+ * `CURSOR_ROUTE_ZEN_CATALOG_JSON`.
+ */
+export function pickZenFreeModel(opts) {
+    const refresh = opts?.refresh ||
+        process.env.CURSOR_ROUTE_ZEN_REFRESH === "1";
+    if (!refresh && opts?.catalog === undefined) {
+        const cached = readCache();
+        if (cached)
+            return cached.id;
+    }
+    const models = opts?.catalog ?? loadZenCatalog();
+    const ranked = rankZenFreeModels(models);
+    const winner = ranked[0];
+    if (!winner) {
+        const fallback = {
+            id: OPENCODE_DEFAULT_MODEL,
+            name: "Ox Alpha Free (fallback)",
+            context_length: 0,
+            boost: 0,
+            picked_at: new Date().toISOString(),
+            candidates: 0,
+            source: "fallback",
+        };
+        if (opts?.catalog === undefined)
+            writeCache(fallback);
+        return fallback.id;
+    }
+    const pick = {
+        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 OpenCode `--model` / env to a concrete `provider/model` id.
+ * Empty or `free` → CURSOR_ROUTE_OPENCODE_MODEL pin, else live Zen free pick.
+ */
+export function openCodeModel(raw) {
+    const v = (raw ?? "").trim();
+    if (!v || v.toLowerCase() === "free") {
+        const env = (process.env.CURSOR_ROUTE_OPENCODE_MODEL ?? "").trim();
+        if (env && env.toLowerCase() !== "free")
+            return assertOpenCodeModel(env);
+        return pickZenFreeModel();
+    }
+    return assertOpenCodeModel(v);
+}

package/docs/briefs/WORKING.md

@@ -1,7 +1,7 @@
 ---
 title: cursor-route workspace — working brief (edit in place)
 repo: ~/Projects/cursor-route
-npm: cursor-route@0.1.10 (unreleased — OpenCode worker)
+npm: cursor-route@0.1.11 (LIVE on npm latest)
 created: 2026-08-12
 updated: 2026-08-21
 ---
@@ -21,11 +21,11 @@ Cursor Agent plans. Workers run in tmux via `cursor-route`:
 | `easy` | OpenRouter free | Wording / drafts — non-secret prompts only |
 | `mid` | claude-ds (DeepSeek behind Claude Code) | Default implement (**Flash**; `--model pro` when needed) |
 | `hard` | Grok CLI | Hard implement |
-| opt-in | OpenCode | `--worker opencode` coding agent on Zen free models (default `opencode/big-pickle`) |
+| opt-in | OpenCode | `--worker opencode` coding agent; `--model free` ranks live Zen catalog (Ox Alpha first while listed) |
 
 Always-approve on for coding worktrees (`--ask` / `CURSOR_ROUTE_ASK=1` to opt out) — not LIVE Discord/trading. Jobs live in `~/.local/share/cursor-route/jobs`, not in this clone.
 
-Install: `npm i -g cursor-route` → **0.1.9** live; **0.1.10** unreleased (OpenCode worker). Release notes: [CHANGELOG.md](../../CHANGELOG.md).
+Install: `npm i -g cursor-route` → **0.1.11**. Release notes: [CHANGELOG.md](../../CHANGELOG.md).
 
 ## Open (edit / check off)
 
@@ -39,7 +39,8 @@ Install: `npm i -g cursor-route` → **0.1.9** live; **0.1.10** unreleased (Open
 - [x] **Experimental `--worker deepseek`** — 0.1.8: real dsh adapter (`dsh --profile headless` + per-job Cordis patch pins the model; never writes `~/.dsh/settings.yaml`). Always-approve → `DSH_PERMISSION_MODE=danger-full-access`, `--ask` → `workspace-write`; key via env only. Health ✓ needs `dsh` + `DEEPSEEK_API_KEY` (override `CURSOR_ROUTE_DSH_BIN`). Mid stays **claude-ds**.
 - [x] **route-orch brief steals (2026-08-14)** — AutoDesign / misevolution / Vero habits into the public skill: **Verify / claim closeout** (external eval contract; activity ≠ verification), **Eval & skill hygiene** (mid-run Verify-rewrite ban; skill misevolution HITL — no auto-promotion of worker-trajectory variants; verify-fail → reconsider plan/definition + stage attribution spawn/execute/verify); handoff shape Success criteria + Verify + NEVER; skills synced; mid stays claude-ds.
 - [x] **Health proves mid DeepSeek + evidence tree** — 0.1.9: `lane:mid` ✓ only when DeepSeek is proven (shim or DeepSeek `ANTHROPIC_BASE_URL`; Anthropic hatch is not proof); health JSON `lanes.mid`; `status --json` evidence tree (`spawn` / `execute` / `verify.claim=unverified`); skill health-before-mid + evidence-tree closeout. Mid stays **claude-ds**.
-- [x] **Opt-in `--worker opencode`** — 0.1.10: `opencode run --dir` + `--model` (default Zen free `opencode/big-pickle` / `--model free`); always-approve → `--auto`; `--ask` omits it; never rewrites `~/.config/opencode/opencode.json`. Health ✓ needs `opencode` on PATH (`CURSOR_ROUTE_OPENCODE_BIN`). Mid stays **claude-ds**; easy stays OpenRouter chat. Free Zen may log/train — non-secret prompts.
+- [x] **Opt-in `--worker opencode`** — 0.1.10: `opencode run --dir` + `--model`; always-approve → `--auto`; `--ask` omits it; never rewrites `~/.config/opencode/opencode.json`. Health ✓ needs `opencode` on PATH (`CURSOR_ROUTE_OPENCODE_BIN`). Mid stays **claude-ds**; easy stays OpenRouter chat. Free Zen may log/train — non-secret prompts.
+- [x] **Live Zen free pick** — 0.1.11: `--model free` ranks `GET https://opencode.ai/zen/v1/models` (Ox Alpha first while listed; ~15 min cache; Ox Alpha fallback if fetch fails). Pin with `CURSOR_ROUTE_OPENCODE_MODEL`. Health stays offline (cache/fallback only).
 - [ ] **Hero GIF** — still outstanding; dry-run fixture ships as the substitute for now (`docs/fixtures/hero-demo.log` — see `docs/DEMO_GIF.md`)
 - [x] **Do not** paste private `ROUTE_KIT`, SIP, prod paths, or hang-watchdog env into this public repo
 
@@ -53,6 +54,7 @@ Install: `npm i -g cursor-route` → **0.1.9** live; **0.1.10** unreleased (Open
 | `src/adapters/grok.ts` | Hard worker |
 | `src/adapters/openrouter.ts` | Easy worker |
 | `src/adapters/opencode.ts` | Opt-in OpenCode worker (`--worker opencode`; mid stays claude-ds) |
+| `src/zen-free.ts` | Live Zen catalog rank for `--model free` |
 | `skills/route-orch/SKILL.md` | Cursor skill — spawn CLI, do not implement in-session |
 | `CHANGELOG.md` | Release notes |
 | `SECURITY.md` | Secret refuse gate |
@@ -71,4 +73,5 @@ Install: `npm i -g cursor-route` → **0.1.9** live; **0.1.10** unreleased (Open
 | 2026-08-14 | Experimental `--worker deepseek` wired to official dsh (headless + per-job patch + `DSH_PERMISSION_MODE` + key-via-env); `--model` applies to claude-ds + deepseek; mid stays claude-ds → 0.1.8 LIVE. |
 | 2026-08-14 | route-orch brief steals (AutoDesign / misevolution / Vero): **Verify / claim closeout** + **Eval & skill hygiene**; handoff Success criteria + Verify + NEVER; both skill copies synced; mid stays claude-ds. Docs-only, no version bump. |
 | 2026-08-18 | Health `lane:mid` + `lanes.mid` prove DeepSeek; status evidence tree (`verify.claim` stays unverified); skill health-before-mid + closeout tree; mid stays claude-ds → 0.1.9 LIVE. |
-| 2026-08-21 | Opt-in `--worker opencode` (Zen free `opencode/big-pickle`, `--auto`, no config rewrite); mid stays claude-ds → 0.1.10. |
+| 2026-08-21 | Opt-in `--worker opencode` (Zen free `opencode/big-pickle`, `--auto`, no config rewrite); mid stays claude-ds → 0.1.10 LIVE. |
+| 2026-08-21 | Live Zen free pick (Ox Alpha first while listed; OpenRouter-style catalog rank) → 0.1.11 LIVE. |

package/llms.txt

@@ -2,13 +2,13 @@
 
 > Cursor stays the planner. DeepSeek (mid), Grok CLI (hard), and OpenRouter free models (easy) run parallel coding workers in tmux. `--worker opencode` is an opt-in coding agent on OpenCode Zen free models.
 
-MIT CLI + Cursor skill. npm: https://www.npmjs.com/package/cursor-route (latest **0.1.10**)
+MIT CLI + Cursor skill. npm: https://www.npmjs.com/package/cursor-route (latest **0.1.11**)
 GitHub: https://github.com/cemini23/cursor-route
 
 ## FAQ
 
 ### What is cursor-route?
-cursor-route is a public MIT CLI and Cursor skill that runs parallel coding workers in tmux while Cursor remains the planner. DeepSeek handles the mid lane, Grok CLI handles the hard lane, and OpenRouter free models handle the easy lane (wording/drafts, non-secret prompts only). `--worker opencode` is an opt-in coding agent (default `opencode/big-pickle`) — not a lane default.
+cursor-route is a public MIT CLI and Cursor skill that runs parallel coding workers in tmux while Cursor remains the planner. DeepSeek handles the mid lane, Grok CLI handles the hard lane, and OpenRouter free models handle the easy lane (wording/drafts, non-secret prompts only). `--worker opencode` is an opt-in coding agent (`--model free` ranks the live Zen catalog; Ox Alpha wins while listed) — not a lane default.
 
 ### How is this different from Codex orchestrator?
 It uses the familiar strategist and worker-pane shape, but it is not a Codex clone. cursor-route uses Cursor as the planner and DeepSeek plus Grok CLI as workers. Codex is not required.
@@ -23,7 +23,7 @@ No. The mid worker is DeepSeek. Claude Code is the harness, configured with `ANT
 | `--model pro` | `deepseek-v4-pro` | Harder mid / Grok usage stand-in |
 
 ### How do I use OpenCode free models?
-Install OpenCode (`npm i -g opencode-ai`), run `opencode auth login`, then `cursor-route start --worker opencode "…"`. Default model is `opencode/big-pickle` (`--model free`). Mid stays `claude-ds`.
+Install OpenCode (`npm i -g opencode-ai`), run `opencode auth login`, then `cursor-route start --worker opencode "…"`. `--model free` ranks live Zen free models (Ox Alpha first while listed). Mid stays `claude-ds`.
 
 ### How do I install?
 Run `npm i -g cursor-route`, install tmux if needed, then run `cursor-route health`. Copy the Cursor skill from `$(npm root -g)/cursor-route/skills/route-orch`. Source: https://github.com/cemini23/cursor-route

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-route",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Cursor stays the brain. Grok CLI + DeepSeek (claude-ds) + OpenRouter easy lane + OpenCode (opt-in free) are the parallel army \u2014 lane-aware /route orchestration in tmux.",
   "type": "module",
   "license": "MIT",

package/skills/route-orch/SKILL.md

@@ -71,7 +71,7 @@ cursor-route start --worker opencode --model free --dir "$PWD" "…"
 cursor-route start --worker opencode --model opencode/hy3-free --dir "$PWD" "…"
 ```
 
-Health ✓ needs `opencode` on PATH (override `CURSOR_ROUTE_OPENCODE_BIN`). Default model is `opencode/big-pickle` (`CURSOR_ROUTE_OPENCODE_MODEL` / `--model free`). Always-approve → `opencode run --auto`; `--ask` omits `--auto`. Never rewrites `~/.config/opencode/opencode.json`. Free Zen models may log/train — keep secrets off this worker (same refuse gate as easy).
+Health ✓ needs `opencode` on PATH (override `CURSOR_ROUTE_OPENCODE_BIN`). `--model free` / unset ranks the live OpenCode Zen catalog (Ox Alpha first while listed; pin with `CURSOR_ROUTE_OPENCODE_MODEL` or `--model provider/model`). Always-approve → `opencode run --auto`; `--ask` omits `--auto`. Never rewrites `~/.config/opencode/opencode.json`. Free Zen models may log/train — keep secrets off this worker (same refuse gate as easy). Ox Alpha (`opencode/x-preview-f-free`) is the zero-retention free option.
 
 ## Workflow
 

package/src/adapters/opencode.test.ts

@@ -11,16 +11,36 @@ import {
 } from "../config.ts";
 
 describe("openCodeModel", () => {
-  test("defaults to OpenCode Zen Big Pickle", () => {
-    const prev = process.env.CURSOR_ROUTE_OPENCODE_MODEL;
+  test("defaults to live Zen pick (Ox Alpha fallback when offline)", () => {
+    const prev = {
+      model: process.env.CURSOR_ROUTE_OPENCODE_MODEL,
+      offline: process.env.CURSOR_ROUTE_ZEN_OFFLINE,
+      cache: process.env.CURSOR_ROUTE_ZEN_CACHE_PATH,
+      json: process.env.CURSOR_ROUTE_ZEN_CATALOG_JSON,
+      refresh: process.env.CURSOR_ROUTE_ZEN_REFRESH,
+    };
+    const cache = join(tmpdir(), `cr-oc-model-${process.pid}.json`);
     delete process.env.CURSOR_ROUTE_OPENCODE_MODEL;
+    delete process.env.CURSOR_ROUTE_ZEN_CATALOG_JSON;
+    process.env.CURSOR_ROUTE_ZEN_OFFLINE = "1";
+    process.env.CURSOR_ROUTE_ZEN_CACHE_PATH = cache;
+    process.env.CURSOR_ROUTE_ZEN_REFRESH = "1";
     try {
-      expect(openCodeModel()).toBe("opencode/big-pickle");
+      expect(openCodeModel()).toBe("opencode/x-preview-f-free");
       expect(openCodeModel("")).toBe(OPENCODE_DEFAULT_MODEL);
-      expect(openCodeModel("free")).toBe("opencode/big-pickle");
+      expect(openCodeModel("free")).toBe("opencode/x-preview-f-free");
     } finally {
-      if (prev === undefined) delete process.env.CURSOR_ROUTE_OPENCODE_MODEL;
-      else process.env.CURSOR_ROUTE_OPENCODE_MODEL = prev;
+      if (prev.model === undefined) delete process.env.CURSOR_ROUTE_OPENCODE_MODEL;
+      else process.env.CURSOR_ROUTE_OPENCODE_MODEL = prev.model;
+      if (prev.offline === undefined) delete process.env.CURSOR_ROUTE_ZEN_OFFLINE;
+      else process.env.CURSOR_ROUTE_ZEN_OFFLINE = prev.offline;
+      if (prev.cache === undefined) delete process.env.CURSOR_ROUTE_ZEN_CACHE_PATH;
+      else process.env.CURSOR_ROUTE_ZEN_CACHE_PATH = prev.cache;
+      if (prev.json === undefined) delete process.env.CURSOR_ROUTE_ZEN_CATALOG_JSON;
+      else process.env.CURSOR_ROUTE_ZEN_CATALOG_JSON = prev.json;
+      if (prev.refresh === undefined) delete process.env.CURSOR_ROUTE_ZEN_REFRESH;
+      else process.env.CURSOR_ROUTE_ZEN_REFRESH = prev.refresh;
+      rmSync(cache, { force: true });
     }
   });
 
@@ -100,14 +120,21 @@ describe("opencode adapter", () => {
   });
 
   test("health: binary → ok (auth at first start)", () => {
-    const { bin } = makeFake("ok");
-    withEnv({ CURSOR_ROUTE_OPENCODE_BIN: bin }, () => {
-      const h = opencodeAdapter.health();
-      expect(h.ok).toBe(true);
-      expect(h.binary).toBe(bin);
-      expect(h.detail).toContain("opencode/big-pickle");
-    });
-    rmSync(join(tmpdir(), `cr-oc-${process.pid}-ok`), { recursive: true, force: true });
+    const { dir, bin } = makeFake("ok");
+    withEnv(
+      {
+        CURSOR_ROUTE_OPENCODE_BIN: bin,
+        CURSOR_ROUTE_ZEN_CACHE_PATH: join(dir, "missing-cache.json"),
+      },
+      () => {
+        const h = opencodeAdapter.health();
+        expect(h.ok).toBe(true);
+        expect(h.binary).toBe(bin);
+        expect(h.detail).toContain("live Zen pick");
+        expect(h.detail).toContain("opencode/x-preview-f-free");
+      },
+    );
+    rmSync(dir, { recursive: true, force: true });
   });
 
   test("buildLaunch: default free model + --auto; prompt via cat", () => {
@@ -119,6 +146,10 @@ describe("opencode adapter", () => {
         CURSOR_ROUTE_OPENCODE_BIN: bin,
         CURSOR_ROUTE_OPENCODE_MODEL: undefined,
         CURSOR_ROUTE_ASK: undefined,
+        CURSOR_ROUTE_ZEN_OFFLINE: "1",
+        CURSOR_ROUTE_ZEN_CACHE_PATH: join(dir, "zen-cache.json"),
+        CURSOR_ROUTE_ZEN_REFRESH: "1",
+        CURSOR_ROUTE_ZEN_CATALOG_JSON: undefined,
       },
       () => {
         const plan = opencodeAdapter.buildLaunch({
@@ -128,7 +159,7 @@ describe("opencode adapter", () => {
         });
         expect(plan.command).toContain("run");
         expect(plan.command).toContain("--auto");
-        expect(plan.command).toContain("opencode/big-pickle");
+        expect(plan.command).toContain("opencode/x-preview-f-free");
         expect(plan.command).toContain("$(cat");
         expect(plan.command).toContain("--dir");
         expect(plan.alwaysApprove).toBe(true);
@@ -160,15 +191,24 @@ describe("opencode adapter", () => {
     const { dir, bin } = makeFake("ask-env");
     const promptFile = join(dir, "job.prompt");
     writeFileSync(promptFile, "ping");
-    withEnv({ CURSOR_ROUTE_OPENCODE_BIN: bin, CURSOR_ROUTE_ASK: "1" }, () => {
-      const plan = opencodeAdapter.buildLaunch({
-        promptFile,
-        cwd: dir,
-        alwaysApprove: true,
-      });
-      expect(plan.command).not.toContain("--auto");
-      expect(plan.alwaysApprove).toBe(false);
-    });
+    withEnv(
+      {
+        CURSOR_ROUTE_OPENCODE_BIN: bin,
+        CURSOR_ROUTE_ASK: "1",
+        CURSOR_ROUTE_ZEN_OFFLINE: "1",
+        CURSOR_ROUTE_ZEN_CACHE_PATH: join(dir, "zen-cache.json"),
+        CURSOR_ROUTE_ZEN_REFRESH: "1",
+      },
+      () => {
+        const plan = opencodeAdapter.buildLaunch({
+          promptFile,
+          cwd: dir,
+          alwaysApprove: true,
+        });
+        expect(plan.command).not.toContain("--auto");
+        expect(plan.alwaysApprove).toBe(false);
+      },
+    );
     rmSync(dir, { recursive: true, force: true });
   });
 
@@ -183,6 +223,9 @@ describe("opencode adapter", () => {
         CURSOR_ROUTE_OPENCODE_BIN: undefined,
         PATH: empty,
         CURSOR_ROUTE_OPENCODE_MODEL: undefined,
+        CURSOR_ROUTE_ZEN_OFFLINE: "1",
+        CURSOR_ROUTE_ZEN_CACHE_PATH: join(dir, "zen-cache.json"),
+        CURSOR_ROUTE_ZEN_REFRESH: "1",
       },
       () => {
         const plan = opencodeAdapter.buildLaunch({
@@ -208,10 +251,18 @@ describe("opencode adapter", () => {
       bin: process.env.CURSOR_ROUTE_OPENCODE_BIN,
       model: process.env.CURSOR_ROUTE_OPENCODE_MODEL,
       jobs: process.env.CURSOR_ROUTE_JOBS_DIR,
+      offline: process.env.CURSOR_ROUTE_ZEN_OFFLINE,
+      cache: process.env.CURSOR_ROUTE_ZEN_CACHE_PATH,
+      refresh: process.env.CURSOR_ROUTE_ZEN_REFRESH,
+      json: process.env.CURSOR_ROUTE_ZEN_CATALOG_JSON,
     };
     process.env.CURSOR_ROUTE_OPENCODE_BIN = bin;
     delete process.env.CURSOR_ROUTE_OPENCODE_MODEL;
+    delete process.env.CURSOR_ROUTE_ZEN_CATALOG_JSON;
     process.env.CURSOR_ROUTE_JOBS_DIR = join(dir, "jobs");
+    process.env.CURSOR_ROUTE_ZEN_OFFLINE = "1";
+    process.env.CURSOR_ROUTE_ZEN_CACHE_PATH = join(dir, "zen-cache.json");
+    process.env.CURSOR_ROUTE_ZEN_REFRESH = "1";
     try {
       const result = startJob({
         prompt: "ping",
@@ -221,7 +272,7 @@ describe("opencode adapter", () => {
       expect(result.ok).toBe(true);
       if (!result.ok) return;
       expect(result.job.worker).toBe("opencode");
-      expect(result.job.model).toBe("opencode/big-pickle");
+      expect(result.job.model).toBe("opencode/x-preview-f-free");
       expect(result.command).toContain("run");
       expect(result.command).toContain("--auto");
       expect(result.command).toContain("$(cat");
@@ -232,6 +283,14 @@ describe("opencode adapter", () => {
       else process.env.CURSOR_ROUTE_OPENCODE_MODEL = prev.model;
       if (prev.jobs === undefined) delete process.env.CURSOR_ROUTE_JOBS_DIR;
       else process.env.CURSOR_ROUTE_JOBS_DIR = prev.jobs;
+      if (prev.offline === undefined) delete process.env.CURSOR_ROUTE_ZEN_OFFLINE;
+      else process.env.CURSOR_ROUTE_ZEN_OFFLINE = prev.offline;
+      if (prev.cache === undefined) delete process.env.CURSOR_ROUTE_ZEN_CACHE_PATH;
+      else process.env.CURSOR_ROUTE_ZEN_CACHE_PATH = prev.cache;
+      if (prev.refresh === undefined) delete process.env.CURSOR_ROUTE_ZEN_REFRESH;
+      else process.env.CURSOR_ROUTE_ZEN_REFRESH = prev.refresh;
+      if (prev.json === undefined) delete process.env.CURSOR_ROUTE_ZEN_CATALOG_JSON;
+      else process.env.CURSOR_ROUTE_ZEN_CATALOG_JSON = prev.json;
       rmSync(dir, { recursive: true, force: true });
     }
   });

package/src/adapters/opencode.ts

@@ -2,13 +2,13 @@ import { execSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import type { Adapter, WorkerHealth } from "./types.ts";
 import { shellQuote } from "../util.ts";
-import { openCodeModel, OPENCODE_DEFAULT_MODEL } from "../config.ts";
+import { openCodeModel, OPENCODE_DEFAULT_MODEL, cachedZenFreePick } from "../config.ts";
 
 /**
- * Opt-in OpenCode worker (`opencode run`) — a coding agent that can use
- * OpenCode Zen free models (default `opencode/big-pickle`) to cut Grok /
- * DeepSeek usage. Not a lane default: mid stays claude-ds; easy stays
- * OpenRouter chat (no tools).
+ * Opt-in OpenCode worker (`opencode run`) — a coding agent on live OpenCode
+ * Zen free models (`--model free` ranks the catalog; Ox Alpha wins while
+ * listed). Not a lane default: mid stays claude-ds; easy stays OpenRouter
+ * chat (no tools).
  *
  * We never rewrite ~/.config/opencode/opencode.json (parallel jobs would
  * race). Always-approve maps to `opencode run --auto` (still honors explicit
@@ -47,17 +47,13 @@ export const opencodeAdapter: Adapter = {
           "opencode not found — install: npm i -g opencode-ai (or brew install opencode). Then: opencode auth login. Mid default remains claude-ds.",
       };
     }
-    let defaultModel = OPENCODE_DEFAULT_MODEL;
-    try {
-      defaultModel = openCodeModel();
-    } catch {
-      /* invalid env — health still ok; startJob will fail loud */
-    }
+    // Health stays offline: show a fresh cache hit, else the Ox Alpha fallback.
+    const pick = cachedZenFreePick() || OPENCODE_DEFAULT_MODEL;
     return {
       worker: "opencode",
       ok: true,
       binary,
-      detail: `ok (opencode run; default model ${defaultModel}; auth at first start — opencode auth login if jobs fail; mid default remains claude-ds)`,
+      detail: `ok (opencode run; --model free = live Zen pick, now ${pick}; auth at first start — opencode auth login if jobs fail; mid default remains claude-ds)`,
     };
   },
   buildLaunch({ promptFile, cwd, alwaysApprove, modelId }) {

package/src/cli.test.ts

@@ -618,7 +618,7 @@ describe("health", () => {
   test("returns structured report", () => {
     const r = runHealth();
     expect(r.product).toBe("cursor-route");
-    expect(r.version).toBe("0.1.10");
+    expect(r.version).toBe("0.1.11");
     expect(r.checks.length).toBeGreaterThan(3);
     expect(r.checks.some((c) => c.name === "tmux")).toBe(true);
     expect(r.checks.some((c) => c.name === "cursor_cli")).toBe(true);
@@ -630,8 +630,8 @@ describe("health", () => {
     expect(r.checks.some((c) => c.name === "worker:deepseek")).toBe(true);
   });
 
-  test("config version is 0.1.10", () => {
-    expect(config.version).toBe("0.1.10");
+  test("config version is 0.1.11", () => {
+    expect(config.version).toBe("0.1.11");
   });
 
   test("OR-gate: ok can be true while worker:opencode is false", () => {

package/src/cli.ts

@@ -56,7 +56,7 @@ Usage:
 Start options:
   --worker <grok|claude-ds|openrouter|deepseek|opencode>  Worker adapter (default: grok; deepseek/opencode = opt-in)
   --lane <easy|mid|hard>                Lane → worker (easy=openrouter, mid=claude-ds, hard=grok)
-  --model <flash|pro|free|provider/model>  claude-ds/deepseek: flash|pro. opencode: free (default opencode/big-pickle) or provider/model
+  --model <flash|pro|free|provider/model>  claude-ds/deepseek: flash|pro. opencode: free (live Zen catalog pick) or provider/model
   --dir <path>                          Working directory (default: cwd)
   --ask                                 Disable always-approve for this job
   --dry-run                             Print launch command; do not start
@@ -78,7 +78,7 @@ Env:
   OPENROUTER_API_KEY                 OpenRouter key (required for --worker openrouter / --lane easy)
   CURSOR_ROUTE_OPENROUTER_MODEL      OpenRouter model (default: openrouter/free)
   OPENROUTER_BASE_URL                OpenRouter API base (default: https://openrouter.ai/api/v1)
-  CURSOR_ROUTE_OPENCODE_MODEL        OpenCode model (default: opencode/big-pickle); --model overrides
+  CURSOR_ROUTE_OPENCODE_MODEL        OpenCode model pin (unset or free = live Zen free pick); --model overrides
 `);
   process.exit(exitCode);
 }
@@ -177,7 +177,7 @@ function asDsModelChoice(v: unknown): { alias: DsModelAlias; id: string } | unde
 function asOpenCodeModel(v: unknown): string | undefined {
   if (v === undefined || v === true) return undefined;
   if (typeof v !== "string") {
-    throw new Error(`Invalid --model; expected provider/model (e.g. opencode/big-pickle) or free`);
+    throw new Error(`Invalid --model; expected provider/model (e.g. opencode/x-preview-f-free) or free`);
   }
   return openCodeModel(v);
 }

package/src/config.ts

@@ -74,36 +74,12 @@ export function openRouterBaseUrl(): string {
   return process.env.OPENROUTER_BASE_URL || "https://openrouter.ai/api/v1";
 }
 
-/**
- * Default OpenCode model: OpenCode Zen Big Pickle (free, limited-time).
- * Override: CURSOR_ROUTE_OPENCODE_MODEL or `--model provider/model`.
- * Alias `free` resolves to this default (or the env override).
- */
-export const OPENCODE_DEFAULT_MODEL = "opencode/big-pickle";
-
-/** Whitelist OpenCode `provider/model` ids (no spaces / injection). */
-export function assertOpenCodeModel(id: string): string {
-  if (!/^[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._\-:]+)+$/i.test(id)) {
-    throw new Error(
-      `Invalid OpenCode model ${id}; expected provider/model (e.g. opencode/big-pickle) or free`,
-    );
-  }
-  return id;
-}
-
-/**
- * Resolve OpenCode `--model` / env to a concrete `provider/model` id.
- * Empty or `free` → CURSOR_ROUTE_OPENCODE_MODEL, else OPENCODE_DEFAULT_MODEL.
- */
-export function openCodeModel(raw?: string | null): string {
-  const v = (raw ?? "").trim();
-  if (!v || v.toLowerCase() === "free") {
-    const env = (process.env.CURSOR_ROUTE_OPENCODE_MODEL ?? "").trim();
-    if (!env || env.toLowerCase() === "free") return OPENCODE_DEFAULT_MODEL;
-    return assertOpenCodeModel(env);
-  }
-  return assertOpenCodeModel(v);
-}
+export {
+  OPENCODE_DEFAULT_MODEL,
+  assertOpenCodeModel,
+  openCodeModel,
+  cachedZenFreePick,
+} from "./zen-free.ts";
 
 function maxConcurrentJobsFromEnv(): number {
   const raw = process.env.CURSOR_ROUTE_MAX_JOBS;
@@ -121,7 +97,7 @@ function maxConcurrentJobsFromEnv(): number {
  */
 export const config = {
   product: "cursor-route",
-  version: "0.1.10",
+  version: "0.1.11",
   get jobsDir(): string {
     return defaultJobsDir();
   },

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

package/src/zen-free.ts

@@ -0,0 +1,258 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Live OpenCode Zen free-model pick — same idea as agent-toolkit
+ * `select-openrouter-free-model.ps1`: probe the catalog, keep $0 text/coding
+ * models, rank, cache ~15 min. Hardcoded ids are fallback only.
+ *
+ * Catalog: GET https://opencode.ai/zen/v1/models (no key). Zen ids are
+ * `big-pickle` / `x-preview-f-free`; the CLI wants `opencode/<id>`.
+ */
+
+export const ZEN_MODELS_URL_DEFAULT = "https://opencode.ai/zen/v1/models";
+
+/** Offline / fetch-fail fallback — Ox Alpha (zero-retention, currently top-tier free). */
+export const OPENCODE_DEFAULT_MODEL = "opencode/x-preview-f-free";
+
+export interface ZenModel {
+  id?: string;
+  name?: string;
+  context_length?: number;
+  pricing?: { prompt?: number | string; completion?: number | string };
+}
+
+export interface ZenFreePick {
+  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 CODING_RE =
+  /coder|instruct|chat|laguna|nemotron|glm|qwen|kimi|deepseek|mimo|hy3|gpt-oss|north|gemma/i;
+const OX_ALPHA_RE = /x-preview|ox-alpha|oxalpha/i;
+const CONTRIBUTOR_RE = /contributor-free/i;
+
+function zenModelsUrl(): string {
+  return (process.env.CURSOR_ROUTE_ZEN_MODELS_URL || ZEN_MODELS_URL_DEFAULT).trim();
+}
+
+function cacheMinutes(): number {
+  const n = Number(process.env.CURSOR_ROUTE_ZEN_CACHE_MINUTES);
+  return Number.isFinite(n) && n > 0 ? n : 15;
+}
+
+function cachePath(): string {
+  return process.env.CURSOR_ROUTE_ZEN_CACHE_PATH?.trim() ||
+    join(tmpdir(), "cursor-route-zen-best-free.json");
+}
+
+export function assertOpenCodeModel(id: string): string {
+  if (!/^[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._\-:]+)+$/i.test(id)) {
+    throw new Error(
+      `Invalid OpenCode model ${id}; expected provider/model (e.g. opencode/x-preview-f-free) or free`,
+    );
+  }
+  return id;
+}
+
+/** Prefix a Zen catalog id (`x-preview-f-free`) for `opencode run --model`. */
+export function asOpenCodeZenId(raw: string): string {
+  const id = raw.trim();
+  if (!id) throw new Error("empty Zen model id");
+  return id.includes("/") ? assertOpenCodeModel(id) : assertOpenCodeModel(`opencode/${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 isZenFreeModel(m: ZenModel): boolean {
+  const id = (m.id || "").trim();
+  if (!id) return false;
+  if (EXCLUDE_RE.test(id) || EXCLUDE_RE.test(m.name || "")) 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") ||
+    id.endsWith(":free") ||
+    /(^|\/)big-pickle$/i.test(id);
+  return tagged || pricedFree;
+}
+
+/** Higher boost wins. Ox Alpha first while it is in the free catalog. */
+export function zenFreeBoost(id: string): number {
+  const s = id.toLowerCase();
+  if (OX_ALPHA_RE.test(s)) return 40;
+  if (CONTRIBUTOR_RE.test(s)) return 1;
+  if (CODING_RE.test(s)) return 20;
+  if (s.endsWith("-free") || s.endsWith(":free")) return 10;
+  if (/(^|\/)big-pickle$/.test(s)) return 5;
+  return 0;
+}
+
+export function rankZenFreeModels(models: ZenModel[]): 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 (!isZenFreeModel(m)) continue;
+    const raw = (m.id || "").trim();
+    let id: string;
+    try {
+      id = asOpenCodeZenId(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: zenFreeBoost(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(): ZenFreePick | null {
+  const p = cachePath();
+  if (!existsSync(p)) return null;
+  try {
+    const j = JSON.parse(readFileSync(p, "utf8")) as ZenFreePick;
+    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;
+    assertOpenCodeModel(j.id);
+    return j;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(pick: ZenFreePick): 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));
+  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): ZenModel[] {
+  const j = JSON.parse(raw) as { data?: ZenModel[] } | ZenModel[];
+  if (Array.isArray(j)) return j;
+  if (Array.isArray(j.data)) return j.data;
+  return [];
+}
+
+export function loadZenCatalog(): ZenModel[] {
+  const inline = process.env.CURSOR_ROUTE_ZEN_CATALOG_JSON?.trim();
+  if (inline) return parseCatalog(inline);
+  if (process.env.CURSOR_ROUTE_ZEN_OFFLINE === "1") return [];
+  const body = httpGetSync(zenModelsUrl());
+  if (!body) return [];
+  try {
+    return parseCatalog(body);
+  } catch {
+    return [];
+  }
+}
+
+/** Last live pick if the cache is still fresh — health-safe (no network). */
+export function cachedZenFreePick(): string | null {
+  try {
+    return readCache()?.id ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Best live Zen free model, or OPENCODE_DEFAULT_MODEL if the catalog is empty/offline.
+ * `CURSOR_ROUTE_ZEN_REFRESH=1` skips cache. Tests: `CURSOR_ROUTE_ZEN_OFFLINE=1` or
+ * `CURSOR_ROUTE_ZEN_CATALOG_JSON`.
+ */
+export function pickZenFreeModel(opts?: { catalog?: ZenModel[]; refresh?: boolean }): string {
+  const refresh =
+    opts?.refresh ||
+    process.env.CURSOR_ROUTE_ZEN_REFRESH === "1";
+  if (!refresh && opts?.catalog === undefined) {
+    const cached = readCache();
+    if (cached) return cached.id;
+  }
+  const models = opts?.catalog ?? loadZenCatalog();
+  const ranked = rankZenFreeModels(models);
+  const winner = ranked[0];
+  if (!winner) {
+    const fallback: ZenFreePick = {
+      id: OPENCODE_DEFAULT_MODEL,
+      name: "Ox Alpha Free (fallback)",
+      context_length: 0,
+      boost: 0,
+      picked_at: new Date().toISOString(),
+      candidates: 0,
+      source: "fallback",
+    };
+    if (opts?.catalog === undefined) writeCache(fallback);
+    return fallback.id;
+  }
+  const pick: ZenFreePick = {
+    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 OpenCode `--model` / env to a concrete `provider/model` id.
+ * Empty or `free` → CURSOR_ROUTE_OPENCODE_MODEL pin, else live Zen free pick.
+ */
+export function openCodeModel(raw?: string | null): string {
+  const v = (raw ?? "").trim();
+  if (!v || v.toLowerCase() === "free") {
+    const env = (process.env.CURSOR_ROUTE_OPENCODE_MODEL ?? "").trim();
+    if (env && env.toLowerCase() !== "free") return assertOpenCodeModel(env);
+    return pickZenFreeModel();
+  }
+  return assertOpenCodeModel(v);
+}