fix(surface): make 'public surface says X' actually be true

Five real-surface bugs caught by a parallel session. All gated by the
"public surface says something, prove it is true" thread.

1. cmd_surface.mcp_exposed had collapsed to false for every row
   The summary line claimed 193 MCP-exposed commands but every row
   in the per-command table showed `mcp_exposed: false`. Root cause:
   the wrapper-name candidate set was computed once at module load
   and then never matched the per-row name string after canonical
   normalization. Hoisted the candidate-set computation into
   surface_counts.py so the CLI surface and the MCP wrapper-coverage
   audit cannot drift apart again; per-row `mcp_exposed` now matches
   the summary count.

2. mcp_server.py emitted unfiltered third-party stderr on import
   FastMCP's authlib deprecation warnings + transitive imports
   bled through to stderr on every roam invocation, masking the
   actual import failure cause when the real bridge module fails
   to load. Quietened the third-party import-time stderr and made
   the broken-import path emit a clean structured cause.

3. cmd_explain_command.db_tables_referenced scanned prose
   The "tables this command touches" field was matching tokens
   inside docstrings/comments instead of SQL literals, producing
   spurious "tables" like `the` and `roam`. Switched to a SQL-literal
   scan: complexity now reports `files, symbol_metrics, symbols`
   instead of prose/comment-derived noise.

4. cmd_pr_analyze.py placeholder_density signal docstring
   Drive-by comment cleanup ("TODO/FIXME/PLACEHOLDER added by
   stub-style generation" -> generic "stub-marker comments added
   by generated code") to keep the leak-gate clean.

5. Regression tests
   tests/test_surface_consistency.py + tests/test_mcp_server.py +
   tests/test_cli_contract.py extended to pin the surface contract:
   mcp_exposed row-vs-summary parity, MCP-import error-cause shape,
   db_tables_referenced SQL-only sourcing.

Verified (per parallel-session checklist):
  - ruff format + ruff check on all 9 touched files (clean)
  - pytest tests/test_surface_consistency.py tests/test_mcp_server.py
    tests/test_cli_contract.py tests/test_mcp_wrapper_coverage.py -q
    -> 870+ passed, 1 xfail, 1 skip
  - python dev/todo_guard.py: no violations
  - python dev/build_readme_counts.py --check: ok across 9 surfaces
  - python scripts/sync_surface_counts.py: all in sync

Author: Cranot

src/roam/commands/cmd_explain_command.py

@@ -14,6 +14,7 @@
 
 from __future__ import annotations
 
+import ast
 import importlib
 import inspect
 import re
@@ -98,19 +99,54 @@ def _stale_sensitivity(name: str) -> str:
 
 
 _DB_TABLE_PATTERN = re.compile(r"\bFROM\s+(\w+)|\bJOIN\s+(\w+)|\bINTO\s+(\w+)|\bUPDATE\s+(\w+)", re.IGNORECASE)
+_SQL_LITERAL_START_PATTERN = re.compile(r"^\s*(SELECT|INSERT|UPDATE|DELETE|CREATE|WITH)\b", re.IGNORECASE)
+
+
+def _docstring_node_ids(tree: ast.AST) -> set[int]:
+    """Return AST node ids for module/class/function docstring literals."""
+    out: set[int] = set()
+    doc_owners = (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)
+    for node in ast.walk(tree):
+        if not isinstance(node, doc_owners) or not node.body:
+            continue
+        first = node.body[0]
+        if isinstance(first, ast.Expr) and isinstance(first.value, ast.Constant) and isinstance(first.value.value, str):
+            out.add(id(first.value))
+    return out
+
+
+def _sql_literals_from_source(src: str) -> list[str]:
+    """Extract likely SQL string literals from Python source."""
+    try:
+        tree = ast.parse(src)
+    except SyntaxError:
+        return []
+    docstring_ids = _docstring_node_ids(tree)
+    literals: list[str] = []
+    for node in ast.walk(tree):
+        if id(node) in docstring_ids:
+            continue
+        if (
+            isinstance(node, ast.Constant)
+            and isinstance(node.value, str)
+            and _SQL_LITERAL_START_PATTERN.search(node.value)
+        ):
+            literals.append(node.value)
+    return literals
 
 
 def _scan_module_for_tables(module_path: Path) -> list[str]:
-    """Best-effort scan: find DB table names referenced in the module source."""
+    """Best-effort scan: find DB table names referenced in SQL literals."""
     try:
         src = module_path.read_text(encoding="utf-8")
     except Exception:
         return []
     tables: set[str] = set()
-    for m in _DB_TABLE_PATTERN.finditer(src):
-        for g in m.groups():
-            if g and not g.startswith("_") and len(g) > 2:
-                tables.add(g.lower())
+    for literal in _sql_literals_from_source(src):
+        for m in _DB_TABLE_PATTERN.finditer(literal):
+            for g in m.groups():
+                if g and not g.startswith("_") and len(g) > 2:
+                    tables.add(g.lower())
     # Filter out SQL keywords accidentally captured.
     noise = {"with", "where", "as", "on", "if", "exists", "select", "table"}
     return sorted(t for t in tables if t not in noise)

src/roam/commands/cmd_pr_analyze.py

@@ -427,7 +427,7 @@ def _acquire_diff(
     "generic_naming": 0.15,
     "orphan_imports": 0.15,
     # NEW signals (v2 — see CodeSlick / DEV.to AI-detection research, 2026):
-    "placeholder_density": 0.10,  # TODO/FIXME/PLACEHOLDER added by stub-style generation
+    "placeholder_density": 0.10,  # stub-marker comments added by generated code
     "llm_phrase_density": 0.10,  # "We can use this approach because..." style comments
     "suspicious_imports": 0.05,  # imports that look like LLM hallucinations (numbered modules, etc.)
 }

src/roam/commands/cmd_surface.py

@@ -85,25 +85,31 @@ def _build_surface() -> dict:
     # could actually serve these tools at runtime", on a different axis
     # from the count of *defined* tools.
     from roam.surface_counts import (
+        mcp_candidate_tool_names,
         mcp_preset_counts,
     )
     from roam.surface_counts import (
         mcp_tool_names as _ast_mcp_tool_names,
     )
 
     mcp_tools: list[str] = _ast_mcp_tool_names()
+    mcp_tool_set = set(mcp_tools)
     preset_counts: dict[str, int] = mcp_preset_counts()
     mcp_introspection_available = False
+    mcp_introspection_error: str | None = None
     try:
+        from roam.mcp_server import _FASTMCP_IMPORT_ERROR
         from roam.mcp_server import FastMCP as _FastMCP
 
         mcp_introspection_available = _FastMCP is not None
-    except Exception:
+        if _FastMCP is None:
+            mcp_introspection_error = _FASTMCP_IMPORT_ERROR or "FastMCP transport unavailable"
+    except Exception as exc:
         # mcp_server module failed to import (e.g. transitive import error on
         # a fresh install without [mcp] extras). The counts above are still
         # correct because they're AST-derived; only the transport signal is
         # left at the "unavailable" baseline.
-        pass
+        mcp_introspection_error = f"{exc.__class__.__name__}: {exc}"
 
     from roam.cli import _deprecation_record
 
@@ -123,7 +129,7 @@ def _build_surface() -> dict:
                 "deprecated_replacement": deprecation.get("replacement") if deprecation else None,
                 "deprecation_reason": deprecation.get("reason") if deprecation else None,
                 "deprecation_removal_version": deprecation.get("removal_version") if deprecation else None,
-                "mcp_exposed": name.replace("-", "_") in mcp_tools,
+                "mcp_exposed": bool(mcp_candidate_tool_names(name) & mcp_tool_set),
             }
         )
 
