cursor-route 0.1.10 → 0.1.13

package/dist/openrouter-run.js

@@ -19,7 +19,7 @@ function parseArgs(argv) {
         const a = argv[i];
         if (a === "-h" || a === "--help") {
             console.log("usage: cursor-route/openrouter-run --prompt-file <path>\n" +
-                "env: OPENROUTER_API_KEY (required), CURSOR_ROUTE_OPENROUTER_MODEL, OPENROUTER_BASE_URL");
+                "env: OPENROUTER_API_KEY (required), CURSOR_ROUTE_OPENROUTER_MODEL (unset/free = live pick), OPENROUTER_BASE_URL");
             process.exit(0);
         }
         if (a === "--prompt-file") {

package/dist/or-free.js

@@ -0,0 +1,216 @@
+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";
+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() {
+    const base = (process.env.OPENROUTER_BASE_URL || "https://openrouter.ai/api/v1")
+        .trim()
+        .replace(/\/+$/, "");
+    return `${base}/models`;
+}
+function cacheMinutes() {
+    const n = Number(process.env.CURSOR_ROUTE_OR_CACHE_MINUTES);
+    return Number.isFinite(n) && n > 0 ? n : 15;
+}
+function cachePath() {
+    return process.env.CURSOR_ROUTE_OR_CACHE_PATH?.trim() ||
+        join(tmpdir(), "cursor-route-or-best-free.json");
+}
+export function assertOpenRouterModel(id) {
+    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) {
+    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) {
+    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) {
+    return BOOST_RE.test(id) ? 20 : 10;
+}
+export function rankOrFreeModels(models) {
+    const out = [];
+    for (const m of models) {
+        if (!isOrFreeModel(m))
+            continue;
+        const raw = (m.id || "").trim();
+        let id;
+        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() {
+    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;
+        assertOpenRouterModel(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));
+    // 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) {
+    const j = JSON.parse(raw);
+    if (Array.isArray(j))
+        return j;
+    if (Array.isArray(j.data))
+        return j.data;
+    return [];
+}
+export function loadOrCatalog() {
+    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() {
+    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) {
+    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 = {
+        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) {
+    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/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,9 +1,9 @@
 ---
 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.13 (publishing this slice)
 created: 2026-08-12
-updated: 2026-08-21
+updated: 2026-08-29
 ---
 
 # cursor-route — living brief
@@ -18,28 +18,31 @@ Cursor Agent plans. Workers run in tmux via `cursor-route`:
 
 | Lane | Worker | Intent |
 |------|--------|--------|
-| `easy` | OpenRouter free | Wording / drafts — non-secret prompts only |
-| `mid` | claude-ds (DeepSeek behind Claude Code) | Default implement (**Flash**; `--model pro` when needed) |
+| `easy` | OpenRouter free (live pick) | Wording / drafts — non-secret prompts only |
+| `mid` | claude-ds (DeepSeek behind Claude Code) | Default implement (**Flash**; `--model vision` for screenshots; `--model pro` harder mid / hard backup only) |
 | `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.13**. Release notes: [CHANGELOG.md](../../CHANGELOG.md).
 
 ## Open (edit / check off)
 
 - [x] **Flash vs Pro on the CLI** — public default **Flash**; `--model pro` → `deepseek-v4-pro` (LIVE 0.1.6+)
   - [x] pass `claude-ds -Model deepseek-v4-flash|deepseek-v4-pro` from the adapter
   - [x] add `--model flash|pro` on `start`
-  - [x] document Grok **auth** ≠ usage-out (`grok login`) vs quota → Pro stand-in
+  - [x] document Grok **auth** ≠ usage-out (`grok login`); Flash-first when Grok **usage** is out; Pro = harder mid / hard backup only (0.1.12)
 - [x] **Skill `route-orch`** — Flash/Pro table in `skills/` + `.cursor/skills/`
 - [x] **Official DeepSeek Harness** — `deepseek` adapter slot present; `@deepseek-ai/dsh` 0.1.0-rc.6 (2026-08-13, github.com/deepseek-ai/deepseek-harness, MIT) is a developer-preview plugin kernel (web UI + `dsh --profile headless "job"`), not a Claude Code replacement; mid does not swap
 - [x] **0.1.7 debug fixes** — env default wired through `startJob`; Anthropic hatch omits DS ids; preserve `[1m]`
 - [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).
+- [x] **Flash-first + vision + live OpenRouter pick** — 0.1.12: `--model flash` stays the cheap Grok-out default; `--model vision` + screenshot auto-pick; easy lane live-picks free OpenRouter text models (`openrouter/free` is fetch-fail fallback only). Health never fetches `/models`. `route-orch` ProgRouter + MoRe one-liners. Hero fixture regenerated to 0.1.12. No npm publish in this slice.
+- [x] **Kimi 0.1.13 follow-up** — do not cache OpenRouter fallback; health labels uncached fallback; no Authorization on GET /models; env-invalid model error names the env vars; `\bimage\b` vision trigger.
 - [ ] **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 +56,8 @@ 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` |
+| `src/or-free.ts` | Live OpenRouter catalog rank for easy-lane `--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 +76,7 @@ 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. |
+| 2026-08-29 | Flash-first docs, `--model vision` + auto-pick, live OpenRouter free pick, route-orch K318/K322, hero fixture 0.1.12. No npm publish. |
+| 2026-08-29 | Kimi audit follow-up → 0.1.13: no fallback cache, health labels, unauth GET /models, env error wording. |

package/docs/demo-notes.md

@@ -6,10 +6,10 @@ Simulated capture output for README / tweet assets — replace with a real GIF o
 
 ```
 $ cursor-route --version
-0.1.9
+0.1.13
 
 $ cursor-route health
-cursor-route v0.1.9
+cursor-route v0.1.13
 health: OK
   ✓ tmux
   ✓ runtime          bun ok
@@ -32,7 +32,7 @@ $ cursor-route jobs --json
 
 Verified locally (2026-08-10): headless `claude-ds` smoke returned `CURSOR_ROUTE_SMOKE_OK`.
 Grok smoke hit 402 (Build usage balance exhausted) — auth/PATH wiring works; top up Grok Build for live demos.
-Use `--model pro` when Grok **usage** is out (not the same as a missing `grok login`).
+Use `--model flash` when Grok **usage** is out (cheap default). `--model pro` is harder mid / hard backup only — not the default Grok-out stand-in. A missing `grok login` is auth, not the Pro case.
 
 Current commands: `health`, `start`, `jobs`, `status`, `capture`, `send`, `attach`, `kill`, `sessions`, `clean`.
 Headless demos (no tmux) use `--no-tmux` and `capture`/`status` instead of `attach`/`send`.

package/docs/fixtures/generate-hero-demo.sh

@@ -23,8 +23,11 @@ unset CURSOR_ROUTE_CLAUDE_DS_BIN CURSOR_ROUTE_GROK_BIN CURSOR_ROUTE_DSH_BIN \
   CURSOR_ROUTE_ALLOW_ANTHROPIC \
   CURSOR_ROUTE_ALLOW_STOCK_CLAUDE CURSOR_ROUTE_ANTHROPIC_BASE_URL CURSOR_ROUTE_DS_MODEL \
   CURSOR_ROUTE_OPENROUTER_MODEL OPENROUTER_API_KEY OPENROUTER_BASE_URL \
+  CURSOR_ROUTE_OR_CATALOG_JSON CURSOR_ROUTE_OR_CACHE_PATH CURSOR_ROUTE_OR_REFRESH \
   ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY ANTHROPIC_MODEL \
   DEEPSEEK_API_KEY XAI_API_KEY 2>/dev/null || true
+# Stable easy-lane dry-run: do not fetch the live catalog while generating the fixture.
+export CURSOR_ROUTE_OR_OFFLINE=1
 
 TMP="$(mktemp -d)"
 trap 'rm -rf "$TMP"' EXIT

package/docs/fixtures/hero-demo.log

@@ -1,8 +1,8 @@
 $ cursor-route --version
-0.1.9
+0.1.13
 
 $ CURSOR_ROUTE_RELAXED=1 cursor-route health
-cursor-route v0.1.9
+cursor-route v0.1.13
 health: OK
 
   ✓ tmux             ok
@@ -10,8 +10,9 @@ health: OK
   ✓ script(1)        ok (tty log capture)
   ✓ worker:grok      ok (auth checked at first start — run grok login if jobs fail) @ ~/.grok/bin/grok
   ✓ worker:claude-ds ok (claude-ds (DeepSeek shim); default model deepseek-v4-flash) @ ~/.local/bin/claude-ds
-  ✗ worker:openrouter OPENROUTER_API_KEY not set — export your OpenRouter key (easy lane model defaults to openrouter/free) @ node '~/Projects/cursor-route/dist/openrouter-run.js'
+  ✗ worker:openrouter OPENROUTER_API_KEY not set — export your OpenRouter key (easy lane live-picks a free model at start; pin with CURSOR_ROUTE_OPENROUTER_MODEL) @ node '~/Projects/cursor-route/dist/openrouter-run.js'
   ✗ worker:deepseek  dsh (@deepseek-ai/dsh) not found — install: npm i -g @deepseek-ai/dsh. Mid default remains claude-ds.
+  ✓ worker:opencode  ok (opencode run; --model free = live Zen pick, now opencode/x-preview-f-free; auth at first start — opencode auth login if jobs fail; mid default remains claude-ds) @ ~/.local/bin/opencode
   ✓ lane:mid         DeepSeek proven (claude-ds (DeepSeek shim))
   ✓ cursor_cli       optional ok (agent on PATH) — v0 supervisor is Cursor skill, not CLI
   ✓ relaxed          CURSOR_ROUTE_RELAXED=1 — tmux optional (headless OK)
@@ -26,6 +27,7 @@ command: cd '~/Projects/cursor-route' && '~/.local/bin/claude-ds' -PromptFile '~
 $ cursor-route start --lane easy --dry-run "Rewrite this FAQ answer in 3 sentences"
 dry-run job b2c3d4e5
 worker: openrouter
+model:  openrouter/free
 command: node '~/Projects/cursor-route/dist/openrouter-run.js' --prompt-file '~/.local/share/cursor-route/jobs/b2c3d4e5.prompt'
 
 $ cursor-route start --lane hard --dry-run "Refactor auth module; run tests; report verify evidence"

package/llms.txt

@@ -2,39 +2,41 @@
 
 > 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.13**)
 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.
 
 ### Does mid lane use Anthropic Claude?
-No. The mid worker is DeepSeek. Claude Code is the harness, configured with `ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic` and a DeepSeek key in `ANTHROPIC_AUTH_TOKEN`. Default model is Flash (`--model flash`); use `--model pro` for harder mid work or when Grok usage is exhausted (not the same as a missing `grok login`).
+No. The mid worker is DeepSeek. Claude Code is the harness, configured with `ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic` and a DeepSeek key in `ANTHROPIC_AUTH_TOKEN`. Default model is Flash (`--model flash`) — keep Flash when Grok **usage** is out. `--model vision` is for screenshots / ui mocks. `--model pro` is harder mid / **hard backup only**, not the default Grok-out stand-in. A missing `grok login` is auth, not the Pro case.
 
 ### Flash vs Pro?
 | Flag | Model | When |
 |------|-------|------|
-| `--model flash` (default) | `deepseek-v4-flash` | Cheap mid execute |
-| `--model pro` | `deepseek-v4-pro` | Harder mid / Grok usage stand-in |
+| `--model flash` (default) | `deepseek-v4-flash` | Cheap mid execute. Prefer this when Grok **usage** is out |
+| `--model vision` | `deepseek-v4-flash-vision-exp` | Screenshots / ui mocks / image prompts (or auto-pick) |
+| `--model pro` | `deepseek-v4-pro` | Harder mid / **hard backup** only — not the default Grok-out stand-in |
+| `--model deepseek-v4-pro[1m]` | preserved SKU | Large-context Pro |
 
 ### 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
 
 ### 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 use OpenCode Zen free models.
+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 live-picks a free OpenRouter text model at start (fallback router `openrouter/free` only if the catalog fetch fails). `--worker opencode` can use OpenCode Zen free models.
 
 ## Install
 
 - npm: `npm i -g cursor-route`
 - Health: `cursor-route health`
-- Mid: `cursor-route start --lane mid "…"` (Flash) · `--model pro` when needed
+- Mid: `cursor-route start --lane mid "…"` (Flash; keep Flash when Grok usage is out) · `--model vision` for screenshots · `--model pro` harder mid / hard backup only
 - OpenCode (opt-in): `cursor-route start --worker opencode "…"`
 - Skill: `/route-orch` (Cursor)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-route",
-  "version": "0.1.10",
+  "version": "0.1.13",
   "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",