refs-mcp 0.2.0__py3-none-any.whl

refs_mcp/__init__.py

@@ -0,0 +1,16 @@
+"""FastMCP server for managing the refs/ reference-repo tree."""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+# Resolve at import time from the installed distribution so the value
+# tracks pyproject.toml automatically instead of going stale on every
+# version bump. The hardcoded "0.1.0" string that previously lived here
+# stayed at 0.1.0 from PR #2 through 0.1.2's release, contradicting
+# every other version source. The PyInstaller bundle's refs.spec ships
+# the ``refs-mcp`` dist-info via ``copy_metadata("refs-mcp")`` so this
+# resolves in frozen mode too. The dist name is ``refs-mcp`` (PyPI);
+# the console-script entry stays ``refs`` (project.scripts).
+try:
+    __version__ = _pkg_version("refs-mcp")
+except PackageNotFoundError:  # pragma: no cover - dev tree without install
+    __version__ = "unknown"

refs_mcp/__main__.py

@@ -0,0 +1,23 @@
+"""Entry-point shim for ``python -m refs_mcp`` and PyInstaller.
+
+PyInstaller's ``Analysis`` takes a script path, not a console-script
+target, so we route ``__main__`` through ``cli.main`` here. The
+``[project.scripts]`` ``refs`` entry in pyproject.toml points at
+``refs_mcp.cli:main`` for the pip-installed wheel path.
+
+Absolute import (``from refs_mcp.cli import main``) rather than the
+package-relative form because PyInstaller bundles ``__main__.py`` as a
+standalone script with no package context; relative imports raise
+``ImportError`` at frozen runtime. The wheel install path still
+resolves the same module via the absolute name.
+"""
+
+from __future__ import annotations
+
+from refs_mcp.cli import main
+
+if __name__ == "__main__":
+    # ``main`` is a click.Command; calling it parses ``sys.argv`` and exits
+    # via ``SystemExit`` from inside click. No explicit return code wiring
+    # needed here.
+    main()

refs_mcp/_arch.py

