cursor-route 0.1.13 → 0.1.14

package/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 _(none)_
 
+## 0.1.14 — 2026-09-02
+
+- Easy-lane OpenRouter live pick now **tier-ranks** free models like the toolkit: Qwen 100, GLM/Kimi 95, DeepSeek 90, coding/chat families 70, **Nemotron 15**, default 40. Score adds a context bonus capped at 131072 (`tier + min(ctx, 131072)/131072 × 5`) so a huge Nemotron 550B free model can no longer outrank Qwen/GLM/Kimi on context alone.
+- Tests: all seven tier buckets; equal-score tier/id tiebreakers; same-tier 131072-vs-262144 cap; ranked-pick cache round-trip.
+- Mid lane still `claude-ds`; no worker swap. Hero demo fixture regenerated to **0.1.14**.
+
 ## 0.1.13 — 2026-08-29
 
 - OpenRouter live-pick: do **not** cache the fetch-fail fallback (`openrouter/free`) — health no longer presents a stale fallback as `now openrouter/free`. Health says `cached <id>` only for a ranked catalog hit; otherwise `no catalog cache, fetch-fail fallback openrouter/free`.

package/README.md

@@ -116,10 +116,10 @@ docs/fixtures/generate-hero-demo.sh      # regenerate docs/fixtures/hero-demo.lo
 
 ```text
 $ cursor-route --version
-0.1.13
+0.1.14
 
 $ CURSOR_ROUTE_RELAXED=1 cursor-route health
-cursor-route v0.1.13
+cursor-route v0.1.14
 health: OK
 
 $ cursor-route start --lane mid --model flash --dry-run "Add a unit test for shellQuote"
@@ -214,7 +214,9 @@ No DeepSeek yet? Use `--lane hard` / `--worker grok` (X Premium).
 
 `--lane easy` / `--worker openrouter` sends wording/draft prompts to OpenRouter
 and **live-picks the best free text model** at request time (`GET /models`, rank
-`:free` or $0 text models). Do not hardcode a specific model id as the default.
+`:free` or $0 text models). The live rank prefers Qwen/GLM/Kimi coding free
+models over huge general free models (e.g. Nemotron 550B). Do not hardcode a
+specific model id as the default.
 Pin with `CURSOR_ROUTE_OPENROUTER_MODEL` or `--model provider/model`. Empty /
 `free` = live pick. If the catalog fetch fails, the fallback is OpenRouter's
 **router** id `openrouter/free` (a live router, not a locked model). Get a key

package/dist/config.js

@@ -72,7 +72,7 @@ function maxConcurrentJobsFromEnv() {
  */
 export const config = {
     product: "cursor-route",
-    version: "0.1.13",
+    version: "0.1.14",
     get jobsDir() {
         return defaultJobsDir();
     },

package/dist/or-free.js

@@ -12,7 +12,6 @@ export const OPENROUTER_MODELS_URL_DEFAULT = "https://openrouter.ai/api/v1/model
 /** 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()
@@ -59,9 +58,28 @@ export function isOrFreeModel(m) {
     const tagged = id.endsWith(":free");
     return tagged || pricedFree;
 }
-/** Higher boost wins. Coding/chat families beat generic free. No hardcoded id. */
+/**
+ * Toolkit-parity tier for a live OpenRouter free model id (first match wins).
+ * Huge general free models (Nemotron) rank well below coding/chat families so
+ * the easy-lane live pick does not land on a slow 550B generalist. Order
+ * matters: `qwen` is checked before `nemotron`, and the generic coding bucket
+ * (70) sits before `nemotron` exactly like the toolkit, so
+ * `nvidia/nemotron-3-550b:free` scores 15 — never 70. No hardcoded model id.
+ */
 export function orFreeBoost(id) {
-    return BOOST_RE.test(id) ? 20 : 10;
+    if (/qwen/i.test(id))
+        return 100;
+    if (/(^|\/)z-ai\/glm|glm/i.test(id))
+        return 95;
+    if (/kimi|moonshot/i.test(id))
+        return 95;
+    if (/deepseek|hy-/i.test(id))
+        return 90;
+    if (/coder|instruct|chat|llama|gemma|gpt-oss|minimax/i.test(id))
+        return 70;
+    if (/nemotron/i.test(id))
+        return 15;
+    return 40;
 }
 export function rankOrFreeModels(models) {
     const out = [];
@@ -77,18 +95,24 @@ export function rankOrFreeModels(models) {
             continue;
         }
         const ctx = Number.isFinite(Number(m.context_length)) ? Number(m.context_length) : 0;
+        const tier = orFreeBoost(id);
+        // Cap the context bonus at 131072 so a huge Nemotron ctx cannot outrank a
+        // higher tier on context alone: score = tier + min(ctx, 131072)/131072 * 5.
+        const score = tier + (Math.min(ctx, 131_072) / 131_072) * 5;
         out.push({
             id,
             name: (m.name || raw).trim(),
             context_length: ctx,
-            boost: orFreeBoost(id),
+            boost: score,
         });
     }
+    // Sort like the toolkit: score desc, then tier desc, then id asc.
     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;
+        const tierDiff = orFreeBoost(b.id) - orFreeBoost(a.id);
+        if (tierDiff !== 0)
+            return tierDiff;
         return a.id.localeCompare(b.id);
     });
     return out;

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.13 (publishing this slice)
+npm: cursor-route@0.1.14 (not yet published — Kimi audit next)
 created: 2026-08-12
-updated: 2026-08-29
+updated: 2026-09-02
 ---
 
 # cursor-route — living brief
@@ -43,6 +43,7 @@ Install: `npm i -g cursor-route` → **0.1.13**. Release notes: [CHANGELOG.md](.
 - [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.
+- [x] **Super-audit OR ranker parity (0.1.14)** — tier-rank Qwen/GLM/Kimi above Nemotron 550B in `or-free.ts` (match agent-toolkit `select-openrouter-free-model.ps1`); brief `docs/briefs/2026-09-02_super-audit-or-ranker-parity.md`
 - [ ] **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
 
@@ -79,4 +80,5 @@ Install: `npm i -g cursor-route` → **0.1.13**. Release notes: [CHANGELOG.md](.
 | 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. |
+| 2026-08-29 | Kimi audit follow-up → 0.1.13 LIVE on npm: no fallback cache, health labels, unauth GET /models, env error wording. |
+| 2026-09-02 | Tier-rank OpenRouter free picks in `or-free.ts` (Qwen 100 / GLM-Kimi 95 / DeepSeek 90 / coding 70 / Nemotron 15 / default 40; ctx bonus capped at 131072) → 0.1.14. Commit + tag `v0.1.14`. **No npm publish** — parent Kimi-audits then publishes. Mid stays claude-ds. |

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.13
+0.1.14
 
 $ cursor-route health
-cursor-route v0.1.13
+cursor-route v0.1.14
 health: OK
   ✓ tmux
   ✓ runtime          bun ok

package/docs/fixtures/hero-demo.log

@@ -1,8 +1,8 @@
 $ cursor-route --version
-0.1.13
+0.1.14
 
 $ CURSOR_ROUTE_RELAXED=1 cursor-route health
-cursor-route v0.1.13
+cursor-route v0.1.14
 health: OK
 
   ✓ tmux             ok

package/llms.txt

@@ -2,7 +2,7 @@
 
 > 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.13**)
+MIT CLI + Cursor skill. npm: https://www.npmjs.com/package/cursor-route (latest **0.1.14**)
 GitHub: https://github.com/cemini23/cursor-route
 
 ## FAQ

package/package.json

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

@@ -28,7 +28,7 @@ You are the **orchestrator**. Do **not** implement bulk code in this Cursor sess
 | `mid` | `claude-ds` (DeepSeek via Claude Code harness) | Standard implement / refactor |
 | `hard` | `grok` | Premium plan in Cursor → Grok implement |
 
-Free OpenRouter models may log prompts — keep secrets off the easy lane (the CLI refuse gate still applies). Easy lane **live-picks** the best free text model at request time (unset / `--model free`). Pin with `CURSOR_ROUTE_OPENROUTER_MODEL` or `--model provider/model`. Fetch-fail fallback is the OpenRouter router `openrouter/free` only.
+Free OpenRouter models may log prompts — keep secrets off the easy lane (the CLI refuse gate still applies). Easy lane **live-picks** the best free text model at request time (unset / `--model free`), preferring Qwen/GLM/Kimi coding free models over huge general free models (Nemotron). Pin with `CURSOR_ROUTE_OPENROUTER_MODEL` or `--model provider/model`. Fetch-fail fallback is the OpenRouter router `openrouter/free` only.
 
 ## claude-ds models
 

package/src/cli.test.ts

@@ -879,7 +879,7 @@ describe("health", () => {
   test("returns structured report", () => {
     const r = runHealth();
     expect(r.product).toBe("cursor-route");
-    expect(r.version).toBe("0.1.13");
+    expect(r.version).toBe("0.1.14");
     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);
@@ -891,8 +891,8 @@ describe("health", () => {
     expect(r.checks.some((c) => c.name === "worker:deepseek")).toBe(true);
   });
 
-  test("config version is 0.1.13", () => {
-    expect(config.version).toBe("0.1.13");
+  test("config version is 0.1.14", () => {
+    expect(config.version).toBe("0.1.14");
   });
 
   test("OR-gate: ok can be true while worker:opencode is false", () => {

package/src/config.ts

@@ -111,7 +111,7 @@ function maxConcurrentJobsFromEnv(): number {
  */
 export const config = {
   product: "cursor-route",
-  version: "0.1.13",
+  version: "0.1.14",
   get jobsDir(): string {
     return defaultJobsDir();
   },

package/src/or-free.test.ts

@@ -62,10 +62,13 @@ describe("openrouter free catalog", () => {
     ).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("boost: tier ranks Qwen/GLM/Kimi above Nemotron; generic free is default", () => {
+    expect(orFreeBoost("qwen/qwen-coder:free")).toBe(100);
+    expect(orFreeBoost("z-ai/glm-5.2:free")).toBe(95);
+    expect(orFreeBoost("moonshotai/kimi-k2:free")).toBe(95);
+    expect(orFreeBoost("acme/generic:free")).toBe(40);
+    expect(orFreeBoost("meta-llama/llama-3.3-70b-instruct:free")).toBe(70);
+    expect(orFreeBoost("nvidia/nemotron-3-550b:free")).toBe(15);
   });
 
   test("rank prefers a :free coder with larger context over a generic :free", () => {
@@ -85,10 +88,83 @@ describe("openrouter free catalog", () => {
     expect(ranked[1]?.id).toBe("qwen/small-coder:free");
   });
 
+  test("all seven tier buckets", () => {
+    expect(orFreeBoost("qwen/qwen3-coder:free")).toBe(100);
+    expect(orFreeBoost("z-ai/glm-5.2:free")).toBe(95);
+    expect(orFreeBoost("moonshotai/kimi-k2:free")).toBe(95);
+    expect(orFreeBoost("deepseek/deepseek-chat:free")).toBe(90);
+    expect(orFreeBoost("acme/hy-foo:free")).toBe(90);
+    expect(orFreeBoost("meta-llama/llama-3.3-70b-instruct:free")).toBe(70);
+    expect(orFreeBoost("google/gemma-3-12b:free")).toBe(70);
+    expect(orFreeBoost("openai/gpt-oss-120b:free")).toBe(70);
+    expect(orFreeBoost("minimax/minimax-m1:free")).toBe(70);
+    expect(orFreeBoost("nvidia/nemotron-3-550b:free")).toBe(15);
+    expect(orFreeBoost("acme/generic:free")).toBe(40);
+  });
+
+  test("equal score: higher tier wins (Qwen ctx 0 vs GLM at ctx cap)", () => {
+    const ranked = rankOrFreeModels([
+      { id: "qwen/qwen3-coder:free", context_length: 0 },
+      { id: "z-ai/glm-5.2:free", context_length: 131_072 },
+    ]);
+    expect(ranked[0]?.boost).toBe(ranked[1]?.boost);
+    expect(ranked[0]?.id).toBe("qwen/qwen3-coder:free");
+  });
+
+  test("equal score same tier: id ascending", () => {
+    const ranked = rankOrFreeModels([
+      { id: "qwen/zzz-coder:free", context_length: 8_000 },
+      { id: "qwen/aaa-coder:free", context_length: 8_000 },
+    ]);
+    expect(ranked[0]?.id).toBe("qwen/aaa-coder:free");
+    expect(ranked[1]?.id).toBe("qwen/zzz-coder:free");
+  });
+
+  test("ctx bonus caps at 131072: same-tier 131072 vs 262144 ties then id asc", () => {
+    const ranked = rankOrFreeModels([
+      { id: "qwen/zzz-coder:free", context_length: 262_144 },
+      { id: "qwen/aaa-coder:free", context_length: 131_072 },
+    ]);
+    expect(ranked[0]?.boost).toBe(ranked[1]?.boost);
+    expect(ranked[0]?.id).toBe("qwen/aaa-coder:free");
+  });
+
+  test("huge Nemotron free model loses to GLM/Qwen on tier rank", () => {
+    const ranked = rankOrFreeModels([
+      { id: "nvidia/nemotron-3-550b:free", name: "Nemotron 3 550B", context_length: 262_144 },
+      { id: "z-ai/glm-5.2:free", name: "GLM 5.2", context_length: 32_768 },
+      { id: "qwen/qwen3-coder:free", name: "Qwen3 Coder", context_length: 32_768 },
+    ]);
+    expect(ranked[0]?.id).toBe("qwen/qwen3-coder:free");
+    expect(ranked[0]?.id).not.toBe("nvidia/nemotron-3-550b:free");
+    expect(ranked[1]?.id).toBe("z-ai/glm-5.2:free");
+    expect(ranked[2]?.id).toBe("nvidia/nemotron-3-550b:free");
+    expect(ranked[0]!.boost).toBeGreaterThan(ranked[2]!.boost);
+  });
+
+  test("huge ctx alone does not beat a higher tier (ctx bonus caps at 131072)", () => {
+    const ranked = rankOrFreeModels([
+      { id: "nvidia/nemotron-3-550b:free", context_length: 1_048_576 },
+      { id: "qwen/qwen3-coder:free", context_length: 1_000 },
+    ]);
+    expect(ranked[0]?.id).toBe("qwen/qwen3-coder:free");
+  });
+
   test("pickOrFreeModel uses the ranked catalog winner", () => {
     expect(pickOrFreeModel({ catalog: CATALOG })).toBe("qwen/qwen-coder:free");
   });
 
+  test("pickOrFreeModel winner is not a huge Nemotron when GLM/Qwen are free", () => {
+    const winner = pickOrFreeModel({
+      catalog: [
+        { id: "nvidia/nemotron-3-550b:free", name: "Nemotron 3 550B", context_length: 262_144 },
+        { id: "z-ai/glm-5.2:free", name: "GLM 5.2", context_length: 32_768 },
+      ],
+    });
+    expect(winner).not.toBe("nvidia/nemotron-3-550b:free");
+    expect(winner).toBe("z-ai/glm-5.2: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");
@@ -175,6 +251,18 @@ describe("openRouterModel live pick", () => {
       expect(existsSync(cache)).toBe(false);
     });
   });
+
+  test("ranked pick is cached; offline second call returns the cached id", () => {
+    isolate(() => {
+      process.env.CURSOR_ROUTE_OR_CATALOG_JSON = JSON.stringify({ data: CATALOG });
+      expect(openRouterModel("free")).toBe("qwen/qwen-coder:free");
+      delete process.env.CURSOR_ROUTE_OR_REFRESH;
+      process.env.CURSOR_ROUTE_OR_OFFLINE = "1";
+      delete process.env.CURSOR_ROUTE_OR_CATALOG_JSON;
+      expect(existsSync(process.env.CURSOR_ROUTE_OR_CACHE_PATH!)).toBe(true);
+      expect(openRouterModel("free")).toBe("qwen/qwen-coder:free");
+    });
+  });
 });
 
 describe("openrouter health stays offline", () => {

package/src/or-free.ts

@@ -35,8 +35,6 @@ export interface OrFreePick {
 
 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")
@@ -88,9 +86,22 @@ export function isOrFreeModel(m: OrModel): boolean {
   return tagged || pricedFree;
 }
 
-/** Higher boost wins. Coding/chat families beat generic free. No hardcoded id. */
+/**
+ * Toolkit-parity tier for a live OpenRouter free model id (first match wins).
+ * Huge general free models (Nemotron) rank well below coding/chat families so
+ * the easy-lane live pick does not land on a slow 550B generalist. Order
+ * matters: `qwen` is checked before `nemotron`, and the generic coding bucket
+ * (70) sits before `nemotron` exactly like the toolkit, so
+ * `nvidia/nemotron-3-550b:free` scores 15 — never 70. No hardcoded model id.
+ */
 export function orFreeBoost(id: string): number {
-  return BOOST_RE.test(id) ? 20 : 10;
+  if (/qwen/i.test(id)) return 100;
+  if (/(^|\/)z-ai\/glm|glm/i.test(id)) return 95;
+  if (/kimi|moonshot/i.test(id)) return 95;
+  if (/deepseek|hy-/i.test(id)) return 90;
+  if (/coder|instruct|chat|llama|gemma|gpt-oss|minimax/i.test(id)) return 70;
+  if (/nemotron/i.test(id)) return 15;
+  return 40;
 }
 
 export function rankOrFreeModels(models: OrModel[]): Array<{
@@ -110,16 +121,22 @@ export function rankOrFreeModels(models: OrModel[]): Array<{
       continue;
     }
     const ctx = Number.isFinite(Number(m.context_length)) ? Number(m.context_length) : 0;
+    const tier = orFreeBoost(id);
+    // Cap the context bonus at 131072 so a huge Nemotron ctx cannot outrank a
+    // higher tier on context alone: score = tier + min(ctx, 131072)/131072 * 5.
+    const score = tier + (Math.min(ctx, 131_072) / 131_072) * 5;
     out.push({
       id,
       name: (m.name || raw).trim(),
       context_length: ctx,
-      boost: orFreeBoost(id),
+      boost: score,
     });
   }
+  // Sort like the toolkit: score desc, then tier desc, then id asc.
   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;
+    const tierDiff = orFreeBoost(b.id) - orFreeBoost(a.id);
+    if (tierDiff !== 0) return tierDiff;
     return a.id.localeCompare(b.id);
   });
   return out;