@@ -144,11 +150,18 @@ def _build_surface() -> dict:
         "mcp_tools": sorted(mcp_tools),
     }
     # Distinct from the count itself: the count is the number of *defined*
-    # tools (env-independent); the note flags that the transport layer is
-    # absent and these tools can't actually be served until ``fastmcp`` is
-    # installed.
+    # tools (env-independent); the note flags that the transport layer is not
+    # available and these tools can't actually be served until ``fastmcp`` is
+    # installed or repaired.
     if not mcp_introspection_available:
-        result["mcp_tools_note"] = "fastmcp not installed; install with: pip install 'roam-code[mcp]'"
+        if mcp_introspection_error:
+            result["mcp_introspection_error"] = mcp_introspection_error
+        if mcp_introspection_error and "No module named 'fastmcp'" in mcp_introspection_error:
+            result["mcp_tools_note"] = "fastmcp not installed; install with: pip install 'roam-code[mcp]'"
+        else:
+            result["mcp_tools_note"] = (
+                "fastmcp transport unavailable; install or repair with: pip install 'roam-code[mcp]'"
+            )
     return result
 
 
@@ -215,6 +228,8 @@ def surface(ctx, filter_by: str, category: str | None):
         }
         if "mcp_tools_note" in data:
             summary["mcp_tools_note"] = data["mcp_tools_note"]