@@ -0,0 +1,92 @@
+"""Assert a PyInstaller binary's machine code matches the labeled npm target.
+
+Called from CI's build job right after PyInstaller writes ``dist/``, before
+the artifact is uploaded. Catches "arm64-labeled x86_64" and similar
+mis-labeled-artifact failure modes that a GitHub runner-alias shift
+(e.g. ``macos-latest`` flipping between Intel and Apple Silicon) would
+otherwise let through.
+
+Pure stdlib + magic-byte parsing — no ``file`` dependency, no third-party
+binary inspection lib. Anchored to:
+
+* ELF ``e_machine`` constants — ``/usr/include/elf.h`` (``EM_X86_64 = 0x3E``)
+* PE/COFF machine constants —
+  https://learn.microsoft.com/en-us/windows/win32/debug/pe-format
+  (``IMAGE_FILE_MACHINE_AMD64 = 0x8664``)
+* Mach-O cputype — ``/usr/include/mach/machine.h``
+  (``CPU_TYPE_ARM64 = CPU_TYPE_ARM | CPU_ARCH_ABI64 = 0x0100000C``,
+   little-endian 64-bit magic ``0xCFFAEDFE``)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+import struct
+import sys
+
+
+def _fail(msg: str) -> None:
+    print(f"::error::{msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def _check_linux_x64(head: bytes) -> None:
+    if head[:4] != b"\x7fELF":
+        _fail("not an ELF binary")
+    # e_machine: 2-byte LE at offset 18.
+    machine = struct.unpack_from("<H", head, 18)[0]
+    if machine != 0x3E:
+        _fail(f"ELF e_machine={machine:#06x}, expected 0x003e (EM_X86_64)")
+
+
+def _check_win32_x64(head: bytes) -> None:
+    if head[:2] != b"MZ":
+        _fail("not a PE/MZ binary")
+    # PE header offset lives at 0x3C as a 4-byte LE.
+    pe_offset = struct.unpack_from("<I", head, 0x3C)[0]
+    if head[pe_offset : pe_offset + 4] != b"PE\0\0":
+        _fail(f"PE signature missing at offset {pe_offset:#x}")
+    # IMAGE_FILE_HEADER.Machine is the first 2-byte LE after "PE\0\0".
+    machine = struct.unpack_from("<H", head, pe_offset + 4)[0]
+    if machine != 0x8664:
+        _fail(f"PE Machine={machine:#06x}, expected 0x8664 (AMD64)")
+
+
+def _check_darwin_arm64(head: bytes) -> None:
+    # 64-bit Mach-O little-endian magic.
+    if head[:4] != b"\xcf\xfa\xed\xfe":
+        _fail(f"unexpected Mach-O magic {head[:4]!r}; expected MH_MAGIC_64 LE")
+    # cputype: 4-byte LE at offset 4.
+    cpu_type = struct.unpack_from("<I", head, 4)[0]
+    if cpu_type != 0x0100000C:
+        _fail(f"Mach-O cputype={cpu_type:#010x}, expected 0x0100000c (arm64)")
+
+
+_CHECKS = {
+    "linux-x64": _check_linux_x64,
+    "win32-x64": _check_win32_x64,
+    "darwin-arm64": _check_darwin_arm64,
+}
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 3:
+        print("usage: assert_binary_arch.py <binary> <npm-target>", file=sys.stderr)
+        return 2
+
+    binary = Path(argv[1])
+    target = argv[2]
+
+    check = _CHECKS.get(target)
+    if check is None:
+        _fail(f"unknown target {target!r}; expected one of {sorted(_CHECKS)}")
+        return 1  # _fail exits; keeps pyright happy on the path below
+
+    head = binary.read_bytes()[:4096]
+    check(head)
+    print(f"{binary}: {target} OK ({len(head)} byte header inspected)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

refs_mcp/_build.py

@@ -0,0 +1,135 @@
+"""Build refs.exe via PyInstaller with warnings-as-errors.
+
+PyInstaller has NO ``--werror`` / ``--strict`` CLI flag. Verified via
+full reads of:
+
+* ``../refs/pyinstaller/pyinstaller/PyInstaller/log.py``
+  — only ``--log-level`` / ``PYI_LOG_LEVEL``; the level only silences,
+  it does not escalate.
+* ``../refs/pyinstaller/pyinstaller/PyInstaller/__main__.py``
+  — assembles the parser from three ``__add_options`` callables and
+  exposes a programmatic entrypoint ``PyInstaller.__main__.run()``.
+* ``../refs/pyinstaller/pyinstaller/PyInstaller/building/makespec.py:__add_options``
+  — every spec-generation flag; none related to warnings-as-errors.
+* ``../refs/pyinstaller/pyinstaller/PyInstaller/building/build_main.py:__add_options``
+  — only ``--distpath``, ``--workpath``, ``--noconfirm``, ``--upx-dir``,
+  ``--clean``. ``_write_warnings`` (line 1064) just writes the
+  ``warn-*.txt`` report; it does not exit.
+
+UV also has no equivalent flag (``uv sync --help`` / ``uv lock --help``
+yield no warning-escalation options).
+
+What PyInstaller DOES expose: standard Python ``logging``. At
+``log.py:42`` it does ``logger = getLogger('PyInstaller')``. Every
+``logger.warning(...)`` call inside PyInstaller — including the
+``"Hidden import X not found!"`` site at
+``../refs/pyinstaller/pyinstaller/PyInstaller/depend/imphook.py:551``
+— routes through that logger. So the legitimate config option is to
+install a ``logging.Handler`` on the ``PyInstaller`` logger that
+raises on records at WARNING level or above.
+
+This script does exactly that. No regex on stdout; the handler sees
+the actual ``LogRecord`` at emit time and converts it into a real
+exception, surfacing the level, module, and message via the logging
+API the upstream itself defines.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from pathlib import Path
+import sys
+
+
+class WarningsAsErrorsHandler(logging.Handler):
+    """Abort on every PyInstaller log record at WARNING or above.
+
+    Reads in full that anchor this design:
+
+    * ``../refs/pyinstaller/pyinstaller/PyInstaller/log.py`` — uses
+      ``logging.getLogger('PyInstaller')`` as the package's root
+      logger.
+    * ``../refs/pyinstaller/pyinstaller/PyInstaller/depend/imphook.py``
+      — line 27 binds ``logger = logging.getLogger(__name__)``
+      (resolves to ``PyInstaller.depend.imphook``, which inherits from
+      ``PyInstaller``). Line 551 emits ``logger.warning('Hidden import
+      "%s" not found!', ...)`` — the exact warning we have to escalate.
+
+    Why ``sys.exit`` instead of raising a regular exception:
+    ``logging.Handler.handle`` wraps ``emit`` in ``except Exception:``
+    and routes failures to ``Handler.handleError`` which (by default)
+    prints to stderr and KEEPS GOING. ``SystemExit`` inherits from
+    ``BaseException``, not ``Exception``, so it is NOT caught by that
+    ``except``; it propagates out of the logging framework and back to
+    the build wrapper. This is the only stdlib-clean way to abort.
+
+    DEPRECATION is PyInstaller's custom level above WARN (see
+    ``log.py:23``); levelno >= WARNING covers it.
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if record.levelno < logging.WARNING:
+            return
+        msg = record.getMessage()
+        sys.exit(
+            f"FAIL: PyInstaller warning treated as error\n"
+            f"  level   : {record.levelname}\n"
+            f"  logger  : {record.name}\n"
+            f"  message : {msg}\n\n"
+            'Fix the underlying cause; never ignore. For \'Hidden import "X" not\n'
+            "found!' install X as a runtime dep or add a hook; for deprecated\n"
+            "spec args, update the spec to the supported form."
+        )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--spec",
+        type=Path,
+        default=Path("refs.spec"),
+        help="Path to the PyInstaller .spec file.",
+    )
+    args = parser.parse_args(argv)
+
+    if not args.spec.is_file():
+        sys.stderr.write(f"FAIL: spec file not found: {args.spec}\n")
+        return 1
+
+    # Install the handler BEFORE importing PyInstaller's runtime
+    # machinery so any warning emitted during option parsing or
+    # analysis is caught at the source.
+    pyi_logger = logging.getLogger("PyInstaller")
+    handler = WarningsAsErrorsHandler()
+    handler.setLevel(logging.WARNING)
+    pyi_logger.addHandler(handler)
+
+    # PyInstaller imported AFTER the handler is in place. The
+    # programmatic entrypoint is at ``PyInstaller/__main__.py:160``
+    # (``def run(pyi_args=None, pyi_config=None)``).
+    import PyInstaller.__main__ as pyi_main
+
+    pyi_args = [str(args.spec), "--noconfirm", "--clean", "--log-level=INFO"]
+
+    print(f"[build_binary] PyInstaller.run({pyi_args!r})", flush=True)
+    try:
+        pyi_main.run(pyi_args=pyi_args)
+    except SystemExit as exc:
+        # Two sources of ``SystemExit`` here, both wanted:
+        #   1. ``WarningsAsErrorsHandler.emit`` calls ``sys.exit(msg)`` when
+        #      PyInstaller emits a WARNING/DEPRECATION/ERROR log record.
+        #      ``exc.code`` is the FAIL message string.
+        #   2. PyInstaller itself raises ``SystemExit`` on internal errors.
+        # Either way we surface the code (or 1 for string codes) to CI.
+        if isinstance(exc.code, str):
+            sys.stderr.write(exc.code + "\n")
+            return 1
+        return int(exc.code or 0)
+
+    print("[build_binary] OK: build clean (no warnings).", flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

refs_mcp/_exec_safety.py

@@ -0,0 +1,88 @@
+"""Subprocess argv[0] hardening — single source of truth.
+
+Microsoft's canonical guidance for ``CreateProcess`` (which Python's
+``subprocess`` invokes on Windows when ``shell=False``) explicitly says
+"specify a fully qualified path":
+
+  * Dynamic-Link Library Security:
+    https://learn.microsoft.com/windows/win32/dlls/dynamic-link-library-security
+    "Wherever possible, specify a fully qualified path when using the
+    LoadLibrary, LoadLibraryEx, CreateProcess, or ShellExecute functions."
+  * Security Considerations: Microsoft Windows Shell:
+    https://learn.microsoft.com/windows/win32/shell/sec-shell
+    "Provide the fully qualified path. Do not depend on the Shell to
+    locate the file."
+  * Warning C6277: NULL application name with an unquoted path is a
+    security vulnerability because CreateProcess will search the parent
+    process's CWD (step 2 of its documented search order) before PATH —
+    a malicious binary in the CWD would win.
+
+``shutil.which`` honors PATHEXT on Windows so a bare ``"rg"`` resolves
+to ``rg.exe``. When ``shutil.which`` returns a path that still has a
+directory component (e.g. ``"./rg"`` for an explicit relative override),
+this module promotes via ``os.path.abspath``. ``os.path.isabs`` is the
+canonical absolute-path check — it correctly handles UNC paths, rooted
+Windows paths, and rejects drive-relative ``"C:tool.exe"`` forms that a
+string-startswith heuristic would mis-classify.
+
+This module exists separately from ``refs_mcp.runner`` so the helpers
+can be imported by any subprocess site (git_runner, gh_runner, operations,
+remote_discover, run_metadata, init scripts) without pulling in the
+OpenTelemetry import graph that ``runner`` carries.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+import os
+import shutil
+
+
+def resolved_executable(name: str) -> str:
+    """Promote ``name`` to an absolute executable path. Bare name on miss.
+
+    Microsoft SDL guidance is unambiguous: always use a fully qualified
+    path when invoking ``CreateProcess`` / ``ShellExecute`` /
+    ``LoadLibrary``. The cited references are in this module's
+    docstring; CWE-426 (Untrusted Search Path) applies to ANY relative
+    argv[0], not only bare names. A caller-supplied ``"./tool"`` would
+    let ``subprocess.run`` honor the passed ``cwd=`` on POSIX —
+    documented behavior, but the SDL prefers absolute resolution
+    regardless because the relative form is ambiguous under cwd
+    races and binary planting.
+
+    Returns the input unchanged when:
+      * ``name`` is already absolute (per ``os.path.isabs``), OR
+      * ``shutil.which(name)`` returns ``None`` (the binary is not
+        locatable — let the eventual ``subprocess.run`` raise
+        ``FileNotFoundError`` so callers can map it to their own typed
+        error contract).
+
+    Otherwise returns ``shutil.which(name)`` promoted to absolute via
+    ``os.path.abspath`` (covers the relative-result case where
+    ``shutil.which`` preserves the directory component instead of
+    prepending the cwd — typically when ``name`` itself had a
+    directory component like ``"./rg"``).
+    """
+    if os.path.isabs(name):
+        return name
+    resolved = shutil.which(name)
+    if resolved is None:
+        return name
+    return resolved if os.path.isabs(resolved) else os.path.abspath(resolved)
+
+
+def hardened_argv(argv: Sequence[str]) -> list[str]:
+    """Return a new argv list with argv[0] resolved to an absolute path.
+
+    Every other element is passed through unchanged. Empty argv is
+    returned as ``[]`` (callers should validate; this helper makes no
+    assumption about minimum length).
+    """
+    out = list(argv)
+    if out:
+        out[0] = resolved_executable(out[0])
+    return out
+
+
+__all__ = ("hardened_argv", "resolved_executable")

