cursor-route 0.1.11 → 0.1.13

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/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.11 (LIVE on npm latest)
+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,21 +18,21 @@ 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; `--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.11**. 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]`
@@ -41,6 +41,8 @@ Install: `npm i -g cursor-route` → **0.1.11**. Release notes: [CHANGELOG.md](.
 - [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`; 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
 
@@ -55,6 +57,7 @@ Install: `npm i -g cursor-route` → **0.1.11**. Release notes: [CHANGELOG.md](.
 | `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 |
@@ -75,3 +78,5 @@ Install: `npm i -g cursor-route` → **0.1.11**. Release notes: [CHANGELOG.md](.
 | 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 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,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.11**)
+MIT CLI + Cursor skill. npm: https://www.npmjs.com/package/cursor-route (latest **0.1.13**)
 GitHub: https://github.com/cemini23/cursor-route
 
 ## FAQ
@@ -14,13 +14,15 @@ cursor-route is a public MIT CLI and Cursor skill that runs parallel coding work
 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 "…"`. `--model free` ranks live Zen free models (Ox Alpha first while listed). Mid stays `claude-ds`.
@@ -29,12 +31,12 @@ Install OpenCode (`npm i -g opencode-ai`), run `opencode auth login`, then `curs
 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.11",
+  "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",

package/skills/route-orch/SKILL.md

@@ -24,27 +24,30 @@ You are the **orchestrator**. Do **not** implement bulk code in this Cursor sess
 
 | Lane | Worker | Use when |
 |------|--------|----------|
-| `easy` | `openrouter` (OpenRouter free models) | Wording / drafts — non-secret prompts only |
+| `easy` | `openrouter` (live OpenRouter free pick) | Wording / drafts — non-secret prompts only |
 | `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).
+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.
 
 ## claude-ds models
 
 One harness. Do not install a second coding loop.
 
-| Flag / role | Model | When |
-|-------------|-------|------|
-| default mid (`--model flash`) | `deepseek-v4-flash` | `--lane mid` cheap execute |
-| Grok stand-in (`--model pro`) | `deepseek-v4-pro` | Grok CLI **usage/quota** out (not a missing `grok login`) |
+| Flag | Model id | When |
+|------|----------|------|
+| `--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 |
 
 ```bash
 cursor-route start --lane mid --dir "$PWD" "…"
+cursor-route start --lane mid --model vision --dir "$PWD" "…"
 cursor-route start --lane mid --model pro --dir "$PWD" "…"
 ```
 
-If `worker:grok` is ✗ on health, that is usually **auth** (`grok login` / `XAI_API_KEY`) — not the Pro stand-in case.
+If `worker:grok` is ✗ on health, that is usually **auth** (`grok login` / `XAI_API_KEY`) — not the Pro case. When Grok **usage** is out, stay on Flash.
 
 ## Experimental: --worker deepseek (dsh)
 
@@ -116,6 +119,8 @@ Verify criteria are an **external eval contract** (AutoDesign pattern), fixed by
 - **External eval contract (AutoDesign):** do not rewrite Verify / Success criteria mid-run to make a failing job look green — capture + exit status are the contract (see Verify / claim closeout).
 - **Skill misevolution:** do not auto-edit `route-orch` or promote skill variants from worker trajectories without operator HITL — write-time approval ≠ safe retrieval later.
 - **On verify fail:** prefer reconsidering the plan/definition (wrong approach) over grinding the same tactic; attribute failure to stage when possible (spawn vs execute vs verify).
+- **Step-wise re-route (ProgRouter):** `--lane` is the first pick. If progress stalls or verify fails, `send` a correction or spawn a follow-up on a different worker/model — do not lock the first worker for the whole job. Parent still closes on capture/exit evidence.
+- **Do not auto-spawn N panes for multi-perspective:** spawn workers for **implementation parallelism** (independent files/jobs). Multi-perspective reasoning stays in the Cursor parent. Do not fan out “one agent per viewpoint.”
 
 ## Always-approve
 

package/src/adapters/claude-ds.ts

@@ -212,7 +212,7 @@ export const claudeDsAdapter: Adapter = {
       resolved.mode.startsWith("claude-ds") || resolved.mode.startsWith("deepseek-claude");
 
     // Anthropic escape hatch: do not pass DeepSeek model ids (unknown to Anthropic).
-    // --model flash|pro is DeepSeek-only; stock Claude uses its own defaults / ANTHROPIC_MODEL.
+    // --model flash|pro|vision is DeepSeek-only; stock Claude uses its own defaults / ANTHROPIC_MODEL.
     if (isAnthropicEscape) {
       const parts = [
         shellQuote(resolved.binary),

package/src/adapters/openrouter.test.ts

@@ -11,6 +11,10 @@ afterEach(() => {
   delete process.env.OPENROUTER_API_KEY;
   delete process.env.CURSOR_ROUTE_OPENROUTER_MODEL;
   delete process.env.OPENROUTER_BASE_URL;
+  delete process.env.CURSOR_ROUTE_OR_OFFLINE;
+  delete process.env.CURSOR_ROUTE_OR_CATALOG_JSON;
+  delete process.env.CURSOR_ROUTE_OR_CACHE_PATH;
+  delete process.env.CURSOR_ROUTE_OR_REFRESH;
 });
 
 describe("openrouter adapter", () => {
@@ -20,13 +24,38 @@ describe("openrouter adapter", () => {
     expect(h.worker).toBe("openrouter");
     expect(h.ok).toBe(false);
     expect(h.detail).toContain("OPENROUTER_API_KEY");
+    expect(h.detail).not.toMatch(/defaults to openrouter\/free/);
   });
 
   test("health passes with a fake key (no network)", () => {
     setKey();
-    const h = openRouterAdapter.health();
-    expect(h.ok).toBe(true);
-    expect(h.detail).toContain("openrouter/free");
+    const prev = {
+      model: process.env.CURSOR_ROUTE_OPENROUTER_MODEL,
+      offline: process.env.CURSOR_ROUTE_OR_OFFLINE,
+      json: process.env.CURSOR_ROUTE_OR_CATALOG_JSON,
+      cache: process.env.CURSOR_ROUTE_OR_CACHE_PATH,
+    };
+    delete process.env.CURSOR_ROUTE_OPENROUTER_MODEL;
+    process.env.CURSOR_ROUTE_OR_OFFLINE = "1";
+    delete process.env.CURSOR_ROUTE_OR_CATALOG_JSON;
+    process.env.CURSOR_ROUTE_OR_CACHE_PATH = "/tmp/cursor-route-or-health-missing.json";
+    try {
+      const h = openRouterAdapter.health();
+      expect(h.ok).toBe(true);
+      expect(h.detail.toLowerCase()).toMatch(/live pick/);
+      expect(h.detail).toMatch(/fallback/);
+      expect(h.detail).not.toMatch(/now openrouter\/free/);
+      expect(h.detail).not.toMatch(/defaults to openrouter\/free/);
+    } finally {
+      if (prev.model === undefined) delete process.env.CURSOR_ROUTE_OPENROUTER_MODEL;
+      else process.env.CURSOR_ROUTE_OPENROUTER_MODEL = prev.model;
+      if (prev.offline === undefined) delete process.env.CURSOR_ROUTE_OR_OFFLINE;
+      else process.env.CURSOR_ROUTE_OR_OFFLINE = prev.offline;
+      if (prev.json === undefined) delete process.env.CURSOR_ROUTE_OR_CATALOG_JSON;
+      else process.env.CURSOR_ROUTE_OR_CATALOG_JSON = prev.json;
+      if (prev.cache === undefined) delete process.env.CURSOR_ROUTE_OR_CACHE_PATH;
+      else process.env.CURSOR_ROUTE_OR_CACHE_PATH = prev.cache;
+    }
   });
 
   test("buildLaunch passes key via env and never echoes it in the command", () => {

package/src/adapters/openrouter.ts

@@ -3,7 +3,11 @@ import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import type { Adapter, WorkerHealth } from "./types.ts";
 import { shellQuote } from "../util.ts";
-import { openRouterModel, openRouterBaseUrl } from "../config.ts";
+import {
+  cachedOrFreePick,
+  OPENROUTER_FALLBACK_MODEL,
+  openRouterBaseUrl,
+} from "../config.ts";
 
 /**
  * Resolve how to invoke the one-shot runner. Prefer the compiled dist via node
@@ -22,11 +26,11 @@ function resolveRunner(): { command: string } | null {
   return null;
 }
 
-function openRouterEnv(): Record<string, string> | undefined {
+function openRouterEnv(modelId?: string): Record<string, string> | undefined {
   const key = process.env.OPENROUTER_API_KEY;
   if (!key) return undefined;
   const env: Record<string, string> = { OPENROUTER_API_KEY: key };
-  const model = process.env.CURSOR_ROUTE_OPENROUTER_MODEL;
+  const model = modelId || process.env.CURSOR_ROUTE_OPENROUTER_MODEL;
   if (model) env.CURSOR_ROUTE_OPENROUTER_MODEL = model;
   const base = process.env.OPENROUTER_BASE_URL;
   if (base) env.OPENROUTER_BASE_URL = base;
@@ -44,7 +48,7 @@ export const openRouterAdapter: Adapter = {
         ok: false,
         binary: runner?.command ?? null,
         detail:
-          "OPENROUTER_API_KEY not set — export your OpenRouter key (easy lane model defaults to openrouter/free)",
+          "OPENROUTER_API_KEY not set — export your OpenRouter key (easy lane live-picks a free model at start; pin with CURSOR_ROUTE_OPENROUTER_MODEL)",
       };
     }
     if (!runner) {
@@ -55,19 +59,25 @@ export const openRouterAdapter: Adapter = {
         detail: "openrouter-run not found — run bun run build (or use Bun from a source clone)",
       };
     }
+    // Health stays offline: ranked cache hit, else label the router fallback
+    // (do not present openrouter/free as a fresh live pick).
+    const cached = cachedOrFreePick();
+    const detail = cached
+      ? `ok (live pick at start; cached ${cached} @ ${openRouterBaseUrl()})`
+      : `ok (live pick at start; no catalog cache, fetch-fail fallback ${OPENROUTER_FALLBACK_MODEL} @ ${openRouterBaseUrl()})`;
     return {
       worker: "openrouter",
       ok: true,
       binary: runner.command,
-      detail: `ok (model ${openRouterModel()} @ ${openRouterBaseUrl()})`,
+      detail,
     };
   },
-  buildLaunch({ promptFile }) {
+  buildLaunch({ promptFile, modelId }) {
     const runner = resolveRunner();
     if (!runner) throw new Error("openrouter runner not available — run: bun run build");
     // Missing key is tolerated here so `--dry-run` can still print the command;
     // real starts are gated by the health preflight (which requires the key).
-    const env = openRouterEnv();
+    const env = openRouterEnv(modelId);
 
     // No interactive approval concept for a pure HTTP call — nothing to auto-approve.
     return {

package/src/adapters/types.ts

@@ -24,9 +24,9 @@ export interface Adapter {
     promptFile: string;
     cwd: string;
     alwaysApprove: boolean;
-    /** Mid-lane DeepSeek flash|pro (claude-ds + deepseek; ignored by grok/openrouter / Anthropic escape hatch). */
+    /** Mid-lane DeepSeek flash|pro|vision (claude-ds + deepseek; ignored by grok / Anthropic escape hatch). */
     model?: DsModelAlias;
-    /** Concrete DeepSeek id (preserves pro[1m]) or OpenCode provider/model. */
+    /** Concrete DeepSeek id (preserves pro[1m]) or OpenCode/OpenRouter provider/model. */
     modelId?: string;
     /** True on --dry-run: adapters may drop artifacts they just wrote (e.g. dsh patch). */
     dryRun?: boolean;