java-codebase-rag 0.9.7__py3-none-any.whl → 0.10.1__py3-none-any.whl

java_codebase_rag/jrag.py

@@ -24,7 +24,9 @@ from __future__ import annotations
 
 import argparse
 import os
+import signal
 import sys
+import time
 import traceback
 from pathlib import Path
 
@@ -195,6 +197,46 @@ def _clamped_limit(args: argparse.Namespace) -> int:
     return min(raw_limit, 499)
 
 
+def _emit(env, args: argparse.Namespace, *, noun: str = "",
+          shape: str | None = None, next_offset: int | None = None) -> int:
+    """Final render+print funnel honoring ``--count`` / ``--exists`` / ``--fields``;
+    returns the exit code.
+
+    The single output seam every ok / not_found / ambiguous result routes
+    through. The shared helpers (:func:`_render_listing`, :func:`_emit_traversal`)
+    delegate their tail here; inline success render sites call it directly. True
+    usage / setup errors (missing index, kind guard, ``neighbors_v2`` failure,
+    argparse errors) bypass it — those render normally via :func:`render`, since a
+    count/exists shape would hide the actionable error message.
+
+    Exit code: ``--exists`` forces 0 when results are present and 2 otherwise
+    (resolve miss AND empty ok both count as absent), computed via
+    :func:`jrag_render.has_results` so output and exit code agree. Without
+    ``--exists``, rc follows the envelope (error -> 2, else 0); ``--count`` does
+    not gate (a zero count on an ok envelope stays exit 0).
+
+    ``getattr`` defaults keep this safe for parsers that lack the flags
+    (``_core_parser`` commands), though only ``_common_parser`` commands are
+    routed here today.
+    """
+    from java_codebase_rag.jrag_render import has_results, render
+
+    print(render(
+        env,
+        fmt=getattr(args, "format", "text"),
+        detail=getattr(args, "detail", "normal"),
+        noun=noun,
+        next_offset=next_offset,
+        shape=shape,
+        count=getattr(args, "count", False),
+        exists=getattr(args, "exists", False),
+        fields=getattr(args, "fields", None),
+    ))
+    if getattr(args, "exists", False):
+        return 0 if has_results(env, shape) else 2
+    return 2 if env.status == "error" else 0
+
+
 def _render_listing(rows, *, limit: int, args: argparse.Namespace, noun: str,
                     extra_hints: list[str] | None = None) -> int:
     """Apply +1-fetch truncation, build the envelope, render as a listing.
@@ -209,7 +251,6 @@ def _render_listing(rows, *, limit: int, args: argparse.Namespace, noun: str,
     (jobs / listeners / entities).
     """
     from java_codebase_rag.jrag_envelope import Envelope, mark_truncated, next_actions_hook, to_envelope_rows
-    from java_codebase_rag.jrag_render import render
 
     node_list = to_envelope_rows(rows) if rows and not isinstance(rows[0], dict) else list(rows)
     display_nodes_list, truncated = mark_truncated(node_list, limit)
@@ -227,8 +268,7 @@ def _render_listing(rows, *, limit: int, args: argparse.Namespace, noun: str,
                 seen.add(h)
                 env.agent_next_actions.append(h)
         env.agent_next_actions = env.agent_next_actions[:5]
-    print(render(env, fmt=args.format, detail=args.detail, noun=noun))
-    return 0
+    return _emit(env, args, noun=noun)
 
 
 def _symbol_hit_to_dict(hit) -> dict:
@@ -429,6 +469,43 @@ def build_parser() -> argparse.ArgumentParser:
                 "normal = +module/role/file/score; full = +signature/annotations/snippet."
             ),
         )
+        # Output-shaping flags (issue #376). NOT on _core_parser: status /
+        # microservices are aggregate rollups (a count there is meaningless) and
+        # vocab-index prints plain text outside the render path, so adding them
+        # there would create silently-ignored flags (violates the
+        # "inapplicable flags never silently ignored" principle).
+        common.add_argument(
+            "--count",
+            action="store_true",
+            default=False,
+            help=(
+                "Print only the result count (no rows) — bare int in text, "
+                "{\"status\",\"count\"} in json. Counts nodes (listing), edges "
+                "(traversal), or 1 (inspect)."
+            ),
+        )
+        common.add_argument(
+            "--exists",
+            action="store_true",
+            default=False,
+            help=(
+                "Print only an exists boolean (true/false, or "
+                "{\"status\",\"exists\"} in json). Exit 0 when results exist, "
+                "2 otherwise (incl. resolve miss / empty result)."
+            ),
+        )
+        common.add_argument(
+            "--fields",
+            type=str,
+            default=None,
+            metavar="LIST",
+            help=(
+                "Comma-separated node-field allowlist that overrides --detail "
+                "(e.g. fqn,role,signature). Ignored with --count/--exists; "
+                "primarily a --format json lever; text still labels rows from "
+                "whatever identity fields survive."
+            ),
+        )
         return common
 
     # Core-only parser for AGGREGATE commands (status / microservices) that have
@@ -484,7 +561,8 @@ def build_parser() -> argparse.ArgumentParser:
         parents=[_common_parser()],
         description=(
             "Find nodes by query or filter. Two modes:\n"
-            "  Query mode (positional <query>): search by exact name/FQN (symbols only).\n"
+            "  Query mode (positional <query>): search by name/FQN (symbols only); --fuzzy\n"
+            "    falls back exact -> prefix -> substring when the exact match is empty.\n"
             "  Filter mode (no positional): apply structured filters (NodeFilter flags).\n"
             "Kind inference: domain flags (--http-method, --client-kind, --producer-kind) imply\n"
             "route/client/producer when --kind is omitted. Contradiction emits an error envelope.\n"
@@ -507,6 +585,12 @@ def build_parser() -> argparse.ArgumentParser:
     find.add_argument("--framework", type=_lower_snake, choices=_FRAMEWORK_CHOICES, default=None, help="Filter by framework.")
     find.add_argument("--source-layer", type=str, default=None, help="Filter by source layer.")
     find.add_argument("--fqn-contains", type=str, default=None, help="Filter by FQN substring.")
+    find.add_argument(
+        "--fuzzy",
+        action="store_true",
+        help="Query mode: fall back from exact name/FQN to prefix then substring "
+             "(case-sensitive) when the exact match is empty.",
+    )
     find.add_argument("--http-method", type=str, default=None, help="Filter by HTTP method (route).")
     find.add_argument("--path-contains", type=str, default=None, help="Filter by path substring (route).")
     find.add_argument("--client-kind", type=str, default=None, help="Filter by client kind (client).")
@@ -1108,9 +1192,9 @@ def build_parser() -> argparse.ArgumentParser:
             "--table all searches all three. --hybrid enables vector+keyword hybrid. "
             "--offset paginates. --path-contains narrows by file path substring. "
             "Filters (NodeFilter flags) narrow results.\n\n"
-            "--fuzzy is accepted but rejected IN-HANDLER with status: error (search is "
-            "inherently semantic; --fuzzy is a no-op synonym). Registering the flag "
-            "prevents argparse from exiting 2 before the handler can produce the envelope."
+            "--fuzzy is accepted as a no-op (search is inherently semantic; "
+            "--fuzzy is implicit). It is kept registered so callers that pass "
+            "it don't hit an argparse error, and is silently ignored."
         ),
     )
     search.add_argument("query", help="Natural-language search query.")
@@ -1132,7 +1216,7 @@ def build_parser() -> argparse.ArgumentParser:
     )
     search.add_argument(
         "--fuzzy", action="store_true",
-        help="Accepted but rejected in-handler (search is semantic; --fuzzy is implicit).",
+        help="Accepted as a no-op (search is always semantic; --fuzzy is implicit).",
     )
     search.add_argument(
         "--min-score", type=float, default=0.0, dest="min_score",
@@ -1177,6 +1261,59 @@ def build_parser() -> argparse.ArgumentParser:
     )
     vocab_index.set_defaults(handler=_cmd_vocab_index, detail="full")
 
+    # ---- watch subparser (jrag watch foreground/detach/stop/status) ----
+    # Uses _core_parser (no auto-scope): watch is a long-lived daemon over a
+    # whole index, not a per-query command, so --service/--module/--limit would
+    # be dishonest on this surface. Keeps --index-dir/--format/--detail so the
+    # daemon anchors and so --status output respects --format.
+    watch = subparsers.add_parser(
+        "watch",
+        help="keep the index fresh and serve warm queries while running",
+        parents=[_core_parser()],
+        description=(
+            "Long-lived daemon: watches the source tree for changes (reindexing "
+            "vectors/graph on a debounce) and serves the read commands (search/find/"
+            "inspect/callers/callees/flow) over a warm Unix socket so queries skip the "
+            "cold-start model/graph load.\n\n"
+            "Lifecycle:\n"
+            "  jrag watch             run in the foreground (Ctrl+C / SIGTERM to stop)\n"
+            "  jrag watch --detach    start as a background daemon and return\n"
+            "  jrag watch --status    report up/down + pid + socket + last reindex\n"
+            "  jrag watch --stop      SIGTERM a running daemon (SIGKILL after 5s)\n"
+            "Only one daemon may run per index (project lock). --status/--stop do NOT "
+            "acquire the lock."
+        ),
+    )
+    watch.add_argument(
+        "--detach",
+        action="store_true",
+        help="Start the daemon as a detached background process and return.",
+    )
+    watch.add_argument(
+        "--stop",
+        action="store_true",
+        help="Stop a running daemon (SIGTERM; SIGKILL after 5s).",
+    )
+    watch.add_argument(
+        "--status",
+        action="store_true",
+        help="Print whether the daemon is up or down and exit.",
+    )
+    watch.add_argument(
+        "--debounce-ms",
+        type=int,
+        default=None,
+        dest="debounce_ms",
+        help="Reindex debounce window in ms (overrides YAML `watch:debounce_ms`).",
+    )
+    watch.add_argument(
+        "--backend",
+        choices=("auto", "watchdog", "polling"),
+        default=None,
+        help="File-watch backend (overrides YAML `watch:backend`).",
+    )
+    watch.set_defaults(handler=_cmd_watch)
+
     return parser
 
 