refs_mcp/_link.py

@@ -0,0 +1,195 @@
+"""Cross-platform unprivileged directory aliasing.
+
+POSIX  → ``os.symlink(target, link, target_is_directory=True)``
+         Unprivileged on every supported POSIX.
+Windows → ``mklink /J`` (junction; an NTFS reparse point with the
+         ``IO_REPARSE_TAG_MOUNT_POINT`` tag). Junctions DO NOT
+         require ``SeCreateSymbolicLinkPrivilege`` — distinct from
+         symbolic links (Microsoft Learn: ``Hard links and
+         junctions``). They are the canonical Windows-native
+         unprivileged way to alias a directory across drives on the
+         same machine. Limitations: local volumes only (no UNC),
+         directory-only (no file junctions), reported by Python as
+         ``Path.is_symlink() == False`` because their reparse tag is
+         ``IO_REPARSE_TAG_MOUNT_POINT`` not ``IO_REPARSE_TAG_SYMLINK``.
+
+``link_directory`` raises by default when neither symlink nor
+junction is available, so callers don't silently absorb a multi-GB
+``copytree`` they didn't ask for. Pass ``copy_fallback=True`` to
+opt in to the copy semantics (used by ``safe_directory_move`` where
+copy-on-cross-FS is the existing ``shutil.move`` contract).
+
+``safe_directory_move`` patches the one ``shutil.move`` correctness
+hole that bites Windows unprivileged callers: when ``src`` is a
+symlink and the move crosses a filesystem boundary, ``shutil`` falls
+back to ``copytree`` + ``rmtree`` and recreates the link via
+``os.symlink``, which requires ``SeCreateSymbolicLinkPrivilege``.
+Routing the recreation through ``link_directory`` (junction-capable)
+keeps the move unprivileged.
+
+AGENTS.md Rule #1 (subprocess argv[0] hardened via ``hardened_argv``),
+Rule #11 (production runs unprivileged).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+from typing import Literal
+
+from ._exec_safety import hardened_argv
+
+LinkMechanism = Literal["symlink", "junction", "copy", "move"]
+
+
+@dataclass(frozen=True)
+class LinkResult:
+    """Outcome of a directory-link or directory-move operation.
+
+    ``mechanism`` reports which OS primitive actually took effect:
+
+    * ``"symlink"``  POSIX ``os.symlink`` or Windows symlink (rare)
+    * ``"junction"`` Windows NTFS junction via ``mklink /J``
+    * ``"copy"``     ``shutil.copytree`` — link is a full tree copy,
+                     NOT a reference. Downstream rm / mutation
+                     semantics differ.
+    * ``"move"``     non-link directory moved by ``shutil.move``
+                     (used by ``safe_directory_move``)
+
+    Audit trails carry this so operators can tell whether downstream
+    behavior will affect just the link or the whole tree.
+    """
+
+    mechanism: LinkMechanism
+    link: Path
+    target: Path
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def link_directory(target: Path, link: Path, *, copy_fallback: bool = False) -> LinkResult:
+    """Create ``link`` as an alias for the directory ``target``.
+
+    Cross-platform without requiring elevated privilege.
+
+    Order of attempts:
+
+      1. POSIX  → ``os.symlink`` (always works unprivileged)
+      2. Windows → junction via ``mklink /J`` (unprivileged)
+      3. If junction creation fails AND ``copy_fallback=True`` →
+         ``shutil.copytree(symlinks=True)`` (the link is no longer
+         a reference; it's a full tree copy)
+      4. If junction creation fails AND ``copy_fallback=False`` →
+         ``OSError`` raised, no fallback
+
+    ``target`` must already exist as a directory. ``link`` must not
+    exist. The link's parent directory must already exist (this
+    function doesn't ``mkdir`` intermediates — caller's policy stays
+    explicit).
+    """
+    if not target.is_dir():
+        raise NotADirectoryError(f"link target is not a directory: {target!r}")
+    if link.exists() or link.is_symlink():
+        raise FileExistsError(f"link path already exists: {link!r}")
+
+    if sys.platform != "win32":
+        # POSIX ``os.symlink`` is unprivileged on every supported POSIX.
+        # The Windows branch (below) uses junctions via ``mklink /J``,
+        # also unprivileged. This module is the boundary that lets the
+        # rest of the codebase alias directories without ever needing
+        # ``SeCreateSymbolicLinkPrivilege`` — the privilege-allow on the
+        # call below documents that intentional shape.
+        os.symlink(
+            str(target), str(link), target_is_directory=True
+        )  # privilege-allow: POSIX unprivileged path; Windows uses junctions
+        return LinkResult(mechanism="symlink", link=link, target=target)
+
+    if _create_junction(link=link, target=target):
+        return LinkResult(mechanism="junction", link=link, target=target)
+
+    if not copy_fallback:
+        raise OSError(
+            f"could not create junction at {link!r} -> {target!r}; "
+            f"pass copy_fallback=True to copy the directory tree instead"
+        )
+    shutil.copytree(str(target), str(link), symlinks=True)
+    return LinkResult(mechanism="copy", link=link, target=target)
+
+
+def safe_directory_move(src: Path, dst: Path) -> LinkResult:
+    """Move ``src`` to ``dst``; preserve link semantics across filesystems.
+
+    Default ``shutil.move`` is correct except in one case: a symlink
+    source moved across a filesystem boundary uses ``os.symlink`` to
+    recreate the link atom at the destination, which requires
+    ``SeCreateSymbolicLinkPrivilege`` on Windows. This wrapper routes
+    that case through ``link_directory`` (junction-capable) so the
+    move stays unprivileged.
+
+    Same-filesystem moves of symlinks use ``os.rename`` directly — the
+    link atom is preserved without copying. Non-symlink sources
+    delegate to ``shutil.move`` unchanged.
+    """
+    if src.is_symlink():
+        raw_target = os.readlink(src)
+        # ``os.readlink`` returns the stored target STRING. A relative
+        # target is interpreted relative to ``src.parent``, NOT the
+        # current working directory. Resolving lexically against
+        # ``src.parent`` gives the actual target so ``link_directory``
+        # (which checks ``target.is_dir()``) sees the right path and
+        # the ``LinkResult`` audit field carries an accurate value.
+        # ``Path.__truediv__`` resets if ``raw_target`` is already
+        # absolute, so this works for both relative and absolute
+        # stored targets.
+        link_target = (src.parent / raw_target).absolute()
+        try:
+            os.rename(src, dst)
+            return LinkResult(mechanism="symlink", link=dst, target=link_target)
+        except OSError:
+            # Cross-filesystem move of a symlink. ``link_directory``
+            # creates a junction on Windows (unprivileged) or a real
+            # symlink on POSIX; copy_fallback=True matches
+            # ``shutil.move``'s existing cross-FS behavior.
+            result = link_directory(link_target, dst, copy_fallback=True)
+            src.unlink()
+            return result
+
+    shutil.move(str(src), str(dst))
+    return LinkResult(mechanism="move", link=dst, target=src)
+
+
+# ---------------------------------------------------------------------------
+# Private — Windows junction creation via ``cmd /c mklink /J``
+# ---------------------------------------------------------------------------
+
+
+def _create_junction(*, link: Path, target: Path) -> bool:
+    """Create a Windows directory junction via ``mklink /J``.
+
+    ``mklink`` is a ``cmd.exe`` builtin (not a standalone exe) so the
+    invocation has to go through ``cmd /c``. ``hardened_argv``
+    promotes ``cmd`` to its absolute path (AGENTS Rule #1).
+
+    Returns ``True`` on success, ``False`` if ``cmd.exe`` is not
+    reachable on PATH or ``mklink`` returns non-zero. Never raises —
+    the caller decides whether to fall back or surface failure.
+    """
+    try:
+        argv = hardened_argv(["cmd", "/c", "mklink", "/J", str(link), str(target)])
+    except OSError:
+        return False
+    proc = subprocess.run(  # noqa: S603 - argv-list, hardened, no shell
+        argv,
+        capture_output=True,
+        text=True,
+        timeout=10,
+        check=False,
+    )
+    return proc.returncode == 0

refs_mcp/api/__init__.py

@@ -0,0 +1,39 @@
+"""Noun-namespace MCP tool surface for refs.
+
+Three tools instead of 27. Each is a thin dispatcher around the existing
+engine functions in ``refs_mcp.search`` / ``refs_mcp.operations`` /
+``refs_mcp.symbols`` / etc. — the engines stay, only the public MCP
+surface collapses.
+
+Tools:
+
+* ``refs_repo(slug, action, ...)`` — every operation scoped to a single
+  repo. ``action`` is a ``Literal`` over: find / clone / status /
+  update / search / symbols / sparse / export.
+* ``refs_inventory(action, ...)`` — every cross-repo / corpus operation.
+  Local sweeps, remote discovery, reorg, index, preseed.
+* ``refs_observability(action, ...)`` — server-side diagnostic. Host
+  tools probe, contract drift, events tail, journal, help.
+
+Internalized (no longer exposed as separate tools):
+
+* ``refs_prove_absence`` → every ``refs_repo(action=search)`` returns
+  ``receipt.verdict``. ``VALIDATED_EMPTY`` is the proof; clients check
+  the verdict, no separate tool.
+* ``refs_inspect_terms`` → ``refs_repo(action=search, target=[list])``
+  auto-fans-out across the term list.
+* ``refs_search_files`` → ``refs_repo(action=search, mode='files_with')``.
+* ``refs_count_matches`` → ``refs_repo(action=search, mode='count')``.
+* ``refs_find_symbol`` → ``refs_repo(action=symbols, name=X)`` (the
+  point-lookup is just a filter on the list-symbols query).
+
+Design rationale: pydantic discriminated unions were considered but
+FastMCP's discriminator support has only one regression test in the
+upstream suite (jlowin/fastmcp tests/utilities/test_json_schema.py
+line 249), so we use the simpler ``action: Literal[...]`` + flat
+optional per-action params. Body code validates per-action requirements.
+Every MCP client renders this shape; discriminator-mapping rendering
+varies.
+"""
+
+from __future__ import annotations