@caddis/cli 0.2.6 → 0.3.0

package/bundles/antigravity-plugin/scripts/enforcement_inventory.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+"""Inventory caddis's load-bearing rules, and measure how many are actually enforced.
+
+WHY THIS EXISTS
+---------------
+Three independent audits reached the same conclusion in different words: strip the prose from
+this plugin and the machine content is very small. Nearly every "MUST" / "NEVER" / "STOP" is a
+sentence in a markdown file that a model may or may not honour. Those degrade silently under
+model change, context pressure, a cheaper lane, or a distracted session — and they read as
+guarantees, which is worse than reading as advice.
+
+The things that actually held under pressure were the ones with exit codes: pytest,
+validate_pool, the hooks, oss_review's exit 2.
+
+So this script measures the ratio of rules that a machine can fail on, to rules that only a
+model can choose to honour. That number is the health metric for the plugin. It is expected to
+start LOW; the point is that it is visible and moves in one direction.
+
+THE ANTI-FLATTERY RULE
+----------------------
+The classification is DERIVED FROM THE LINT TESTS, never asserted by hand. A rule counts as
+`machine` only when a test that targets its file asserts a literal string contained in that
+rule's text — i.e. deleting the rule would turn a test red. Everything else is `advisory`.
+
+This matters because the first version of this script DID use a hand-written registry, and it
+was wrong in both directions: a global substring match credited an unrelated skill's "ALWAYS ask
+via AskUserQuestion" to the headless-mode test, while genuinely-covered rules went uncounted
+because their sentence lacked the registry keyword. A metric you can talk yourself into is not a
+metric. Deriving it from the tests also means it moves on its own the moment someone adds or
+removes a lint, which is the only way a health number stays honest.
+
+Known limit, stated rather than hidden: matching is per-line, so a rule spanning two lines can be
+missed, and a long asserted literal can match a neighbouring sentence. Treat the ratio as an
+order-of-magnitude signal and a direction of travel, not a precise score.
+
+Usage:
+  python scripts/enforcement_inventory.py            # summary + ratio
+  python scripts/enforcement_inventory.py --list     # every rule, classified
+  python scripts/enforcement_inventory.py --advisory # only the unenforced ones
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+
+REPO = Path(__file__).resolve().parents[1]
+SCAN_ROOTS = [REPO / "claude-harness" / "commands", REPO / ".github" / "skills"]
+
+# An imperative that makes a promise. Ordered longest-first so MUST NOT wins over MUST.
+IMPERATIVE = re.compile(
+    r"\b(MUST NOT|MUST|NEVER|ALWAYS|REQUIRED|STOP|DO NOT|Do not)\b"
+)
+
+# ── Deriving enforcement FROM THE TESTS, not from a hand-written claim ──────
+# An earlier version used a hand-maintained registry of rule->enforcer. It was wrong in both
+# directions: a global substring match credited brand-design's "ALWAYS ask via AskUserQuestion"
+# to the headless-mode test, which has nothing to do with it, while genuinely-covered rules went
+# uncounted because their sentence lacked the registry's keyword.
+#
+# So the classifier now READS THE LINT TESTS. For each test module it works out which source
+# files that module targets (from its module-level Path constants) and which literal strings it
+# asserts on. A rule is `machine` when a test targeting ITS file asserts a literal contained in
+# its text. Nothing is claimed that a test does not actually check, and the metric updates itself
+# the moment someone adds or deletes a lint - which is the property a health metric must have.
+LINT_TEST_DIRS = [REPO / "scripts" / "tests", REPO / "claude-harness" / "hooks" / "tests"]
+
+# Literals shorter than this match too much to mean anything.
+MIN_LITERAL = 10
+
+
+def _test_modules() -> list[tuple[set[str], set[str]]]:
+    """(source files this test targets, literals it asserts) for every lint test module."""
+    import ast
+    out = []
+    for d in LINT_TEST_DIRS:
+        if not d.exists():
+            continue
+        for f in sorted(d.glob("test_*.py")):
+            if f.name == "test_enforcement_inventory.py":
+                continue  # measures the metric; must not feed it
+            try:
+                tree = ast.parse(f.read_text(encoding="utf-8", errors="ignore"))
+            except SyntaxError:
+                continue
+            # ONLY literals inside an `assert` count. Scanning every string constant swept in
+            # docstrings and fixture data, and this module's own test docstrings describe the very
+            # rules being measured - so prose about a rule was being counted as enforcement OF that
+            # rule. The metric was measuring how much we had WRITTEN about enforcement.
+            literals: set[str] = set()
+            for node in ast.walk(tree):
+                if not isinstance(node, ast.Assert):
+                    continue
+                for sub in ast.walk(node):
+                    if isinstance(sub, ast.Constant) and isinstance(sub.value, str):
+                        v = sub.value.strip()
+                        if len(v) >= MIN_LITERAL:
+                            literals.add(v)
+            # TARGETS come from ALL string constants, not just asserts: a module names the file
+            # it lints in a module-level Path constant (`_IMPLEMENT = ... / "implement.md"`), which
+            # is not an assert. Deriving both from the assert set emptied every target and drove
+            # the ratio to a false 0.0% - caught by this module's own plausibility test.
+            targets = {
+                v.strip() for node in ast.walk(tree)
+                if isinstance(node, ast.Constant) and isinstance(node.value, str)
+                for v in [node.value] if v.strip().endswith(".md")
+            }
+            out.append((targets, literals))
+    return out
+
+
+_MODULES = _test_modules()
+
+
+def _enforcer_for(rel_path: str, text: str) -> str | None:
+    """The lint that would fail if this rule were deleted, or None."""
+    fname = rel_path.rsplit("/", 1)[-1]
+    for targets, literals in _MODULES:
+        if not any(t == fname or t.endswith(fname) for t in targets):
+            continue
+        for lit in literals:
+            if lit.lower() in text.lower():
+                return "lint"
+    return None
+
+
+# ── Gates: rules enforced by an executable, not merely by a content lint ────
+# The first version counted only lint tests, so a rule backed by a REAL gate scored the same as
+# one backed by nothing - the metric was blind to the strongest form of enforcement and would
+# have shown no movement for the phase that introduced it. A rule counts as gate-enforced when
+# its file invokes caddis_gate.py AND the rule concerns one of the gate's actual subcommands.
+# The subcommand must exist in the script: a claim nobody implements is exactly what this file
+# refuses to reward.
+GATE_SCRIPT = REPO / "scripts" / "caddis_gate.py"
+GATE_CONCERNS = {
+    "lane-check": ("lane", "spawn", "launch command", "--print", "-p"),
+    "verdict-gate": ("verdict", "advisory-hub", "blocked-pending-hub", "accept-degraded"),
+    "tracker-vs-git": ("tracker",),
+}
+
+
+def _live_gates() -> dict[str, tuple[str, ...]]:
+    """Subcommands the gate script actually implements. Verified, never assumed."""
+    if not GATE_SCRIPT.is_file():
+        return {}
+    src = GATE_SCRIPT.read_text(encoding="utf-8", errors="ignore")
+    return {k: v for k, v in GATE_CONCERNS.items() if f'"{k}"' in src or f"'{k}'" in src}
+
+
+_GATES = _live_gates()
+
+
+def _gate_for(file_text: str, text: str) -> str | None:
+    if "caddis_gate.py" not in file_text:
+        return None
+    low = text.lower()
+    for sub, needles in _GATES.items():
+        if any(n.lower() in low for n in needles):
+            return sub
+    return None
+
+
+@dataclass
+class Rule:
+    path: str
+    line: int
+    marker: str
+    text: str
+    enforcer: str | None = None
+
+    @property
+    def machine(self) -> bool:
+        return self.enforcer is not None
+
+
+def _sentence(line: str) -> str:
+    return " ".join(line.split())[:150]
+
+
+def collect(roots: list[Path] | None = None) -> list[Rule]:
+    rules: list[Rule] = []
+    for root in (roots or SCAN_ROOTS):
+        if not root.exists():
+            continue
+        for f in sorted(root.rglob("*.md")):
+            try:
+                lines = f.read_text(encoding="utf-8", errors="ignore").splitlines()
+            except Exception:
+                continue
+            # Fall back to the absolute path for roots outside the repo, so collect() can be
+            # pointed at a fixture directory. A metric script that cannot be tested on a fixture
+            # can only be verified by eyeballing its output, which is how metrics start lying.
+            whole = "\n".join(lines)
+            try:
+                rel = str(f.relative_to(REPO)).replace("\\", "/")
+            except ValueError:
+                rel = str(f).replace("\\", "/")
+            for i, line in enumerate(lines, 1):
+                m = IMPERATIVE.search(line)
+                if not m:
+                    continue
+                text = _sentence(line)
+                enf = _enforcer_for(rel, text) or _gate_for(whole, text)
+                rules.append(Rule(rel, i, m.group(1), text, enf))
+    return rules
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="caddis enforcement inventory")
+    ap.add_argument("--list", action="store_true", help="print every rule, classified")
+    ap.add_argument("--advisory", action="store_true", help="print only the unenforced rules")
+    args = ap.parse_args(argv)
+
+    rules = collect()
+    machine = [r for r in rules if r.machine]
+    advisory = [r for r in rules if not r.machine]
+    total = len(rules)
+    ratio = (len(machine) / total) if total else 0.0
+
+    if args.list or args.advisory:
+        for r in rules:
+            if args.advisory and r.machine:
+                continue
+            tag = f"machine <- {r.enforcer}" if r.machine else "advisory"
+            print(f"  [{tag}] {r.path}:{r.line}  {r.marker}")
+            print(f"      {r.text}")
+        print()
+
+    # Report the SPLIT, not just the headline. A single blended number is actively misleading:
+    # it is dominated by the ~235 skill rules, which are guidance ("prefer this", "consider that")
+    # and SHOULD be advisory - turning them into exit codes would be theatre. The number that
+    # matters is commands, because that is the execution path where a broken guarantee costs you.
+    cmd = [r for r in rules if "/commands/" in r.path]
+    skl = [r for r in rules if "/commands/" not in r.path]
+    def _pct(group):
+        return (sum(1 for r in group if r.machine) / len(group)) if group else 0.0
+
+    print("=" * 62)
+    print(f"  load-bearing rules found : {total}")
+    print(f"  machine-enforced         : {len(machine)}")
+    print(f"  advisory only            : {len(advisory)}")
+    print("-" * 62)
+    print(f"  COMMANDS (execution path): {sum(1 for r in cmd if r.machine)}/{len(cmd)}  "
+          f"= {_pct(cmd):.1%}   <- the figure that matters")
+    print(f"  SKILLS   (guidance)      : {sum(1 for r in skl if r.machine)}/{len(skl)}  "
+          f"= {_pct(skl):.1%}   (advisory is correct here)")
+    print(f"  blended                  : {ratio:.1%}")
+    print("=" * 62)
+    print("  A low number is not a bug report - it is the starting point. Advisory rules are")
+    print("  legitimate; the danger is an advisory rule that READS like a guarantee. Move the")
+    print("  load-bearing ones to exit codes, and label the rest honestly.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundles/antigravity-plugin/scripts/hook_log.py

@@ -0,0 +1,156 @@
+"""Throttled error ledger for caddis hooks — so a broken hook is not a silent one.
+
+The problem
+-----------
+caddis hooks fail open, which is right: a SessionStart hook that raises would break
+the session, and a PreToolUse hook that raises would break the tool call. The way
+they fail open is ``except Exception: pass``, which is wrong: a hook that is broken
+and a hook that had nothing to say produce the identical result — nothing.
+
+There were 20 such swallows across 6 hook files. Each one guards a named feature.
+When ``dream_memory``'s surface stops printing, nobody learns that it stopped; they
+learn that they have not seen it lately, months later, if at all.
+
+The fix keeps fail-open and adds a record. ``record()`` never raises, never prints,
+and never blocks — if the ledger itself cannot be written, that is swallowed too.
+
+Throttle
+--------
+One line per ``(hook, feature, error type)`` per day. A hook that fails on every
+single tool call writes one line, not thousands. The ledger is a signal, not a trace.
+
+Surfacing
+---------
+``summarise()`` returns a one-line summary of the last N days, or "" when clean.
+``inject_relay.py`` prints it at SessionStart. That is the only place a user is
+told; there is no second channel to ignore.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+
+_ARTIFACT_DIR = ".caddis"
+_LEDGER_NAME = "hook-errors.jsonl"
+_MAX_LINES = 400  # ring-buffer cap; the ledger must never grow without bound
+
+
+def _ledger_path(root: str | None) -> str | None:
+    try:
+        base = root or os.getcwd()
+        d = os.path.join(base, _ARTIFACT_DIR)
+        if not os.path.isdir(d):
+            return None  # not a caddis project — nothing to write into, and that is fine
+        return os.path.join(d, _LEDGER_NAME)
+    except Exception:
+        return None
+
+
+def record(hook: str, feature: str, exc: BaseException, root: str | None = None) -> None:
+    """Note that ``feature`` inside ``hook`` failed. Never raises, never prints.
+
+    ``feature`` is the thing the user loses — "parked-stack surface", "relay read" —
+    not the function name. The ledger is read by a human deciding whether to care.
+    """
+    try:
+        path = _ledger_path(root)
+        if path is None:
+            return
+
+        etype = type(exc).__name__
+        # Truncate: an exception message can carry a path, a command, or a chunk of
+        # file content. One line of context is enough to act on.
+        emsg = str(exc)[:200]
+        today = time.strftime("%Y-%m-%d")
+        key = f"{hook}|{feature}|{etype}"
+
+        lines: list[str] = []
+        if os.path.isfile(path):
+            try:
+                with open(path, "r", encoding="utf-8", errors="replace") as fh:
+                    lines = fh.read().splitlines()
+            except Exception:
+                lines = []
+
+        for line in reversed(lines[-120:]):  # today's entries are at the tail
+            try:
+                rec = json.loads(line)
+            except Exception:
+                continue
+            if rec.get("key") == key and str(rec.get("ts", ""))[:10] == today:
+                return  # already recorded today — throttled
+
+        lines.append(json.dumps({
+            "ts": time.strftime("%Y-%m-%dT%H:%M:%S"),
+            "key": key,
+            "hook": hook,
+            "feature": feature,
+            "error": etype,
+            "message": emsg,
+        }, ensure_ascii=False))
+
+        with open(path, "w", encoding="utf-8", newline="\n") as fh:
+            fh.write("\n".join(lines[-_MAX_LINES:]) + "\n")
+    except Exception:
+        return  # the ledger must never be the thing that breaks a hook
+
+
+def summarise(root: str | None = None, days: int = 7) -> str:
+    """One line naming what has been failing, or "" when there is nothing to say."""
+    try:
+        path = _ledger_path(root)
+        if path is None or not os.path.isfile(path):
+            return ""
+
+        cutoff = time.strftime("%Y-%m-%d", time.localtime(time.time() - days * 86400))
+        counts: dict[str, int] = {}
+        with open(path, "r", encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    rec = json.loads(line)
+                except Exception:
+                    continue
+                if str(rec.get("ts", ""))[:10] < cutoff:
+                    continue
+                label = f"{rec.get('hook', '?')}/{rec.get('feature', '?')}"
+                counts[label] = counts.get(label, 0) + 1
+
+        if not counts:
+            return ""
+        ranked = sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))
+        shown = ", ".join(f"{k} x{v}" for k, v in ranked[:4])
+        more = f" (+{len(ranked) - 4} more)" if len(ranked) > 4 else ""
+        return (f"[caddis] hook errors in the last {days} days: {shown}{more} — "
+                f"see {_ARTIFACT_DIR}/{_LEDGER_NAME}")
+    except Exception:
+        return ""
+
+
+def main() -> int:
+    """``python hook_log.py [root]`` prints the ledger, newest last. For eyeballing."""
+    import sys
+    root = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
+    path = _ledger_path(root)
+    if path is None or not os.path.isfile(path):
+        print(f"no hook-error ledger at {root}/{_ARTIFACT_DIR}/{_LEDGER_NAME} — nothing has failed")
+        return 0
+    with open(path, "r", encoding="utf-8", errors="replace") as fh:
+        for line in fh:
+            try:
+                rec = json.loads(line)
+            except Exception:
+                continue
+            print(f"{rec.get('ts', '?'):<20} {rec.get('hook', '?')}/{rec.get('feature', '?'):<28} "
+                  f"{rec.get('error', '?')}: {rec.get('message', '')}")
+    summary = summarise(root)
+    if summary:
+        print("\n" + summary)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundles/antigravity-plugin/scripts/oss_ask.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""One-shot question to an OSS provider (DeepSeek/GLM/OpenRouter) — plain chat, no tools.
+
+Backs the /ask-glm and /ask-deepseek commands: a fast second-opinion answer from a
+different model family, without spinning up a full Claude Code session. Speaks the
+providers' OpenAI-compatible ``/chat/completions`` dialect (NOT the Anthropic endpoints
+oss_model.py hands to Claude Code), and reuses oss_model's key resolution so one entry
+in ~/.caddis/keys.env lights up every lane.
+
+Usage:
+  python oss_ask.py <provider> <prompt...>  [--model M] [--base-url U] [--system S]
+
+Exit codes: 0 answer printed; 2 endpoint/parse error; 3 config error (message on stderr).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import oss_model  # noqa: E402  (same-directory import: shared key resolution)
+
+# OpenAI-compatible chat endpoints — intentionally different from oss_model.PROVIDERS,
+# which holds the Anthropic-protocol endpoints for Claude Code.
+CHAT_PROVIDERS: dict[str, dict[str, str]] = {
+    "deepseek":   {"base_url": "https://api.deepseek.com",            "model": "deepseek-v4-flash",          "key_env": "DEEPSEEK_API_KEY"},
+    "glm":        {"base_url": "https://api.z.ai/api/coding/paas/v4", "model": "glm-5.2",                    "key_env": "GLM_API_KEY"},
+    "openrouter": {"base_url": "https://openrouter.ai/api/v1",        "model": "deepseek/deepseek-v4-flash", "key_env": "OPENROUTER_API_KEY"},
+}
+
+EXIT_OK = 0
+EXIT_ERROR = 2
+EXIT_CONFIG = 3
+
+
+def resolve_chat_config(provider: str, env: dict[str, str],
+                        model: str | None = None, base_url: str | None = None) -> dict[str, str]:
+    """{base_url, model, api_key} for the chat lane. Flag > preset; key via oss_model."""
+    preset = CHAT_PROVIDERS.get(provider.strip().lower(), {})
+    resolved_base = (base_url or preset.get("base_url") or "").rstrip("/")
+    resolved_model = model or preset.get("model") or ""
+    if not resolved_base or not resolved_model:
+        known = ", ".join(sorted(CHAT_PROVIDERS))
+        raise oss_model.ConfigError(
+            f"unknown provider {provider!r}: pass --base-url and --model, or use one of: {known}."
+        )
+    key_env = preset.get("key_env") or f"{provider.upper()}_API_KEY"
+    api_key = oss_model._resolve_key(provider, key_env, env)
+    return {"base_url": resolved_base, "model": resolved_model, "api_key": api_key}
+
+
+def ask(cfg: dict[str, str], prompt: str, system: str | None = None, timeout: int = 120) -> str:
+    """POST the prompt to {base_url}/chat/completions and return the reply text."""
+    messages = ([{"role": "system", "content": system}] if system else []) + [
+        {"role": "user", "content": prompt}
+    ]
+    body = json.dumps({"model": cfg["model"], "messages": messages}).encode("utf-8")
+    req = urllib.request.Request(
+        f"{cfg['base_url']}/chat/completions",
+        data=body,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {cfg['api_key']}",
+        },
+    )
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        payload = json.loads(resp.read().decode("utf-8"))
+    return payload["choices"][0]["message"]["content"]
+
+
+def main(argv: list[str], env: dict[str, str] | None = None) -> int:
+    env = dict(oss_model.os.environ) if env is None else env
+    ap = argparse.ArgumentParser(description="One-shot question to an OSS provider (no tools).")
+    ap.add_argument("provider", help="deepseek | glm | openrouter (or custom with --base-url/--model)")
+    ap.add_argument("prompt", nargs="+", help="the question")
+    ap.add_argument("--model", default=None)
+    ap.add_argument("--base-url", default=None)
+    ap.add_argument("--system", default=None)
+    args = ap.parse_args(argv)
+    try:
+        cfg = resolve_chat_config(args.provider, env, model=args.model, base_url=args.base_url)
+    except oss_model.ConfigError as exc:
+        print(str(exc), file=sys.stderr)
+        return EXIT_CONFIG
+    try:
+        print(ask(cfg, " ".join(args.prompt), system=args.system))
+    except (urllib.error.URLError, KeyError, IndexError, json.JSONDecodeError, TimeoutError) as exc:
+        print(f"oss_ask: endpoint/parse failure: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    return EXIT_OK
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/bundles/antigravity-plugin/scripts/oss_model.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Shared provider + key resolver for the model-switching launchers (Track A).
+
+`claude-oss` / `claude-glm` point a Claude Code session at an OpenAI-compatible
+endpoint (GLM, DeepSeek, OpenRouter, or any custom base_url) by setting the
+``ANTHROPIC_*`` env vars. This module owns the ONE place that maps a provider name
+to its endpoint + default model, and resolves the API key WITHOUT ever hardcoding a
+path or a secret.
+
+Key resolution precedence (highest wins):
+  1. the provider's explicit env var (GLM_API_KEY / DEEPSEEK_API_KEY / OPENROUTER_API_KEY),
+     or the generic OSS_API_KEY;
+  2. a keys file at CADDIS_KEYS_FILE (default ~/.caddis/keys.env), INI/KEY=VALUE style,
+     comments (#) and blank lines allowed;
+  3. ConfigError with an actionable message.
+
+Endpoint/model precedence: OSS_BASE_URL / OSS_MODEL env override > the provider preset.
+An unknown provider is fine as long as OSS_BASE_URL + OSS_MODEL are supplied.
+
+The PROVIDERS table mirrors oss_review.py so a renamed model id / moved endpoint is a
+one-line edit in each. (oss_review may import this later; not refactored here to keep
+the diff small.)
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+# Provider presets — the SINGLE place a renamed model id / moved endpoint is edited.
+# These are the providers' ANTHROPIC-protocol endpoints: this table feeds
+# ANTHROPIC_BASE_URL for Claude Code, which speaks the Anthropic Messages API — NOT the
+# OpenAI /chat/completions dialect that oss_review.py uses (its table differs on purpose).
+# "openrouter" has no Anthropic-protocol endpoint: it only works through an
+# Anthropic-compatible gateway (e.g. LiteLLM — see claude-harness/LOCAL-MODELS.md) whose
+# URL you supply via OSS_BASE_URL.
+PROVIDERS: dict[str, dict[str, str]] = {
+    "deepseek":   {"base_url": "https://api.deepseek.com/anthropic",  "model": "deepseek-v4-flash",          "key_env": "DEEPSEEK_API_KEY"},
+    "glm":        {"base_url": "https://api.z.ai/api/anthropic",      "model": "glm-5.2",                    "key_env": "GLM_API_KEY"},
+    "openrouter": {"base_url": "",                                    "model": "deepseek/deepseek-v4-flash", "key_env": "OPENROUTER_API_KEY"},
+}
+DEFAULT_PROVIDER = "deepseek"
+DEFAULT_KEYS_FILE = "~/.caddis/keys.env"
+
+# Env-var naming derives from the shared prefix constant, so a future rename is one edit there.
+try:
+    from claudster_config import ENV_PREFIX
+except Exception:  # pragma: no cover — standalone copy
+    ENV_PREFIX = "CADDIS"
+KEYS_FILE_ENV = f"{ENV_PREFIX}_KEYS_FILE"
+
+
+class ConfigError(Exception):
+    """Configuration can't be resolved — unknown provider without an override, or no key."""
+
+
+def _parse_keys_file(path: str) -> dict[str, str]:
+    """Parse an INI/``KEY=VALUE`` keys file. Comments (#) and blank lines are ignored;
+    surrounding quotes are stripped. A missing file yields ``{}`` (not an error — the
+    key may still come from the environment)."""
+    p = Path(path).expanduser()
+    if not p.is_file():
+        return {}
+    out: dict[str, str] = {}
+    for raw in p.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, val = line.split("=", 1)
+        out[key.strip()] = val.strip().strip('"').strip("'")
+    return out
+
+
+def _resolve_key(provider: str, key_env: str, env: dict[str, str]) -> str:
+    """Provider key via env, then the keys file, else ConfigError. Never logged/echoed."""
+    # 1. explicit env (provider-specific, then generic)
+    for name in (key_env, "OSS_API_KEY"):
+        val = (env.get(name) or "").strip()
+        if val:
+            return val
+    # 2. keys file (CADDIS_KEYS_FILE if set, else ~/.caddis/keys.env)
+    keys_path = env.get(KEYS_FILE_ENV) or DEFAULT_KEYS_FILE
+    file_keys = _parse_keys_file(keys_path)
+    for name in (key_env, "OSS_API_KEY"):
+        val = (file_keys.get(name) or "").strip()
+        if val:
+            return val
+    # 3. actionable error — name the var and the file, never a value.
+    #
+    # It also names the providers that DO have a key. When DeepSeek is unset but GLM is configured,
+    # the fix is `--provider glm`, not "go and find a key" — and the old message sent the reader
+    # hunting for a credential they already had. This fails at the moment of use, which is the
+    # least convenient moment to be told to go looking (`.caddis/parking-lot/003`).
+    others = [p for p in configured_providers(env) if p != provider]
+    have = (f"\nProviders that DO have a key here: {', '.join(others)}. "
+            f"To use one now: --provider {others[0]}." if others else "")
+    raise ConfigError(
+        f"no API key for provider {provider!r}. Set ${key_env} (or $OSS_API_KEY), or add\n"
+        f"  {key_env}=<your-key>\n"
+        f"to your keys file ({keys_path}). Override the file path with ${KEYS_FILE_ENV}."
+        + have
+    )
+
+
+def configured_providers(env: dict[str, str]) -> list[str]:
+    """Every preset provider that currently has a usable key. Never returns or logs a key value.
+
+    Exists so a caller can find out BEFORE it needs one. `/caddis:cross-review` used to discover a
+    missing key mid-task, with a commit pending — and a command that fails once at an inconvenient
+    moment does not get retried, so the safety check it provides is simply lost and nobody records
+    that it was lost.
+    """
+    keys_path = env.get(KEYS_FILE_ENV) or DEFAULT_KEYS_FILE
+    file_keys = _parse_keys_file(keys_path)
+    generic = (env.get("OSS_API_KEY") or file_keys.get("OSS_API_KEY") or "").strip()
+    out = []
+    for name, preset in sorted(PROVIDERS.items()):
+        key_env = preset.get("key_env") or f"{name.upper()}_API_KEY"
+        if generic or (env.get(key_env) or "").strip() or (file_keys.get(key_env) or "").strip():
+            out.append(name)
+    return out
+
+
+def resolve(provider: str | None, env: dict[str, str]) -> dict[str, str]:
+    """Resolve ``{base_url, model, api_key}`` for ``provider`` using ``env``.
+
+    ``provider`` defaults to $OSS_PROVIDER then DEEPSEEK. An unknown provider is allowed
+    only when OSS_BASE_URL + OSS_MODEL are supplied. Raises ConfigError otherwise, or
+    when no API key can be resolved.
+    """
+    provider = (provider or env.get("OSS_PROVIDER") or DEFAULT_PROVIDER).strip().lower()
+    preset = PROVIDERS.get(provider, {})
+    base_url = (env.get("OSS_BASE_URL") or preset.get("base_url") or "").rstrip("/")
+    model = env.get("OSS_MODEL") or preset.get("model") or ""
+    if not base_url or not model:
+        known = ", ".join(sorted(PROVIDERS))
+        raise ConfigError(
+            f"unknown provider {provider!r}: set $OSS_BASE_URL and $OSS_MODEL, "
+            f"or use one of: {known}."
+        )
+    key_env = preset.get("key_env") or f"{provider.upper()}_API_KEY"
+    api_key = _resolve_key(provider, key_env, env)
+    return {"base_url": base_url, "model": model, "api_key": api_key}
+
+
+def main(argv: list[str], env: dict[str, str] | None = None) -> int:
+    """CLI bridge for the launchers: ``oss_model.py <provider>`` prints the resolved
+    base_url, model, and api_key on three lines (in that order) to stdout — the caller
+    (claude-oss.sh / .ps1) CAPTURES this output into variables and sets ANTHROPIC_*; it
+    is never displayed. A ConfigError prints its message to stderr and exits 3.
+    """
+    env = os.environ if env is None else env
+    provider = argv[0] if argv else None
+    try:
+        cfg = resolve(provider, env)
+    except ConfigError as exc:
+        print(str(exc), file=sys.stderr)
+        return 3
+    print(cfg["base_url"])
+    print(cfg["model"])
+    print(cfg["api_key"])
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))