loki-mode 7.30.0 → 7.32.0

package/mcp/__init__.py

@@ -57,4 +57,4 @@ try:
 except ImportError:
     __all__ = ['mcp']
 
-__version__ = '7.30.0'
+__version__ = '7.32.0'

package/mcp/_sdk_loader.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""
+mcp/_sdk_loader.py -- shared pip-MCP-SDK FastMCP loader.
+
+Extracted verbatim from mcp/server.py (task 566) so BOTH the main server
+(mcp/server.py) and the LSP proxy (mcp/lsp_proxy.py) load the genuine pip
+MCP SDK's FastMCP through one battle-tested code path. Importing this module
+has NO side effects (no FastMCP instantiation, no sys.exit, no tool
+registration), so consumers can pull the helpers in without booting a server.
+
+============================================================
+Loading the pip MCP SDK's FastMCP under a NAMESPACE COLLISION
+============================================================
+
+Root cause (task 562, re-applied to the proxy in task 566): this repo ships
+a local package named `mcp/` (this module is mcp/_sdk_loader.py). That local
+package SHADOWS the pip-installed MCP SDK, which is also named `mcp`. The two
+cannot both own the top-level `mcp` name in one interpreter.
+
+The pre-task code tried to sidestep this by loading mcp/server/fastmcp.py
+directly from site-packages via importlib. That worked for the SDK's old
+single-FILE layout, but MCP SDK 1.x ships FastMCP as a PACKAGE DIRECTORY
+(mcp/server/fastmcp/__init__.py) whose own code does absolute imports like
+`from mcp.types import Icon` and `from mcp.server.lowlevel import Server`.
+Under shadowing those resolve to the LOCAL package and raise
+`ModuleNotFoundError: No module named 'mcp.types'`, so FastMCP never loads.
+mcp/server.py used to sys.exit(1) on that; mcp/lsp_proxy.py used to silently
+degrade to a no-op shim, so its LSP tools never loaded for consumers.
+
+So the real fix is NOT file-vs-directory detection: it is resolving the
+namespace collision so the genuine SDK can import its own `mcp.*` subtree.
+We do this by temporarily letting the REAL SDK own the `mcp` name:
+  1. snapshot + evict the local `mcp` / `mcp.*` modules from sys.modules,
+  2. drop the repo root (and "" / ".") from sys.path so the next import of
+     `mcp` resolves to site-packages, not the local package,
+  3. import the real `mcp.server.fastmcp` (and eagerly `mcp.types`), which
+     transitively caches the real `mcp.*` subtree in sys.modules,
+  4. restore the LOCAL `mcp` and `mcp.server` entries so the rest of this
+     codebase keeps using the local package for its own relative imports,
+     while the real SDK submodules (mcp.types, mcp.shared.*,
+     mcp.server.fastmcp.*, mcp.server.lowlevel.*) stay cached for the SDK's
+     runtime use. FastMCP holds direct references to its dependencies once
+     imported, so it does not re-resolve `mcp.server` by name at runtime.
+
+This is the least-invasive fix (it does not rename the local package, which
+mcp/__init__.py documents as intended behavior). It is inherently a bit
+fragile because it juggles sys.modules; the regression test for this code
+path is an END-TO-END one (start the server, complete an MCP stdio
+handshake, list tools), not a file-exists check, because only a real
+handshake proves FastMCP actually loaded and the subtree resolved.
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+import site
+import sys
+
+logger = logging.getLogger('loki-mcp-sdk-loader')
+
+
+def _real_mcp_search_dirs():
+    """Ordered site directories to search for the pip MCP SDK."""
+    dirs = []
+    try:
+        dirs.extend(site.getsitepackages())
+    except AttributeError:
+        pass
+    try:
+        dirs.append(site.getusersitepackages())
+    except AttributeError:
+        pass
+    return dirs
+
+
+def _mcp_sdk_present(search_dirs=None):
+    """True if the pip MCP SDK appears installed in any site dir, accepting
+    both the legacy single-file layout and the 1.x package-directory layout.
+
+    Pure filesystem probe (no import side effects), kept standalone so the
+    both-layouts behaviour can be unit-tested against mktemp fixture dirs.
+    """
+    if search_dirs is None:
+        search_dirs = _real_mcp_search_dirs()
+    for _site_dir in search_dirs:
+        if not _site_dir:
+            continue
+        _file_layout = os.path.join(_site_dir, "mcp", "server", "fastmcp.py")
+        _pkg_layout = os.path.join(
+            _site_dir, "mcp", "server", "fastmcp", "__init__.py"
+        )
+        if os.path.isfile(_file_layout) or os.path.isfile(_pkg_layout):
+            return True
+    return False
+
+
+def _load_real_fastmcp():
+    """Import the genuine pip MCP SDK's FastMCP class, resolving the local-vs-
+    SDK `mcp` namespace collision. Returns the FastMCP class, or None if the
+    SDK cannot be loaded. Restores the local `mcp`/`mcp.server` modules before
+    returning so the rest of this module keeps working unchanged.
+    """
+    if not _mcp_sdk_present():
+        return None
+
+    # 1. Snapshot every currently-loaded local `mcp`/`mcp.*` module so we can
+    #    restore the ones this codebase depends on afterwards.
+    _saved_local = {
+        _k: _v for _k, _v in list(sys.modules.items())
+        if _k == "mcp" or _k.startswith("mcp.")
+    }
+    # 2. Evict them so the real SDK can claim the `mcp` name on import.
+    for _k in list(_saved_local):
+        del sys.modules[_k]
+
+    # 3. Drop repo-root / cwd entries from sys.path for the SDK import so
+    #    `mcp` resolves to site-packages rather than the local package.
+    _repo_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    _saved_path = sys.path[:]
+    sys.path[:] = [
+        _p for _p in sys.path
+        if _p not in ("", ".")
+        and os.path.abspath(_p) != os.path.abspath(_repo_root)
+    ]
+
+    _fastmcp_cls = None
+    try:
+        _real_fastmcp = importlib.import_module("mcp.server.fastmcp")
+        # Eagerly import the subtree FastMCP touches at runtime so the real
+        # modules are cached before we restore the local `mcp` over the name.
+        importlib.import_module("mcp.types")
+        importlib.import_module("mcp.server.lowlevel")
+        _fastmcp_cls = getattr(_real_fastmcp, "FastMCP", None)
+    except Exception as _exc:  # pragma: no cover - defensive
+        logger.error("Failed to import the pip MCP SDK FastMCP: %s", _exc)
+        _fastmcp_cls = None
+    finally:
+        # 4. Restore sys.path and re-pin the LOCAL `mcp` + `mcp.server` modules
+        #    so this codebase's own relative/absolute imports keep resolving
+        #    locally. We intentionally leave the real `mcp.types`,
+        #    `mcp.shared.*`, `mcp.server.fastmcp.*`, and `mcp.server.lowlevel.*`
+        #    cached for the SDK's runtime use; the local package never defined
+        #    those submodules, so there is nothing to clobber.
+        sys.path[:] = _saved_path
+        for _k in ("mcp", "mcp.server"):
+            if _k in _saved_local:
+                sys.modules[_k] = _saved_local[_k]
+        for _k, _v in _saved_local.items():
+            # Restore any other purely-local submodules that the SDK import did
+            # not legitimately replace (e.g. mcp.magic_tools, mcp.tools).
+            _real = sys.modules.get(_k)
+            if _real is None:
+                sys.modules[_k] = _v
+
+    return _fastmcp_cls