@@ -1204,6 +1341,11 @@ def _resolve_cfg(args: argparse.Namespace):  # type: ignore[no-untyped-def]
     cfg = resolve_operator_config(
         source_root=None,
         cli_index_dir=getattr(args, "index_dir", None),
+        # ``jrag watch`` CLI overrides for the watch block (absent / None for
+        # every other subcommand via getattr default; resolve_operator_config
+        # treats ``None`` as "not provided" so non-watch commands are unaffected).
+        cli_watch_debounce_ms=getattr(args, "debounce_ms", None),
+        cli_watch_backend=getattr(args, "backend", None),
     )
     cfg.apply_to_os_environ()
     return cfg
@@ -1265,6 +1407,269 @@ def _cmd_vocab_index(args: argparse.Namespace) -> int:
     return 0
 
 
+# ---------------------------------------------------------------------------
+# jrag watch — long-lived daemon lifecycle (foreground / --detach / --stop / --status)
+#
+# ``--status``/``--stop`` are OUT-OF-PROCESS verbs: they read the lock holder
+# (``ProjectLock.read_holder``) and never acquire the lock themselves. Only the
+# running daemon (foreground or detached) holds the lock.
+# ---------------------------------------------------------------------------
+
+
+def _watch_child_argv(extra_args: list[str]) -> list[str]:
+    """Build the argv for the detached ``jrag watch`` child process.
+
+    Invokes the daemon via ``python -m java_codebase_rag.jrag`` (NOT the
+    module's file path): running ``python src/.../jrag.py`` directly would put
+    the package directory on ``sys.path[0]`` and shadow the stdlib ``ast``
+    module with the project's ``java_codebase_rag.ast`` package (breaking
+    ``inspect``). ``-m`` runs the module as ``__main__`` within its package
+    context, so stdlib imports resolve correctly. A separate function (rather
+    than inline) so a test can swap in a stub child.
+    """
+    return [sys.executable, "-m", "java_codebase_rag.jrag", "watch"] + list(extra_args)
+
+
+def _watch_passthrough_args(args: argparse.Namespace) -> list[str]:
+    """Reconstruct the watch flags to pass through to a detached child.
+
+    Only re-emits the flags that influence the daemon's behavior; --index-dir is
+    included so the child anchors on the same index without re-discovering it.
+    """
+    out: list[str] = []
+    if getattr(args, "index_dir", None):
+        out += ["--index-dir", str(args.index_dir)]
+    if getattr(args, "debounce_ms", None) is not None:
+        out += ["--debounce-ms", str(args.debounce_ms)]
+    if getattr(args, "backend", None) is not None:
+        out += ["--backend", str(args.backend)]
+    return out
+
+
+def _cmd_watch_status(cfg) -> int:
+    """``jrag watch --status``: print up/down + pid + socket + last reindex.
+
+    Does NOT acquire the lock. Returns 0 if a daemon is alive, 1 otherwise.
+    """
+    from java_codebase_rag.watch import paths
+    from java_codebase_rag.watch.client import is_daemon_alive
+    from java_codebase_rag.watch.lock import ProjectLock
+
+    sock = paths.socket_path(cfg.index_dir)
+    alive = is_daemon_alive(cfg.index_dir)
+    pid = ProjectLock.read_holder(cfg.index_dir)
+    state = _read_state_file(cfg.index_dir)
+    if alive:
+        print(f"jrag watch: up (pid {pid}, socket {sock})")
+        if state:
+            kind = state.get("last_reindex_kind")
+            at = state.get("last_reindex_at")
+            count = state.get("reindex_count", 0)
+            if kind and at:
+                when = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(at))
+                print(f"  last reindex: {kind} at {when} (total {count})")
+            else:
+                print(f"  last reindex: none (total {count})")
+        return 0
+    print(f"jrag watch: down (no daemon at {sock})")
+    return 1
+
+
+def _cmd_watch_stop(cfg) -> int:
+    """``jrag watch --stop``: SIGTERM the daemon, SIGKILL after 5s if needed.
+
+    Polls for socket removal (the daemon's own shutdown unlinks it). Always
+    cleans a leftover socket/state so a fresh start isn't blocked by a corpse.
+    Returns 0 if a daemon was stopped, 1 if none was running.
+    """
+    from java_codebase_rag.watch import paths
+    from java_codebase_rag.watch.lock import ProjectLock
+
+    sock = paths.socket_path(cfg.index_dir)
+    state_path = paths.state_path(cfg.index_dir)
+    pid = ProjectLock.read_holder(cfg.index_dir)
+    if pid is None:
+        print("jrag watch: not running")
+        _watch_unlink(sock)
+        _watch_unlink(state_path)
+        return 1
+
+    _watch_signal(pid, signal.SIGTERM)
+    # Poll for the socket's removal (the daemon unlinks it on clean shutdown).
+    deadline = time.monotonic() + _WATCH_STOP_TIMEOUT_S
+    while time.monotonic() < deadline:
+        if not sock.exists():
+            break
+        if not _watch_pid_alive(pid):
+            break
+        time.sleep(0.05)
+    # If still alive after the timeout, escalate to SIGKILL.
+    if _watch_pid_alive(pid):
+        _watch_signal(pid, signal.SIGKILL)
+    _watch_unlink(sock)
+    _watch_unlink(state_path)
+    print(f"jrag watch: stopped (pid {pid})")
+    return 0
+
+
+def _cmd_watch_detach(args: argparse.Namespace, cfg) -> int:
+    """``jrag watch --detach``: spawn the daemon detached and wait until it serves.
+
+    ``start_new_session=True`` detaches the child from the controlling terminal
+    (setsid); stdio is redirected to a per-index log under ``paths.runtime_dir``
+    so the parent can return. Waits until ``is_daemon_alive`` (socket bound AND a
+    live holder pid) or a timeout, then prints the socket path + pid. Returns 0
+    on success, 2 on timeout / child exit.
+    """
+    import subprocess
+
+    from java_codebase_rag.watch import paths
+    from java_codebase_rag.watch.client import is_daemon_alive
+    from java_codebase_rag.watch.lock import ProjectLock
+
+    child_argv = _watch_child_argv(_watch_passthrough_args(args))
+    log_path = paths.runtime_dir() / f"jrag-watch-{paths.project_key(cfg.index_dir)}.log"
+    try:
+        log_fh = open(log_path, "ab")
+    except OSError:
+        log_fh = None
+    try:
+        proc = subprocess.Popen(
+            child_argv,
+            stdin=subprocess.DEVNULL,
+            stdout=log_fh,
+            stderr=log_fh,
+            start_new_session=True,  # setsid: detach from the controlling terminal
+            close_fds=True,
+        )
+    finally:
+        if log_fh is not None:
+            log_fh.close()
+
+    deadline = time.monotonic() + _WATCH_DETACH_TIMEOUT_S
+    child_exited = False
+    while time.monotonic() < deadline:
+        if is_daemon_alive(cfg.index_dir):
+            break
+        # Fail fast: a child that crashes on startup (model-load/import failure)
+        # should not make the parent wait the whole timeout. proc.poll() is None
+        # while the child lives; a non-None return code means it has exited.
+        if proc.poll() is not None:
+            child_exited = True
+            break
+        time.sleep(0.1)
+    if is_daemon_alive(cfg.index_dir):
+        pid = ProjectLock.read_holder(cfg.index_dir)
+        print(
+            f"jrag watch: detached (pid {pid}, socket "
+            f"{paths.socket_path(cfg.index_dir)}, log {log_path})"
+        )
+        return 0
+    if child_exited:
+        print(
+            f"jrag watch: child exited before serving (see {log_path})",
+            file=sys.stderr,
+        )
+    else:
+        print(
+            f"jrag watch: failed to start within {_WATCH_DETACH_TIMEOUT_S}s "
+            f"(see {log_path})",
+            file=sys.stderr,
+        )
+    return 2
+
+
+def _cmd_watch(args: argparse.Namespace) -> int:
+    """Dispatch ``jrag watch`` to its lifecycle verb (or the foreground daemon).
+
+    The lightweight probe verbs (``--status``/``--stop``/``--detach``) must NOT
+    import the daemon module: that import eagerly pulls torch/
+    sentence_transformers/lancedb/pyarrow (~2.5s + ~1GB), defeating their purpose.
+    ``WatchDaemon`` is therefore imported inline ONLY on the foreground path below.
+    """
+    cfg = _resolve_cfg(args)
+    if args.status:
+        return _cmd_watch_status(cfg)
+    if args.stop:
+        return _cmd_watch_stop(cfg)
+    if args.detach:
+        return _cmd_watch_detach(args, cfg)
+    # default: run the daemon in the foreground. Ends with os._exit(0) on the
+    # serving path; only the early-failure returns (lock held / model load) come
+    # back here with a non-zero int.
+    from java_codebase_rag.watch.daemon import WatchDaemon
+
+    return WatchDaemon(cfg).run_foreground()
+
+
+# Small lifecycle helpers (kept here, not in daemon.py, so --stop/--status have
+# zero coupling to the heavy daemon import path).
+
+
+def _watch_pid_alive(pid: int) -> bool:
+    """True iff ``pid`` is currently a live process (best-effort signal-0 probe)."""
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True  # exists, just not signalable by us
+    except OSError:
+        return False
+    return True
+
+
+def _watch_signal(pid: int, sig: int) -> None:
+    """Send ``sig`` to ``pid``, swallowing ProcessLookupError (already gone)."""
+    try:
+        os.kill(pid, sig)
+    except ProcessLookupError:
+        pass
+
+
+def _watch_unlink(path) -> None:
+    """Idempotent, best-effort unlink."""
+    try:
+        path.unlink()
+    except FileNotFoundError:
+        pass
+    except OSError:
+        pass
+
+
+def _read_state_file(index_dir) -> dict | None:
+    """Return the parsed daemon state JSON, or ``None`` if missing/unreadable.
+
+    Kept HERE (not in ``watch.daemon``) so ``jrag watch --status`` can read the
+    last reindex WITHOUT importing the daemon module — that import eagerly pulls
+    torch/sentence_transformers/lancedb/pyarrow (~2.5s + ~1GB). A corrupt/partial
+    file yields ``None`` rather than raising.
+    """
+    import json
+
+    from java_codebase_rag.watch import paths
+
+    path = paths.state_path(index_dir)
+    try:
+        raw = path.read_text()
+    except (FileNotFoundError, OSError):
+        return None
+    try:
+        obj = json.loads(raw)
+    except (ValueError, OSError):
+        return None
+    return obj if isinstance(obj, dict) else None
+
+
+# The daemon's shutdown (watcher.stop joins the debounce thread up to 10s, then
+# server.shutdown joins the accept thread up to 2s) is well under this on an
+# idle watcher; 5s is the brief's prescribed SIGTERM->SIGKILL grace window.
+_WATCH_STOP_TIMEOUT_S = 5.0
+# Model warm-up dominates the detach readiness window on a cold cache; generous
+# so a fresh start isn't reported as a failure while the SBERT model loads.
+_WATCH_DETACH_TIMEOUT_S = 60.0
+
+
 def _cmd_status(args: argparse.Namespace) -> int:
     from java_codebase_rag.jrag_envelope import Envelope
     from java_codebase_rag.jrag_render import render
