ruvnet-brain 2.0.0 → 2.4.1

package/config/model-router/catalog.template.json

@@ -0,0 +1,220 @@
+{
+  "_comment": "Model candidate catalog for model-router-engine.mjs. EDIT ME freely. Pricing is $/Mtok. 'verified' names the source+date a price was confirmed live; null pricing means UNKNOWN \u2014 the engine will NOT invent a cost for it (same honesty rule as route-cheap.mjs). 'harness' = which agent(s) can launch each model \u2014 EMPTY [] means landscape-only: known to exist, but no wired execution path yet, so the engine will never select it (see model-router-engine.mjs pool filter). Do not add a real execution path (an entry to route-cheap.mjs PRICING or a harness value) until dispatch is actually implemented and tested \u2014 an engine that 'chooses' a model it can't run is worse than one that doesn't know the model exists. 'subscription' = harness(es) under which this model is covered by a flat subscription (Claude Max, Codex/ChatGPT), so its marginal cost to the user is ~$0 \u2014 the default policy treats those as free and will NOT prefer a billed model over them (never spend where the subscription is free).",
+  "updated": "2026-07-12 (template)",
+  "candidates": [
+    {
+      "id": "claude-haiku-4-5-20251001",
+      "provider": "anthropic",
+      "harness": [
+        "claude-code"
+      ],
+      "subscription": [
+        "claude-code"
+      ],
+      "tier": "cheap",
+      "costPerMTok": null,
+      "verified": null,
+      "note": "covered by Claude Max under Claude Code (marginal $0); API price unverified"
+    },
+    {
+      "id": "claude-sonnet-5",
+      "provider": "anthropic",
+      "harness": [
+        "claude-code"
+      ],
+      "subscription": [
+        "claude-code"
+      ],
+      "tier": "mid",
+      "costPerMTok": null,
+      "verified": null
+    },
+    {
+      "id": "claude-opus-4-8",
+      "provider": "anthropic",
+      "harness": [
+        "claude-code"
+      ],
+      "subscription": [
+        "claude-code"
+      ],
+      "tier": "frontier",
+      "costPerMTok": {
+        "in": 5,
+        "out": 25
+      },
+      "verified": "2026-07-07 route-cheap.mjs FRONTIER (API price; $0 under Max)"
+    },
+    {
+      "id": "claude-fable-5",
+      "provider": "anthropic",
+      "harness": [
+        "claude-code"
+      ],
+      "subscription": [
+        "claude-code"
+      ],
+      "tier": "frontier",
+      "costPerMTok": null,
+      "verified": "2026-07-12 Artificial Analysis leaderboard (WebSearch) \u2014 listed as top-intelligence tier alongside GPT-5.6 Sol",
+      "note": "covered by Claude Max under Claude Code (marginal $0); API price unverified. Use sparingly per Stuart's directive \u2014 Opus 4.8 measures ~96% of comparable quality at far lower cost; Fable 5 is for tasks that specifically need its top-tier profile, not a default."
+    },
+    {
+      "id": "deepseek/deepseek-chat",
+      "provider": "openrouter",
+      "harness": [
+        "claude-code",
+        "codex"
+      ],
+      "subscription": [],
+      "tier": "cheap",
+      "costPerMTok": {
+        "in": 0.2002,
+        "out": 0.8001
+      },
+      "verified": "2026-07-12 OpenRouter API (goldie)",
+      "note": "Resolves to LEGACY DeepSeek V3 per OpenRouter model card (Goldie 2026-07-12) \u2014 superseded by deepseek/deepseek-v4-flash (landscape entry, cheaper+newer). Keep until v4-flash passes a measured quality check, then switch."
+    },
+    {
+      "id": "z-ai/glm-4.6",
+      "provider": "openrouter",
+      "harness": [
+        "claude-code",
+        "codex"
+      ],
+      "subscription": [],
+      "tier": "mid",
+      "costPerMTok": {
+        "in": 0.43,
+        "out": 1.75
+      },
+      "verified": "2026-07-12 OpenRouter API (goldie)"
+    },
+    {
+      "id": "z-ai/glm-5",
+      "provider": "openrouter",
+      "harness": [
+        "claude-code",
+        "codex"
+      ],
+      "subscription": [],
+      "tier": "mid",
+      "costPerMTok": {
+        "in": 0.6,
+        "out": 1.92
+      },
+      "verified": "2026-07-12 OpenRouter API (goldie)"
+    },
+    {
+      "id": "gpt-5.5",
+      "provider": "openai",
+      "harness": [
+        "codex"
+      ],
+      "subscription": [
+        "codex"
+      ],
+      "tier": "frontier",
+      "costPerMTok": null,
+      "verified": null,
+      "note": "Codex-harness model; whether YOUR install can launch it and whether a subscription covers it comes from profile.json (model-router-setup.mjs) and your live ~/.codex/models_cache.json"
+    },
+    {
+      "id": "gpt-5.6-sol",
+      "provider": "openai",
+      "harness": [],
+      "subscription": [],
+      "tier": "frontier",
+      "costPerMTok": null,
+      "verified": null,
+      "note": "Codex-harness model; whether YOUR install can launch it and whether a subscription covers it comes from profile.json (model-router-setup.mjs) and your live ~/.codex/models_cache.json"
+    },
+    {
+      "id": "gpt-5.6-terra",
+      "provider": "openai",
+      "harness": [],
+      "subscription": [],
+      "tier": "mid",
+      "costPerMTok": null,
+      "verified": null,
+      "note": "Codex-harness model; whether YOUR install can launch it and whether a subscription covers it comes from profile.json (model-router-setup.mjs) and your live ~/.codex/models_cache.json"
+    },
+    {
+      "id": "gpt-5.6-luna",
+      "provider": "openai",
+      "harness": [],
+      "subscription": [],
+      "tier": "cheap",
+      "costPerMTok": null,
+      "verified": null,
+      "note": "Codex-harness model; whether YOUR install can launch it and whether a subscription covers it comes from profile.json (model-router-setup.mjs) and your live ~/.codex/models_cache.json"
+    },
+    {
+      "id": "gpt-5-mini",
+      "provider": "openai",
+      "harness": [
+        "codex",
+        "claude-code"
+      ],
+      "subscription": [],
+      "tier": "mid",
+      "costPerMTok": null,
+      "verified": null
+    },
+    {
+      "id": "x-ai/grok-4.5",
+      "provider": "openrouter",
+      "harness": [
+        "claude-code",
+        "codex"
+      ],
+      "subscription": [],
+      "tier": "frontier",
+      "costPerMTok": {
+        "in": 2.0,
+        "out": 6.0
+      },
+      "verified": "2026-07-12 OpenRouter /models live (goldie judgment + direct API check)",
+      "note": "LANDSCAPE-ONLY, one step from wireable: live on OpenRouter (tools=true, ctx 500K) \u2014 the old 'needs a bespoke xAI adapter' note is obsolete. To wire: add to route-cheap.mjs PRICING + one tested dispatch + a measured quality check. Secondary-source numbers promising (SWE-bench Pro 64.7% between GLM-5.2 and Opus 4.8; ~4.2x fewer output tokens than Opus at max reasoning) \u2014 'mid priced, frontier-adjacent'. See goldie/2026-07-12.md Q3."
+    },
+    {
+      "id": "muse-spark-1.1",
+      "provider": "meta",
+      "harness": [],
+      "subscription": [],
+      "tier": null,
+      "costPerMTok": null,
+      "verified": "2026-07-12 Meta/Fortune announcement 2026-07-09 (WebSearch)",
+      "note": "LANDSCAPE-ONLY, not selectable: general-capability model (coding/captioning/reasoning per Meta's announcement) but developer/API accessibility, pricing, and tier are UNCONFIRMED \u2014 the announcement centers on Meta AI app / WhatsApp / Instagram integration, not a clear developer API. Do not assume this is reachable until that's verified."
+    },
+    {
+      "id": "deepseek/deepseek-v4-flash",
+      "provider": "openrouter",
+      "harness": [
+        "claude-code",
+        "codex"
+      ],
+      "subscription": [],
+      "tier": "cheap",
+      "costPerMTok": {
+        "in": 0.077,
+        "out": 0.154
+      },
+      "verified": "2026-07-12 OpenRouter /models live (direct API check)",
+      "note": "LANDSCAPE-ONLY: proposed successor to deepseek/deepseek-chat (which OpenRouter resolves to LEGACY DeepSeek V3 per its own model card \u2014 Goldie 2026-07-12). Full generation newer, ~5x cheaper output, tools=true, ctx 1M. Wire via route-cheap PRICING + tested dispatch + measured quality check before giving it a harness path."
+    },
+    {
+      "id": "tencent/hy3",
+      "provider": "openrouter",
+      "harness": [],
+      "subscription": [],
+      "tier": "cheap",
+      "costPerMTok": {
+        "in": 0.14,
+        "out": 0.58
+      },
+      "verified": "2026-07-12 OpenRouter /models live (direct API check)",
+      "note": "LANDSCAPE-ONLY: 295B MoE Apache-2.0, strong generalist, second-tier coder (SWE-bench V 78.0 vs GLM-5.2 84.2, vendor numbers). IMPORTANT: this is the PAID slug on purpose \u2014 the tencent/hy3:free promo window closes ~2026-07-20 and would silently die/bill; never wire the :free slug. See goldie/2026-07-12.md Q3."
+    }
+  ]
+}