package/mcp/lsp_proxy.py

@@ -26,10 +26,14 @@ Supported languages (suffix -> binary):
     .go               -> gopls
     .rs               -> rust-analyzer
 
-Tools:
+Tools (7):
     lsp_find_references(file, line, character, include_declaration=False)
     lsp_go_to_definition(file, line, character)
     lsp_symbol_at_position(file, line, character)
+    lsp_check_exists(symbol, kind=None, ...)
+    lsp_get_diagnostics(file)
+    lsp_workspace_symbols(query, limit=20, ...)
+    lsp_find_definition_by_name(symbol, ...)
 
 Usage:
     python3 -m mcp.lsp_proxy                # stdio mode (default)
@@ -39,14 +43,12 @@ Usage:
 from __future__ import annotations
 
 import atexit
-import importlib.util
 import json
 import logging
 import os
 import queue
 import shutil
 import signal
-import site
 import subprocess
 import sys
 import threading
@@ -660,13 +662,21 @@ def _dispatch_lsp(file: str, line: int, character: int,
 # ============================================================
 # FASTMCP LOADING
 # ============================================================
-# Same trick as mcp/server.py: the local `mcp/` package shadows the pip
-# `mcp` SDK, so we have to load FastMCP from site-packages via
-# importlib.util. Unlike server.py we do NOT sys.exit() when the SDK
-# isn't installed -- we install a no-op shim so the module imports
-# cleanly under test (and so production-without-MCP-SDK fails on
-# `.run()` rather than at import time, matching the silent-skip
-# philosophy).
+# Task 566: the local `mcp/` package shadows the pip `mcp` SDK, which under
+# MCP SDK 1.x (FastMCP shipped as a package DIRECTORY) makes a naive
+# importlib.util load of mcp/server/fastmcp/__init__.py fail with
+# `ModuleNotFoundError: No module named 'mcp.types'`. The previous loader
+# here did exactly that and then SILENTLY degraded to a no-op shim, so the
+# LSP tools never loaded for real consumers even with the SDK installed.
+#
+# The fix: reuse the SAME namespace-collision-resolving loader that
+# mcp/server.py uses (now shared in mcp/_sdk_loader.py). Unlike server.py we
+# do NOT sys.exit() when the SDK is genuinely absent -- we degrade to a no-op
+# shim so the module imports cleanly under test, and production-without-SDK
+# fails on `.run()` rather than at import time (silent-skip philosophy). But
+# the degrade is now LOUD: one warning line naming the cause, never silent.
+from mcp._sdk_loader import _load_real_fastmcp  # noqa: E402
+
 
 class _NoopFastMCP:
     """Fallback used when the pip `mcp` SDK is not installed. Tool
@@ -688,51 +698,21 @@ class _NoopFastMCP:
 
 
 def _load_fastmcp():
-    """Walk site-packages for the pip `mcp` SDK's FastMCP class.
-    Returns the FastMCP class on success, or `_NoopFastMCP` on failure
-    (so import never raises)."""
-    search_paths: List[str] = []
-    try:
-        search_paths.extend(site.getsitepackages())
-    except AttributeError:
-        pass
-    try:
-        search_paths.append(site.getusersitepackages())
-    except AttributeError:
-        pass
-    for site_dir in search_paths:
-        # First shape: fastmcp.py module file.
-        candidate_file = os.path.join(site_dir, 'mcp', 'server', 'fastmcp.py')
-        if os.path.isfile(candidate_file):
-            spec = importlib.util.spec_from_file_location(
-                'mcp_pip_sdk_lsp.server.fastmcp', candidate_file,
-                submodule_search_locations=[],
-            )
-            if spec and spec.loader:
-                mod = importlib.util.module_from_spec(spec)
-                try:
-                    spec.loader.exec_module(mod)
-                    return mod.FastMCP
-                except Exception as exc:  # pragma: no cover - defensive
-                    logger.debug("FastMCP file-import failed: %s", exc)
-        # Second shape: fastmcp/__init__.py package directory.
-        candidate_pkg = os.path.join(site_dir, 'mcp', 'server', 'fastmcp', '__init__.py')
-        if os.path.isfile(candidate_pkg):
-            spec = importlib.util.spec_from_file_location(
-                'mcp_pip_sdk_lsp.server.fastmcp', candidate_pkg,
-                submodule_search_locations=[
-                    os.path.join(site_dir, 'mcp', 'server', 'fastmcp'),
-                ],
-            )
-            if spec and spec.loader:
-                mod = importlib.util.module_from_spec(spec)
-                try:
-                    spec.loader.exec_module(mod)
-                    if hasattr(mod, 'FastMCP'):
-                        return mod.FastMCP
-                except Exception as exc:  # pragma: no cover - defensive
-                    logger.debug("FastMCP pkg-import failed: %s", exc)
-    logger.warning("MCP SDK not found; LSP proxy MCP server will not be runnable.")
+    """Load the genuine pip MCP SDK's FastMCP via the shared loader, which
+    resolves the local-vs-SDK `mcp` namespace collision under both SDK
+    layouts. Returns the real FastMCP class on success, or `_NoopFastMCP`
+    on a genuinely-absent SDK (so import never raises). The degrade path is
+    LOUD: it logs one warning naming the cause rather than failing silently
+    the way the old importlib.util shim did."""
+    cls = _load_real_fastmcp()
+    if cls is not None:
+        return cls
+    logger.warning(
+        "MCP SDK (pip package 'mcp') not found or not importable; LSP proxy "
+        "MCP server will not be runnable. Tools are registered against a "
+        "no-op shim and mcp.run() will raise. Install with: "
+        "pip install -r mcp/requirements.txt (or: pip install mcp)."
+    )
     return _NoopFastMCP
 
 
@@ -748,12 +728,32 @@ except Exception:
     _version = 'unknown'
 
 
-mcp = FastMCP(
-    'loki-mode-lsp-proxy',
-    version=_version,
-    description='Loki Mode LSP proxy: find references, go to definition, '
-                'symbol-at-position via on-PATH language servers.',
-)
+def _build_lsp_fastmcp():
+    """Instantiate FastMCP forwarding only the optional kwargs the installed
+    SDK actually accepts. Mirrors mcp/server.py's _build_fastmcp: MCP SDK 1.x
+    FastMCP.__init__ has no `version=`/`description=` parameters (it uses
+    `instructions=`), so passing them unconditionally raises TypeError and
+    the proxy never starts. We introspect the signature and forward only
+    supported kwargs, keeping forward/backward compatibility. The no-op shim
+    accepts any kwargs, so this is safe on the degrade path too."""
+    import inspect
+    _kwargs = {}
+    try:
+        _params = inspect.signature(FastMCP.__init__).parameters
+    except (TypeError, ValueError):  # pragma: no cover - defensive
+        _params = {}
+    _desc = ('Loki Mode LSP proxy: find references, go to definition, '
+             'symbol-at-position via on-PATH language servers.')
+    if "instructions" in _params:
+        _kwargs["instructions"] = _desc
+    elif "description" in _params:
+        _kwargs["description"] = _desc
+    if "version" in _params:
+        _kwargs["version"] = _version
+    return FastMCP('loki-mode-lsp-proxy', **_kwargs)
+
+
+mcp = _build_lsp_fastmcp()
 
 
 # ============================================================

package/mcp/server.py

@@ -476,135 +476,20 @@ def _emit_context_relevance_signal(
 # pip-installed MCP SDK, which is also named `mcp`. The two cannot both
 # own the top-level `mcp` name in one interpreter.
 #
-# The pre-task code tried to sidestep this by loading mcp/server/fastmcp.py
-# directly from site-packages via importlib. That worked for the SDK's old
-# single-FILE layout, but MCP SDK 1.x ships FastMCP as a PACKAGE DIRECTORY
-# (mcp/server/fastmcp/__init__.py) whose own code does absolute imports like
-# `from mcp.types import Icon` and `from mcp.server.lowlevel import Server`.
-# Under shadowing those resolve to the LOCAL package and raise
-# `ModuleNotFoundError: No module named 'mcp.types'`, so FastMCP never loads
-# and the server exits. (lsp_proxy.py has the same latent failure but
-# silently degrades to a no-op shim.)
-#
-# So the real fix is NOT file-vs-directory detection: it is resolving the
-# namespace collision so the genuine SDK can import its own `mcp.*` subtree.
-# We do this by temporarily letting the REAL SDK own the `mcp` name:
-#   1. snapshot + evict the local `mcp` / `mcp.*` modules from sys.modules,
-#   2. drop the repo root (and "" / ".") from sys.path so the next import of
-#      `mcp` resolves to site-packages, not the local package,
-#   3. import the real `mcp.server.fastmcp` (and eagerly `mcp.types`), which
-#      transitively caches the real `mcp.*` subtree in sys.modules,
-#   4. restore the LOCAL `mcp` and `mcp.server` entries so the rest of this
-#      codebase keeps using the local package for its own relative imports,
-#      while the real SDK submodules (mcp.types, mcp.shared.*,
-#      mcp.server.fastmcp.*, mcp.server.lowlevel.*) stay cached for the SDK's
-#      runtime use. FastMCP holds direct references to its dependencies once
-#      imported, so it does not re-resolve `mcp.server` by name at runtime.
-#
-# This is the least-invasive fix (it does not rename the local package, which
-# mcp/__init__.py documents as intended behavior). It is inherently a bit
-# fragile because it juggles sys.modules; the regression test for this code
-# path is an END-TO-END one (start the server, complete an MCP stdio
-# handshake, list tools), not a file-exists check, because only a real
-# handshake proves FastMCP actually loaded and the subtree resolved.
-import importlib
-import site
-
-
-def _real_mcp_search_dirs():
-    """Ordered site directories to search for the pip MCP SDK."""
-    dirs = []
-    try:
-        dirs.extend(site.getsitepackages())
-    except AttributeError:
-        pass
-    try:
-        dirs.append(site.getusersitepackages())
-    except AttributeError:
-        pass
-    return dirs
-
-
-def _mcp_sdk_present(search_dirs=None):
-    """True if the pip MCP SDK appears installed in any site dir, accepting
-    both the legacy single-file layout and the 1.x package-directory layout.
-
-    Pure filesystem probe (no import side effects), kept standalone so the
-    both-layouts behaviour can be unit-tested against mktemp fixture dirs.
-    """
-    if search_dirs is None:
-        search_dirs = _real_mcp_search_dirs()
-    for _site_dir in search_dirs:
-        if not _site_dir:
-            continue
-        _file_layout = os.path.join(_site_dir, "mcp", "server", "fastmcp.py")
-        _pkg_layout = os.path.join(
-            _site_dir, "mcp", "server", "fastmcp", "__init__.py"
-        )
-        if os.path.isfile(_file_layout) or os.path.isfile(_pkg_layout):
-            return True
-    return False
-
-
-def _load_real_fastmcp():
-    """Import the genuine pip MCP SDK's FastMCP class, resolving the local-vs-
-    SDK `mcp` namespace collision. Returns the FastMCP class, or None if the
-    SDK cannot be loaded. Restores the local `mcp`/`mcp.server` modules before
-    returning so the rest of this module keeps working unchanged.
-    """
-    if not _mcp_sdk_present():
-        return None
-
-    # 1. Snapshot every currently-loaded local `mcp`/`mcp.*` module so we can
-    #    restore the ones this codebase depends on afterwards.
-    _saved_local = {
-        _k: _v for _k, _v in list(sys.modules.items())
-        if _k == "mcp" or _k.startswith("mcp.")
-    }
-    # 2. Evict them so the real SDK can claim the `mcp` name on import.
-    for _k in list(_saved_local):
-        del sys.modules[_k]
-
-    # 3. Drop repo-root / cwd entries from sys.path for the SDK import so
-    #    `mcp` resolves to site-packages rather than the local package.
-    _repo_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-    _saved_path = sys.path[:]
-    sys.path[:] = [
-        _p for _p in sys.path
-        if _p not in ("", ".")
-        and os.path.abspath(_p) != os.path.abspath(_repo_root)
-    ]
-
-    _fastmcp_cls = None
-    try:
-        _real_fastmcp = importlib.import_module("mcp.server.fastmcp")
-        # Eagerly import the subtree FastMCP touches at runtime so the real
-        # modules are cached before we restore the local `mcp` over the name.
-        importlib.import_module("mcp.types")
-        importlib.import_module("mcp.server.lowlevel")
-        _fastmcp_cls = getattr(_real_fastmcp, "FastMCP", None)
-    except Exception as _exc:  # pragma: no cover - defensive
-        logger.error("Failed to import the pip MCP SDK FastMCP: %s", _exc)
-        _fastmcp_cls = None
-    finally:
-        # 4. Restore sys.path and re-pin the LOCAL `mcp` + `mcp.server` modules
-        #    so this codebase's own relative/absolute imports keep resolving
-        #    locally. We intentionally leave the real `mcp.types`,
-        #    `mcp.shared.*`, `mcp.server.fastmcp.*`, and `mcp.server.lowlevel.*`
-        #    cached for the SDK's runtime use; the local package never defined
-        #    those submodules, so there is nothing to clobber.
-        sys.path[:] = _saved_path
-        for _k in ("mcp", "mcp.server"):
-            if _k in _saved_local:
-                sys.modules[_k] = _saved_local[_k]
-        for _k, _v in _saved_local.items():
-            # Restore any other purely-local submodules that the SDK import did
-            # not legitimately replace (e.g. mcp.magic_tools, mcp.tools).
-            _real = sys.modules.get(_k)
-            if _real is None:
-                sys.modules[_k] = _v
-
-    return _fastmcp_cls
+# The FastMCP loader that resolves this collision used to live inline here.
+# Task 566 extracted it VERBATIM into mcp/_sdk_loader.py so the LSP proxy
+# (mcp/lsp_proxy.py) can load FastMCP through the SAME battle-tested path
+# instead of its old importlib.util shim, which silently degraded to a
+# no-op under the MCP SDK 1.x package-directory layout. The shared module
+# carries the full root-cause writeup; behavior here is unchanged (the
+# three helpers are re-exported below under their original names so any
+# existing `mcp.server._mcp_sdk_present` / `_load_real_fastmcp` reference
+# keeps resolving).
+from mcp._sdk_loader import (  # noqa: E402
+    _real_mcp_search_dirs,
+    _mcp_sdk_present,
+    _load_real_fastmcp,
+)
 
 
 FastMCP = _load_real_fastmcp()
@@ -652,6 +537,27 @@ def _build_fastmcp():
 
 mcp = _build_fastmcp()
 
+# Propagate the loki-mode VERSION into serverInfo.version.
+#
+# FastMCP 1.x exposes no `version=` kwarg (see _build_fastmcp above), so the
+# kwarg branch there never fires on the installed SDK. FastMCP DOES forward to
+# an underlying lowlevel `Server` (mcp._mcp_server), whose `version` attribute
+# is what `create_initialization_options()` reads into serverInfo at the
+# initialize handshake -- falling back to importlib.metadata.version("mcp")
+# (the SDK's OWN pip version, e.g. 1.27.x) when it is None. That fallback is
+# why the listing surfaced the SDK version instead of ours. Setting this
+# attribute is the only mechanism the installed SDK exposes to override
+# serverInfo.version; `version=` is a documented public parameter on the
+# lowlevel Server.__init__, so this is the supported field, not an internal
+# hack. Guarded so a future SDK that already set a version (e.g. via the
+# _build_fastmcp kwarg branch) is left untouched.
+try:
+    _inner = getattr(mcp, "_mcp_server", None)
+    if _inner is not None and getattr(_inner, "version", None) in (None, ""):
+        _inner.version = _version
+except Exception:  # pragma: no cover - defensive: never block server startup
+    pass
+
 # ============================================================
 # TOOLS - Functions Claude can call
 # ============================================================

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "7.30.0",
+  "version": "7.32.0",
   "description": "Loki Mode by Autonomi. Autonomous spec-to-product system: takes a PRD, GitHub issue, OpenAPI/JSON/YAML, or one-line brief to a deployed app via the RARV-C closure loop with 11 quality gates. Provider-agnostic (Claude Code, OpenAI Codex, Cline, Aider).",
   "keywords": [
     "agent",

package/providers/claude.sh

@@ -287,6 +287,65 @@ provider_get_tier_param() {
     fi
 }
 
+# Canonical model-override / session-model normalization (single source of
+# truth shared by run.sh, the dashboard, and the estimator). Trim leading and
+# trailing whitespace, lowercase, and accept ONLY an exact allowlisted alias.
+# Interior whitespace (e.g. "fab le") is therefore rejected rather than silently
+# collapsed into "fable". bash 3.2 safe (no ${var,,}); uses tr for lowercasing.
+# Echoes the canonical alias on success, or the empty string when the input is
+# not an exact allowlisted alias.
+loki_normalize_model_alias() {
+    local raw="$1"
+    # Trim leading/trailing whitespace (interior whitespace preserved so a
+    # value like "fab le" stays "fab le" and fails the exact-match below).
+    raw="${raw#"${raw%%[![:space:]]*}"}"
+    raw="${raw%"${raw##*[![:space:]]}"}"
+    raw="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')"
+    case "$raw" in
+        haiku|sonnet|opus|fable) printf '%s' "$raw" ;;
+        *) printf '%s' "" ;;
+    esac
+}
+
+# Shared cost-ceiling clamp (single source of truth for LOKI_MAX_TIER). Given a
+# resolved model name and a tier hint, return the model clamped down to the
+# operator's LOKI_MAX_TIER ceiling. Used by resolve_model_for_tier AND by the
+# mid-flight model-override path in run.sh so a dashboard/CLI override cannot
+# silently bypass the ceiling. Clamps are byte-identical by construction:
+# sonnet-cap resolves planning/fable down to PROVIDER_MODEL_DEVELOPMENT (opus by
+# default), opus-cap resolves fable down to opus, haiku-cap pins everything to
+# PROVIDER_MODEL_FAST. No ceiling set -> model unchanged.
+loki_apply_max_tier_clamp() {
+    local model="$1"
+    local tier="${2:-}"
+    local max_tier="${LOKI_MAX_TIER:-}"
+    # Normalize EXACTLY like the python ports (dashboard _clamp_to_max_tier,
+    # estimator _max_tier): trim + lowercase. Without this, a user-typed cap
+    # like "Sonnet" (settings.json maxTier exports verbatim) was silently
+    # ignored here while quote and dashboard claimed the ceiling enforced:
+    # the run would exceed the quote. Council R1 finding, v7.31.0.
+    max_tier="$(printf '%s' "$max_tier" | tr '[:upper:]' '[:lower:]' | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')"
+    [ -z "$max_tier" ] && { printf '%s' "$model"; return; }
+    case "$max_tier" in
+        haiku)
+            model="$PROVIDER_MODEL_FAST"
+            ;;
+        sonnet)
+            # Cap planning/fable down to development.
+            if [ "$tier" = "planning" ] || [ "$tier" = "fable" ] || [ "$model" = "fable" ]; then
+                model="$PROVIDER_MODEL_DEVELOPMENT"
+            fi
+            ;;
+        opus)
+            # Opus is the ceiling: cap fable back to opus.
+            if [ "$model" = "fable" ]; then
+                model="opus"
+            fi
+            ;;
+    esac
+    printf '%s' "$model"
+}
+
 # Dynamic model resolution (v6.0.0)
 # Resolves a capability tier to a concrete model name at runtime.
 # Respects LOKI_MAX_TIER to cap cost (e.g., maxTier=sonnet prevents opus usage).
@@ -301,35 +360,33 @@ resolve_model_for_tier() {
         cheap)   tier="fast" ;;
     esac
 
-    local max_tier="${LOKI_MAX_TIER:-}"
     local model=""
 
     # Resolve tier to model
+    #   fable) explicit top-tier advisory model (Fable 5, 2x Opus). Reached when
+    #          the session is pinned to fable (LOKI_SESSION_MODEL=fable), the
+    #          mid-flight override file selects fable, or the architect opt-in
+    #          (LOKI_FABLE_ARCHITECT=1) pins the first iteration's tier to fable
+    #          in run.sh. So the resolver honors the documented lever instead of
+    #          falling through the `*` arm to opus (the model-honesty fix).
     case "$tier" in
         planning)    model="$PROVIDER_MODEL_PLANNING" ;;
         development) model="$PROVIDER_MODEL_DEVELOPMENT" ;;
         fast)        model="$PROVIDER_MODEL_FAST" ;;
+        fable)       model="fable" ;;
         *)           model="$PROVIDER_MODEL_DEVELOPMENT" ;;
     esac
 
-    # Apply maxTier ceiling if set
-    if [ -n "$max_tier" ]; then
-        case "$max_tier" in
-            haiku)
-                # Cap everything to haiku/fast
-                model="$PROVIDER_MODEL_FAST"
-                ;;
-            sonnet)
-                # Cap planning to development
-                if [ "$tier" = "planning" ]; then
-                    model="$PROVIDER_MODEL_DEVELOPMENT"
-                fi
-                ;;
-            opus)
-                # No cap needed, opus is max
-                ;;
-        esac
-    fi
+    # Architect opt-in (LOKI_FABLE_ARCHITECT) is NOT applied here. It is applied
+    # in run.sh, scoped to the FIRST iteration only (the architecture pass), so
+    # a session pinned to opus does not silently route every iteration to fable.
+    # run.sh sets CURRENT_TIER=fable for that one iteration, which lands on the
+    # `fable)` arm above. Keeping the decision in run.sh is the only place that
+    # has ITERATION_COUNT, so the scoping is honest.
+
+    # Apply the shared LOKI_MAX_TIER ceiling (same clamp the run.sh override path
+    # uses, so the cost ceiling is enforced byte-identically on both paths).
+    model="$(loki_apply_max_tier_clamp "$model" "$tier")"
 
     # Phase I (v7.5.25): when ANTHROPIC_BASE_URL is set, the user is routing
     # Claude Code to an alt-provider (OpenRouter, Ollama, LiteLLM, self-hosted).

package/providers/model_catalog.json

@@ -8,11 +8,20 @@
       "latest_development": "claude-opus-4-7",
       "latest_fast": "claude-sonnet-4-6",
       "cli_aliases": {
+        "fable": "claude-fable-5",
         "opus": "claude-opus-4-7",
         "sonnet": "claude-sonnet-4-6",
         "haiku": "claude-haiku-4-5"
       },
       "models": [
+        {
+          "id": "claude-fable-5",
+          "alias": "fable",
+          "tier": "advisor",
+          "context_window": 1000000,
+          "max_output": 128000,
+          "notes": "Top-tier advisory model. Pricing 2x Opus ($10/$50 per MTok). Doc-supported for architecture/root-cause; opt-in only (cost). Refuses cyber content, so NOT used for security review."
+        },
         {
           "id": "claude-opus-4-7",
           "alias": "opus",