@@ -1369,6 +1774,8 @@ def _check_kind_contradiction(args: argparse.Namespace, inferred: str | None) ->
 def _cmd_find(args: argparse.Namespace) -> int:
     from java_codebase_rag.jrag_envelope import Envelope
     from java_codebase_rag.jrag_render import render
+    from java_codebase_rag.read_payloads import PayloadError, find_payload
+    from java_codebase_rag.watch.client import get_payload
 
     cfg = _resolve_cfg(args)
     try:
@@ -1382,104 +1789,40 @@ def _cmd_find(args: argparse.Namespace) -> int:
     # auto-scope default here too (MCP parity).
     _apply_auto_scope(args, cfg, graph)
 
-    # Check kind contradiction first (before any backend work)
-    inferred = _infer_kind(args)
-    is_contradiction, error_msg = _check_kind_contradiction(args, inferred)
-    if is_contradiction:
-        env = Envelope(status="error", message=error_msg or "kind contradiction")
-        print(render(env, fmt=args.format, detail=args.detail))
-        return 2
+    # find_payload does the mode selection (query vs filter), kind-contradiction
+    # check, and the backend call (find_by_name_or_fqn + post-filters, or find_v2).
+    # Rendering (nodes/warnings/empty-result hint/offset) is split into the two
+    # render helpers below, branch by payload["mode"].
+    try:
+        payload = get_payload("find", vars(args), cfg, cold_core=find_payload)
+    except PayloadError as pe:
+        print(render(pe.env, fmt=args.format, detail=args.detail))
+        return pe.rc
 
-    # Cap at 499 so limit+1 <= 500 (backend clamp)
-    # If args.limit is None, default to 20 (from argparse)
-    raw_limit = args.limit if args.limit is not None else 20
-    limit = min(raw_limit, 499)
-
-    # Query mode: positional <query> present
-    if args.query:
-        # find_by_name_or_fqn is Symbol-only (MATCH (s:Symbol) WHERE s.name=$needle
-        # OR s.fqn=$needle). A positional <query> with a non-symbol kind (explicit
-        # OR inferred from --http-method/--client-kind/--producer-kind/etc.) is a
-        # usage contract violation -> status: error envelope (NOT argparse exit),
-        # telling the user to drop the positional and use filter mode.
-        effective_kind = inferred or "symbol"
-        if effective_kind != "symbol":
-            env = Envelope(
-                status="error",
-                message=(
-                    f"query mode (positional <query>) only searches Symbols, but kind "
-                    f"'{effective_kind}' was {'inferred from domain flags' if args.kind is None else 'set via --kind'}. "
-                    "Drop the positional <query> and use filter mode (the domain flags) "
-                    "for route/client/producer searches."
-                ),
-            )
-            print(render(env, fmt=args.format, detail=args.detail))
-            return 2
-        return _cmd_find_query_mode(args, cfg, graph, limit)
+    if payload["mode"] == "query":
+        return _render_find_query(args, payload)
+    return _render_find_filter(args, payload)
 
-    # Filter mode: build NodeFilter and call find_v2
-    return _cmd_find_filter_mode(args, cfg, graph, inferred or "symbol", limit)
 