package/config/model-router/policy.default.mjs

@@ -0,0 +1,83 @@
+// ~/.claude/model-router/policy.default.mjs — the DEFAULT (placeholder) routing policy.
+//
+// HOW TO SWAP IN YOUR HEURISTICS: create ~/.claude/model-router/policy.mjs with the same
+// `choose` signature. The engine prefers policy.mjs when it exists and only falls back to this
+// file otherwise. A learned router (e.g. a @metaharness/router / tiny-dancer JSON) can also be a
+// policy — load it inside choose() and map its output to {model, provider, tier}.
+//
+// SIGNATURE:
+//   choose({ features, candidates, harness }) -> { model, provider, tier, reason, confidence }
+//     features   = output of the engine's extractFeatures() (chars, estTokens, hasCode,
+//                  codeFences, fileTypes, questionCount, taskHints, harness)
+//     candidates = the catalog entries (already filterable by .harness)
+//     harness    = 'claude-code' | 'codex'
+//
+// WHY THIS DEFAULT IS DELIBERATELY WEAK (and says so): ADR-040 (DRACO) MEASURED that a
+// hand-built self-signal threshold routed WORSE than always-cheapest, while a learned map from a
+// real feature beat the best fixed model. So this placeholder makes NO claim of optimality — it is
+// a transparent complexity proxy so the engine is usable TODAY, to be replaced by your researched
+// (ideally learned) policy. confidence is pinned low to signal "not tuned."
+
+export function choose({ features, candidates, harness }) {
+  const pool = candidates.filter((m) => Array.isArray(m.harness) && m.harness.includes(harness));
+  if (pool.length === 0) {
+    return { model: null, provider: null, tier: null, reason: `no candidate supports harness=${harness}`, confidence: 0 };
+  }
+  const c = complexity(features);
+  const tier = c < 0.33 ? 'cheap' : c < 0.66 ? 'mid' : 'frontier';
+  let pick = cheapestInTier(pool, tier, harness) || cheapestInTier(pool, 'mid', harness) || pool[0];
+  let floorNote = '';
+  // $1,600 floor, CROSS-TIER (Goldie 2026-07-12): when the in-tier winner is a BILLED model but a
+  // subscription-covered model exists at-or-above the needed tier, the subscription model wins —
+  // more capability for $0 beats less capability for money, always. (Found live: demoting the
+  // unreachable gpt-5.6 tiers left codex cheap/mid pointing at billed DeepSeek while gpt-5.5,
+  // subscription-covered and MORE capable, sat unused one tier up.)
+  if (effCost(pick, harness) > 0) {
+    const order = ['cheap', 'mid', 'frontier'];
+    const atOrAbove = order.slice(order.indexOf(tier));
+    const subs = pool
+      .filter((m) => Array.isArray(m.subscription) && m.subscription.includes(harness) && atOrAbove.includes(m.tier))
+      .sort((a, b) => order.indexOf(a.tier) - order.indexOf(b.tier)); // least-capable sufficient one
+    if (subs.length) { pick = subs[0]; floorNote = ` [cross-tier $0 floor: subscription ${pick.tier} model beats billed ${tier} candidate]`; }
+  }
+  return {
+    model: pick.id,
+    provider: pick.provider,
+    tier,
+    reason: `default(placeholder) policy: complexity≈${c.toFixed(2)} → ${tier} tier; subscription-covered model preferred ($0), else cheapest ${harness} candidate.${floorNote} NOT a tuned heuristic — replace via policy.mjs.`,
+    confidence: 0.4,
+  };
+}
+
+// Transparent, crude complexity proxy in [0,1]. Documented as a starting point, not a claim.
+function complexity(f) {
+  let s = 0;
+  s += Math.min(0.3, (f.estTokens || 0) / 4000); // longer prompt → likely harder
+  if (f.hasCode) s += 0.25;
+  s += Math.min(0.15, (f.codeFences || 0) * 0.05);
+  const hints = f.taskHints || '';
+  // Accumulate hard/easy signals rather than one flat bump, so genuinely complex prompts
+  // (architect + prove + optimize + security + debug …) actually climb past the tier thresholds
+  // instead of maxing out at a single +0.25. Still crude on purpose — a learned policy replaces this.
+  const hard = (hints.match(/\b(refactor|architect|design|debug|migrat\w*|optimi[sz]\w*|security|secure|proof|prove|correctness|distributed|consensus|concurren\w*|race\s+condition|algorithm|cryptograph\w*)\b/gi) || []).length;
+  const easy = (hints.match(/\b(summari[sz]e|translate|classify|extract|rephrase|list|format|rename|typo|lookup)\b/gi) || []).length;
+  s += Math.min(0.5, hard * 0.12);
+  s -= Math.min(0.3, easy * 0.12);
+  return Math.max(0, Math.min(1, s));
+}
+
+function cheapestInTier(pool, tier, harness) {
+  const inTier = pool.filter((m) => m.tier === tier);
+  // cheapest by EFFECTIVE cost for this harness; unknown-price candidates sort last (Infinity) so a
+  // priced option is preferred over an unpriced one, but an unpriced one is still returned last
+  // rather than nothing.
+  return inTier.sort((a, b) => effCost(a, harness) - effCost(b, harness))[0];
+}
+// SAFETY FLOOR — the cardinal $1,600 lesson (cross-ref AgentDB intel-1600-postmortem): a model
+// covered by THIS harness's subscription is marginal-$0 to the user, so it must NEVER lose to a
+// billed OpenRouter/API model that only looks cheaper by sticker price. Spending money where the
+// subscription is free is exactly the "clever but reckless" mistake this system exists to prevent.
+function effCost(m, harness) {
+  if (m && Array.isArray(m.subscription) && m.subscription.includes(harness)) return 0;
+  return m && m.costPerMTok && typeof m.costPerMTok.out === 'number' ? m.costPerMTok.out : Infinity;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
-  "version": "2.0.0",
-  "description": "One-command installer for RuvNet Brain — a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
+  "version": "2.4.1",
+  "description": "One-command installer for RuvNet Brain \u2014 a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {
     "ruvnet-brain": "bin/install.mjs"
@@ -14,6 +14,8 @@
     "test:unit": "vitest run tests/unit",
     "test:cov": "vitest run tests/unit --coverage",
     "test:all": "npm run test:unit && npm run test:integration && npm test",
+    "metaharness:receipts": "node scripts/metaharness-receipts.mjs",
+    "route:cheap": "node scripts/route-cheap.mjs",
     "metaharness:fix": "node scripts/fix-metaharness-memretrieve.mjs --apply",
     "metaharness:check": "node scripts/fix-metaharness-memretrieve.mjs --check",
     "eval": "node scripts/eval-brain.mjs",
@@ -28,7 +30,14 @@
   "files": [
     "bin/install.mjs",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "config/",
+    "scripts/model-router-engine.mjs",
+    "scripts/model-router-setup.mjs",
+    "scripts/model-router-status.mjs",
+    "scripts/model-router-outcome.mjs",
+    "scripts/route-cheap.mjs",
+    "scripts/codex-routed.sh"
   ],
   "engines": {
     "node": ">=18"

package/scripts/codex-routed.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# scripts/codex-routed.sh — built 2026-07-12. Codex has no native routing surface
+# (~/.codex/config.toml launches ONE model per run), so a consulted wrapper is the only
+# per-prompt model-selection path available to it. Part of the MetaHarness router (see
+# scripts/model-router-engine.mjs, the harness-neutral prompt -> {model, reason} decision
+# engine). This script only CONSULTS the engine and LAUNCHES codex — all selection logic
+# (features, policy, pricing) lives in the engine, not here.
+#
+# Contract: never block Stuart's launch. If the engine errors, times out, or returns a
+# null model, fall straight through to plain `codex` with no --model flag — a missing
+# routing decision must never be worse than no routing at all.
+set -uo pipefail
+DIR="$(cd "$(dirname "$0")" && pwd)"
+
+DECISION=$(node "$DIR/model-router-engine.mjs" --harness codex --prompt "$*" --json 2>/dev/null)
+
+# Extract .model + a short .reason without a jq dependency (Stuart directive). python3 ships
+# with macOS by default and its json module handles arbitrary reason text (quotes, unicode)
+# more safely than hand-rolled JS string escaping in a node -e one-liner would. Single call,
+# tab-delimited output, so we only shell out once per launch.
+IFS=$'\t' read -r M REASON <<< "$(printf '%s' "$DECISION" | python3 -c '
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    m = d.get("model") or ""
+    r = (d.get("reason") or "").replace("\n", " ").replace("\t", " ")[:80]
+    print(f"{m}\t{r}")
+except Exception:
+    print("\t")
+' 2>/dev/null)"
+
+if [ -z "${M:-}" ] || [ "$M" = "None" ]; then
+  # Engine failed / no policy resolved a model — never block, just launch codex unrouted.
+  exec codex "$@"
+fi
+
+printf '\x1b[2m🧭 codex-routed → %s (%s)\x1b[0m\n' "$M" "$REASON"
+exec codex --model "$M" "$@"

package/scripts/model-router-engine.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+// scripts/model-router-engine.mjs — the harness-neutral MODEL SELECTION engine.
+//
+// WHAT THIS IS (and is NOT):
+//   • IS: a pure `prompt -> {model, provider, reason, cost}` DECISION engine. It extracts features
+//     from the prompt and hands them to a PLUGGABLE POLICY that decides which model to use. The
+//     policy is the swappable part — drop your researched heuristics (or a learned router) into
+//     ~/.claude/model-router/policy.mjs and the engine picks them up. NO heuristics are baked in
+//     here. (ADR-040 / DRACO, verified via search_ruvnet: a hand-built self-signal threshold routed
+//     WORSE than always-cheapest; a learned map from a real feature beat the best fixed model. So
+//     the SIGNAL/policy is everything and must never be hard-coded into the engine.)
+//   • IS harness-neutral: the SAME CLI is consulted by Claude Code AND Codex. It only DECIDES; it
+//     does not launch a model. The caller acts on the JSON. (Codex has no native routing surface —
+//     ~/.codex/config.toml launches one model per run — so a consulted CLI is the only way to make
+//     selection work for Codex too. That is the fix for "only partially OK for Codex.")
+//   • Is NOT an executor. Running a task on a cheap model is route-cheap.mjs's job (OpenRouter).
+//     This answers only "which model should handle this prompt?"
+//
+// INTEGRATION:
+//   Claude Code : call from a hook/skill, parse the JSON, use .model.
+//                   node model-router-engine.mjs --harness claude-code --prompt "$PROMPT" --json
+//   Codex       : wrap the codex launch —
+//                   M=$(node model-router-engine.mjs --harness codex --prompt "$TASK" --json | jq -r .model)
+//                   codex --model "$M"  ...
+//
+// Config (edit freely):  ~/.claude/model-router/catalog.json   (candidates + verified pricing)
+//                        ~/.claude/model-router/policy.mjs      (YOUR policy; falls back to policy.default.mjs)
+// Decision log:          ~/.claude/metaharness/routing-decisions.jsonl  (sibling to route-cheap's execution receipts)
+//
+// Usage:
+//   node model-router-engine.mjs --prompt "..." [--harness claude-code|codex] [--policy <path>] [--json|--line]
+//   echo "the prompt text" | node model-router-engine.mjs --harness codex
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { estTokens } from './route-cheap.mjs'; // reuse the verified char/4 estimator (DRY)
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const CONFIG_DIR = path.join(os.homedir(), '.claude', 'model-router');
+const CATALOG_PATH = path.join(CONFIG_DIR, 'catalog.json');
+const POLICY_USER = path.join(CONFIG_DIR, 'policy.mjs');
+const POLICY_DEFAULT = path.join(CONFIG_DIR, 'policy.default.mjs');
+const DECISIONS_LOG =
+  process.env.MODEL_ROUTER_DECISIONS ||
+  path.join(os.homedir(), '.claude', 'metaharness', 'routing-decisions.jsonl');
+
+// ─── feature extraction: this is "based on what the prompt is" ────────────────────────────────
+// Pure and deterministic. Emits SIGNALS only — it never decides. Policies consume these; extend
+// this object as your research identifies new predictive features (it is the documented surface).
+export function extractFeatures(prompt, harness) {
+  const text = prompt || '';
+  const codeFences = Math.floor((text.match(/```/g) || []).length / 2);
+  const fileTypes = [...new Set((text.match(/\.[a-z0-9]{1,5}\b/gi) || []).map((s) => s.toLowerCase()))].slice(0, 12);
+  const hasCode =
+    codeFences > 0 || /\b(function|const|let|def|class|import|=>|SELECT|async)\b/.test(text) || /[{};]\s*$/m.test(text);
+  return {
+    chars: text.length,
+    estTokens: estTokens(text),
+    codeFences,
+    hasCode,
+    fileTypes,
+    questionCount: (text.match(/\?/g) || []).length,
+    taskHints: text.slice(0, 4000), // policies may regex over the actual prompt head
+    harness,
+  };
+}
+
+// ── PER-USER SUBSCRIPTION PROFILE (2026-07-12) ─────────────────────────────────────────────────
+// The catalog states facts about MODELS; the profile states facts about THIS USER (which harnesses
+// they have, which are subscription-covered — detected/asked/verified by model-router-setup.mjs).
+// The overlay strips any subscription or harness claim the profile doesn't back, so the $0 floor
+// can never assume a plan the user doesn't have (silently billing them) or miss one they do
+// (silently wasting it). No profile file = catalog taken as-is (pre-profile installs keep working).
+export const PROFILE_PATH =
+  process.env.MODEL_ROUTER_PROFILE || path.join(CONFIG_DIR, 'profile.json');
+
+export function loadProfile() {
+  try { return JSON.parse(fs.readFileSync(PROFILE_PATH, 'utf8')); } catch { return null; }
+}
+
+export function applyProfile(candidates, profile) {
+  const h = profile?.harnesses;
+  if (!h) return candidates;
+  return candidates.map((c) => ({
+    ...c,
+    // A harness the user doesn't have can never launch anything — remove it from the pool filter.
+    harness: (c.harness || []).filter((x) => h[x] === undefined || h[x].available !== false),
+    // A subscription claim only survives if THIS user's profile confirms that harness is covered.
+    subscription: (c.subscription || []).filter((x) => h[x]?.subscription === true),
+  }));
+}
+
+export function loadCatalog() {
+  try {
+    const j = JSON.parse(fs.readFileSync(CATALOG_PATH, 'utf8'));
+    if (Array.isArray(j.candidates) && j.candidates.length) return j.candidates;
+  } catch {
+    /* fall through to a minimal built-in so the engine still answers */
+  }
+  // Built-in fallback (verified OpenRouter prices from route-cheap; Anthropic frontier from same).
+  return [
+    { id: 'deepseek/deepseek-chat', provider: 'openrouter', harness: ['claude-code', 'codex'], tier: 'cheap', costPerMTok: { in: 0.2, out: 0.8 }, verified: '2026-07-07' },
+    { id: 'claude-opus-4-8', provider: 'anthropic', harness: ['claude-code'], tier: 'frontier', costPerMTok: { in: 5.0, out: 25.0 }, verified: '2026-07-07' },
+    { id: 'gpt-5.5', provider: 'openai', harness: ['codex'], tier: 'frontier', costPerMTok: null, verified: null },
+  ];
+}
+
+export async function loadPolicy(explicit) {
+  const candidatePaths = [explicit, POLICY_USER, POLICY_DEFAULT].filter(Boolean);
+  for (const p of candidatePaths) {
+    if (!fs.existsSync(p)) continue;
+    try {
+      const mod = await import(pathToFileURL(p).href);
+      if (typeof mod.choose === 'function') return { choose: mod.choose, source: p };
+    } catch (e) {
+      process.stderr.write(`[model-router] policy at ${p} failed to load: ${e.message}\n`);
+    }
+  }
+  return null;
+}
+
+function parseArgs(argv) {
+  const a = { harness: null, prompt: null, policy: null, mode: 'json' };
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i];
+    if (k === '--prompt') a.prompt = argv[++i];
+    else if (k === '--harness') a.harness = argv[++i];
+    else if (k === '--policy') a.policy = argv[++i];
+    else if (k === '--line') a.mode = 'line';
+    else if (k === '--json') a.mode = 'json';
+    else if (k === '--help' || k === '-h') a.help = true;
+  }
+  return a;
+}
+
+function readStdin() {
+  try { return fs.readFileSync(0, 'utf8'); } catch { return ''; }
+}
+
+// Selection-time cost is INPUT-only and clearly labeled: at selection we don't know output length,
+// so we never fabricate one. Returns null when the chosen model has no verified price.
+function estInputCost(candidate, inTokens) {
+  const p = candidate && candidate.costPerMTok;
+  if (!p || typeof p.in !== 'number') return null;
+  return +((inTokens * p.in) / 1e6).toFixed(6);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    process.stdout.write(fs.readFileSync(fileURLToPath(import.meta.url), 'utf8').split('\n').slice(1, 33).join('\n') + '\n');
+    return;
+  }
+  // Harness: explicit flag wins; else detect Codex by its env/dir; else default claude-code.
+  const harness =
+    args.harness ||
+    (process.env.CODEX_SANDBOX || fs.existsSync(path.join(os.homedir(), '.codex', 'config.toml')) && process.env.CODEX ? 'codex' : null) ||
+    'claude-code';
+  const prompt = args.prompt || readStdin();
+  if (!prompt || !prompt.trim()) {
+    process.stderr.write('model-router-engine: no prompt (use --prompt "..." or pipe text on stdin)\n');
+    process.exit(2);
+  }
+
+  const profile = loadProfile();
+  const candidates = applyProfile(loadCatalog(), profile);
+  const policy = await loadPolicy(args.policy);
+  const features = extractFeatures(prompt, harness);
+
+  let decision;
+  if (!policy) {
+    // No policy at all: pick cheapest priced candidate for the harness as a safe floor, and SAY SO.
+    const pool = candidates.filter((m) => (m.harness || []).includes(harness));
+    const pick = pool.slice().sort((x, y) => (x.costPerMTok?.out ?? Infinity) - (y.costPerMTok?.out ?? Infinity))[0] || candidates[0];
+    decision = { model: pick?.id ?? null, provider: pick?.provider ?? null, tier: pick?.tier ?? null, reason: 'NO POLICY FOUND — fell back to cheapest priced candidate for the harness', confidence: 0 };
+  } else {
+    decision = policy.choose({ features, candidates, harness });
+  }
+
+  const chosen = candidates.find((m) => m.id === decision.model) || null;
+  const out = {
+    ts: new Date().toISOString(),
+    harness,
+    model: decision.model,
+    provider: decision.provider,
+    tier: decision.tier,
+    reason: decision.reason,
+    confidence: decision.confidence,
+    policy_source: policy ? policy.source.replace(os.homedir(), '~') : 'none',
+    profile: profile ? PROFILE_PATH.replace(os.homedir(), '~') : 'none (catalog taken as-is — run model-router-setup.mjs)',
+    price_verified: chosen ? chosen.verified : null,
+    est_input_cost_usd: estInputCost(chosen, features.estTokens), // null if price unknown — never invented
+    features: { estTokens: features.estTokens, hasCode: features.hasCode, codeFences: features.codeFences, fileTypes: features.fileTypes, questionCount: features.questionCount },
+  };
+
+  // Durable decision log (append-only; separate from route-cheap's execution/savings ledger).
+  try {
+    fs.mkdirSync(path.dirname(DECISIONS_LOG), { recursive: true });
+    fs.appendFileSync(DECISIONS_LOG, JSON.stringify({ ...out, features: undefined, prompt_head: prompt.slice(0, 120) }) + '\n');
+  } catch { /* logging must never break selection */ }
+
+  if (args.mode === 'line') {
+    const cost = out.est_input_cost_usd == null ? 'cost:unpriced' : `est-in:$${out.est_input_cost_usd}`;
+    process.stdout.write(`\x1b[2m🧭 model-router → ${out.model} (${out.harness}, ${out.tier}, ${cost}) — ${out.reason}\x1b[0m\n`);
+  } else {
+    process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((e) => { process.stderr.write(`model-router-engine: ${e.stack || e.message}\n`); process.exit(1); });
+}