codegraph-engine 2.1.7__py3-none-any.whl → 2.1.8__py3-none-any.whl

codegraph/__init__.py

@@ -1,6 +1,6 @@
 """CodeGraph MCP: local, evidence-backed codebase intelligence."""
 
-__version__ = "2.1.7"
+__version__ = "2.1.8"
 from codegraph.errors import (
     CodeGraphError,
     ErrorCode,

codegraph/cli.py

@@ -9,6 +9,7 @@ import typer
 
 from codegraph import __version__
 from codegraph.architecture import get_architecture
+from codegraph.cli_output import cli_echo
 from codegraph.config import Settings
 from codegraph.context import get_context
 from codegraph.errors import ErrorCode, SecurityError
@@ -605,8 +606,10 @@ def serve(
     """Run the stdio MCP server (requires the optional mcp extra)."""
     repo = _resolve_repo(path, repository)
     from codegraph.mcp import create_server
+    from codegraph.process_lifecycle import run_mcp_stdio_server
 
-    create_server(repo, profile=profile).run()
+    server = create_server(repo, profile=profile)
+    run_mcp_stdio_server(server, repo, profile=profile)
 
 
 mcp_app = typer.Typer(help="MCP server commands.")
@@ -622,8 +625,70 @@ def mcp_serve(
     """Run the stdio MCP server (requires the optional mcp extra)."""
     repo = _resolve_repo(path, repository)
     from codegraph.mcp import create_server
+    from codegraph.process_lifecycle import run_mcp_stdio_server
 
-    create_server(repo, profile=profile).run()
+    server = create_server(repo, profile=profile)
+    run_mcp_stdio_server(server, repo, profile=profile)
+
+
+def _execute_stop(
+    path: Path | None,
+    repository: Path | None,
+    all_processes: bool,
+    timeout: float,
+    json_output: bool,
+) -> None:
+    from codegraph.process_lifecycle import stop_codegraph_processes
+
+    target_repo: Path | None = None
+    if not all_processes:
+        target_repo = _resolve_repo(path, repository)
+
+    res = stop_codegraph_processes(
+        repository=target_repo,
+        stop_all=all_processes,
+        timeout_sec=timeout,
+    )
+    if json_output:
+        cli_echo(json.dumps(res.as_dict(), indent=2), json_mode=True)
+    else:
+        cli_echo(res.format_human())
+
+
+@app.command("stop")
+def stop_cmd(
+    path: Annotated[Path | None, typer.Argument(help="Repository path (default: current directory)")] = None,
+    repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
+    all_processes: Annotated[bool, typer.Option("--all", "-a", help="Stop all CodeGraph-owned MCP processes across all repositories")] = False,
+    timeout: Annotated[float, typer.Option("--timeout", help="Graceful shutdown timeout in seconds before force-kill")] = 3.0,
+    json_output: Annotated[bool, typer.Option("--json", help="Output deterministic machine-readable JSON")] = False,
+) -> None:
+    """Safely stop running CodeGraph MCP background processes and release file locks."""
+    _execute_stop(path, repository, all_processes, timeout, json_output)
+
+
+@mcp_app.command("stop")
+def mcp_stop_cmd(
+    path: Annotated[Path | None, typer.Argument(help="Repository path (default: current directory)")] = None,
+    repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
+    all_processes: Annotated[bool, typer.Option("--all", "-a", help="Stop all CodeGraph-owned MCP processes across all repositories")] = False,
+    timeout: Annotated[float, typer.Option("--timeout", help="Graceful shutdown timeout in seconds before force-kill")] = 3.0,
+    json_output: Annotated[bool, typer.Option("--json", help="Output deterministic machine-readable JSON")] = False,
+) -> None:
+    """Safely stop running CodeGraph MCP background processes and release file locks."""
+    _execute_stop(path, repository, all_processes, timeout, json_output)
+
+
+@mcp_app.command("kill")
+def mcp_kill_cmd(
+    path: Annotated[Path | None, typer.Argument(help="Repository path (default: current directory)")] = None,
+    repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
+    all_processes: Annotated[bool, typer.Option("--all", "-a", help="Stop all CodeGraph-owned MCP processes across all repositories")] = False,
+    timeout: Annotated[float, typer.Option("--timeout", help="Graceful shutdown timeout in seconds before force-kill")] = 1.0,
+    json_output: Annotated[bool, typer.Option("--json", help="Output deterministic machine-readable JSON")] = False,
+) -> None:
+    """Alias for `codegraph stop` to terminate CodeGraph MCP processes and release locks."""
+    _execute_stop(path, repository, all_processes, timeout, json_output)
 
 
 @mcp_app.command("doctor")
@@ -636,9 +701,9 @@ def mcp_doctor(
 
     report = run_mcp_doctor(profile=profile)
     if json_output:
-        typer.echo(json.dumps(report.as_dict(), indent=2))
+        cli_echo(json.dumps(report.as_dict(), indent=2), json_mode=True)
     else:
-        typer.echo(report.format_human())
+        cli_echo(report.format_human())
     if not report.healthy:
         raise typer.Exit(code=1)
 
@@ -656,9 +721,9 @@ def mcp_config_check(
     ws = (path or Path.cwd()).resolve()
     rep = check_mcp_configuration(workspace_dir=ws, config_file=config_file, include_example=include_example)
     if json_output:
-        typer.echo(json.dumps(rep.as_dict(), indent=2))
+        cli_echo(json.dumps(rep.as_dict(), indent=2), json_mode=True)
     else:
-        typer.echo(f"{rep.status.value}: {rep.message}")
+        cli_echo(f"{rep.status.value}: {rep.message}")
 
 
 @mcp_app.command("capabilities")
@@ -666,7 +731,7 @@ def mcp_capabilities() -> None:
     """Output the deterministic machine-readable CodeGraph capability manifest."""
     from codegraph.agent_capabilities import get_capability_manifest
 
-    typer.echo(json.dumps(get_capability_manifest(), indent=2))
+    cli_echo(json.dumps(get_capability_manifest(), indent=2), json_mode=True)
 
 
 @mcp_app.command("rules")
@@ -676,7 +741,7 @@ def mcp_rules(
     """Render deterministic CodeGraph agent rules for the specified agent."""
     from codegraph.agent_rules import render_agent_rules
 
-    typer.echo(render_agent_rules(agent=agent), nl=False)
+    cli_echo(render_agent_rules(agent=agent), nl=False)
 
 
 @app.command()
@@ -685,9 +750,20 @@ def doctor(
     repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
     resources: Annotated[bool, typer.Option("--resources")] = False,
     database: Annotated[bool, typer.Option("--database", help="Run comprehensive database integrity and schema checks")] = False,
+    processes: Annotated[bool, typer.Option("--processes", help="Inspect active CodeGraph processes, parent state, and stale PID files")] = False,
     json_output: Annotated[bool, typer.Option("--json")] = False,
 ) -> None:
-    """Check repository and index readiness, database integrity, and freshness."""
+    """Check repository and index readiness, database integrity, process lifecycle, and freshness."""
+    if processes:
+        from codegraph.process_lifecycle import discover_codegraph_processes
+
+        discovery = discover_codegraph_processes(clean_stale=True)
+        if json_output:
+            cli_echo(json.dumps(discovery.as_dict(), indent=2), json_mode=True)
+        else:
+            cli_echo(discovery.format_human())
+        return
+
     repo = _resolve_repo(path, repository)
     indexer_inst = _indexer(repo)
     db = repo / ".codegraph.sqlite3"
@@ -1007,7 +1083,7 @@ def install(
 
             rules_txt = render_agent_rules(canon)
             if json_output:
-                typer.echo(
+                cli_echo(
                     json.dumps(
                         {
                             "status": "ok",
@@ -1016,21 +1092,22 @@ def install(
                             "instructions_block": format_marker_block(rules_txt),
                         },
                         indent=2,
-                    )
+                    ),
+                    json_mode=True,
                 )
             else:
-                typer.echo(f"# MCP Configuration ({canon})\n")
-                typer.echo(json.dumps(snippet, indent=2))
-                typer.echo(f"\n# Instructions Block ({canon})\n")
-                typer.echo(format_marker_block(rules_txt), nl=False)
+                cli_echo(f"# MCP Configuration ({canon})\n")
+                cli_echo(json.dumps(snippet, indent=2), json_mode=True)
+                cli_echo(f"\n# Instructions Block ({canon})\n")
+                cli_echo(format_marker_block(rules_txt), nl=False)
             return
         except CodeGraphError as exc:
             if json_output:
-                typer.echo(json.dumps(exc.to_response(), indent=2))
+                cli_echo(json.dumps(exc.to_response(), indent=2), json_mode=True)
             else:
-                typer.echo(f"Error [{exc.code}]: {exc.message}")
+                cli_echo(f"Error [{exc.code}]: {exc.message}")
                 if exc.next_action and exc.next_action.get("command"):
-                    typer.echo(f"\nTry:\n  {exc.next_action['command']}")
+                    cli_echo(f"\nTry:\n  {exc.next_action['command']}")
             raise typer.Exit(code=1) from exc
 
     ws = _resolve_repo(path, repository)
@@ -1040,15 +1117,15 @@ def install(
 
         assert isinstance(preview_rep, InstallerReport)
         if not json_output:
-            typer.echo(preview_rep.format_preview_human())
-            typer.echo("")
-            typer.echo("Continue? [y/N] ", nl=False)
+            cli_echo(preview_rep.format_preview_human())
+            cli_echo("")
+            cli_echo("Continue? [y/N] ", nl=False)
         try:
             ans = input().strip().lower()
         except EOFError:
             ans = ""
         if not json_output:
-            typer.echo("")
+            cli_echo("")
         return ans in ("y", "yes")
 
     try:
@@ -1062,22 +1139,22 @@ def install(
         )
     except CodeGraphError as exc:
         if json_output:
-            typer.echo(json.dumps(exc.to_response(), indent=2))
+            cli_echo(json.dumps(exc.to_response(), indent=2), json_mode=True)
         else:
-            typer.echo(f"Error [{exc.code}]: {exc.message}")
+            cli_echo(f"Error [{exc.code}]: {exc.message}")
             if exc.next_action and exc.next_action.get("reason"):
-                typer.echo(f"\nExpected:\n  {exc.next_action['reason']}")
+                cli_echo(f"\nExpected:\n  {exc.next_action['reason']}")
             if exc.next_action and exc.next_action.get("command"):
-                typer.echo(f"\nTry:\n  {exc.next_action['command']}")
+                cli_echo(f"\nTry:\n  {exc.next_action['command']}")
         raise typer.Exit(code=1) from exc
 
     if json_output:
-        typer.echo(json.dumps(report.as_dict(), indent=2))
+        cli_echo(json.dumps(report.as_dict(), indent=2), json_mode=True)
     else:
         if yes and not dry_run:
-            typer.echo(report.format_preview_human())
-            typer.echo("")
-        typer.echo(report.format_human())
+            cli_echo(report.format_preview_human())
+            cli_echo("")
+        cli_echo(report.format_human())
 
     if report.status == "error":
         raise typer.Exit(code=1)
@@ -1107,17 +1184,17 @@ def uninstall(
 
     def _confirm_uninstall(preview_rep: InstallerReport) -> bool:
         if not json_output:
-            typer.echo("CodeGraph Uninstaller\n")
+            cli_echo("CodeGraph Uninstaller\n")
             for c in preview_rep.changes:
                 if c.action in ("remove", "modify"):
-                    typer.echo(f"  - {c.display_path} ({c.action})")
-            typer.echo("\nContinue? [y/N] ", nl=False)
+                    cli_echo(f"  - {c.display_path} ({c.action})")
+            cli_echo("\nContinue? [y/N] ", nl=False)
         try:
             ans = input().strip().lower()
         except EOFError:
             ans = ""
         if not json_output:
-            typer.echo("")
+            cli_echo("")
         return ans in ("y", "yes")
 
     try:
@@ -1130,17 +1207,17 @@ def uninstall(
         )
     except CodeGraphError as exc:
         if json_output:
-            typer.echo(json.dumps(exc.to_response(), indent=2))
+            cli_echo(json.dumps(exc.to_response(), indent=2), json_mode=True)
         else:
-            typer.echo(f"Error [{exc.code}]: {exc.message}")
+            cli_echo(f"Error [{exc.code}]: {exc.message}")
             if exc.next_action and exc.next_action.get("command"):
-                typer.echo(f"\nTry:\n  {exc.next_action['command']}")
+                cli_echo(f"\nTry:\n  {exc.next_action['command']}")
         raise typer.Exit(code=1) from exc
 
     if json_output:
-        typer.echo(json.dumps(report.as_dict(), indent=2))
+        cli_echo(json.dumps(report.as_dict(), indent=2), json_mode=True)
     else:
-        typer.echo(report.format_human())
+        cli_echo(report.format_human())
 
 
 @app.command()
@@ -1159,16 +1236,16 @@ def uninit(
 
     def _confirm_uninit(preview_rep: InstallerReport) -> bool:
         if not json_output:
-            typer.echo("Remove CodeGraph project index files?\n")
+            cli_echo("Remove CodeGraph project index files?\n")
             for c in preview_rep.changes:
-                typer.echo(f"  - {c.display_path}")
-            typer.echo("\nContinue? [y/N] ", nl=False)
+                cli_echo(f"  - {c.display_path}")
+            cli_echo("\nContinue? [y/N] ", nl=False)
         try:
             ans = input().strip().lower()
         except EOFError:
             ans = ""
         if not json_output:
-            typer.echo("")
+            cli_echo("")
         return ans in ("y", "yes")
 
     try:
@@ -1179,15 +1256,15 @@ def uninit(
         )
     except CodeGraphError as exc:
         if json_output:
-            typer.echo(json.dumps(exc.to_response(), indent=2))
+            cli_echo(json.dumps(exc.to_response(), indent=2), json_mode=True)
         else:
-            typer.echo(f"Error [{exc.code}]: {exc.message}")
+            cli_echo(f"Error [{exc.code}]: {exc.message}")
         raise typer.Exit(code=1) from exc
 
     if json_output:
-        typer.echo(json.dumps(report.as_dict(), indent=2))
+        cli_echo(json.dumps(report.as_dict(), indent=2), json_mode=True)
     else:
-        typer.echo(report.format_human())
+        cli_echo(report.format_human())
 
 
 if __name__ == "__main__":

codegraph/cli_output.py

@@ -0,0 +1,190 @@
+"""Centralized cross-platform CLI output utility for Windows/macOS/Linux encoding safety.
+
+Guarantees:
+- Never assumes stdout/stderr is UTF-8 (safe on Windows cp1252, cp437, ASCII, and redirected pipes).
+- Preserves rich Unicode symbols (`✓`, `✗`, `⚠`, `↻`, `(•)`) when the target stream supports them.
+- Automatically degrades to deterministic ASCII markers (`[OK]`, `[ERROR]`, `[WARN]`, `[REPAIRED]`, `(*)`)
+  when the stream encoding does not support Unicode box/status glyphs.
+- Ensures `--json` output is strictly machine-readable and never contains decorative Unicode glyphs.
+"""
+from __future__ import annotations
+
+import codecs
+import os
+import sys
+from dataclasses import dataclass
+from typing import Any, TextIO
+
+import typer
+
+_PROBE_GLYPHS = "✓✗⚠↻•→↓─—–"
+
+# Ordered replacements so multi-char patterns (e.g. "(•)") are replaced before single chars ("•")
+_UNICODE_TO_ASCII_MAP: tuple[tuple[str, str], ...] = (
+    ("(•)", "(*)"),
+    ("✓", "[OK]"),
+    ("✗", "[ERROR]"),
+    ("⚠", "[WARN]"),
+    ("↻", "[REPAIRED]"),
+    ("•", "*"),
+    ("→", "->"),
+    ("↓", "v"),
+    ("—", "--"),
+    ("–", "-"),
+    ("─", "-"),
+)
+
+
+@dataclass(frozen=True)
+class CliSymbols:
+    """Encoding-aware CLI status symbols."""
+
+    unicode_enabled: bool
+    ok: str
+    error: str
+    warn: str
+    repair: str
+    radio_on: str
+    radio_off: str
+    arrow_right: str
+    arrow_down: str
+
+
+UNICODE_SYMBOLS = CliSymbols(
+    unicode_enabled=True,
+    ok="✓",
+    error="✗",
+    warn="⚠",
+    repair="↻",
+    radio_on="(•)",
+    radio_off="( )",
+    arrow_right="→",
+    arrow_down="↓",
+)
+
+ASCII_SYMBOLS = CliSymbols(
+    unicode_enabled=False,
+    ok="[OK]",
+    error="[ERROR]",
+    warn="[WARN]",
+    repair="[REPAIRED]",
+    radio_on="(*)",
+    radio_off="( )",
+    arrow_right="->",
+    arrow_down="v",
+)
+
+
+def detect_stream_encoding(stream: Any = None) -> str:
+    """Safely detect the character encoding of `stream` (defaults to `sys.stdout`)."""
+    target = stream if stream is not None else sys.stdout
+    enc = getattr(target, "encoding", None)
+    if not enc or not isinstance(enc, str):
+        return "ascii"
+    try:
+        info = codecs.lookup(enc)
+        return info.name
+    except LookupError:
+        return "ascii"
+
+
+def supports_unicode(
+    stream: Any = None,
+    *,
+    unicode_override: bool | None = None,
+) -> bool:
+    """Return True if `stream` can encode all CodeGraph Unicode status glyphs without error."""
+    if unicode_override is not None:
+        return unicode_override
+
+    env_ascii = os.environ.get("CODEGRAPH_ASCII_OUTPUT", "").strip().lower()
+    if env_ascii in ("1", "true", "yes", "on"):
+        return False
+
+    env_unicode = os.environ.get("CODEGRAPH_UNICODE_OUTPUT", "").strip().lower()
+    if env_unicode in ("1", "true", "yes", "on"):
+        return True
+    if env_unicode in ("0", "false", "no", "off"):
+        return False
+
+    enc = detect_stream_encoding(stream)
+    try:
+        _PROBE_GLYPHS.encode(enc, errors="strict")
+        return True
+    except (UnicodeEncodeError, LookupError):
+        return False
+
+
+def get_cli_symbols(
+    stream: Any = None,
+    *,
+    unicode_override: bool | None = None,
+) -> CliSymbols:
+    """Return `UNICODE_SYMBOLS` when supported by `stream`, else `ASCII_SYMBOLS`."""
+    if supports_unicode(stream, unicode_override=unicode_override):
+        return UNICODE_SYMBOLS
+    return ASCII_SYMBOLS
+
+
+def sanitize_text_for_stream(
+    text: str,
+    stream: Any = None,
+    *,
+    unicode_override: bool | None = None,
+) -> str:
+    """Format `text` safely for `stream`, converting decorative Unicode when unsupported."""
+    if not text:
+        return text
+
+    target = stream if stream is not None else sys.stdout
+    use_unicode = supports_unicode(target, unicode_override=unicode_override)
+    out = text
+    if not use_unicode:
+        for uni_tok, ascii_tok in _UNICODE_TO_ASCII_MAP:
+            if uni_tok in out:
+                out = out.replace(uni_tok, ascii_tok)
+
+    enc = detect_stream_encoding(target)
+    try:
+        out.encode(enc, errors="strict")
+        return out
+    except (UnicodeEncodeError, LookupError):
+        # Replace any remaining unencodable glyphs cleanly so write() never raises UnicodeEncodeError
+        for uni_tok, ascii_tok in _UNICODE_TO_ASCII_MAP:
+            if uni_tok in out:
+                out = out.replace(uni_tok, ascii_tok)
+        return out.encode(enc, errors="replace").decode(enc, errors="replace")
+
+
+def sanitize_json_string(raw_json: str, stream: Any = None) -> str:
+    """Ensure machine-readable JSON output never crashes non-UTF-8 streams."""
+    enc = detect_stream_encoding(stream)
+    try:
+        raw_json.encode(enc, errors="strict")
+        return raw_json
+    except (UnicodeEncodeError, LookupError):
+        # Escape non-ASCII characters using standard JSON \uXXXX escapes
+        return raw_json.encode("unicode_escape").decode("ascii")
+
+
+def cli_echo(
+    message: str = "",
+    *,
+    nl: bool = True,
+    err: bool = False,
+    json_mode: bool = False,
+    stream: TextIO | None = None,
+    unicode_override: bool | None = None,
+) -> None:
+    """Centralized safe CLI output function replacing raw `typer.echo`."""
+    target = stream if stream is not None else (sys.stderr if err else sys.stdout)
+    if json_mode:
+        safe_msg = sanitize_json_string(str(message), target)
+    else:
+        safe_msg = sanitize_text_for_stream(str(message), target, unicode_override=unicode_override)
+
+    if stream is not None:
+        stream.write(safe_msg + ("\n" if nl else ""))
+        stream.flush()
+    else:
+        typer.echo(safe_msg, nl=nl, err=err)

codegraph/context.py

@@ -708,6 +708,9 @@ def _get_context_impl(
 
         stage1_candidate_count = len(candidate_dicts)
 
+        # Instantiate ConstraintGuard for hard safety invariants
+        _guard = ConstraintGuard.from_task_spec(task_spec)
+
         # Process framework routes
         route_relationships: list[Relationship] = []
         entry_points_out: list[dict[str, object]] = []
@@ -717,16 +720,26 @@ def _get_context_impl(
             r_path = r["route_path"]
             r_method = r["http_method"]
             ep_id = r["endpoint_id"] or f"{r_method} {r_path}"
+            r_segments = [
+                seg.lower()
+                for seg in str(r_path).split("/")
+                if len(seg) >= 4
+                and not seg.startswith("{")
+                and not seg.startswith("<")
+                and seg.lower() not in {"api", "v1", "v2"}
+            ]
             matches_task = (
                 r_path in task_display_str
                 or ep_id.lower() in task_display_str.lower()
                 or (r_method in task_display_str.upper() and r_path in task_display_str)
+                or task_spec.intent == "ARCHITECTURE"
+                or any(seg in task_display_str.lower() for seg in r_segments)
                 or any(
                     (len(tgt) >= 3 and (tgt.lower() == r["handler_name"].lower() or tgt.lower() in r_path.lower()))
                     for tgt in task_spec.targets
                 )
             )
-            if matches_task:
+            if matches_task and _guard.allows_symbol(str(r["handler_name"])) and _guard.allows_file(str(r["file_path"])):
                 target_symbols.add(r["handler_name"])
                 r_line = r["line"] or 1
                 candidate_dicts.append(
@@ -799,8 +812,108 @@ def _get_context_impl(
                 except Exception:
                     pass
 
-        # Instantiate ConstraintGuard for hard safety invariants
-        _guard = ConstraintGuard.from_task_spec(task_spec)
+        # Seed architectural boundary classes and gateway methods for ARCHITECTURE intent
+        if task_spec.intent == "ARCHITECTURE":
+            try:
+                arch_rows = con.execute(
+                    "SELECT canonical_id, qualified_name, name, kind, path, start_line, end_line "
+                    "FROM symbols WHERE kind = 'class' OR name = 'app'"
+                ).fetchall()
+                for a_row in arch_rows:
+                    a_name = str(a_row["name"])
+                    a_sym = str(a_row["qualified_name"] or a_name)
+                    a_cid = str(a_row["canonical_id"] or "")
+                    a_file = str(a_row["path"] or "")
+                    if (
+                        _guard.allows_symbol(a_sym)
+                        and _guard.allows_symbol(a_name)
+                        and (not a_cid or _guard.allows_canonical_id(a_cid))
+                        and _guard.allows_file(a_file)
+                    ):
+                        target_symbols.add(a_name)
+                        target_symbols.add(a_sym)
+                        candidate_dicts.append(
+                            {
+                                "file": a_file,
+                                "symbol": a_name,
+                                "canonical_id": a_cid,
+                                "start_line": int(a_row["start_line"] or 1),
+                                "end_line": int(a_row["end_line"] or 1),
+                                "score": 0.90,
+                                "relationship": "DEFINES",
+                                "snippet": f"Architectural symbol {a_sym} ({a_row['kind']}) in {a_file}",
+                            }
+                        )
+                if "gateway" in task_display_str.lower():
+                    gw_rows = con.execute(
+                        "SELECT canonical_id, qualified_name, name, kind, path, start_line, end_line "
+                        "FROM symbols WHERE qualified_name LIKE '%Gateway.%'"
+                    ).fetchall()
+                    for g_row in gw_rows:
+                        g_name = str(g_row["name"])
+                        g_sym = str(g_row["qualified_name"] or g_name)
+                        g_cid = str(g_row["canonical_id"] or "")
+                        g_file = str(g_row["path"] or "")
+                        if (
+                            _guard.allows_symbol(g_sym)
+                            and _guard.allows_symbol(g_name)
+                            and (not g_cid or _guard.allows_canonical_id(g_cid))
+                            and _guard.allows_file(g_file)
+                        ):
+                            target_symbols.add(g_name)
+                            target_symbols.add(g_sym)
+                            candidate_dicts.append(
+                                {
+                                    "file": g_file,
+                                    "symbol": g_name,
+                                    "canonical_id": g_cid,
+                                    "start_line": int(g_row["start_line"] or 1),
+                                    "end_line": int(g_row["end_line"] or 1),
+                                    "score": 0.88,
+                                    "relationship": "DEFINES",
+                                    "snippet": f"Gateway method {g_sym} in {g_file}",
+                                }
+                            )
+            except Exception:
+                pass
+
+        # Seed direct methods of resolved class targets
+        for res in _target_resolutions.values():
+            cls_qname = res.qualified_name
+            if cls_qname and res.target_type.value == "CLASS":
+                try:
+                    m_rows = con.execute(
+                        "SELECT canonical_id, qualified_name, name, kind, path, start_line, end_line "
+                        "FROM symbols WHERE qualified_name LIKE ?",
+                        (f"{cls_qname}.%",),
+                    ).fetchall()
+                    for m_row in m_rows:
+                        m_name = str(m_row["name"])
+                        m_sym = str(m_row["qualified_name"] or m_name)
+                        m_cid = str(m_row["canonical_id"] or "")
+                        m_file = str(m_row["path"] or "")
+                        if (
+                            _guard.allows_symbol(m_sym)
+                            and _guard.allows_symbol(m_name)
+                            and (not m_cid or _guard.allows_canonical_id(m_cid))
+                            and _guard.allows_file(m_file)
+                        ):
+                            target_symbols.add(m_name)
+                            target_symbols.add(m_sym)
+                            candidate_dicts.append(
+                                {
+                                    "file": m_file,
+                                    "symbol": m_name,
+                                    "canonical_id": m_cid,
+                                    "start_line": int(m_row["start_line"] or 1),
+                                    "end_line": int(m_row["end_line"] or 1),
+                                    "score": 0.88,
+                                    "relationship": "DEFINES",
+                                    "snippet": f"Method {m_sym} of target class {cls_qname}",
+                                }
+                            )
+                except Exception:
+                    pass
 
         # 5. Graph exploration (callers/callees) & Tests with deterministic seeds
         t_graph_start = time.perf_counter()