+def _render_find_query(args: argparse.Namespace, payload) -> int:
+    """Render find query-mode payload (rows from find_by_name_or_fqn + post-filters).
 
-def _cmd_find_query_mode(
-    args: argparse.Namespace,
-    cfg,
-    graph,
-    limit: int,
-) -> int:
-    """Find query mode: g.find_by_name_or_fqn (Symbol-only, exact name/FQN match).
-
-    ``find_by_name_or_fqn`` runs ``MATCH (s:Symbol) WHERE s.name=$needle OR
-    s.fqn=$needle`` — Symbol-only, exact-only. There is no fuzzy/prefix/contains
-    path; ``--fuzzy`` was deferred (see plans/active/PLAN-JRAG-CLI.md Out of
-    scope). Query mode is gated to ``effective_kind == "symbol"`` upstream in
-    ``_cmd_find``, so the only ``kinds`` filter we may pass is symbol sub-kinds
-    derived from ``--java-kind``.
+    The backend call + post-filters live in ``read_payloads.find_payload``; this
+    builds the envelope node dicts, warnings, and empty-result hint, then renders.
+    With ``--fuzzy``, ``find_payload`` widens an empty exact result to prefix then
+    substring (issue #375) and reports the matched tier via ``payload["matched_mode"]``
+    (exact/prefix/contains) plus ``payload["identifier_matched"]`` for the hint.
     """
-    from java_codebase_rag.jrag_envelope import Envelope, next_actions_hook, normalize_enum
+    from java_codebase_rag.jrag_envelope import Envelope, next_actions_hook
     from java_codebase_rag.jrag_render import render
 
-    query = args.query
-
-    # find_by_name_or_fqn is always Symbol; the only valid kinds filter is the
-    # symbol sub-kind derived from --java-kind (lowercase, matching s.kind).
-    # route/client/producer kinds were removed: they would never match Symbols.
-    if args.java_kind:
-        java_kind_norm = normalize_enum(args.java_kind, kind="java_kind")
-        kinds = [java_kind_norm.lower()]
-    else:
-        kinds = None
-
-    # Call find_by_name_or_fqn (exact name OR fqn match).
-    rows = graph.find_by_name_or_fqn(
-        query,
-        kinds=kinds,
-        module=args.module,
-        microservice=args.service,
-        limit=limit + 1,  # +1 for truncated detection
-    )
-    # Truncation is decided by the RAW name/FQN fetch (limit+1), BEFORE
-    # post-filters reduce the set — otherwise a post-filter that drops rows
-    # would silently clear `truncated` even though more name matches may exist
-    # beyond the fetch (silent wrong-results).
-    raw_truncated = len(rows) > limit
-
-    # Post-filter by role/annotation/capability (SymbolHit carries these).
-    post_filter_active = False
-    if args.role:
-        post_filter_active = True
-        role_norm = normalize_enum(args.role, kind="role")
-        rows = [r for r in rows if (r.role or "").upper().replace("-", "_") == role_norm.upper()]
-    if args.exclude_role:
-        post_filter_active = True
-        exclude_role_norm = normalize_enum(args.exclude_role, kind="role")
-        rows = [r for r in rows if (r.role or "").upper().replace("-", "_") != exclude_role_norm.upper()]
-    if args.annotation:
-        post_filter_active = True
-        rows = [r for r in rows if args.annotation in (r.annotations or [])]
-    if args.capability:
-        post_filter_active = True
-        rows = [r for r in rows if args.capability in (r.capabilities or [])]
+    rows = payload["rows"]
+    raw_truncated = payload["raw_truncated"]
+    post_filter_active = payload["post_filter_active"]
+    limit = payload["limit"]
+    query = payload["query"]
+    matched_mode = payload["matched_mode"]
+    identifier_matched = payload["identifier_matched"]
 
     # Build warnings for filters that cannot apply in query mode. SymbolHit
     # carries no framework/source_layer fields; rather than silently dropping
@@ -1504,6 +1847,12 @@ def _cmd_find_query_mode(
 
     # Display at most `limit` of the (post-filtered) rows.
     display_rows = rows[:limit]
+    # Map internal mode -> user-facing term (help/empty-hint say "substring").
+    mode_label = "substring" if matched_mode == "contains" else matched_mode
+    if matched_mode != "exact" and display_rows:
+        warnings.append(
+            f"no exact name/FQN match; --fuzzy matched via {mode_label}"
+        )
     nodes = {}
     for row in display_rows:
         node_id = row.id
@@ -1539,21 +1888,29 @@ def _cmd_find_query_mode(
     )
     next_actions_hook(env)
 
-    # Empty-result discoverability: query mode is exact-match only (name OR fqn),
-    # so a partial like `find ChatManagement` legitimately returns 0. Surface a
-    # cross-ref so the agent knows the substring fallback exists instead of
-    # seeing a bare `0 symbol`. Carried as both a `message` (renders inline) and
-    # an `agent_next_action` (renders as `next:` / JSON). A literal FQN-shaped
-    # query (contains '.') almost certainly won't substring-match either, so the
-    # hint applies regardless of shape.
+    # Empty-result discoverability: a partial like `find ChatManag` returns 0
+    # under exact match. Three cases: (1) some tier matched the identifier but
+    # --role/--exclude-role/--annotation/--capability removed every hit — blame
+    # the filter, not the query; (2) --fuzzy widened to prefix/substring and
+    # still found nothing; (3) no --fuzzy, so suggest it. Carried as `message`
+    # (inline) + `agent_next_actions` (`next:`/JSON).
     if not nodes and query:
-        hint = f"no exact match for {query!r} — try `jrag find --fqn-contains {query}` for substring"
+        if identifier_matched and post_filter_active:
+            hint = (
+                f"matched {query!r} (via {mode_label}), but "
+                "--role/--exclude-role/--annotation/--capability removed all hits"
+            )
+        elif getattr(args, "fuzzy", False):
+            hint = f"no match for {query!r} (tried exact, prefix, substring)"
+            env.agent_next_actions = [f"jrag find --fqn-contains {query}"]
+        else:
+            hint = f"no exact match for {query!r} — try `jrag find {query} --fuzzy`"
+            env.agent_next_actions = [f"jrag find {query} --fuzzy"]
         env.message = hint
-        env.agent_next_actions = [f"jrag find --fqn-contains {query}"]
 
     # Offset is not supported in query mode (find_by_name_or_fqn has no offset).
-    print(render(env, fmt=args.format, detail=args.detail, noun="symbol"))
-    return 0
+    return _emit(env, args, noun="symbol")
+
 
 
 def _build_node_filter_or_error(filter_dict: dict):
@@ -1583,69 +1940,20 @@ def _build_node_filter_or_error(filter_dict: dict):
         return None, Envelope(status="error", message=f"invalid filter: {message}")
 
 
-def _cmd_find_filter_mode(
-    args: argparse.Namespace,
-    cfg,
-    graph,
-    kind: str,
-    limit: int,
-) -> int:
-    """Find filter mode: build NodeFilter and call find_v2."""
-    from java_codebase_rag.mcp import mcp_v2
+def _render_find_filter(args: argparse.Namespace, payload) -> int:
+    """Render find filter-mode payload (a FindOutput from find_v2).
 
-    from java_codebase_rag.jrag_envelope import Envelope, next_actions_hook, normalize_enum, to_envelope_rows
+    The backend call + NodeFilter construction live in
+    ``read_payloads.find_payload``; this slices to the limit, builds the envelope
+    node dicts, and renders — verbatim from the original
+    ``_cmd_find_filter_mode`` render portion.
+    """
+    from java_codebase_rag.jrag_envelope import Envelope, next_actions_hook, to_envelope_rows
     from java_codebase_rag.jrag_render import render
 
-    # Build NodeFilter from args
-    filter_dict: dict = {}
-    if args.service:
-        filter_dict["microservice"] = args.service
-    if args.module:
-        filter_dict["module"] = args.module
-    if args.role:
-        filter_dict["role"] = normalize_enum(args.role, kind="role")
-    if args.exclude_role:
-        filter_dict["exclude_roles"] = [normalize_enum(args.exclude_role, kind="role")]
-    if args.annotation:
-        filter_dict["annotation"] = args.annotation
-    if args.capability:
-        filter_dict["capability"] = args.capability
-    if args.fqn_contains:
-        filter_dict["fqn_contains"] = args.fqn_contains
-    if args.java_kind:
-        filter_dict["symbol_kind"] = normalize_enum(args.java_kind, kind="java_kind")
-    if args.framework:
-        filter_dict["framework"] = normalize_enum(args.framework, kind="framework")
-    if args.source_layer:
-        filter_dict["source_layer"] = normalize_enum(args.source_layer, kind="source_layer")
-    if args.http_method:
-        filter_dict["http_method"] = args.http_method.upper()
-    if args.path_contains:
-        filter_dict["path_contains"] = args.path_contains
-    if args.client_kind:
-        filter_dict["client_kind"] = normalize_enum(args.client_kind, kind="client_kind")
-    if args.calls_service:
-        filter_dict["target_service"] = args.calls_service
-    if args.calls_path_contains:
-        filter_dict["target_path_contains"] = args.calls_path_contains
-    if args.producer_kind:
-        filter_dict["producer_kind"] = normalize_enum(args.producer_kind, kind="producer_kind")
-    if args.topic_contains:
-        filter_dict["topic_contains"] = args.topic_contains
-
-    node_filter, err_env = _build_node_filter_or_error(filter_dict)
-    if err_env is not None:
-        print(render(err_env, fmt=args.format, detail=args.detail))
-        return 2
-
-    # Call find_v2
-    out = mcp_v2.find_v2(
-        kind=kind,
-        filter=node_filter,
-        limit=limit + 1,  # +1 for has_more_results detection
-        offset=args.offset,
-        graph=graph,
-    )
+    out = payload["out"]
+    kind = payload["kind"]
+    limit = payload["limit"]
 
     if not out.success:
         env = Envelope(status="error", message=out.message)
@@ -1669,14 +1977,12 @@ def _cmd_find_filter_mode(
 
     # Render with offset hint if truncated
     next_offset = args.offset + limit if truncated else None
-    print(render(env, fmt=args.format, detail=args.detail, noun=kind, next_offset=next_offset))
-    return 0
+    return _emit(env, args, noun=kind, next_offset=next_offset)
 
 
-def _cmd_inspect(args: argparse.Namespace) -> int:
-    from java_codebase_rag.mcp import mcp_v2
 
-    from java_codebase_rag.jrag_envelope import Envelope, next_actions_hook, resolve_query
+def _cmd_inspect(args: argparse.Namespace) -> int:
+    from java_codebase_rag.jrag_envelope import Envelope, next_actions_hook
     from java_codebase_rag.jrag_render import render
 
     cfg = _resolve_cfg(args)
@@ -1687,28 +1993,22 @@ def _cmd_inspect(args: argparse.Namespace) -> int:
         print(render(env, fmt=args.format, detail=args.detail))
         return 2
 
-    # Resolve the query. Forward --service/--module so an ambiguous name
-    # (same name across services) disambiguates by microservice/module, the
-    # same way find and the traversal commands do. Without this, inspect
-    # silently ignored these inherited flags (resolve_query accepts them).
-    node, env = resolve_query(
-        args.query,
-        hint_kind=args.kind,
-        java_kind=args.java_kind,
-        role=args.role,
-        fqn_contains=args.fqn_contains,
-        cfg=cfg,
-        graph=graph,
-        microservice=args.service or "",
-        module=args.module or "",
-    )
-
-    if env.status != "ok":
-        print(render(env, fmt=args.format, detail=args.detail))
-        return 2 if env.status == "error" else 0
+    # inspect_payload resolves the query (forwarding --service/--module, same as
+    # before) and calls describe_v2. It returns the DescribeOutput plus the
+    # resolve-derived node id/fqn and file_location the flatten+render below
+    # needs (file_location lives on the resolve Envelope, not on DescribeOutput).
+    # On resolve failure it raises PayloadError carrying that Envelope + rc.
+    from java_codebase_rag.read_payloads import PayloadError, inspect_payload
+    from java_codebase_rag.watch.client import get_payload
 
-    # Node resolved successfully - call describe_v2
-    desc_out = mcp_v2.describe_v2(id=node.id, graph=graph)
+    try:
+        payload = get_payload("inspect", vars(args), cfg, cold_core=inspect_payload)
+    except PayloadError as pe:
+        # Resolve-miss: route through _emit so --exists/--count shape it
+        # (inspect Missing --exists -> false, rc 2), mirroring master's inspect
+        # resolve-miss path. No flag -> rc matches the prior 2-if-error-else-0.
+        return _emit(pe.env, args)
+    desc_out = payload["describe"]
 
     if not desc_out.success or desc_out.record is None:
         env = Envelope(status="error", message=desc_out.message or "describe failed")
@@ -1736,11 +2036,11 @@ def _cmd_inspect(args: argparse.Namespace) -> int:
     # renamed ``symbol_kind`` to match find/search/listings (which use
     # ``symbol_kind`` for the sub-kind and reserve ``kind`` for the category).
     record_dict = desc_out.record.model_dump()
-    node_id = record_dict.get("id") or node.id
+    node_id = record_dict.get("id") or payload["node_id"]
     data = record_dict.get("data") or {}
     flat: dict[str, Any] = {
         "kind": record_dict.get("kind") or "symbol",
-        "fqn": record_dict.get("fqn") or data.get("fqn") or node.fqn,
+        "fqn": record_dict.get("fqn") or data.get("fqn") or payload["node_fqn"],
     }
     # Promote inner data fields. Skip ``kind`` here — renamed to symbol_kind.
     for src_key, dest_key in (
@@ -1772,13 +2072,12 @@ def _cmd_inspect(args: argparse.Namespace) -> int:
         status="ok",
         nodes={node_id: flat},
         root=node_id,
-        file_location=env.file_location,  # Preserve file_location from resolve
+        file_location=payload["file_location"],  # Preserve file_location from resolve
     )
     next_actions_hook(env, root=node_id, edge_summary=record_dict.get("edge_summary"))
 
     # Render with inspect shape
-    print(render(env, fmt=args.format, detail=args.detail, shape="inspect"))
-    return 0
+    return _emit(env, args, shape="inspect")
 
 
 def _backfill_service_from_filename(row: dict) -> None:
@@ -1874,9 +2173,45 @@ def _cmd_producers(args: argparse.Namespace) -> int:
     return _render_listing(rows, limit=limit, args=args, noun="producer")
 
 
+def _producer_summary(producer: dict) -> dict:
+    """Display-oriented producer dict for the ``topics`` grouping.
+
+    The raw ``list_producers`` row carries 11 fields (incl. empty ``broker``,
+    raw ``filename``/``start_line``/``end_line``, ``direction``, ``source_layer``)
+    which the text renderer used to collapse into one unreadable comma-line.
+    This folds location into a single ``file`` and keeps only the fields an
+    operator needs to identify the producer under a topic header (the topic
+    itself is the group header, so it's dropped here). Empty values omitted.
+    """
+    member_fqn = str(producer.get("member_fqn") or "")
+    member_simple = member_fqn.rsplit(".", 1)[-1] if member_fqn else ""
+    filename = str(producer.get("filename") or "")
+    start_line = producer.get("start_line")
+    try:
+        sl = int(start_line) if start_line not in (None, "") else None
+    except (TypeError, ValueError):
+        sl = None
+    file_loc = f"{filename}:{sl}" if filename and sl else filename
+    out: dict = {}
+    if member_simple:
+        out["member"] = member_simple
+    if file_loc:
+        out["file"] = file_loc
+    # ``direction`` is intentionally omitted: every Producer is built with
+    # direction="producer" (build_ast_graph), so it's a constant that only
+    # inflates each block with zero information.
+    for k in ("microservice", "module", "producer_kind", "broker"):
+        v = producer.get(k)
+        if v not in (None, "", []):
+            out[k] = v
+    resolved = producer.get("resolved")
+    if resolved is not None:
+        out["resolved"] = bool(resolved)
+    return out
+
+
 def _cmd_topics(args: argparse.Namespace) -> int:
     from java_codebase_rag.jrag_envelope import Envelope, mark_truncated, next_actions_hook
-    from java_codebase_rag.jrag_render import render
 
     _, graph, rc = _load_graph_or_error(args)
     if rc:
@@ -1908,7 +2243,7 @@ def _cmd_topics(args: argparse.Namespace) -> int:
                 "producers": [],
                 "broker": producer.get("broker") or "",
             }
-        topics_dict[topic]["producers"].append(producer)
+        topics_dict[topic]["producers"].append(_producer_summary(producer))
 
     warnings: list[str] = []
     if no_topic_count:
@@ -1956,8 +2291,7 @@ def _cmd_topics(args: argparse.Namespace) -> int:
         warnings=warnings + _auto_scope_notice(args),
     )
     next_actions_hook(env, command=getattr(args, "command", None))
-    print(render(env, fmt=args.format, detail=args.detail, noun="topic"))
-    return 0
+    return _emit(env, args, noun="topic")
 
 
 def _inspect_hints_for_rows(rows: list[dict], *, limit: int = 2) -> list[str]:
@@ -2160,7 +2494,6 @@ def _resolve_traversal_node(
     resolves for the cross-service route-caller flow.
     """
     from java_codebase_rag.jrag_envelope import resolve_query
-    from java_codebase_rag.jrag_render import render
 
     node, env = resolve_query(
         args.query,
@@ -2174,8 +2507,10 @@ def _resolve_traversal_node(
         module=(getattr(args, "module", None) or "") if apply_scope else "",
     )
     if env.status != "ok":
-        print(render(env, fmt=args.format, detail=args.detail))
-        return None, env, 2 if env.status == "error" else 0
+        # Route through _emit so --exists/--count shape a resolve miss (e.g.
+        # `callers Missing --exists` -> false, rc 2) instead of rendering the
+        # not_found body. rc matches the prior 2-if-error-else-0 when no flag.
+        return None, env, _emit(env, args)
     return node, env, 0
 
 
@@ -2235,7 +2570,6 @@ def _emit_traversal(
     ``jrag implementations <fqn>``).
     """
     from java_codebase_rag.jrag_envelope import Envelope, next_actions_hook
-    from java_codebase_rag.jrag_render import render
 
     env = Envelope(
         status="ok",
@@ -2254,8 +2588,7 @@ def _emit_traversal(
                 seen.add(h)
                 env.agent_next_actions.append(h)
         env.agent_next_actions = env.agent_next_actions[:5]
-    print(render(env, fmt=args.format, detail=args.detail, noun=noun))
-    return 0
+    return _emit(env, args, noun=noun)
 
 
 def _require_kind(
@@ -2388,161 +2721,20 @@ def _cmd_callers(args: argparse.Namespace) -> int:
     cfg, graph, rc = _load_graph_or_error(args)
     if rc:
         return rc
-    node, _renv, rrc = _resolve_traversal_node(
-        args, cfg=cfg, graph=graph, hint_kind=args.kind, apply_scope=True
-    )
-    if rrc or node is None:
-        return rrc
-    limit = _clamped_limit(args)
-
-    root_dict = _noderef_to_node_dict(node)
-    root_id = node.id
-
-    # Route root -> find_route_callers. Route callers are inherently cross-
-    # service (a Client in microservice A calls a server Route in microservice B),
-    # so --service is NOT applied as a caller-microservice post-filter here;
-    # it has already narrowed resolve (which route was selected) via
-    # _resolve_traversal_node -> resolve_query.
-    if node.kind == "route":
-        route_callers = graph.find_route_callers(route_id=root_id)
-        warnings: list[str] = []
-        # No backend limit on find_route_callers; client-side slice for truncation.
-        truncated = len(route_callers) > limit
-        display = route_callers[:limit]
-        nodes: dict[str, dict] = {}
-        edges: list[dict] = []
-        for rc in display:
-            caller_id = rc.caller_node_id
-            if rc.caller_node_kind == "client":
-                edge_type = "HTTP_CALLS"
-            else:
-                edge_type = "ASYNC_CALLS"
-            # The caller's identity is the declaring Symbol (the method that owns
-            # the Client/Producer), not the call-site path — mirrors
-            # trace_request_flow, which surfaces declaring_symbol_fqn. The
-            # path/topic the caller hits is kept as raw_uri/topic so the agent
-            # sees both WHO calls and WHAT they hit.
-            node = {
-                "id": caller_id,
-                "kind": rc.caller_node_kind,
-                "fqn": rc.declaring_symbol_fqn or caller_id,
-                "microservice": rc.caller_microservice,
-            }
-            if rc.target_service:
-                node["target_service"] = rc.target_service
-            if rc.caller_node_kind == "client" and rc.raw_uri:
-                node["raw_uri"] = rc.raw_uri
-            elif rc.caller_node_kind != "client" and rc.topic:
-                node["topic"] = rc.topic
-            nodes[caller_id] = node
-            edges.append(
-                {"other_id": caller_id, "edge_type": edge_type, "confidence": rc.confidence}
-            )
-        # Include the root (Route) node so the zero-callers rendering surfaces
-        # the route path rather than a bare "0 callers" line.
-        nodes[root_id] = root_dict
-        # External-entrypoint detection: a server-exposed HTTP route (kind
-        # http_endpoint with an inbound EXPOSES edge from a controller Symbol)
-        # genuinely has zero in-repo callers — the route IS the entrypoint. Flag
-        # it so the renderer says so instead of emitting a bug-looking bare
-        # "0 callers". NodeRef.kind is the node label ("route"), not the stored
-        # http_endpoint/kafka_topic property, so fetch the property directly.
-        # Kafka topics are excluded: their empty-callers case has different
-        # semantics (a topic with no producers is not an HTTP entrypoint).
-        is_external_entrypoint = False
-        if not display:
-            kind_row = graph._rows(  # noqa: SLF001 - same pattern as jrag_envelope._node_file_location
-                "MATCH (r:Route) WHERE r.id = $rid RETURN r.kind AS kind LIMIT 1",
-                {"rid": root_id},
-            )
-            route_kind = str(kind_row[0].get("kind") or "") if kind_row else ""
-            if route_kind == "http_endpoint" and graph.find_route_handlers(route_id=root_id):
-                is_external_entrypoint = True
-        return _emit_traversal(
-            args, root_id=root_id, nodes=nodes, edges=edges,
-            noun="callers", warnings=warnings, truncated=truncated,
-            is_external_entrypoint=is_external_entrypoint,
-        )
-
-    # Symbol root -> find_callers (push down --service/--module/depth/etc.).
-    if node.kind != "symbol":
-        from java_codebase_rag.jrag_envelope import Envelope
-        from java_codebase_rag.jrag_render import render
-
-        env = Envelope(
-            status="error",
-            message=(
-                f"callers expects a Symbol or Route root; resolved node kind is "
-                f"{node.kind!r}. Use --kind to narrow resolve."
-            ),
-        )
-        print(render(env, fmt=args.format, detail=args.detail))
-        return 2
+    from java_codebase_rag.read_payloads import PayloadError, callers_payload
+    from java_codebase_rag.watch.client import get_payload
 
-    depth = getattr(args, "depth", 1)
-    min_conf = getattr(args, "min_confidence", 0.0)
-    exclude_external = not getattr(args, "include_external", False)
-    call_edges = graph.find_callers(
-        node.fqn,
-        depth=depth,
-        limit=limit + 1,
-        min_confidence=min_conf,
-        exclude_external=exclude_external,
-        module=args.module,
-        microservice=args.service,
-    )
-    from java_codebase_rag.jrag_envelope import mark_truncated
-
-    display, truncated = mark_truncated(call_edges, limit)
-    nodes = {}
-    edges = []
-    for ce in display:
-        nodes[ce.src.id] = _symbol_hit_to_dict(ce.src)
-        edges.append(
-            {"other_id": ce.src.id, "edge_type": "CALLS", "confidence": ce.confidence}
-        )
-    # Entry-point awareness. A controller / messaging-listener type is invoked
-    # via the routes its methods EXPOSE (Controller -[:DECLARES]-> method
-    # -[:EXPOSES]-> Route), NOT via in-repo CALLS edges — so find_callers is
-    # typically empty for HTTP handlers. Without this fold, `callers
-    # <Controller>` returns a bug-looking empty list when the controller is the
-    # very thing the agent is investigating. The routes ARE its inbound callers,
-    # so surface them as additional EXPOSES rows alongside any CALLS-in edges.
-    # Gated on having DECLARES.EXPOSES out-edges (covers any entry-point holder,
-    # not just role=CONTROLLER). Routes are additive and usually few, so they do
-    # not count against the CALLS --limit (cf. the callees client/producer path,
-    # which likewise emits its own targets without sharing the CALLS budget).
-    expose_rows = graph._rows(  # noqa: SLF001 - one-shot aggregation, cf. _cmd_callees client path
-        "MATCH (t:Symbol {id: $tid})-[:DECLARES]->(m:Symbol)-[e:EXPOSES]->(r:Route) "
-        "RETURN r.id AS rid, r.method AS rmethod, r.path AS rpath, "
-        "r.path_template AS rpt, r.microservice AS rms, "
-        "m.fqn AS via_fqn, e.confidence AS conf",
-        {"tid": root_id},
-    )
-    for row in expose_rows:
-        rid = str(row.get("rid") or "")
-        if not rid or rid in nodes:
-            continue
-        rmethod = str(row.get("rmethod") or "")
-        rpath = str(row.get("rpt") or row.get("rpath") or "")
-        nodes[rid] = {
-            "id": rid,
-            "kind": "route",
-            "fqn": f"{rmethod} {rpath}".strip(),
-            "method": rmethod,
-            "path": rpath,
-            "microservice": str(row.get("rms") or ""),
-        }
-        edge_row: dict = {"other_id": rid, "edge_type": "EXPOSES"}
-        via_fqn = str(row.get("via_fqn") or "")
-        if via_fqn:
-            # Declaring method that exposes the route; rendered at --detail full.
-            edge_row["from_fqn"] = via_fqn
-        edges.append(edge_row)
-    nodes[root_id] = root_dict
+    try:
+        payload = get_payload("callers", vars(args), cfg, cold_core=callers_payload)
+    except PayloadError as pe:
+        # Resolve-miss: route through _emit so --exists/--count shape it
+        # (callers Missing --exists -> false, rc 2), mirroring master's
+        # _resolve_traversal_node resolve-miss path.
+        return _emit(pe.env, args)
     return _emit_traversal(
-        args, root_id=root_id, nodes=nodes, edges=edges,
-        noun="callers", truncated=truncated,
+        args, root_id=payload["root_id"], nodes=payload["nodes"], edges=payload["edges"],
+        noun=payload["noun"], warnings=payload["warnings"], truncated=payload["truncated"],
+        is_external_entrypoint=payload["is_external_entrypoint"],
     )
 
 
@@ -2550,165 +2742,24 @@ def _cmd_callees(args: argparse.Namespace) -> int:
     cfg, graph, rc = _load_graph_or_error(args)
     if rc:
         return rc
-    node, _renv, rrc = _resolve_traversal_node(args, cfg=cfg, graph=graph, hint_kind=args.kind)
-    if rrc or node is None:
-        return rrc
-    limit = _clamped_limit(args)
+    from java_codebase_rag.read_payloads import PayloadError, callees_payload
+    from java_codebase_rag.watch.client import get_payload
 
-    # PR-JRAG-3b: accept Symbol (CALLS), Client (HTTP_CALLS), and Producer
-    # (ASYNC_CALLS) roots. The Symbol path is unchanged from PR-JRAG-3a.
-    guard = _require_kind(
-        node,
-        expected="callees expects a Symbol, Client, or Producer root",
-        kinds=("symbol", "client", "producer"),
-        args=args,
-        hint="Use --kind to narrow resolve.",
-    )
-    if guard is not None:
-        return guard
-
-    from java_codebase_rag.jrag_envelope import Envelope, mark_truncated
-    from java_codebase_rag.jrag_render import render
-
-    # Client root -> HTTP_CALLS out (Client -> :Route).
-    # Producer root -> ASYNC_CALLS out (Producer -> :Route, the kafka_topic
-    # Route this producer publishes to — NOT a :Producer node).
-    if node.kind in ("client", "producer"):
-        from java_codebase_rag.mcp import mcp_v2
-
-        edge_types = ["HTTP_CALLS"] if node.kind == "client" else ["ASYNC_CALLS"]
-        out = mcp_v2.neighbors_v2(
-            [node.id], direction="out", edge_types=edge_types,
-            limit=limit + 1, graph=graph,
-        )
-        if not out.success:
-            print(render(Envelope(status="error", message=out.message or "neighbors_v2 failed"), fmt=args.format, detail=args.detail))
-            return 2
-        root_id = node.id
-        nodes: dict[str, dict] = {root_id: _noderef_to_node_dict(node)}
-        edges: list[dict] = []
-        for e in out.results:
-            nodes[e.other.id] = _noderef_to_node_dict(e.other)
-            edges.append(
-                {
-                    "other_id": e.other.id,
-                    "edge_type": e.edge_type,
-                    "confidence": e.attrs.get("confidence"),
-                }
-            )
-        truncated = bool(out.has_more_results) or len(edges) > limit
-        if len(edges) > limit:
-            edges = edges[:limit]
-        # --include-external is accepted but does not apply on Client/Producer
-        # roots (the edges are to :Route, which is always in-graph; there is no
-        # external-exclusion analog). Surface as a warning so the flag is not
-        # silently dropped (plan principle: inapplicable flags never silently ignored).
-        warnings: list[str] = []
-        if getattr(args, "include_external", False):
-            warnings.append(
-                "--include-external does not apply to Client/Producer roots "
-                "(HTTP_CALLS/ASYNC_CALLS reach :Route, which is always in-graph)"
-            )
-        edges = _dedupe_traversal_edges(edges)
-        truncated = truncated or len(edges) > limit
-        edges = edges[:limit]
-        return _emit_traversal(
-            args, root_id=root_id, nodes=nodes, edges=edges,
-            noun="callees", warnings=warnings, truncated=truncated,
-        )
-
-    depth = getattr(args, "depth", 1)
-    min_conf = getattr(args, "min_confidence", 0.0)
-    exclude_external = not getattr(args, "include_external", False)
-    # CLIENT-role type Symbol (e.g. a Feign client interface): its "callees" are
-    # the outbound HTTP endpoints its declared client methods call, NOT CALLS
-    # edges from the interface (a Feign interface declares methods but its
-    # methods' HTTP_CALLS edges carry the real outbound surface). Aggregate the
-    # declared Client nodes and their HTTP_CALLS targets so `jrag callees
-    # 'ChatCoreFeignClient'` shows the routes it hits.
-    if (node.role or "") == "CLIENT":
-        root_id = node.id
-        client_rows = graph._rows(  # noqa: SLF001 - one-shot aggregation query
-            "MATCH (iface:Symbol {id: $sid})-[:DECLARES]->(m:Symbol)"
-            "-[:DECLARES_CLIENT]->(c:Client) "
-            "OPTIONAL MATCH (c)-[e:HTTP_CALLS]->(r:Route) "
-            "RETURN c.id AS cid, c.member_fqn AS cfqn, c.path AS cpath, "
-            "c.method AS cmethod, c.microservice AS cms, "
-            "r.id AS rid, r.method AS rmethod, r.path AS rpath, "
-            "r.path_template AS rpt, r.microservice AS rms, "
-            "e.confidence AS conf",
-            {"sid": root_id},
-        )
-        nodes = {root_id: _noderef_to_node_dict(node)}
-        edges: list[dict] = []
-        for row in client_rows:
-            rid = str(row.get("rid") or "")
-            if rid:
-                target_id = rid
-                rmethod = str(row.get("rmethod") or "")
-                rpath = str(row.get("rpt") or row.get("rpath") or "")
-                nodes[target_id] = {
-                    "id": target_id,
-                    "kind": "route",
-                    "fqn": f"{rmethod} {rpath}".strip(),
-                    "microservice": str(row.get("rms") or ""),
-                }
-                edge_type = "HTTP_CALLS"
-            else:
-                # Client with no resolved HTTP_CALLS edge: surface the client
-                # node + its declared path so the outbound intent is visible.
-                target_id = str(row.get("cid") or "")
-                if not target_id:
-                    continue
-                cmethod = str(row.get("cmethod") or "")
-                cpath = str(row.get("cpath") or "")
-                nodes[target_id] = {
-                    "id": target_id,
-                    "kind": "client",
-                    "fqn": f"{cmethod} {cpath}".strip() or str(row.get("cfqn") or ""),
-                    "microservice": str(row.get("cms") or ""),
-                }
-                edge_type = "HTTP_CALLS"
-            edges.append({
-                "other_id": target_id,
-                "edge_type": edge_type,
-                "confidence": float(row.get("conf") or 0.0) or None,
-            })
-        edges = _dedupe_traversal_edges(edges)
-        truncated = len(edges) > limit
-        edges = edges[:limit]
-        return _emit_traversal(
-            args, root_id=root_id, nodes=nodes, edges=edges,
-            noun="callees", truncated=truncated,
-        )
-
-    call_edges = graph.find_callees(
-        node.fqn,
-        depth=depth,
-        limit=limit + 1,
-        min_confidence=min_conf,
-        exclude_external=exclude_external,
-        module=args.module,
-        microservice=args.service,
-    )
-    display, truncated = mark_truncated(call_edges, limit)
-    root_id = node.id
-    nodes = {root_id: _noderef_to_node_dict(node)}
-    edges = []
-    for ce in display:
-        nodes[ce.dst.id] = _symbol_hit_to_dict(ce.dst)
-        edges.append(
-            {"other_id": ce.dst.id, "edge_type": "CALLS", "confidence": ce.confidence}
-        )
-    edges = _dedupe_traversal_edges(edges)
-    truncated = truncated or len(edges) > limit
-    edges = edges[:limit]
+    try:
+        payload = get_payload("callees", vars(args), cfg, cold_core=callees_payload)
+    except PayloadError as pe:
+        # Resolve-miss: route through _emit so --exists/--count shape it
+        # (callees Missing --exists -> false, rc 2), mirroring master's
+        # _resolve_traversal_node resolve-miss path.
+        return _emit(pe.env, args)
     return _emit_traversal(
-        args, root_id=root_id, nodes=nodes, edges=edges,
-        noun="callees", truncated=truncated,
+        args, root_id=payload["root_id"], nodes=payload["nodes"], edges=payload["edges"],
+        noun=payload["noun"], warnings=payload["warnings"], truncated=payload["truncated"],
+        is_external_entrypoint=payload["is_external_entrypoint"],
     )
 
 
+
 def _cmd_hierarchy(args: argparse.Namespace) -> int:
     from java_codebase_rag.mcp import mcp_v2
 
@@ -3135,93 +3186,23 @@ def _cmd_flow(args: argparse.Namespace) -> int:
     cfg, graph, rc = _load_graph_or_error(args)
     if rc:
         return rc
-    # flow requires a Route root; force hint_kind="route".
-    node, _renv, rrc = _resolve_traversal_node(args, cfg=cfg, graph=graph, hint_kind="route")
-    if rrc or node is None:
-        return rrc
-    limit = _clamped_limit(args)
+    from java_codebase_rag.read_payloads import PayloadError, flow_payload
+    from java_codebase_rag.watch.client import get_payload
 
-    guard = _require_kind(
-        node, expected="flow requires a Route root", kinds=("route",), args=args,
-        hint="Pass a route path (e.g. /chat/assign).",
-    )
-    if guard is not None:
-        return guard
-
-    warnings = _warn_unapplied_scope(
-        args, reason="trace_request_flow carries no microservice predicate; intra-codebase is an index-time data property"
-    )
-
-    max_hops = max(1, min(8, getattr(args, "depth", 5)))
-    flow_data = graph.trace_request_flow(entry_route_id=node.id, max_hops=max_hops)
-
-    root_id = node.id
-    nodes: dict[str, dict] = {root_id: _noderef_to_node_dict(node)}
-    edges: list[dict] = []
-    # Inbound: cross-service HTTP/async callers (Client/Producer two-hop).
-    for row in flow_data.get("inbound", []):
-        caller_id = str(row.get("caller_node_id") or "")
-        if not caller_id:
-            continue
-        kind = str(row.get("caller_node_kind") or "")
-        nodes[caller_id] = {
-            "id": caller_id,
-            "kind": kind,
-            "fqn": str(row.get("declaring_symbol_fqn") or ""),
-            "microservice": str(row.get("microservice") or ""),
-        }
-        edges.append(
-            {
-                "other_id": caller_id,
-                "edge_type": "HTTP_CALLS" if kind == "client" else "ASYNC_CALLS",
-                "confidence": float(row.get("confidence") or 0.0),
-            }
-        )
-    # Outbound: CALLS hops from the route handler (intra-service by construction).
-    for row in flow_data.get("outbound", []):
-        next_id = str(row.get("next_symbol_id") or "")
-        if not next_id:
-            continue
-        nodes[next_id] = {
-            "id": next_id,
-            "kind": "symbol",
-            "fqn": str(row.get("next_fqn") or ""),
-            "microservice": str(row.get("next_microservice") or ""),
-        }
-        edges.append({"other_id": next_id, "edge_type": "CALLS"})
-
-    # Client-side slice for truncation (trace_request_flow has no limit param).
-    truncated = len(edges) > limit
-    if truncated:
-        edges = edges[:limit]
+    try:
+        payload = get_payload("flow", vars(args), cfg, cold_core=flow_payload)
+    except PayloadError as pe:
+        # Resolve-miss: route through _emit so --exists/--count shape it
+        # (flow Missing --exists -> false, rc 2), mirroring master's
+        # _resolve_traversal_node resolve-miss path.
+        return _emit(pe.env, args)
     return _emit_traversal(
-        args, root_id=root_id, nodes=nodes, edges=edges,
-        noun="flow", warnings=warnings, truncated=truncated,
+        args, root_id=payload["root_id"], nodes=payload["nodes"], edges=payload["edges"],
+        noun=payload["noun"], warnings=payload["warnings"], truncated=payload["truncated"],
+        is_external_entrypoint=payload["is_external_entrypoint"],
     )
 
 
-# ============================================================================
-# PR-JRAG-3b: compose traversals + connection + outline/imports.
-#
-# callees Client/Producer variant (above) re-uses _cmd_callees. The four new
-# handlers below cover: dependencies (INJECTS out), connection (multi-section
-# microservice view, resolve-first EXCEPTION), outline (file -> symbols),
-# imports (file -> tree-sitter parse -> resolve_v2 per FQN).
-#
-# Backend signatures verified at PR-JRAG-3b time:
-#  * neighbors_v2(ids, direction, edge_types, limit=25, offset=0, ...) returns
-#    NeighborsOutput.results: list[Edge] where Edge.other: NodeRef,
-#    Edge.edge_type: str, Edge.attrs: dict (mcp_v2.py:1284).
-#  * find_symbols_in_file_range(graph, *, filename, start_line, end_line)
-#    returns list[SymbolHit]; start_line<1 returns [] (ladybug_queries.py:302).
-#  * parse_java(source, *, filename, verbose) -> JavaFileAst with
-#    explicit_imports: dict[str, str] (simple_name -> FQN) (ast_java.py:2612).
-#  * INJECTS is Symbol -> Symbol (java_ontology.py:216); out = types this
-#    symbol injects = direct dependencies.
-#  * HTTP_CALLS is Client -> Route (java_ontology.py:352); ASYNC_CALLS is
-#    Producer -> Route (java_ontology.py:386). Both confirmed.
-# ============================================================================
-
 
 def _cmd_dependencies(args: argparse.Namespace) -> int:
     from java_codebase_rag.mcp import mcp_v2
@@ -3332,7 +3313,6 @@ def _cmd_connection(args: argparse.Namespace) -> int:
     limit = _clamped_limit(args)
 
     from java_codebase_rag.jrag_envelope import Envelope, next_actions_hook
-    from java_codebase_rag.jrag_render import render
 
     # Validate the microservice against the known set so a bogus name surfaces a
     # clear error instead of an empty inbound:/outbound: view (silent wrong
@@ -3532,8 +3512,7 @@ def _cmd_connection(args: argparse.Namespace) -> int:
         truncated=truncated,
     )
     next_actions_hook(env, root=root_id, result_edges=display_edges)
-    print(render(env, fmt=args.format, detail=args.detail, noun="connection"))
-    return 0
+    return _emit(env, args, noun="connection")
 
 
 def _resolve_source_path(cfg, file_arg: str) -> Path | None:
@@ -3616,8 +3595,7 @@ def _cmd_outline(args: argparse.Namespace) -> int:
     # thing to inspect from an outline. Per-row inspect hints for the leading
     # entries give the agent a concrete next step.
     env.agent_next_actions = _inspect_hints_for_rows(display, limit=2)
-    print(render(env, fmt=args.format, detail=args.detail, noun="symbol"))
-    return 0
+    return _emit(env, args, noun="symbol")
 
 
 def _cmd_imports(args: argparse.Namespace) -> int:
@@ -3730,8 +3708,7 @@ def _cmd_imports(args: argparse.Namespace) -> int:
 
     env = Envelope(status="ok", nodes=nodes, edges=edges, warnings=warnings)
     next_actions_hook(env, result_edges=edges)
-    print(render(env, fmt=args.format, detail=args.detail, noun="import"))
-    return 0
+    return _emit(env, args, noun="import")
 
 
 # ============================================================================
@@ -3743,8 +3720,8 @@ def _cmd_imports(args: argparse.Namespace) -> int:
 # (kv-block + nested dict sections) so the agent sees compact structured data.
 #
 # Search dispatches to search_v2 (mcp_v2.search_v2) after building a NodeFilter
-# from flags. --fuzzy is registered on the parser but rejected IN-HANDLER with
-# status: error (not argparse exit) so the envelope carries the message.
+# from flags. --fuzzy is registered on the parser and accepted as a silent
+# no-op (search is inherently semantic; --fuzzy is implicit).
 # ============================================================================
 
 
@@ -3781,7 +3758,6 @@ def _cmd_map(args: argparse.Namespace) -> int:
     axis, which made "group by ALL modules" unreachable.
     """
     from java_codebase_rag.jrag_envelope import Envelope, next_actions_hook
-    from java_codebase_rag.jrag_render import render
 
     _, graph, rc = _load_graph_or_error(args)
     if rc:
@@ -3835,14 +3811,12 @@ def _cmd_map(args: argparse.Namespace) -> int:
         hints.append(f"jrag overview {drill_scope}")
     hints.append("jrag conventions")
     env.agent_next_actions = hints[:5]
-    print(render(env, fmt=args.format, detail=args.detail, noun="map", shape="inspect"))
-    return 0
+    return _emit(env, args, noun="map", shape="inspect")
 
 
 def _cmd_conventions(args: argparse.Namespace) -> int:
     """conventions [--service] — dominant roles + framework tallies."""
     from java_codebase_rag.jrag_envelope import Envelope, next_actions_hook
-    from java_codebase_rag.jrag_render import render
 
     _, graph, rc = _load_graph_or_error(args)
     if rc:
@@ -3904,8 +3878,7 @@ def _cmd_conventions(args: argparse.Namespace) -> int:
         hints.append(f"jrag find --role {top_role}{scope_suffix}")
     hints.append("jrag map")
     env.agent_next_actions = hints[:5]
-    print(render(env, fmt=args.format, detail=args.detail, noun="conventions", shape="inspect"))
-    return 0
+    return _emit(env, args, noun="conventions", shape="inspect")
 
 
 def _overview_detect_type(subject: str, graph) -> str:
@@ -3940,7 +3913,6 @@ def _overview_microservice(args: argparse.Namespace, graph, microservice: str) -
     bundle to empty (subject node) or keep all samples equally (rollup node).
     """
     from java_codebase_rag.jrag_envelope import Envelope, next_actions_hook
-    from java_codebase_rag.jrag_render import render
 
     limit = _clamped_limit(args)
     routes = graph.list_routes(microservice=microservice, limit=limit + 1)
@@ -3994,8 +3966,7 @@ def _overview_microservice(args: argparse.Namespace, graph, microservice: str) -
         nodes={f"microservice:{microservice}": node},
     )
     next_actions_hook(env)
-    print(render(env, fmt=args.format, detail=args.detail, noun="overview", shape="inspect"))
-    return 0
+    return _emit(env, args, noun="overview", shape="inspect")
 
 
 def _overview_route(args: argparse.Namespace, cfg, graph, route_path: str) -> int:
@@ -4009,8 +3980,7 @@ def _overview_route(args: argparse.Namespace, cfg, graph, route_path: str) -> in
         cfg=cfg, graph=graph,
     )
     if renv.status != "ok" or node is None:
-        print(render(renv, fmt=args.format, detail=args.detail))
-        return 2 if renv.status == "error" else 0
+        return _emit(renv, args)
 
     if node.kind != "route":
         env = Envelope(
@@ -4055,8 +4025,7 @@ def _overview_route(args: argparse.Namespace, cfg, graph, route_path: str) -> in
         edges = edges[:limit]
     env = Envelope(status="ok", nodes=nodes_dict, edges=edges, root=root_id, truncated=truncated)
     next_actions_hook(env, root=root_id, result_edges=edges)
-    print(render(env, fmt=args.format, detail=args.detail, noun="overview"))
-    return 0
+    return _emit(env, args, noun="overview")
 
 
 def _overview_topic(args: argparse.Namespace, graph, topic: str) -> int:
@@ -4069,7 +4038,6 @@ def _overview_topic(args: argparse.Namespace, graph, topic: str) -> int:
     samples, full = +limit samples.
     """
     from java_codebase_rag.jrag_envelope import Envelope, next_actions_hook
-    from java_codebase_rag.jrag_render import render
 
     limit = _clamped_limit(args)
     # Producers: exact topic match first, then substring match as fallback.
@@ -4123,8 +4091,7 @@ def _overview_topic(args: argparse.Namespace, graph, topic: str) -> int:
         nodes={f"topic:{topic}": topic_node},
     )
     next_actions_hook(env)
-    print(render(env, fmt=args.format, detail=args.detail, noun="overview", shape="inspect"))
-    return 0
+    return _emit(env, args, noun="overview", shape="inspect")
 
 
 def _cmd_overview(args: argparse.Namespace) -> int:
@@ -4247,24 +4214,17 @@ def _cmd_search(args: argparse.Namespace) -> int:
     """search <query> — semantic search via search_v2 over Lance tables.
 
     Builds a NodeFilter from flags, calls search_v2 with limit+1 for +1-fetch
-    truncation, and renders. --fuzzy is rejected IN-HANDLER (not argparse-exit)
-    so the error carries the canonical envelope shape.
+    truncation, and renders. --fuzzy is accepted as a silent no-op (search is
+    always semantic; --fuzzy is implicit).
     """
-    from java_codebase_rag.mcp import mcp_v2
-
     from java_codebase_rag.jrag_envelope import Envelope, mark_truncated, next_actions_hook, normalize_enum
     from java_codebase_rag.jrag_render import render
 
-    # --fuzzy: registered on the parser (so argparse doesn't exit 2), but rejected
-    # IN-HANDLER with status: error (search is inherently semantic; --fuzzy is
-    # a no-op synonym, not a real mode toggle).
-    if getattr(args, "fuzzy", False):
-        env = Envelope(
-            status="error",
-            message="search is semantic; --fuzzy is implicit",
-        )
-        print(render(env, fmt=args.format, detail=args.detail))
-        return 2
+    # --fuzzy: accepted as a silent no-op. Search is inherently semantic
+    # (vector + lexical), so --fuzzy is implicit; the flag is kept registered
+    # so callers/agents that pass it don't hit an argparse or envelope error,
+    # and is simply ignored here.
+    _ = getattr(args, "fuzzy", False)
 
     cfg, graph, rc = _load_graph_or_error(args)
     if rc:
@@ -4282,8 +4242,7 @@ def _cmd_search(args: argparse.Namespace) -> int:
             warnings=_auto_scope_notice(args),
         )
         next_actions_hook(env)
-        print(render(env, fmt=args.format, detail=args.detail, noun="search"))
-        return 0
+        return _emit(env, args, noun="search")
 
     # Build NodeFilter from flags (same set as `find` filter mode).
     filter_dict: dict = {}
@@ -4325,23 +4284,21 @@ def _cmd_search(args: argparse.Namespace) -> int:
         )
         print(render(env, fmt=args.format, detail=args.detail))
         return 2
