ruvnet-brain 2.1.0 → 2.4.3

package/scripts/model-router-outcome.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// scripts/model-router-outcome.mjs — the LABELED-DATA pipeline for a future learned routing policy.
+//
+// WHY THIS EXISTS: both 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) and
+// ruflo's own ADR-149 point the same direction — learned routing beats hand-tuned routing, but ONLY
+// once there are labeled outcomes to learn from. model-router-engine.mjs's placeholder policy
+// (policy.default.mjs) is a 3-tier heuristic precisely because there is no such label set yet. This
+// file is where those labels accumulate, one JSON line at a time, so that placeholder can eventually
+// be replaced by something trained on real outcomes instead of a guess.
+//
+// A label is not just "did the task succeed" — an OVERRIDE (an operator escalating past whatever the
+// engine picked) is itself a label: it says the engine's choice was wrong for that prompt shape, even
+// if no downstream failure was ever observed. Log overrides the same way you log pass/fail outcomes;
+// don't wait for a hard failure to record that the router under- or over-shot.
+//
+// Usage:
+//   node model-router-outcome.mjs --model <id> --success true|false [--note "..."] [--task-hash <h>]
+//   node model-router-outcome.mjs --summary
+//
+// Storage: ~/.claude/metaharness/routing-outcomes.jsonl (append-only; sibling to routing-decisions.jsonl
+// and routing-receipts.jsonl — decisions record what was CHOSEN, outcomes record what HAPPENED).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const OUTCOMES_LOG =
+  process.env.MODEL_ROUTER_OUTCOMES ||
+  path.join(os.homedir(), '.claude', 'metaharness', 'routing-outcomes.jsonl');
+
+function parseArgs(argv) {
+  const a = { model: null, success: null, note: null, taskHash: null, summary: false };
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i];
+    if (k === '--model') a.model = argv[++i];
+    else if (k === '--success') a.success = argv[++i];
+    else if (k === '--note') a.note = argv[++i];
+    else if (k === '--task-hash') a.taskHash = argv[++i];
+    else if (k === '--summary') a.summary = true;
+    else if (k === '--help' || k === '-h') a.help = true;
+  }
+  return a;
+}
+
+function appendOutcome({ model, success, note, taskHash }) {
+  if (!model) throw new Error('--model is required');
+  if (success !== 'true' && success !== 'false') throw new Error('--success must be "true" or "false"');
+  const entry = { ts: new Date().toISOString(), model, success: success === 'true' };
+  if (note) entry.note = note;
+  if (taskHash) entry.taskHash = taskHash;
+  fs.mkdirSync(path.dirname(OUTCOMES_LOG), { recursive: true });
+  fs.appendFileSync(OUTCOMES_LOG, JSON.stringify(entry) + '\n');
+  return entry;
+}
+
+function summarize() {
+  let lines;
+  try {
+    lines = fs.readFileSync(OUTCOMES_LOG, 'utf8').trim().split('\n').filter(Boolean);
+  } catch {
+    return { total: 0, byModel: {} };
+  }
+  const byModel = {};
+  for (const l of lines) {
+    let d;
+    try { d = JSON.parse(l); } catch { continue; }
+    const m = byModel[d.model] || (byModel[d.model] = { total: 0, successes: 0, failures: 0 });
+    m.total++;
+    if (d.success) m.successes++; else m.failures++;
+  }
+  return { total: lines.length, byModel };
+}
+
+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, 24).join('\n') + '\n');
+    return;
+  }
+
+  if (args.summary) {
+    const { total, byModel } = summarize();
+    console.log(`Routing outcomes: ${total} labeled (${OUTCOMES_LOG.replace(os.homedir(), '~')})`);
+    for (const [model, s] of Object.entries(byModel)) {
+      console.log(`  ${model.padEnd(32)} total:${s.total}  successes:${s.successes}  failures:${s.failures}`);
+    }
+    return;
+  }
+
+  const entry = appendOutcome(args);
+  console.log(`[model-router-outcome] logged: ${JSON.stringify(entry)}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try { main(); } catch (e) { process.stderr.write(`model-router-outcome: ${e.message}\n`); process.exit(1); }
+}

package/scripts/model-router-setup.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// model-router-setup.mjs — build THIS user's subscription profile: detect, ASK, verify, record.
+//
+// Stuart's mandate (2026-07-12): "Just because you verified it for me doesn't mean other people
+// have the same setup. For this thing to be useful it needs to be aware of what THEY have — ask
+// 'Do you have a Claude account? A ChatGPT/Codex account?', verify, and record it, so routing
+// sends work to the right place." The router's whole $0-floor logic is only as true as this
+// profile: a catalog that assumes a subscription the user doesn't have quietly bills them, and
+// one that misses a subscription they DO have quietly wastes it.
+//
+// Three layers of truth, recorded with their basis so nobody over-trusts a guess:
+//   verified      — machine-checkable proof (e.g. ~/.codex/auth.json carries ChatGPT OAuth tokens)
+//   user-attested — the user answered the question (plans aren't reliably probeable)
+//   assumed       — --detect-only defaults, explicitly labeled as assumptions
+//
+// Output: ~/.claude/model-router/profile.json — consumed by model-router-engine.mjs, which strips
+// subscription/harness claims the profile doesn't back. No profile file = catalog taken as-is
+// (grandfathers pre-profile installs; the session-start hook nudges once to create one).
+//
+// Usage:
+//   node model-router-setup.mjs                 # interactive: detect, ask, verify, record
+//   node model-router-setup.mjs --detect-only   # non-interactive (installer): record detections + labeled assumptions
+//   node model-router-setup.mjs --show          # print the current profile
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+import readline from 'node:readline/promises';
+
+const CONFIG_DIR = path.join(os.homedir(), '.claude', 'model-router');
+export const PROFILE_PATH = process.env.MODEL_ROUTER_PROFILE || path.join(CONFIG_DIR, 'profile.json');
+const TODAY = new Date().toISOString().slice(0, 10);
+
+const has = (cmd) => { try { execFileSync('which', [cmd], { stdio: 'ignore' }); return true; } catch { return false; } };
+
+// The one subscription state we can PROVE from disk: Codex's auth mode. OAuth tokens = signed in
+// with ChatGPT (Plus/Pro/Business all include Codex → subscription-covered). An API key = metered.
+// Shape only — never the secret values.
+function detectCodex() {
+  const cli = has('codex');
+  try {
+    const a = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.codex', 'auth.json'), 'utf8'));
+    if (a.tokens) return { cli, auth: 'chatgpt-subscription' };
+    if (a.OPENAI_API_KEY) return { cli, auth: 'api-key-metered' };
+  } catch { /* not authed */ }
+  return { cli, auth: null };
+}
+
+function detectKeys() {
+  const names = ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'OPENROUTER_API_KEY', 'GOOGLE_API_KEY', 'GEMINI_API_KEY', 'XAI_API_KEY'];
+  return Object.fromEntries(names.map((n) => [n, !!process.env[n]]));
+}
+
+function buildDetected() {
+  const codex = detectCodex();
+  return {
+    updated: TODAY,
+    harnesses: {
+      // Claude plan tier (Pro vs Max vs API-billed) is not reliably probeable from disk, so
+      // detect-only ASSUMES subscription=true when the CLI is present: right-sizing WITHIN
+      // Anthropic (haiku over fable) is correct under every Claude billing mode, whereas a false
+      // "no subscription" would push claude-code work to BILLED OpenRouter — the worse error.
+      'claude-code': has('claude')
+        ? { available: true, subscription: true, plan: 'unknown', basis: `assumed: claude CLI present (${TODAY}); run setup to attest your plan` }
+        : { available: false, subscription: false, plan: null, basis: `detected: no claude CLI (${TODAY})` },
+      codex: codex.auth === 'chatgpt-subscription'
+        ? { available: true, subscription: true, plan: 'chatgpt', basis: `verified: ~/.codex/auth.json ChatGPT OAuth tokens (${TODAY})` }
+        : codex.auth === 'api-key-metered'
+          ? { available: true, subscription: false, plan: 'api-key', basis: `verified: ~/.codex/auth.json API key — METERED (${TODAY})` }
+          : { available: codex.cli, subscription: false, plan: null, basis: `detected: codex ${codex.cli ? 'present, not authed' : 'not installed'} (${TODAY})` },
+    },
+    keys: detectKeys(),
+  };
+}
+
+function save(profile) {
+  fs.mkdirSync(path.dirname(PROFILE_PATH), { recursive: true });
+  fs.writeFileSync(PROFILE_PATH, JSON.stringify(profile, null, 2) + '\n');
+}
+
+function show(profile) {
+  console.log(`Model-router subscription profile (${PROFILE_PATH.replace(os.homedir(), '~')}):`);
+  for (const [h, p] of Object.entries(profile.harnesses)) {
+    console.log(`  ${h.padEnd(12)} ${p.available ? 'available' : 'not available'}${p.available ? `, subscription: ${p.subscription ? 'YES ($0 marginal)' : 'NO (metered/absent)'}` : ''}`);
+    console.log(`  ${''.padEnd(12)} basis: ${p.basis}`);
+  }
+  const keys = Object.entries(profile.keys || {}).filter(([, v]) => v).map(([k]) => k.replace('_API_KEY', ''));
+  console.log(`  API keys present at setup: ${keys.join(', ') || 'none'}`);
+}
+
+async function interactive() {
+  const detected = buildDetected();
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = async (q, def) => {
+    const a = (await rl.question(`${q} [${def ? 'Y/n' : 'y/N'}] `)).trim().toLowerCase();
+    return a === '' ? def : a.startsWith('y');
+  };
+
+  console.log('Setting up YOUR subscription profile — this decides where the router sends work for $0.\n');
+
+  const cc = detected.harnesses['claude-code'];
+  if (cc.available) {
+    const sub = await ask('Do you have a Claude subscription (Pro or Max) that covers your Claude Code usage?', cc.subscription);
+    detected.harnesses['claude-code'] = { available: true, subscription: sub, plan: sub ? 'pro-or-max' : 'api-billed', basis: `user-attested ${TODAY}` };
+  }
+
+  const cx = detected.harnesses.codex;
+  if (cx.plan === 'chatgpt') {
+    console.log(`\nCodex: VERIFIED signed in with ChatGPT — your ChatGPT plan covers it ($0 marginal). Nothing to ask.`);
+  } else if (cx.available) {
+    const sub = await ask('\nDo you have a ChatGPT subscription (Plus/Pro/Business) you use to sign into the Codex CLI?', false);
+    if (sub) console.log('  Note: run `codex login` and sign in with ChatGPT — until then Codex runs are metered or unavailable.');
+    detected.harnesses.codex = { ...cx, subscription: cx.plan === 'chatgpt' ? true : false, basis: `user-attested ${TODAY} (subscription only counts once codex login shows ChatGPT auth)` };
+  }
+
+  rl.close();
+  save(detected);
+  console.log('');
+  show(detected);
+  console.log('\nSaved. The router now uses THIS profile for every routing decision.');
+}
+
+async function main() {
+  if (process.argv.includes('--show')) {
+    try { show(JSON.parse(fs.readFileSync(PROFILE_PATH, 'utf8'))); } catch { console.log(`No profile at ${PROFILE_PATH.replace(os.homedir(), '~')} — run: node scripts/model-router-setup.mjs`); process.exit(1); }
+    return;
+  }
+  if (process.argv.includes('--detect-only')) {
+    const p = buildDetected();
+    save(p);
+    show(p);
+    return;
+  }
+  await interactive();
+}
+
+const { pathToFileURL } = await import('node:url');
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((e) => { console.error(`model-router-setup: ${e.message}`); process.exit(1); });
+}

package/scripts/model-router-status.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+// scripts/model-router-status.mjs — "what is MetaHarness's current plan?", answered plainly.
+//
+// Shows, for each harness (claude-code, codex): the live catalog, which policy is active, what
+// it would actually pick for a cheap/mid/frontier-shaped prompt right now (by calling the REAL
+// engine CLI — this never reimplements selection logic, so it can't drift from what actually runs),
+// which candidates are landscape-only (known, not yet wired for execution), and catalog freshness.
+//
+// Usage: node scripts/model-router-status.mjs [--json]
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { loadCatalog, loadPolicy, loadProfile, applyProfile, CONFIG_DIR } from './model-router-engine.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ENGINE = path.join(__dirname, 'model-router-engine.mjs');
+
+const SAMPLE_PROMPTS = {
+  cheap: 'Fix this typo in the README.',
+  mid: 'Add a new API endpoint that validates input and returns paginated results.',
+  frontier: 'Refactor this auth module to fix a security vulnerability and prove correctness under concurrent access.',
+};
+
+function sampleDecision(harness, prompt) {
+  try {
+    const out = execFileSync('node', [ENGINE, '--harness', harness, '--prompt', prompt, '--json'], {
+      encoding: 'utf8',
+      env: { ...process.env, MODEL_ROUTER_DECISIONS: path.join(os.tmpdir(), 'model-router-status-preview.jsonl') },
+    });
+    return JSON.parse(out);
+  } catch (e) {
+    return { model: null, tier: null, reason: `engine call failed: ${e.message}` };
+  }
+}
+
+// HOW Codex is paid for, read from ~/.codex/auth.json's SHAPE (never its secrets): OAuth tokens =
+// "Sign in with ChatGPT" — usage bills the ChatGPT plan (Plus/Pro/Business all include Codex), so
+// marginal cost is $0 and the catalog's subscription:["codex"] entries are correct. An OPENAI_API_KEY
+// instead = metered per-token billing — flip those subscription fields to [] or the $0-floor lies.
+// Verified live on this machine 2026-07-12: tokens present, no API key -> chatgpt-subscription.
+function codexAuthMode() {
+  try {
+    const a = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.codex', 'auth.json'), 'utf8'));
+    if (a.tokens) return 'chatgpt-subscription';
+    if (a.OPENAI_API_KEY) return 'api-key-metered';
+  } catch { /* absent or unreadable — not authed */ }
+  return null;
+}
+
+function detectInventory() {
+  const has = (cmd) => {
+    try { execFileSync('which', [cmd], { stdio: 'ignore' }); return true; } catch { return false; }
+  };
+  const keyPresent = (name) => !!process.env[name];
+  return {
+    claudeCli: has('claude'),
+    codexCli: has('codex'),
+    codexAuthed: fs.existsSync(path.join(os.homedir(), '.codex', 'auth.json')),
+    codexAuthMode: codexAuthMode(),
+    keys: {
+      ANTHROPIC_API_KEY: keyPresent('ANTHROPIC_API_KEY'),
+      OPENAI_API_KEY: keyPresent('OPENAI_API_KEY'),
+      GOOGLE_API_KEY: keyPresent('GOOGLE_API_KEY') || keyPresent('GEMINI_API_KEY'),
+      XAI_API_KEY: keyPresent('XAI_API_KEY'),
+      OPENROUTER_API_KEY: keyPresent('OPENROUTER_API_KEY'),
+    },
+  };
+}
+
+async function main() {
+  const jsonMode = process.argv.includes('--json');
+  // Profile-aware, same as the engine: what this tool displays must be what routing actually does.
+  const candidates = applyProfile(loadCatalog(), loadProfile());
+  const policy = await loadPolicy();
+  const catalogRaw = JSON.parse(fs.readFileSync(path.join(CONFIG_DIR, 'catalog.json'), 'utf8'));
+  const inventory = detectInventory();
+
+  const selectable = candidates.filter((c) => Array.isArray(c.harness) && c.harness.length > 0);
+  const landscapeOnly = candidates.filter((c) => !Array.isArray(c.harness) || c.harness.length === 0);
+
+  const plan = {};
+  for (const harness of ['claude-code', 'codex']) {
+    plan[harness] = {};
+    for (const [tierLabel, prompt] of Object.entries(SAMPLE_PROMPTS)) {
+      const d = sampleDecision(harness, prompt);
+      plan[harness][tierLabel] = { model: d.model, actualTier: d.tier, cost: d.est_input_cost_usd, reason: d.reason };
+    }
+  }
+
+  const result = {
+    catalogUpdated: catalogRaw.updated,
+    activePolicy: policy ? policy.source.replace(os.homedir(), '~') : 'NONE — falling back to cheapest priced candidate (no policy found)',
+    inventory,
+    plan,
+    selectableCandidateCount: selectable.length,
+    landscapeOnlyCandidates: landscapeOnly.map((c) => ({ id: c.id, provider: c.provider, note: c.note })),
+  };
+
+  if (jsonMode) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  // ── The plain-language answer first (Stuart, 2026-07-12: "show them what the current
+  // recommended path is — the zero-cost options, and what it uses when it must go out for API
+  // calls"). Everything below it is the detailed evidence; this block is the one a person reads.
+  console.log('Recommended path (zero-cost first, always):');
+  console.log('  $0 — covered by YOUR subscriptions:');
+  for (const harness of ['claude-code', 'codex']) {
+    const p = plan[harness];
+    const zero = ['cheap', 'mid', 'frontier']
+      .map((t) => ({ t, m: p[t].model, free: p[t].cost == null && p[t].model }))
+      .filter((x) => x.free);
+    if (zero.length) {
+      const parts = zero.map((x) => `${x.t}→${x.m}`);
+      console.log(`    ${harness.padEnd(12)} ${parts.join(' · ')}`);
+    } else {
+      console.log(`    ${harness.padEnd(12)} (no subscription-covered models for this user — see profile)`);
+    }
+  }
+  const billed = selectable
+    .filter((c) => c.costPerMTok && typeof c.costPerMTok.out === 'number' && !(c.subscription || []).length)
+    .sort((a, b) => a.costPerMTok.out - b.costPerMTok.out)
+    .slice(0, 3);
+  console.log('  Paid API — only when work must leave the subscriptions (parallel fleets, background batch):');
+  for (const c of billed) {
+    console.log(`    ${c.id.padEnd(28)} $${c.costPerMTok.in}/M in · $${c.costPerMTok.out}/M out  (${c.tier}, verified ${String(c.verified || '').slice(0, 10)})`);
+  }
+  console.log('');
+  console.log(`MetaHarness Router — current plan`);
+  console.log(`Catalog last updated: ${result.catalogUpdated}`);
+  console.log(`Active policy: ${result.activePolicy}`);
+  console.log('');
+  console.log('Detected on this machine:');
+  const codexPay = inventory.codexAuthMode === 'chatgpt-subscription' ? 'authed via ChatGPT subscription ($0 marginal)'
+    : inventory.codexAuthMode === 'api-key-metered' ? 'authed via API key (METERED — subscription fields in catalog.json should be [])'
+    : inventory.codexAuthed ? 'authed (mode unknown)' : 'not authed';
+  console.log(`  claude CLI: ${inventory.claudeCli ? 'present' : 'not found'}   codex CLI: ${inventory.codexCli ? `present, ${codexPay}` : 'not found'}`);
+  const keyList = Object.entries(inventory.keys).filter(([, v]) => v).map(([k]) => k.replace('_API_KEY', ''));
+  console.log(`  API keys present: ${keyList.length ? keyList.join(', ') : 'none'}`);
+  console.log('');
+  for (const harness of ['claude-code', 'codex']) {
+    console.log(`${harness}:`);
+    for (const tierLabel of ['cheap', 'mid', 'frontier']) {
+      const p = plan[harness][tierLabel];
+      const costStr = p.cost == null ? (p.model ? 'subscription/$0 or unpriced' : '') : `est $${p.cost}`;
+      console.log(`  ${tierLabel.padEnd(9)} -> ${(p.model || '(none)').padEnd(28)} ${costStr}`);
+    }
+  }
+  console.log('');
+  console.log(`Selectable candidates: ${result.selectableCandidateCount}   Landscape-only (known, not yet wired): ${landscapeOnly.length}`);
+  if (landscapeOnly.length) {
+    for (const c of landscapeOnly) console.log(`  - ${c.id} (${c.provider}): ${c.note}`);
+  }
+}
+
+main().catch((e) => { process.stderr.write(`model-router-status: ${e.stack || e.message}\n`); process.exit(1); });

package/scripts/route-cheap.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// scripts/route-cheap.mjs — THE place cheap-model routing happens, so the visibility line is earned.
+//
+// Grounding (verified, not recalled):
+//   - The real cheap-routing path is agentic-flow's CLI: any --model containing "/" auto-routes
+//     through OpenRouter (agentic-flow/src/router/index.ts exports OpenRouterProvider; verified
+//     live 2026-07-07 — see plugin/skills/ruvnet-brain/SKILL.md "Cost-optimal model routing").
+//   - NOT mcp__ruflo__agent_execute (Anthropic-only), NOT the neural router (chance-level per
+//     rUv's own ROUTER-PILOT.md benchmark).
+//   - Pricing below was pulled live from the OpenRouter API on 2026-07-07 (same SKILL.md table).
+//
+// What it does, visibly (Stuart directive: "invisible value = no value"):
+//   1. Runs the task on a cheap model via `npx agentic-flow@latest`.
+//   2. Appends a receipt to ~/.claude/metaharness/routing-receipts.jsonl (machine-wide).
+//   3. Prints ONE dim line: "⚡ MetaHarness: routed to <model> (est. $X vs $Y frontier — saved ~$Z)".
+//
+// Usage:
+//   node scripts/route-cheap.mjs --task "summarize X" [--model deepseek/deepseek-chat]
+//                                [--agent researcher] [--class research]
+//
+// Scope guard: read-only text work ONLY (research / summarize / classify / transform). This path
+// has no file-write capability and no native tool calling — code edits stay on Claude Code.
+// The OPENROUTER_API_KEY value is read from env or ruvnet-brain/.env and NEVER printed.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// $/Mtok, verified live from the OpenRouter API 2026-07-07 (SKILL.md "Cost-optimal model routing").
+export const PRICING = {
+  'deepseek/deepseek-chat': { in: 0.20, out: 0.80 },
+  'z-ai/glm-4.6': { in: 0.43, out: 1.74 },
+  'z-ai/glm-5': { in: 0.60, out: 1.92 },
+  'deepseek/deepseek-v4-flash': { in: 0.077, out: 0.154 }, // verified 2026-07-12 OpenRouter /models live; successor to deepseek-chat (which resolves to legacy V3)
+  'x-ai/grok-4.5': { in: 2.0, out: 6.0 }, // verified 2026-07-12 OpenRouter /models live; mid-priced frontier-adjacent
+};
+export const FRONTIER = { name: 'claude-opus-4.8', in: 5.0, out: 25.0 };
+
+export function receiptsPath() {
+  return (
+    process.env.METAHARNESS_RECEIPTS ||
+    path.join(os.homedir(), '.claude', 'metaharness', 'routing-receipts.jsonl')
+  );
+}
+
+// Honest token estimate: ~4 chars/token. Labeled "est." everywhere — never presented as measured.
+export const estTokens = (text) => Math.max(1, Math.ceil((text || '').length / 4));
+
+export function estimateCosts(model, inTokens, outTokens) {
+  const p = PRICING[model];
+  if (!p) return null; // unknown model → no receipt rather than an invented number
+  const cost = (inTokens * p.in + outTokens * p.out) / 1e6;
+  const frontier = (inTokens * FRONTIER.in + outTokens * FRONTIER.out) / 1e6;
+  return { cost, frontier, saved: frontier - cost };
+}
+
+const fmt$ = (n) => `$${n < 0.01 ? n.toFixed(5) : n.toFixed(4)}`;
+
+export function receiptLine(model, costs) {
+  return `\x1b[2m⚡ MetaHarness: routed to ${model} (est. ${fmt$(costs.cost)} vs ${fmt$(costs.frontier)} frontier — saved ~${fmt$(costs.saved)})\x1b[0m`;
+}
+
+// Load OPENROUTER_API_KEY from ruvnet-brain/.env if not already in env. Value never printed/logged.
+function ensureOpenRouterKey() {
+  if (process.env.OPENROUTER_API_KEY) return true;
+  try {
+    const envFile = fs.readFileSync(path.join(__dirname, '..', '.env'), 'utf8');
+    const m = envFile.match(/^OPENROUTER_API_KEY=(.+)$/m);
+    if (m && m[1].trim()) {
+      process.env.OPENROUTER_API_KEY = m[1].trim().replace(/^["']|["']$/g, '');
+      return true;
+    }
+  } catch {
+    /* no .env — fall through */
+  }
+  return false;
+}
+
+function parseArgs(argv) {
+  const args = { model: 'deepseek/deepseek-chat', agent: 'researcher', class: 'research' };
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i];
+    if (k === '--task' || k === '--model' || k === '--agent' || k === '--class') args[k.slice(2)] = argv[++i];
+  }
+  return args;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.task) {
+    console.error('Usage: node scripts/route-cheap.mjs --task "<text>" [--model deepseek/deepseek-chat] [--agent researcher] [--class research]');
+    process.exit(2);
+  }
+  if (!PRICING[args.model]) {
+    console.error(`Unknown model "${args.model}" — no verified pricing, refusing to invent savings. Known: ${Object.keys(PRICING).join(', ')}`);
+    process.exit(2);
+  }
+  if (!ensureOpenRouterKey()) {
+    console.error('OPENROUTER_API_KEY not found in env or ruvnet-brain/.env — cannot route. (Key value is never printed.)');
+    process.exit(1);
+  }
+
+  const started = Date.now();
+  const run = spawnSync('npx', ['agentic-flow@latest', '--agent', args.agent, '--model', args.model, '--task', args.task], {
+    encoding: 'utf8',
+    timeout: 180_000,
+    env: process.env,
+  });
+
+  if (run.error || run.status !== 0) {
+    // Honest failure: no receipt, no savings claim.
+    console.error(`route-cheap: agentic-flow failed (exit ${run.status ?? 'spawn-error'}). No receipt written.`);
+    if (run.stderr) console.error(run.stderr.slice(-2000));
+    if (run.stdout) console.error(run.stdout.slice(-1000));
+    process.exit(run.status || 1);
+  }
+
+  const output = (run.stdout || '').trim();
+  console.log(output);
+
+  const inTok = estTokens(args.task);
+  const outTok = estTokens(output);
+  const costs = estimateCosts(args.model, inTok, outTok);
+  const receipt = {
+    ts: new Date().toISOString(),
+    task_class: args.class,
+    task: args.task.slice(0, 120),
+    model: args.model,
+    agent: args.agent,
+    est_in_tokens: inTok,
+    est_out_tokens: outTok,
+    est_cost: +costs.cost.toFixed(6),
+    est_frontier_cost: +costs.frontier.toFixed(6),
+    saved: +costs.saved.toFixed(6),
+    frontier_ref: FRONTIER.name,
+    token_source: 'chars/4 est',
+    duration_ms: Date.now() - started,
+    source: 'agentic-flow',
+  };
+  const file = receiptsPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, JSON.stringify(receipt) + '\n');
+
+  console.log('');
+  console.log(receiptLine(args.model, costs));
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();