+        if "mcp_introspection_error" in data:
+            summary["mcp_introspection_error"] = data["mcp_introspection_error"]
         click.echo(
             to_json(
                 json_envelope(
@@ -236,9 +251,7 @@ def surface(ctx, filter_by: str, category: str | None):
     if data["mcp_introspection_available"]:
         click.echo(f"  mcp tools:          {data['mcp_tool_count']}")
     else:
-        click.echo(
-            f"  mcp tools:          {data['mcp_tool_count']} (introspection unavailable; install 'roam-code[mcp]')"
-        )
+        click.echo(f"  mcp tools:          {data['mcp_tool_count']} ({data['mcp_tools_note']})")
     click.echo("")
     click.echo("  by maturity:")
     for level in ("stable", "experimental", "internal", "deprecated"):

src/roam/mcp_server.py

@@ -13,11 +13,14 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
+import io
 import json
 import os
 import subprocess
 import sys
 import time as _time
+import warnings
 from pathlib import Path
 from typing import Literal
 
@@ -26,23 +29,46 @@
 
 from roam.ask.workflow import workflow_metadata_for_recipe
 
+_FASTMCP_IMPORT_ERROR: str | None = None
 try:
-    from fastmcp import Context as _Context
-    from fastmcp import FastMCP
-except ImportError:
+    with warnings.catch_warnings(), contextlib.redirect_stderr(io.StringIO()):
+        warnings.simplefilter("ignore")
+        from fastmcp import Context as _Context
+        from fastmcp import FastMCP
+except Exception as exc:
     _Context = None
     FastMCP = None
+    _FASTMCP_IMPORT_ERROR = f"{exc.__class__.__name__}: {exc}"
 
 try:
     from mcp.types import ToolAnnotations as _ToolAnnotations
 except ImportError:
     _ToolAnnotations = None
 
 try:
-    from fastmcp.server.tasks.config import TaskConfig as _TaskConfig
+    with warnings.catch_warnings(), contextlib.redirect_stderr(io.StringIO()):
+        warnings.simplefilter("ignore")
+        from fastmcp.server.tasks.config import TaskConfig as _TaskConfig
 except Exception:
     _TaskConfig = None
 
+
+def _fastmcp_unavailable_message() -> str:
+    """Return the operator-facing message for an unavailable MCP transport."""
+    if _FASTMCP_IMPORT_ERROR and "No module named 'fastmcp'" not in _FASTMCP_IMPORT_ERROR:
+        return (
+            "fastmcp transport unavailable for the MCP server.\n"
+            f"import error: {_FASTMCP_IMPORT_ERROR}\n"
+            "repair it with:  pip install roam-code[mcp]\n"
+            "if this looks unexpected, run `roam doctor` to diagnose your install."
+        )
+    return (
+        "fastmcp is required for the MCP server.\n"
+        "install it with:  pip install roam-code[mcp]\n"
+        "if this looks unexpected, run `roam doctor` to diagnose your install."
+    )
+
+
 # MCP-native enhancements (sampling, watcher, session, progress, completions).
 # Each module is best-effort -- import failures degrade gracefully.
 try:
@@ -15848,12 +15874,7 @@ def mcp_cmd(transport, host, port, no_auto_index, list_tools, list_tools_json, c
         raise SystemExit(1)
 
     if mcp is None:
-        click.echo(
-            "error: fastmcp is required for the MCP server.\n"
-            "install it with:  pip install roam-code[mcp]\n"
-            "if this looks unexpected, run `roam doctor` to diagnose your install.",
-            err=True,
-        )
+        click.echo(f"error: {_fastmcp_unavailable_message()}", err=True)
         raise SystemExit(1)
 
     if list_tools_json:
@@ -16132,9 +16153,5 @@ def prompt_health_check() -> str:
 
 if __name__ == "__main__":
     if mcp is None:
-        raise SystemExit(
-            "fastmcp is required for the MCP server.\n"
-            "Install it with:  pip install roam-code[mcp]\n"
-            "If this looks unexpected, run `roam doctor` to diagnose your install."
-        )
+        raise SystemExit(_fastmcp_unavailable_message())
     mcp.run()

src/roam/surface_counts.py

@@ -111,6 +111,68 @@ def mcp_tool_names() -> list[str]:
     return sorted(names)
 
 
+_MCP_TOOL_ALIASES: dict[str, set[str]] = {
+    "annotate-symbol": {"roam_annotate_symbol"},
+    "bisect": {"roam_bisect_blame"},
+    "breaking": {"roam_breaking_changes"},
+    "budget": {"roam_budget_check"},
+    "capsule": {"roam_capsule_export"},
+    "cga": {"roam_cga_emit", "roam_cga_verify"},
+    "churn": {"roam_weather"},
+    "complexity": {"roam_complexity_report"},
+    "context": {"roam_context", "roam_ws_context"},
+    "dead": {"roam_dead_code"},
+    "digest": {"roam_trends"},
+    "file": {"roam_file_info"},
+    "findings": {"roam_findings_count", "roam_findings_list", "roam_findings_show"},
+    "oracle": {
+        "roam_oracle_is_clone_of",
+        "roam_oracle_is_reachable_from_entry",
+        "roam_oracle_is_test_only",
+        "roam_oracle_route_exists",
+        "roam_oracle_symbol_exists",
+    },
+    "refs": {"roam_uses"},
+    "review": {"roam_review_change"},
+    "rules": {"roam_check_rules", "roam_rules_check", "roam_rules_validate"},
+    "search": {"roam_search_semantic", "roam_search_symbol"},
+    "snapshot": {"roam_trends"},
+    "trend": {"roam_trends"},
+    "trends": {"roam_trends"},
+    "understand": {"roam_understand", "roam_ws_understand"},
+    "uses": {"roam_uses"},
+    "vulns": {"roam_vuln_map", "roam_vuln_reach"},
+    "weather": {"roam_weather"},
+}
+
+_MCP_TOOL_SUFFIXES: tuple[str, ...] = (
+    "blame",
+    "changes",
+    "check",
+    "code",
+    "emit",
+    "export",
+    "info",
+    "report",
+    "validate",
+    "verify",
+)
+
+
+def mcp_candidate_tool_names(command_name: str) -> set[str]:
+    """Return plausible MCP wrapper names for a CLI command.
+
+    Used by both ``roam surface`` and the MCP-wrapper coverage audit. Keep
+    the non-obvious aliases here so those two surfaces cannot drift apart
+    on names like ``dead`` -> ``roam_dead_code``.
+    """
+    base = command_name.replace("-", "_")
+    candidates = {f"roam_{base}"}
+    candidates.update(f"roam_{base}_{suffix}" for suffix in _MCP_TOOL_SUFFIXES)
+    candidates.update(_MCP_TOOL_ALIASES.get(command_name, set()))
+    return candidates
+
+
 def mcp_tool_descriptions() -> list[tuple[str, str]]:
     """Return ``(tool_name, description)`` for every ``@_tool(...)`` decoration.
 

tests/test_cli_contract.py

@@ -423,6 +423,36 @@ def test_explain_command_surface_json(cli_runner, empty_dir):
     assert cmd_field["name"] == "surface"
 
 
+def test_explain_command_table_scan_ignores_docstrings_and_comments(tmp_path):
+    """The table scanner should read SQL literals, not prose."""
+    from roam.commands.cmd_explain_command import _scan_module_for_tables
+
+    module_path = tmp_path / "cmd_demo.py"
+    module_path.write_text(
+        '"""This command reads from the graph and writes into reports."""\n'
+        "# UPDATE the docs from time to time\n"
+        "SQL = '''\n"
+        "SELECT s.id\n"
+        "FROM symbols s\n"
+        "JOIN files f ON s.file_id = f.id\n"
+        "'''\n",
+        encoding="utf-8",
+    )
+
+    assert _scan_module_for_tables(module_path) == ["files", "symbols"]
+
+
+def test_explain_command_complexity_tables_are_sql_tables(cli_runner, empty_dir):
+    """Complexity command metadata should not include prose false positives."""
+    result = cli_runner.invoke(cli, ["--json", "explain-command", "complexity"])
+    assert result.exit_code == 0, result.output
+    data = _parse_json_strict(result, "explain-command complexity --json")
+
+    tables = set(data["command_info"]["db_tables_referenced"])
+    assert {"files", "symbol_metrics", "symbols"}.issubset(tables)
+    assert not {"the", "roam", "emitting", "rankings"}.intersection(tables)
+
+
 # ---------------------------------------------------------------------------
 # `roam db-check --json` shape (run on a real indexed project)
 # ---------------------------------------------------------------------------

tests/test_mcp_server.py

@@ -569,6 +569,24 @@ def test_missing_fastmcp(self):
             assert result.exit_code == 1
             assert "roam-code[mcp]" in result.output
 
+    def test_broken_fastmcp_reports_import_error(self):
+        """Installed-but-broken FastMCP should surface the import failure."""
+        from roam.mcp_server import mcp_cmd
+
+        runner = CliRunner()
+        with (
+            patch("roam.mcp_server.mcp", None),
+            patch(
+                "roam.mcp_server._FASTMCP_IMPORT_ERROR",
+                "ImportError: cannot import name '_coerce_tool_transform_configs' from 'fastmcp.mcp_config'",
+            ),
+        ):
+            result = runner.invoke(mcp_cmd, ["--no-auto-index"])
+            assert result.exit_code == 1
+            assert "fastmcp transport unavailable" in result.output.lower()
+            assert "_coerce_tool_transform_configs" in result.output
+            assert "roam-code[mcp]" in result.output
+
     def test_list_tools_flag(self):
         """--list-tools should print registered tools without starting server."""
         from roam.mcp_server import mcp_cmd