-    node_filter, err_env = _build_node_filter_or_error(filter_dict)
-    if err_env is not None:
-        print(render(err_env, fmt=args.format, detail=args.detail))
-        return 2
-
-    out = mcp_v2.search_v2(
-        args.query,
-        table=args.table,
-        hybrid=args.hybrid,
-        limit=limit + 1,  # +1 for truncated detection
-        offset=args.offset,
-        path_contains=args.path_contains,
-        filter=node_filter,
-        explain=args.explain,
-        graph=graph,
-        dedup=not getattr(args, "chunks", False),
-    )
+    from java_codebase_rag.read_payloads import PayloadError, search_payload
+    from java_codebase_rag.watch.client import get_payload
+
+    # search_payload builds the NodeFilter from args (same filter_dict set above)
+    # and calls search_v2 with limit+1. On filter-validation failure it raises
+    # PayloadError carrying the error Envelope (rendered identically to before).
+    # get_payload tries the watch daemon first (hot), cold-falling-back to the
+    # identical search_payload core when no daemon is alive (every non-watch jrag
+    # invocation). Reconstructs the SearchOutput object on the hot path so the
+    # downstream render is unchanged.
+    try:
+        out = get_payload("search", vars(args), cfg, cold_core=search_payload)
+    except PayloadError as pe:
+        print(render(pe.env, fmt=args.format, detail=args.detail))
+        return pe.rc
 
     if not out.success:
         env = Envelope(status="error", message=out.message or "search failed")
