trantor 0.15.0 → 0.16.0

package/engine/bin/scrooge-capabilities

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""
+scrooge-capabilities — refresh per-model quality scores for the weighted router.
+
+Pulls live model-capability data and writes ~/.token-scrooge/capabilities.json, which
+`scrooge` uses to route a --task to the best value model (quality-for-task ÷ cost, gated
+by difficulty) instead of always the cheapest. Run it weekly (cron) so routing tracks how
+models actually rank as they improve and get retired.
+
+Sources (zero new deps — plain HTTPS GET + JSON):
+  • Artificial Analysis  (https://artificialanalysis.ai)  — Intelligence/Coding/Math indices,
+      GPQA (reasoning proxy), output tok/s. Needs a FREE key in $AA_API_KEY (or
+      $ARTIFICIAL_ANALYSIS_API_KEY); header x-api-key. Attribution: artificialanalysis.ai.
+  • OpenRouter  (/api/v1/models) — context length + input/output modalities (best-effort,
+      uses your existing OpenRouter key if present).
+
+Matching: each registry model id maps to an AA slug via its stored `aa_slug` (from the seed),
+else by normalising the id (lowercase, '.'/'_' → '-'). Unmatched models are reported and
+left as-is. Nothing is overwritten destructively — only the score fields are updated.
+
+Usage:  scrooge-capabilities            # refresh from AA (+OpenRouter), show a report
+        scrooge-capabilities --dry-run  # fetch + match, print, but don't write
+Exit: 0 updated · 1 nothing fetched (no key / network) · 2 error.
+"""
+import sys, os, json, argparse, urllib.request, urllib.error
+
+HOME = os.path.expanduser("~")
+SCROOGE_DIR = os.environ.get("SCROOGE_HOME", os.path.join(HOME, ".token-scrooge"))
+REGISTRY = os.path.join(SCROOGE_DIR, "registry.json")
+CAPS = os.path.join(SCROOGE_DIR, "capabilities.json")
+AA_URL = "https://artificialanalysis.ai/api/v2/data/llms/models"
+
+def _c(code, s):
+    return s if not sys.stderr.isatty() else "\033[%sm%s\033[0m" % (code, s)
+GOLD = lambda s: _c("38;5;208", s)
+DIM = lambda s: _c("2", s)
+OK = lambda s: _c("32", s)
+WARN = lambda s: _c("33", s)
+ERR = lambda s: _c("31", s)
+
+def load_env_file(path):
+    if not os.path.exists(path):
+        return
+    try:
+        for line in open(path):
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            k, v = line.split("=", 1)
+            k = k.strip()
+            if k.startswith("export "):
+                k = k[len("export "):].strip()
+            v = v.strip().strip('"').strip("'")
+            if k and k not in os.environ:
+                os.environ[k] = v
+    except Exception:
+        pass
+
+def http_get_json(url, headers, timeout=30):
+    req = urllib.request.Request(url, headers=headers, method="GET")
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return json.loads(r.read().decode())
+
+def norm(s):
+    return s.lower().replace(".", "-").replace("_", "-")
+
+def load_json(path):
+    try:
+        with open(path) as fh:
+            d = json.load(fh)
+        return d if isinstance(d, dict) else {}
+    except Exception:
+        return {}
+
+def seed_path():
+    here = os.path.dirname(os.path.realpath(__file__))
+    for c in (os.path.join(SCROOGE_DIR, "capabilities.seed.json"),
+              os.path.join(here, "..", "capabilities.seed.json")):
+        if os.path.exists(c):
+            return c
+    return None
+
+def fetch_aa():
+    key = os.environ.get("AA_API_KEY") or os.environ.get("ARTIFICIAL_ANALYSIS_API_KEY")
+    if not key:
+        sys.stderr.write(WARN("  Artificial Analysis: no $AA_API_KEY set — skipping quality refresh.\n"))
+        return {}
+    try:
+        data = http_get_json(AA_URL, {"x-api-key": key})
+    except urllib.error.HTTPError as e:
+        sys.stderr.write(ERR("  Artificial Analysis: HTTP %s (%s)\n" % (e.code, "bad key?" if e.code in (401, 403) else "")))
+        return {}
+    except Exception as e:
+        sys.stderr.write(ERR("  Artificial Analysis: %s\n" % str(e)[:80]))
+        return {}
+    rows = data.get("data") if isinstance(data, dict) else data
+    by_slug = {}
+    for m in (rows or []):
+        s = m.get("slug")
+        if s:
+            by_slug[s] = m
+    sys.stderr.write(DIM("  Artificial Analysis: %d model endpoints fetched.\n" % len(by_slug)))
+    return by_slug
+
+def fetch_openrouter():
+    reg = load_json(REGISTRY)
+    prov = (reg.get("providers", {}) or {}).get("openrouter", {})
+    key = None
+    for name in prov.get("env", ["OPENROUTER_API_KEY"]):
+        if os.environ.get(name):
+            key = os.environ[name]; break
+    if not key:
+        return {}
+    base = prov.get("base_url", "https://openrouter.ai/api/v1").rstrip("/")
+    try:
+        data = http_get_json(base + "/models", {"Authorization": "Bearer " + key})
+    except Exception:
+        return {}
+    out = {}
+    for m in (data.get("data") or []):
+        mid = m.get("id")
+        if not mid:
+            continue
+        arch = m.get("architecture") or {}
+        out[norm(mid.split("/")[-1])] = {
+            "context": m.get("context_length"),
+            "modalities": arch.get("input_modalities"),
+        }
+    sys.stderr.write(DIM("  OpenRouter: %d models fetched (context/modality).\n" % len(out)))
+    return out
+
+def aa_scores(m):
+    ev = m.get("evaluations") or {}
+    g = ev.get("gpqa")
+    return {
+        "intelligence": ev.get("artificial_analysis_intelligence_index"),
+        "coding": ev.get("artificial_analysis_coding_index"),
+        "math": ev.get("artificial_analysis_math_index"),
+        "reasoning": round(g * 100, 1) if isinstance(g, (int, float)) else None,
+        "speed_tps": m.get("median_output_tokens_per_second"),
+        "aa_slug": m.get("slug"),
+    }
+
+def main():
+    ap = argparse.ArgumentParser(prog="scrooge-capabilities")
+    ap.add_argument("--dry-run", action="store_true", help="fetch + match + print, but don't write")
+    args = ap.parse_args()
+
+    load_env_file(os.path.join(SCROOGE_DIR, ".env"))
+    reg = load_json(REGISTRY)
+    if not reg.get("models"):
+        sys.stderr.write(ERR("No registry at %s — run `scrooge setup` first.\n" % REGISTRY)); return 2
+
+    # base store: existing user caps, else the shipped seed
+    caps = load_json(CAPS) or load_json(seed_path() or "")
+    caps.setdefault("_meta", {})
+
+    by_slug = fetch_aa()
+    by_or = fetch_openrouter()
+    if not by_slug and not by_or:
+        sys.stderr.write(WARN("Nothing fetched — set $AA_API_KEY (free at artificialanalysis.ai) and/or an OpenRouter key.\n"))
+        return 1
+
+    today = __import__("time").strftime("%Y-%m-%d")
+    matched, unmatched = [], []
+    for mid in reg["models"]:
+        existing = caps.get(mid) if isinstance(caps.get(mid), dict) else {}
+        slug = (existing.get("aa_slug") or norm(mid))
+        m = by_slug.get(slug) or by_slug.get(norm(mid))
+        rec = dict(existing)
+        if m:
+            rec.update({k: v for k, v in aa_scores(m).items() if v is not None or k == "math"})
+            rec["updated"] = today
+            rec["source"] = "artificialanalysis"
+            matched.append(mid)
+        elif by_slug:
+            unmatched.append(mid)
+        orx = by_or.get(norm(mid))
+        if orx:
+            if orx.get("context"):
+                rec["context"] = orx["context"]
+            if orx.get("modalities"):
+                rec["modalities"] = orx["modalities"]
+        if rec:
+            caps[mid] = rec
+
+    caps["_meta"].update({"source": "artificialanalysis.ai + openrouter", "refreshed": today,
+                          "attribution": "https://artificialanalysis.ai/"})
+
+    sys.stderr.write(GOLD("🪙 scrooge-capabilities — %d matched, %d unmatched\n" % (len(matched), len(unmatched))))
+    for mid in matched:
+        c = caps[mid]
+        sys.stderr.write("  %s %-24s intel=%-5s code=%-5s reason=%-5s %st/s\n" % (
+            OK("✓"), mid, c.get("intelligence"), c.get("coding"), c.get("reasoning"),
+            (str(round(c["speed_tps"])) if isinstance(c.get("speed_tps"), (int, float)) else "?")))
+    for mid in unmatched:
+        sys.stderr.write("  %s %-24s %s\n" % (WARN("?"), mid,
+                         DIM("no AA match for slug '%s' — set its aa_slug in capabilities.json" % norm(mid))))
+
+    if args.dry_run:
+        sys.stderr.write(DIM("  (--dry-run: not written)\n")); return 0
+    os.makedirs(SCROOGE_DIR, exist_ok=True)
+    with open(CAPS, "w") as fh:
+        json.dump(caps, fh, indent=2); fh.write("\n")
+    sys.stderr.write(OK("  wrote %s\n" % CAPS.replace(HOME, "~")))
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())

package/engine/bin/scrooge-diverge

@@ -0,0 +1,263 @@
+#!/usr/bin/env python3
+"""
+diverge — native "diverge then focus" idea generator (claude-adhd pattern).
+
+PHASE 1 (Diverge): spawn N isolated ideation calls, each under a DIFFERENT
+cognitive frame, fanned across DIFFERENT cheap model families (DeepSeek / GLM /
+Gemini / Kimi) so branches can't anchor on each other or on one model's bias.
+Runs in parallel via the ~/.claude/bin/llm harness (cheap, ~free, transparent).
+
+PHASE 2 (Focus): a critic pass scores ideas (novelty/viability/fit), flags
+seductive-but-broken "traps", clusters by approach, and deepens the top-K.
+
+  • Default                : Phase 1 (cheap, parallel) + Phase 2 critic (cheap model).
+  • --raw                  : Phase 1 only — emit aggregated ideas JSON so OPUS
+                             (the orchestrator) can run the focus pass at full quality.
+                             This is the preferred flow inside Claude Code.
+
+Usage:
+  diverge "design a rate limiter that survives leader election"
+  diverge "name this function" --frames 4 --ideas 6 --top 2
+  diverge "..." --raw                 # ideas JSON -> Opus does the critic
+  diverge "..." --critic kimi         # autonomous, pick the critic model
+  diverge --list-frames
+
+Only for DIVERGENT problems (design, naming, API surface, debug hypotheses,
+"a few ways to X"). Not for convergent/execution work.
+"""
+import sys, os, json, argparse, subprocess, re, concurrent.futures, shutil
+
+# Resolve the cheap-model router (sibling `scrooge`), with PATH fallback.
+_HERE = os.path.dirname(os.path.realpath(__file__))
+LLM = os.path.join(_HERE, "scrooge")
+if not os.path.exists(LLM):
+    LLM = shutil.which("scrooge") or LLM
+
+# Cheap model families to rotate across (maximizes cross-family diversity).
+# Only models that are funded/working belong here; edit freely.
+# Fast, non-thinking models with clean JSON output across diverse families.
+# (Thinking models like gemini-2.5-flash / kimi-k2.6 burn the token budget on
+#  reasoning and truncate the JSON — use them explicitly, not in the default fan.)
+DIVERGE_MODELS = ["deepseek-chat", "glm-4.6", "glm-4.5-air", "gemini-2.5-flash-lite"]
+DEFAULT_CRITIC = "deepseek-chat"
+
+# --- live-model resolution (only fan across models the user actually has keys for) ---
+def _scrooge_home():
+    return os.environ.get("SCROOGE_HOME", os.path.join(os.path.expanduser("~"), ".opus-scrooge"))
+
+def _load_keys():
+    """Load SCROOGE_HOME/.env and $SCROOGE_ENV_FILE into os.environ (no override)."""
+    for path in (os.path.join(_scrooge_home(), ".env"), os.environ.get("SCROOGE_ENV_FILE", "")):
+        if path and os.path.exists(path):
+            for line in open(path):
+                line = line.strip()
+                if line and not line.startswith("#") and "=" in line:
+                    k, v = line.split("=", 1); k = k.strip()
+                    if k.startswith("export "): k = k[7:].strip()
+                    if k and k not in os.environ: os.environ[k] = v.strip().strip('"').strip("'")
+
+def live_models(prefer):
+    """Filter `prefer` to models whose provider has a live key; fall back to any live model."""
+    _load_keys()
+    try:
+        reg = json.load(open(os.path.join(_scrooge_home(), "registry.json")))
+    except Exception:
+        return prefer
+    provs, models = reg.get("providers", {}), reg.get("models", {})
+    has = lambda p: any(os.environ.get(n) for n in provs.get(p, {}).get("env", []))
+    live = [m for m in prefer if m in models and has(models[m]["provider"])]
+    if live:
+        return live
+    return [m for m, c in models.items() if has(c["provider"])] or prefer
+
+def first_live(prefer_list):
+    pool = live_models(prefer_list)
+    return pool[0] if pool else prefer_list[0]
+
+FRAMES = [
+    ("first-principles", "Ignore all convention and prior art. Derive solutions purely from the underlying constraints and physics of the problem."),
+    ("constraint-inversion", "Identify the single biggest assumed constraint, then imagine it removed or reversed. What becomes possible?"),
+    ("adversary", "Think like an attacker / red-teamer. Design from the angle of how this breaks, gets abused, or fails under hostile conditions — then what design survives that."),
+    ("minimalist", "Find the absolute simplest thing that could possibly work. Strip every non-essential part. Bias toward less."),
+    ("extreme-scale", "Assume 1000x the load, users, data, or concurrency. What designs only make sense at extreme scale?"),
+    ("cross-domain", "Borrow from a completely different field (biology, logistics, games, finance, distributed systems). What analogy transfers?"),
+    ("user-empathy", "Reason only from the end-user's lived experience and emotional needs. What do THEY actually feel and want?"),
+    ("temporal", "Think 2 years out. What ages badly, what becomes legacy, what is still good in the long run?"),
+    ("pragmatic-cost", "Optimize for cheapest and fastest to ship and operate. What is the 80/20 that ships this week?"),
+    ("composition", "Solve it by combining existing, proven building blocks rather than inventing anything new."),
+    ("contrarian", "Argue hard for the OPPOSITE of the obvious/popular approach. Make the strongest case for the unconventional path."),
+    ("second-order", "Focus on downstream and emergent effects. What does this cause two steps later that nobody planned for?"),
+]
+
+def frame_lookup():
+    return {n: v for n, v in FRAMES}
+
+def extract_json(text):
+    """Pull a JSON object/array out of model output (handles code fences/prose)."""
+    if not text:
+        return None
+    t = text.strip()
+    t = re.sub(r"^```(?:json)?\s*|\s*```$", "", t, flags=re.MULTILINE).strip()
+    for opener, closer in (("{", "}"), ("[", "]")):
+        i = t.find(opener)
+        if i >= 0:
+            depth = 0
+            for j in range(i, len(t)):
+                if t[j] == opener: depth += 1
+                elif t[j] == closer:
+                    depth -= 1
+                    if depth == 0:
+                        try:
+                            return json.loads(t[i:j+1])
+                        except Exception:
+                            break
+    try:
+        return json.loads(t)
+    except Exception:
+        pass
+    # Salvage: pull complete {...} objects out of a truncated array.
+    objs = []
+    for m in re.finditer(r"\{[^{}]*\}", t):
+        try:
+            objs.append(json.loads(m.group(0)))
+        except Exception:
+            continue
+    return objs or None
+
+def call_llm(model, prompt, system=None, max_tokens=900, want_json=True):
+    cmd = [LLM, "--model", model, "--max-tokens", str(max_tokens)]
+    if want_json:
+        cmd.append("--json")
+    if system:
+        cmd += ["--system", system]
+    cmd.append(prompt)
+    # stderr inherits -> the 🔶 EXTERNAL-LLM banners stay visible (transparency).
+    r = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=None, text=True)
+    return r.stdout
+
+def run_frame(problem, frame_name, vantage, model, ideas_per_frame):
+    system = ("You are an idea GENERATOR working under a strict cognitive frame. "
+              "Generate diverse ideas ONLY — do NOT evaluate, rank, or hedge. "
+              "Adopt this lens completely: " + vantage)
+    prompt = (f'PROBLEM: {problem}\n\n'
+              f'Through the "{frame_name}" lens above, produce {ideas_per_frame} DISTINCT ideas. '
+              f'Each idea: a short title and a 1-3 sentence sketch. '
+              f'Respond as JSON: {{"ideas":[{{"title":"...","sketch":"..."}}]}}')
+    out = call_llm(model, prompt, system=system, max_tokens=1400)
+    parsed = extract_json(out)
+    ideas = []
+    if isinstance(parsed, dict):
+        ideas = parsed.get("ideas", []) or []
+    elif isinstance(parsed, list):
+        ideas = parsed
+    norm = []
+    for it in ideas:
+        if isinstance(it, dict) and it.get("title"):
+            norm.append({"title": str(it.get("title"))[:160], "sketch": str(it.get("sketch", ""))[:600],
+                         "frame": frame_name, "model": model})
+    return norm
+
+def diverge(problem, n_frames, ideas_per_frame, workers):
+    chosen = FRAMES[:n_frames] if n_frames <= len(FRAMES) else FRAMES
+    pool = live_models(DIVERGE_MODELS)   # only models the user has keys for
+    sys.stderr.write("\n\033[1m◆ DIVERGE\033[0m — %d frames × %d ideas, fanned across %d cheap model(s) (parallel)\n" % (len(chosen), ideas_per_frame, len(pool)))
+    sys.stderr.write("  frames: %s\n  models: %s\n\n" % (", ".join(n for n, _ in chosen), ", ".join(pool)))
+    results = []
+    with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as ex:
+        futs = {}
+        for i, (fname, vantage) in enumerate(chosen):
+            model = pool[i % len(pool)]
+            futs[ex.submit(run_frame, problem, fname, vantage, model, ideas_per_frame)] = fname
+        for fut in concurrent.futures.as_completed(futs):
+            try:
+                ideas = fut.result()
+                results.extend(ideas)
+                sys.stderr.write("  ✓ %-20s %d ideas\n" % (futs[fut], len(ideas)))
+            except Exception as e:
+                sys.stderr.write("  ✗ %-20s %s\n" % (futs[fut], e))
+    return results
+
+def focus(problem, ideas, top_k, critic_model):
+    # De-identify frames so the critic doesn't bias toward a label.
+    listing = "\n".join("%d. %s — %s" % (i+1, it["title"], it["sketch"]) for i, it in enumerate(ideas))
+    system = ("You are a sharp, skeptical critic. You evaluate a pool of candidate ideas. "
+              "Your highest-value job is spotting SEDUCTIVE-BUT-BROKEN ideas (traps) and saying why. "
+              "Be concrete and honest; do not inflate scores.")
+    prompt = (f'PROBLEM: {problem}\n\nCANDIDATE IDEAS:\n{listing}\n\n'
+              f'Do all of the following and respond as JSON:\n'
+              f'1. Cluster the ideas into a few distinct approaches (name each cluster).\n'
+              f'2. Flag "traps": ideas that look attractive but are broken/risky, WITH the reason.\n'
+              f'3. Pick the top {top_k} ideas overall (by novelty+viability+fit) and DEEPEN each into '
+              f'{{"title","why_it_wins","risks":["..."],"first_steps":["..."]}}.\n'
+              f'JSON shape: {{"clusters":[{{"name","idea_indexes":[..]}}],'
+              f'"traps":[{{"title","why_broken"}}],'
+              f'"top":[{{"title","why_it_wins","risks":[],"first_steps":[]}}]}}')
+    sys.stderr.write("\n\033[1m◆ FOCUS\033[0m — critic pass on %s\n" % critic_model)
+    out = call_llm(critic_model, prompt, system=system, max_tokens=2000)
+    return extract_json(out)
+
+def render(problem, ideas, report):
+    print("=" * 70)
+    print("DIVERGE → FOCUS:", problem)
+    print("=" * 70)
+    print("\nGenerated %d ideas across %d frames.\n" % (len(ideas), len(set(i["frame"] for i in ideas))))
+    if not report:
+        print("(critic returned no parseable result — raw ideas below)")
+        for it in ideas:
+            print("  • [%s] %s — %s" % (it["frame"], it["title"], it["sketch"]))
+        return
+    cl = report.get("clusters", [])
+    if cl:
+        print("APPROACHES:")
+        for c in cl:
+            print("  ▸ %s  (%d ideas)" % (c.get("name", "?"), len(c.get("idea_indexes", []))))
+    traps = report.get("traps", [])
+    if traps:
+        print("\n⚠ TRAPS (seductive but broken):")
+        for t in traps:
+            print("  ✗ %s — %s" % (t.get("title", "?"), t.get("why_broken", "")))
+    top = report.get("top", [])
+    if top:
+        print("\n★ TOP %d (deepened):" % len(top))
+        for i, t in enumerate(top, 1):
+            print("\n  %d. %s" % (i, t.get("title", "?")))
+            print("     why: %s" % t.get("why_it_wins", ""))
+            for r in t.get("risks", []): print("     risk: %s" % r)
+            for s in t.get("first_steps", []): print("     step: %s" % s)
+    print()
+
+def main():
+    ap = argparse.ArgumentParser(prog="diverge")
+    ap.add_argument("problem", nargs="?")
+    ap.add_argument("--frames", type=int, default=6)
+    ap.add_argument("--ideas", type=int, default=5, help="ideas per frame")
+    ap.add_argument("--top", type=int, default=3)
+    ap.add_argument("--workers", type=int, default=6)
+    ap.add_argument("--critic", default=DEFAULT_CRITIC)
+    ap.add_argument("--raw", action="store_true", help="emit ideas JSON only (Opus does the focus)")
+    ap.add_argument("--list-frames", action="store_true")
+    args = ap.parse_args()
+
+    if args.list_frames:
+        for n, v in FRAMES:
+            print("%-20s %s" % (n, v))
+        return
+    if not args.problem:
+        ap.error("provide a problem, or --list-frames")
+
+    ideas = diverge(args.problem, args.frames, args.ideas, args.workers)
+    if not ideas:
+        sys.stderr.write("No ideas generated.\n"); sys.exit(2)
+
+    if args.raw:
+        # Hand structured ideas to the orchestrator (Opus) for a full-quality focus pass.
+        json.dump({"problem": args.problem, "ideas": ideas}, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+        return
+
+    critic = first_live([args.critic] + DIVERGE_MODELS)   # ensure the critic model is live
+    report = focus(args.problem, ideas, args.top, critic)
+    render(args.problem, ideas, report)
+
+if __name__ == "__main__":
+    main()

package/engine/bin/scrooge-drift

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""
+scrooge-drift — detect when the scrooge registry has fallen behind reality.
+
+For every provider that has a live API key, lists the models the provider
+actually serves right now (`scrooge models <provider>`) and diffs that against
+the model ids the registry routes to.
+
+Reports:
+  DEAD   — model id in the registry that the provider no longer serves
+           (these calls will FAIL — fix ASAP)
+  NEW    — current-gen model the provider serves that the registry doesn't know
+           (candidate to adopt; filtered to likely chat models)
+
+Exit code 0 = registry in sync. Exit code 1 = drift found (DEAD or NEW).
+Run weekly via cron; act on the report next session.
+
+Usage: scrooge-drift [--json] [--quiet]
+"""
+import os, sys, json, subprocess, re
+
+HOME = os.path.expanduser("~")
+SCROOGE_DIR = os.environ.get("SCROOGE_HOME", os.path.join(HOME, ".token-scrooge"))
+REGISTRY = os.path.join(SCROOGE_DIR, "registry.json")
+SCROOGE = os.environ.get("SCROOGE_BIN", os.path.join(HOME, ".local", "bin", "scrooge"))
+
+# Live model ids matching these are noise we'd never route grunt work to:
+# media/audio/embeddings/etc, legacy generations, and dated pin snapshots.
+NOISE = re.compile(
+    r"(image|video|audio|tts|embed|whisper|imagine|aqa|computer-use|"
+    r"deep-research|antigravity|guard|rerank|moderation|robotics|realtime|"
+    r"transcribe|search-preview|sora|veo|lyria|gemma|nano-banana|"
+    r"babbage|davinci|instruct|moonshot-v1|"
+    r"gpt-3|gpt-4-|gpt-4o|gpt-4\.|gpt-4$|"           # superseded OpenAI gens
+    r"gemini-2\.0|gemini-1|"                          # superseded Gemini gens
+    r"o1|o3|o4-|"                                      # superseded OpenAI reasoners
+    r"-latest$|"                                       # rolling aliases, not pinned ids
+    r"-\d{4}-\d{2}-\d{2}|-\d{6}$|-\d{4}$|-preview-\d)",  # dated pin snapshots
+    re.I,
+)
+NEW_CAP = 10  # don't flood the report; the refresh pass does the real curation
+
+
+def load_registry():
+    with open(REGISTRY) as fh:
+        return json.load(fh)
+
+
+def live_models(provider):
+    """Return the set of model ids the provider serves right now, or None on error."""
+    try:
+        out = subprocess.run(
+            [SCROOGE, "models", provider],
+            capture_output=True, text=True, timeout=40,
+        )
+    except Exception as e:
+        return None, str(e)
+    if out.returncode != 0:
+        return None, (out.stderr or out.stdout).strip()[:200]
+    ids = set()
+    for line in out.stdout.splitlines():
+        s = line.strip()
+        if not s or " " in s:          # skip headers / banner lines
+            continue
+        ids.add(s.split("/")[-1])      # strip "models/" gemini prefix
+    return ids, None
+
+
+def main():
+    as_json = "--json" in sys.argv
+    quiet = "--quiet" in sys.argv
+    reg = load_registry()
+
+    # provider -> registry model ids
+    reg_by_prov = {}
+    for mid, m in reg["models"].items():
+        reg_by_prov.setdefault(m["provider"], set()).add(mid)
+
+    report = {"dead": {}, "new": {}, "errors": {}}
+    for prov in reg["providers"]:
+        # only providers we actually route to AND have a key for
+        if prov not in reg_by_prov:
+            continue
+        live, err = live_models(prov)
+        if live is None:
+            report["errors"][prov] = err
+            continue
+        registered = reg_by_prov[prov]
+        dead = sorted(m for m in registered if m.split("/")[-1] not in live)
+        new = sorted(
+            m for m in live
+            if m not in {r.split("/")[-1] for r in registered} and not NOISE.search(m)
+        )
+        if dead:
+            report["dead"][prov] = dead
+        if new:
+            report["new"][prov] = new
+
+    drift = bool(report["dead"] or report["new"])
+
+    if as_json:
+        print(json.dumps({"drift": drift, **report}, indent=2))
+    elif not quiet or drift:
+        if report["dead"]:
+            print("DEAD (registry routes to retired models — calls will FAIL):")
+            for p, ms in report["dead"].items():
+                print("  %-10s %s" % (p, ", ".join(ms)))
+        if report["new"]:
+            print("NEW (current-gen models not yet in registry):")
+            for p, ms in report["new"].items():
+                shown = ms[:NEW_CAP]
+                extra = len(ms) - len(shown)
+                tail = "  (+%d more)" % extra if extra > 0 else ""
+                print("  %-10s %s%s" % (p, ", ".join(shown), tail))
+        if report["errors"]:
+            print("ERRORS (couldn't list — skipped):")
+            for p, e in report["errors"].items():
+                print("  %-10s %s" % (p, e))
+        if not drift and not report["errors"]:
+            print("registry in sync — no drift.")
+
+    sys.exit(1 if drift else 0)
+
+
+if __name__ == "__main__":
+    main()