@@ -4430,8 +4387,7 @@ def _cmd_search(args: argparse.Namespace) -> int:
     if display:
         env.agent_next_actions = _inspect_hints_for_rows(display, limit=2)
     next_offset = args.offset + limit if truncated else None
-    print(render(env, fmt=args.format, detail=args.detail, noun="search", next_offset=next_offset))
-    return 0
+    return _emit(env, args, noun="search", next_offset=next_offset)
 
 
 def _suppress_runtime_stderr_noise() -> None:
@@ -4551,9 +4507,19 @@ def _console_script_main() -> None:
     (SIGABRT, exit -6). Flushing + ``os._exit`` skips that racy teardown - the
     command has already done its work and emitted its result. ``main()`` stays
     return-based so in-process test callers keep working.
+
+    ``KeyboardInterrupt`` (Ctrl+C during a long indexing step) is caught here so
+    it routes through the same flush + ``os._exit`` path — clean, immediate exit
+    (code 130, no traceback) and no finalization-time SIGABRT — instead of
+    propagating past this function.
     """
     force_utf8_stdio()
-    rc = main()
+    try:
+        rc = main()
+    except KeyboardInterrupt:
+        sys.stderr.write("\nInterrupted.\n")
+        sys.stderr.flush()
+        rc = 130
     sys.stdout.flush()
     sys.stderr.flush()
     os._exit(rc)